{t(locale, 'Related cookbooks', '相关 Cookbook')}
+-
+ {linkedCookbooks.map((cookbook) => (
+
- {cookbook.title} + ))} +
{t(locale, 'Related integrations', '相关集成')}
+-
+ {linkedIntegrations.map((integration) => (
+
- {integration.name} + ))} +
+
+
+
+ + {isIntegrations + ? t(locale, 'Integration Hub', '集成中心') + : t(locale, 'Cookbooks', '实践指南')} +
+{heading}
+{description}
+-
+
- {entries.length}
- {isIntegrations ? t(locale, 'integrations', '项集成') : t(locale, 'cookbooks', '篇 Cookbook')}
- {groups.length}
- {t(locale, 'categories', '个类别')}
+
+
+
+ {groups.map((group) => (
+
+
+ ))}
+
+
+
+
+
diff --git a/next/src/components/Header.astro b/next/src/components/Header.astro
index 2c0018111367a..0c16cc8c50083 100644
--- a/next/src/components/Header.astro
+++ b/next/src/components/Header.astro
@@ -23,7 +23,7 @@ const switchUrl = switchPath ?? (locale === 'zh' ? path : `/zh${path}`);
) : (
@@ -47,10 +47,57 @@ const switchUrl = switchPath ?? (locale === 'zh' ? path : `/zh${path}`);
+
+ {group.label}
+{group.entries.length} {t(locale, 'items', '项')}
+
+ {group.entries.map((entry) => (
+
+
+
+ {entry.kind === 'integration' && (
+
+ )}
+
+ {localize(locale, verificationLabels[entry.verification])}
+
+
+ {nameOf(entry)}
+{descriptionOf(entry)}
+ {entry.kind === 'integration' ? ( + + ) : ( + + )} + + {entry.kind === 'integration' + ? t(locale, 'View integration', '查看集成') + : t(locale, 'View cookbook', '查看指南')} + + + ))} +☰
{t(locale, 'Explore all 100+ plugins →', '浏览全部 100+ 插件 →')}
+{t(locale, 'Explore integrations →', '浏览集成 →')}
diff --git a/next/src/layouts/EcosystemDetail.astro b/next/src/layouts/EcosystemDetail.astro new file mode 100644 index 0000000000000..16ab6eb953f3a --- /dev/null +++ b/next/src/layouts/EcosystemDetail.astro @@ -0,0 +1,195 @@ +--- +import Base from './Base.astro'; +import { + localize, + verificationLabels, + type VerificationStatus, +} from '../lib/ecosystem'; +import { SITE, localePrefix, t, type Locale } from '../lib/site'; + +interface Props { + locale: Locale; + kind: 'integration' | 'cookbook'; + title: string; + description: string; + path: string; + category: string; + verification: VerificationStatus; + owner: string; + apisixVersion: string; + externalVersion?: string; + lastVerified?: string; + verificationUrl?: string; + reviewedAt: string; + evidenceUrl: string; + protocols?: string[]; + difficulty?: string; + duration?: string; +} + +const { + locale, + kind, + title, + description, + path, + category, + verification, + owner, + apisixVersion, + externalVersion, + lastVerified, + verificationUrl, + reviewedAt, + evidenceUrl, + protocols = [], + difficulty, + duration, +} = Astro.props; +const p = localePrefix(locale); +const hubPath = kind === 'integration' ? '/integrations/' : '/cookbooks/'; +const hubLabel = kind === 'integration' + ? t(locale, 'Integrations', '集成') + : t(locale, 'Cookbooks', 'Cookbook'); + +const articleSchema = { + '@context': 'https://schema.org', + '@type': 'TechArticle', + headline: title, + description, + url: `${SITE}${p}${path}`, + mainEntityOfPage: `${SITE}${p}${path}`, + inLanguage: locale === 'zh' ? 'zh-CN' : 'en', + about: { + '@type': 'SoftwareApplication', + name: kind === 'integration' ? 'Apache APISIX integration' : 'Apache APISIX cookbook', + applicationCategory: 'DeveloperApplication', + }, + author: { + '@type': 'Organization', + name: 'Apache APISIX', + url: SITE, + }, + publisher: { + '@type': 'Organization', + name: 'Apache APISIX', + url: SITE, + }, + isPartOf: { + '@type': 'CollectionPage', + name: hubLabel, + url: `${SITE}${p}${hubPath}`, + }, + dateModified: lastVerified ?? reviewedAt, +}; +const breadcrumbSchema = { + '@context': 'https://schema.org', + '@type': 'BreadcrumbList', + itemListElement: [ + { '@type': 'ListItem', position: 1, name: 'Apache APISIX', item: `${SITE}${p}/` }, + { '@type': 'ListItem', position: 2, name: hubLabel, item: `${SITE}${p}${hubPath}` }, + { '@type': 'ListItem', position: 3, name: title, item: `${SITE}${p}${path}` }, + ], +}; +--- +
+
+
+
+
+
+ {category}
+{title}
+{description}
+
+
+ {localize(locale, verificationLabels[verification])}
+
+ {t(locale, 'Maintained by', '维护者')} {owner}
+
+ -
+
- APISIX
- {apisixVersion}
- {t(locale, 'Dependency', '依赖')}
- {externalVersion}
- {t(locale, 'Protocols', '协议')}
- {protocols.join(', ')}
- {t(locale, 'Difficulty', '难度')}
- {difficulty}
- {t(locale, 'Time', '时间')}
- {duration}
- {t(locale, 'Last verified', '最近验证')} +
- {lastVerified && verificationUrl + ? {lastVerified} + : t(locale, 'Pending', '尚未验证')} +
- {t(locale, 'Code reviewed', '源码审查')}
- {reviewedAt}
+
+
+ {verification === 'validation-in-progress' && (
+
+ )}
+
+
+
+
+
+
diff --git a/next/src/lib/ecosystem.ts b/next/src/lib/ecosystem.ts
new file mode 100644
index 0000000000000..540e3ce322ea4
--- /dev/null
+++ b/next/src/lib/ecosystem.ts
@@ -0,0 +1,266 @@
+import type { MdModule } from './content';
+import type { Locale } from './site';
+
+export type LocalizedText = { en: string; zh: string };
+export type VerificationStatus = 'verified' | 'documented' | 'validation-in-progress';
+export type IntegrationCategory = 'ai-runtime' | 'data';
+export type CookbookCategory = 'cost' | 'deployment' | 'reliability';
+
+interface BaseResource {
+ slug: string;
+ description: string;
+ verification: VerificationStatus;
+ owner: string;
+ apisixVersion: string;
+ externalVersion: string;
+ reviewedAt: string;
+ evidenceUrl: string;
+ lastVerified?: string;
+ verificationUrl?: string;
+ href: string;
+ mod: MdModule;
+}
+
+export interface IntegrationEntry extends BaseResource {
+ kind: 'integration';
+ name: string;
+ category: IntegrationCategory;
+ method: string;
+ protocols: string[];
+ icon?: string;
+}
+
+export interface CookbookEntry extends BaseResource {
+ kind: 'cookbook';
+ title: string;
+ category: CookbookCategory;
+ difficulty: string;
+ duration: string;
+ integrations: string[];
+ plugins: string[];
+}
+
+type MdMap = { [key: string]: MdModule };
+
+// Vite requires literal glob patterns. Files are copied here by sync-content.mjs.
+const integrationEnModules = import.meta.glob('/content/integrations-en/*.md', { eager: true }) as MdMap;
+const integrationZhModules = import.meta.glob('/content/integrations-zh/*.md', { eager: true }) as MdMap;
+const cookbookEnModules = import.meta.glob('/content/cookbooks-en/*.md', { eager: true }) as MdMap;
+const cookbookZhModules = import.meta.glob('/content/cookbooks-zh/*.md', { eager: true }) as MdMap;
+
+export const verificationLabels: { [key: VerificationStatus]: LocalizedText } = {
+ verified: { en: 'E2E verified', zh: '端到端已验证' },
+ documented: { en: 'Documented', zh: '文档已核对' },
+ 'validation-in-progress': { en: 'Validation in progress', zh: '验证进行中' },
+};
+
+export const integrationCategoryLabels: { [key: IntegrationCategory]: LocalizedText } = {
+ 'ai-runtime': { en: 'AI model runtimes', zh: 'AI 模型运行时' },
+ data: { en: 'Data stores, caching, and rate limiting', zh: '数据存储、缓存与限流' },
+};
+
+export const cookbookCategoryLabels: { [key: CookbookCategory]: LocalizedText } = {
+ cost: { en: 'Cost and quotas', zh: '成本与配额' },
+ deployment: { en: 'Deployment and model serving', zh: '部署与模型服务' },
+ reliability: { en: 'Reliability', zh: '可靠性' },
+};
+
+export function localize(locale: Locale, value: LocalizedText | string): string {
+ return typeof value === 'string' ? value : value[locale];
+}
+
+function sourceName(mod: MdModule): string {
+ return mod.file || 'ecosystem markdown';
+}
+
+function requiredString(mod: MdModule, key: string): string {
+ const value = mod.frontmatter[key];
+ if (typeof value !== 'string' || value.trim() === '') {
+ throw new Error(`${sourceName(mod)}: frontmatter ${key} must be a non-empty string`);
+ }
+ return value.trim();
+}
+
+function stringArray(mod: MdModule, key: string): string[] {
+ const value = mod.frontmatter[key];
+ if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string' || item.trim() === '')) {
+ throw new Error(`${sourceName(mod)}: frontmatter ${key} must be a non-empty string array`);
+ }
+ return value.map((item) => item.trim());
+}
+
+function modulesBySlug(modules: MdMap, locale: Locale): Map
+ OpenAI-compatible client→Apache APISIX→LocalAI
+
+
+LocalAI now includes an [Apache APISIX reverse-proxy example](https://github.com/mudler/LocalAI/blob/d85577ff5c6f7cbc5a49c13ab5013a1ecfabf26c/docs/content/advanced/reverse-proxy-tls.md#apache-apisix-configuration). That example is a transparent proxy. The related Cookbook on this site uses the APISIX 3.18 `openai-compatible` provider instead.
+
+## How the connection works
+
+| Setting | Behavior |
+|---|---|
+| Endpoint | Set `override.endpoint` to the LocalAI origin, for example `http://localai:8080`. APISIX selects `/v1/chat/completions` for a Chat Completions body. Do not set the endpoint to `http://localai:8080/v1`: an endpoint path is used as-is and would suppress the provider path. |
+| Model | Set `options.model` to pin one installed LocalAI model and override the client's value. Omit it when clients may select among allowed LocalAI model aliases. |
+| Authentication | Authenticate clients separately, for example with `key-auth`. Configure the LocalAI credential in `ai-proxy.auth.header.Authorization`; that configured value replaces a client `Authorization` header before the upstream request. |
+| Streaming | A request with `stream: true` is handled as SSE. APISIX adds the OpenAI usage-stream option and forwards the LocalAI stream to the client. |
+
+The `openai-compatible` provider also defines OpenAI Responses and Embeddings paths. This page only covers Chat Completions; test the other LocalAI endpoints separately before enabling them.
+
+## Keep the surface small
+
+Expose only the Chat Completions Route needed by applications. `ai-proxy` does not turn the Route into a general LocalAI proxy, so `/v1/models`, the Web UI, model installation, and LocalAI management endpoints remain unavailable unless you create separate Routes for them.
+
+Keep LocalAI on a private network reachable by APISIX. Store its authorization value in an APISIX-supported secret reference, keep payload logging disabled unless you have a reviewed data-handling policy, and use TLS with certificate verification when LocalAI is reached across an untrusted network. Because `ai-proxy` forwards other client headers, remove `Cookie`, `x-api-key`, and `xi-api-key` on Routes that use a dedicated LocalAI identity. LocalAI's legacy `LOCALAI_API_KEY` grants full administrative access without role separation; prefer a least-privilege user API key when LocalAI authentication is enabled.
+
+## Verification status
+
+The merged LocalAI guide and [APISIX documentation PR #13770](https://github.com/apache/apisix/pull/13770) cover a transparent APISIX proxy. The latter records a real run with APISIX 3.17.0 and LocalAI 4.7.1. The APISIX 3.18 `openai-compatible` configuration on this site has been checked against the [3.18.0 provider source](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-providers/openai-compatible.lua), but it has not yet completed the same clean runtime test. The status therefore remains **Validation in progress**.
+
+## References
+
+- [APISIX `ai-proxy` documentation](/docs/apisix/plugins/ai-proxy/)
+- [LocalAI 4.7.1 quickstart](https://github.com/mudler/LocalAI/blob/b224c96db6f4b87306a33a808650bfce63b12588/docs/content/getting-started/quickstart.md)
+- [LocalAI 4.7.1 authentication](https://github.com/mudler/LocalAI/blob/b224c96db6f4b87306a33a808650bfce63b12588/docs/content/features/authentication.md)
+- [Merged LocalAI APISIX documentation PR](https://github.com/mudler/LocalAI/pull/11294)
diff --git a/website/integrations/en/redis.md b/website/integrations/en/redis.md
new file mode 100644
index 0000000000000..2e8adb6efa7d6
--- /dev/null
+++ b/website/integrations/en/redis.md
@@ -0,0 +1,64 @@
+---
+title: Redis
+slug: redis
+description: Use Redis for AI response caching, shared token counters, and request quotas across APISIX nodes.
+category: data
+method: Built-in APISIX plugins
+verification: validation-in-progress
+owner: Apache APISIX community
+apisix_version: 3.18.0
+external_version: Redis Open Source 8.10.1
+protocols:
+ - RESP
+reviewed_at: "2026-08-28"
+evidence_url: https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-cache.lua
+---
+
+Apache APISIX 3.18 can use Redis for reusable LLM responses, shared token counters, and distributed request quotas. These features have different deployment and failure characteristics, so configure and operate them separately.
+
+
+ AI client→Apache APISIX↔Redis
+
+
+## How APISIX uses Redis
+
+| Use case | APISIX 3.18 behavior | Limits and operational notes |
+|---|---|---|
+| Exact response cache | Redis stores the body of an HTTP 200 AI response. The key includes a normalized request body and configured provider options. The default TTL is 3,600 seconds and the default maximum response is 1 MiB. | Forwarded headers are not part of the default key. If a header can change the provider response, remove it or map it to a trusted server-side variable and include that variable in `cache_key.include_vars`. APISIX 3.18 supports one Redis endpoint for the cache. It does not coalesce concurrent cache misses, honor upstream `Cache-Control`, or provide a purge API. A hit restores HTTP 200 and `Content-Type`; other upstream response headers are not replayed. |
+| Semantic response cache | After an exact miss, APISIX can embed a plain-text OpenAI Chat prompt and query Redis Search for a similar cached response. | Semantic matching is limited to plain-text OpenAI Chat requests. Multimodal requests and non-empty tool or function calls bypass this layer. The exact layer remains enabled. |
+| Shared token quota | `ai-rate-limiting` can store a fixed-window token counter in a Redis database so multiple APISIX nodes see the same usage. | Accounting happens after a model response supplies token usage. It is not a prepaid reservation: a large or concurrent response can cross the limit before a later request is rejected. |
+| Shared request quota | `limit-count` with `policy: redis` stores request counters in Redis so different APISIX nodes use the same quota. | Choose the counter key from trusted state. Fixed and sliding windows are available. `sync_interval` reduces Redis round trips but lets the global count lag between synchronizations. The companion lab has not tested this path. |
+| Streaming cache | A complete supported SSE response can be cached after APISIX sees the protocol terminal event. | Interrupted streams are not cached. JSON and SSE use separate entries. A cache hit replays the complete stored SSE immediately; it does not reproduce the original token cadence. |
+
+Semantic caching requires Redis Search commands. The companion lab pins Redis Open Source 8.10.1 and checks that `FT._LIST` is available. This preflight confirms the Redis setup, not the LLM cache path. If you use an earlier Redis Open Source or Redis Stack release, pin and test that exact version.
+
+## Isolation and security
+
+By default, APISIX separates cache entries by Route, not by Consumer. To isolate tenants, authenticate each tenant as a distinct Consumer and set `cache_key.include_consumer: true`, or add a trusted server-side tenant variable to the key. This option does not isolate unauthenticated traffic, and a client-controlled header is not a tenant boundary. Remove any client-controlled header that can change provider routing or output. If a response must vary by another value, derive it from trusted server-side state and include it with `cache_key.include_vars`.
+
+Store Redis credentials in an APISIX Secret and keep Redis on a private network. Enable certificate verification when using TLS, and do not expose cached prompts, embeddings, provider request IDs, or full Redis keys in logs or screenshots.
+
+## Failure behavior
+
+- Cache, vector-search, and embedding errors degrade to a cache miss, so APISIX continues to the LLM. A `MISS` header alone does not prove the Redis service is healthy.
+- Shared quota behaves differently. A pre-request Redis check returns an error when `allow_degradation: false`; when set to `true`, APISIX lets the request continue without quota protection. This setting applies only to the pre-request check. If Redis fails before the log-phase write completes, the response may succeed without recording its token usage. Monitor APISIX for write errors.
+- `limit-count` also follows `allow_degradation` when its Redis dependency fails. Redis Cluster and Sentinel policies are documented and covered by upstream tests, but this page does not claim their failover behavior was validated in the companion lab.
+- A cache hit returns before `ai-rate-limiting` runs. It avoids an upstream model call and does not increase the Redis token counter.
+
+## Observability
+
+The APISIX Prometheus plugin exports cache hits by `exact` or `semantic` layer, misses, bypasses, and embedding-latency histograms. `ai-rate-limiting` does not export a dedicated Redis token-counter metric. To verify shared token usage, compare the response headers, Redis state, APISIX logs, and provider-reported usage.
+
+## References
+
+- [`ai-cache` source at the APISIX 3.18.0 tag](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-cache.lua)
+- [`ai-cache` schema](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-cache/schema.lua)
+- [Semantic-cache implementation](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-cache/semantic.lua)
+- [`ai-rate-limiting` source](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-rate-limiting.lua)
+- [`limit-count` source](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/limit-count.lua)
+- [Redis Search module lifecycle](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/modules-lifecycle/)
+- [Pinned two-node APISIX and Redis lab](https://github.com/apache/apisix-website/tree/master/examples/redis-ai-gateway)
+
+The behavior above matches the APISIX 3.18.0 source, but runtime testing is not complete. Keep this page marked **Validation in progress** until the lab records provider-side chat and embedding call counts, complete and interrupted SSE results, two clean runs, sanitized logs, a rerun by another operator, and a separate validation of the Redis-backed `limit-count` request-quota path.
+
+Redis is a registered trademark of Redis Ltd. This community integration is not endorsed, supported, or certified by Redis Ltd.
diff --git a/website/integrations/zh/localai.md b/website/integrations/zh/localai.md
new file mode 100644
index 0000000000000..59e1548fa8dec
--- /dev/null
+++ b/website/integrations/zh/localai.md
@@ -0,0 +1,43 @@
+---
+title: LocalAI
+slug: localai
+translation_of: localai
+description: 通过 APISIX 3.18 将 OpenAI 兼容的 Chat 请求转发到私有 LocalAI，并分开管理客户端认证与上游认证。
+method: ai-proxy openai-compatible Provider
+---
+
+LocalAI 可在自有基础设施上运行模型，并提供 OpenAI 兼容 API。Apache APISIX 3.18 可以通过 `ai-proxy` 将 Chat Completions 请求发送到 LocalAI，同时在网关侧统一处理客户端认证、上游凭据、限流和日志。
+
+
+ OpenAI 兼容客户端→Apache APISIX→LocalAI
+
+
+LocalAI 已合并 [Apache APISIX 反向代理示例](https://github.com/mudler/LocalAI/blob/d85577ff5c6f7cbc5a49c13ab5013a1ecfabf26c/docs/content/advanced/reverse-proxy-tls.md#apache-apisix-configuration)。该示例使用透明代理；本站的相关 Cookbook 则使用 APISIX 3.18 的 `openai-compatible` Provider。
+
+## 接入方式
+
+| 配置 | 行为 |
+|---|---|
+| Endpoint | 将 `override.endpoint` 设为 LocalAI 的 origin，例如 `http://localai:8080`。APISIX 会根据 Chat Completions 请求正文选择 `/v1/chat/completions`。不要写成 `http://localai:8080/v1`，因为 endpoint 中已有的路径会被原样使用，不会再追加 Provider 路径。 |
+| 模型 | 设置 `options.model` 可固定一个已安装的 LocalAI 模型，并覆盖客户端传入的值。若允许客户端从许可的模型别名中选择，则省略该字段。 |
+| 认证 | 客户端可以使用 `key-auth` 等插件单独认证。LocalAI 凭据配置在 `ai-proxy.auth.header.Authorization` 中；调用上游时，这个值会替换客户端传入的 `Authorization` header。 |
+| 流式响应 | 请求正文包含 `stream: true` 时，APISIX 按 SSE 处理，补充 OpenAI 的流式 usage 选项，并把 LocalAI 的流转发给客户端。 |
+
+`openai-compatible` Provider 还定义了 OpenAI Responses 与 Embeddings 路径。本文只覆盖 Chat Completions；启用其他 LocalAI 接口前，需要分别验证。
+
+## 控制暴露面
+
+只开放应用需要的 Chat Completions Route。`ai-proxy` 不会把这条 Route 变成 LocalAI 的通用反向代理，因此 `/v1/models`、Web UI、模型安装与管理接口不会自动暴露；如确有需要，应单独创建并保护 Route。
+
+LocalAI 应位于 APISIX 可访问的私有网络。其认证值应使用 APISIX 支持的 Secret 引用保存；除非已有评审通过的数据处理策略，否则不要启用正文日志。若 APISIX 需要跨不可信网络访问 LocalAI，应启用 TLS 并校验证书。由于 `ai-proxy` 会转发其他客户端 header，使用独立 LocalAI 身份的 Route 应移除 `Cookie`、`x-api-key` 和 `xi-api-key`。LocalAI 旧版 `LOCALAI_API_KEY` 拥有完整管理权限且没有角色隔离；启用 LocalAI 认证时，应优先使用最小权限的用户 API key。
+
+## 验证状态
+
+LocalAI 已合并的文档和 [APISIX 文档 PR #13770](https://github.com/apache/apisix/pull/13770) 使用透明代理；后者记录了 APISIX 3.17.0 与 LocalAI 4.7.1 的真实运行结果。本站的 APISIX 3.18 `openai-compatible` 配置已根据 [3.18.0 Provider 源码](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-providers/openai-compatible.lua) 核对，但尚未完成同等的干净环境运行测试，因此状态保持“**验证进行中**”。
+
+## 参考资料
+
+- [APISIX `ai-proxy` 文档](/zh/docs/apisix/plugins/ai-proxy/)
+- [LocalAI 4.7.1 快速入门](https://github.com/mudler/LocalAI/blob/b224c96db6f4b87306a33a808650bfce63b12588/docs/content/getting-started/quickstart.md)
+- [LocalAI 4.7.1 认证文档](https://github.com/mudler/LocalAI/blob/b224c96db6f4b87306a33a808650bfce63b12588/docs/content/features/authentication.md)
+- [已合并的 LocalAI APISIX 文档 PR](https://github.com/mudler/LocalAI/pull/11294)
diff --git a/website/integrations/zh/redis.md b/website/integrations/zh/redis.md
new file mode 100644
index 0000000000000..2ca145eb82993
--- /dev/null
+++ b/website/integrations/zh/redis.md
@@ -0,0 +1,56 @@
+---
+title: Redis
+slug: redis
+translation_of: redis
+description: 在多个 APISIX 节点间使用 Redis 共享 AI 响应缓存、Token 计数和请求配额。
+method: APISIX 内置插件
+---
+
+Apache APISIX 3.18 可使用 Redis 保存可复用的 LLM 响应、共享 Token 计数和分布式请求配额。这些能力的部署方式与故障处理不同，需要分别配置和运维。
+
+
+ AI 客户端→Apache APISIX↔Redis
+
+
+## APISIX 如何使用 Redis
+
+| 场景 | APISIX 3.18 行为 | 限制与运维说明 |
+|---|---|---|
+| 精确响应缓存 | Redis 保存 HTTP 200 AI 响应的正文。缓存键包含规范化后的请求正文和 Provider 配置。默认 TTL 为 3,600 秒，默认最大响应为 1 MiB。 | 默认缓存键不包含转发 header。应移除客户端可控的 Provider 路由 header；如果其他值也会影响响应，应从可信服务端变量取值，并通过 `cache_key.include_vars` 加入缓存键。APISIX 3.18 的缓存只支持一个 Redis endpoint，不提供请求合并，也不处理上游 `Cache-Control`，没有专用清理 API。命中时会恢复 HTTP 200 与 `Content-Type`，其他上游响应 header 不会回放。 |
+| 语义响应缓存 | 精确缓存未命中后，APISIX 可为纯文本 OpenAI Chat prompt 生成 embedding，并通过 Redis Search 查找相似响应。 | 语义匹配只适用于纯文本 OpenAI Chat。多模态请求和非空 tool/function call 会绕过这一层；精确缓存层始终启用。 |
+| 共享 token 配额 | `ai-rate-limiting` 可把固定窗口计数保存在 Redis 数据库中，使多个 APISIX 节点看到同一份用量。 | 只有模型响应给出 usage 后才记账，并非预付式额度预留；大响应或并发响应可能先越过阈值，后续请求才被拒绝。 |
+| 共享请求配额 | `limit-count` 使用 `policy: redis` 时，会把请求计数保存在 Redis 中，使不同 APISIX 节点共用一份配额。 | 计数键应来自可信状态。插件支持固定窗口和滑动窗口；`sync_interval` 可减少 Redis 往返，但同步间隔内的全局计数会暂时滞后。配套实验尚未测试这条链路。 |
+| 流式缓存 | APISIX 识别到协议终止事件后，可缓存完整、受支持的 SSE 响应。 | 中断的流不会写入缓存；JSON 与 SSE 使用不同条目；命中时会立即回放完整 SSE，不会复现原始 token 节奏。 |
+
+语义缓存需要 Redis Search 命令。配套实验固定使用 Redis Open Source 8.10.1，并检查 `FT._LIST` 是否可用。这个预检只能确认 Redis 环境正常，不能验证 LLM 缓存链路。若使用更早的 Redis Open Source 或 Redis Stack 版本，需要固定并测试具体版本。
+
+## 隔离与安全
+
+缓存默认按 Route 隔离，而不是按 Consumer 隔离。如果多个 Consumer 共用一条 Route，应先把每个租户认证为独立 Consumer，再设置 `cache_key.include_consumer: true`；也可以把可信的服务端租户变量加入缓存键。这个选项不能隔离未认证流量，客户端可伪造的 header 也不能作为租户边界。代理前应移除会改变 Provider 路由或输出的客户端可控 header。其他影响响应的值应来自可信的服务端状态，并通过 `cache_key.include_vars` 加入缓存键。
+
+Redis 凭据应使用 APISIX Secret 引用。Redis 服务应位于私有网络；使用 TLS 时必须校验证书；日志和截图中不要暴露缓存正文、embedding、Provider request ID 或完整 Redis key。
+
+## 失败行为
+
+- 缓存、向量搜索或 embedding 出错时会降级为缓存未命中，APISIX 继续请求 LLM。因此，仅看到 `MISS` header 不能证明 Redis 服务健康。
+- 共享配额的处理方式不同。请求前 Redis 配额检查失败时，`allow_degradation: false` 会返回错误；设为 `true` 时会放行请求，但不再提供配额保护。这个开关只影响请求前检查。如果 Redis 在 access 阶段检查完成后、log 阶段异步写入计数前发生故障，当前响应仍可能成功，Token 用量也可能未写入；应监控写入错误。
+- `limit-count` 的 Redis 依赖发生故障时，也会按 `allow_degradation` 处理。Redis Cluster 和 Sentinel policy 已有官方文档与上游测试，但本文不声称配套实验验证了故障切换。
+- 缓存命中会在 `ai-rate-limiting` 之前直接返回，因此不会调用上游模型，也不会增加 Redis token 计数。
+
+## 可观测性
+
+APISIX Prometheus 插件会导出按 `exact` 或 `semantic` 分层的命中数、未命中数、绕过数和 embedding 延迟直方图。`ai-rate-limiting` 没有专用的 Redis token-counter 指标，应结合响应 header、Redis 状态、APISIX 日志和 Provider usage 进行验证。
+
+## 参考资料
+
+- [APISIX 3.18.0 标签中的 `ai-cache` 源码](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-cache.lua)
+- [`ai-cache` Schema](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-cache/schema.lua)
+- [语义缓存实现](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-cache/semantic.lua)
+- [`ai-rate-limiting` 源码](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/ai-rate-limiting.lua)
+- [`limit-count` 源码](https://github.com/apache/apisix/blob/0796d9c2cbedb1f8bf8194292ff526599f4fde20/apisix/plugins/limit-count.lua)
+- [Redis Search 模块生命周期](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/modules-lifecycle/)
+- [固定版本的双节点 APISIX 与 Redis 实验](https://github.com/apache/apisix-website/tree/master/examples/redis-ai-gateway)
+
+以上行为与 APISIX 3.18.0 源码一致，但运行时测试尚未完成。在记录 Provider 侧 Chat 与 Embedding 调用次数、完整和中断的 SSE 测试结果、两次从空环境开始的运行结果和脱敏日志，由其他人独立复现，并单独验证基于 Redis 的 `limit-count` 请求配额链路前，状态保持“**验证进行中**”。
+
+Redis 是 Redis Ltd. 的注册商标。本社区集成与 Redis Ltd. 无隶属关系，也未获得其认可、支持或认证。
diff --git a/website/static/llms.txt b/website/static/llms.txt
index 1e688d3a79434..227d3ac96a2b2 100644
--- a/website/static/llms.txt
+++ b/website/static/llms.txt
@@ -34,6 +34,16 @@
- [AI Proxy Plugin](https://apisix.apache.org/docs/apisix/plugins/ai-proxy/): Route requests to 20+ LLM providers
- [AI RAG Plugin](https://apisix.apache.org/docs/apisix/plugins/ai-rag/): Retrieval-augmented generation support
+## Integrations & Cookbooks
+
+- [Integration Hub](https://apisix.apache.org/integrations/): How Apache APISIX connects to external products, with version and testing details
+- [Apache APISIX with LocalAI](https://apisix.apache.org/integrations/localai/): Route OpenAI-compatible LocalAI chat traffic through Apache APISIX
+- [Apache APISIX with Redis](https://apisix.apache.org/integrations/redis/): Redis-backed AI response caching, shared token counters, and distributed request quotas
+- [Cookbooks](https://apisix.apache.org/cookbooks/): Step-by-step guides for common Apache APISIX tasks
+- [LocalAI chat completions](https://apisix.apache.org/cookbooks/localai-chat-completions/): Put APISIX in front of a private LocalAI chat endpoint
+- [Redis exact and semantic AI cache](https://apisix.apache.org/cookbooks/redis-ai-cache/): Set up and test exact hits, semantic matches, tenant isolation, and Redis failures
+- [Shared Redis token quota](https://apisix.apache.org/cookbooks/redis-shared-token-quota/): Share an LLM token counter across APISIX nodes with Redis
+
## Observability
- [Prometheus](https://apisix.apache.org/docs/apisix/plugins/prometheus/): Metrics export for monitoring