# AI Cache 配置选项

ai-cache 插件将完全匹配和语义相似的 LLM 响应存储在 Redis 中，从而降低响应延迟并减少重复的上游模型调用。<!-- --> <!-- -->配置涵盖插件参数。

## 参数[​](#参数 "参数的直接链接")

有关所有插件均可使用的配置项，请参阅[插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)。

该插件支持在字符串类型的配置字段中使用网关引用。使用 `$env://` 前缀引用环境变量中的值，或使用 `$secret://` 前缀引用密钥管理器中的值，例如 HashiCorp Vault 的 [KV 密钥引擎](https://developer.hashicorp.com/vault/docs/secrets/kv)。网关在运行时解析这些引用。ADC 的 `${NAME}` 插值有所不同：ADC 在同步前加载配置文件时解析插值。有关更多信息，请参阅[插件中的环境变量](https://docs.apiseven.com/apisix/reference/environment-variables.md#plugins)和[密钥](https://docs.apiseven.com/apisix/key-concepts/secrets.md)。

* exact

  object

  ***

  精确匹配缓存的设置；仅当规范化后的请求与此前缓存的某个请求完全相同时，才复用其响应。

  * ttl

    integer

    默认值：`3600`

    有效值：

    大于或等于 1

    ***

    缓存条目的存活时间（TTL），单位为秒。

* cache\_key

  object

  ***

  用于控制缓存键作用范围的设置。

  * share\_across\_routes

    boolean

    默认值：`false`

    ***

    如果为 true，缓存键不包含路由 ID，因此不同路由上的相同请求可以共享缓存的响应。如果为 false，每个路由拥有各自独立的缓存作用范围。

  * include\_consumer

    boolean

    默认值：`false`

    ***

    如果为 true，缓存键中包含消费者名称，因此缓存的响应按消费者隔离。

  * include\_vars

    array\[string]

    默认值：`[]`

    ***

    要纳入缓存键作用范围的额外上下文变量名称，使这些变量取值不同的请求不会共享缓存的响应。

* max\_cache\_body\_size

  integer

  默认值：`1048576`

  有效值：

  大于或等于 0

  ***

  允许缓存的响应体最大大小，单位为字节。超过该大小的响应不会被缓存。

* cache\_headers

  boolean

  默认值：`true`

  ***

  如果为 true，插件会添加 `X-AI-Cache-Status` 响应头（缓存命中时还会添加 `X-AI-Cache-Age`）。设置为 false 可省略这些响应头。

* fail\_mode

  string

  默认值：`skip`

  有效值：

  `skip`、`warn` 或 `error`

  ***

  当请求因未选中任何 AI 实例而无法缓存时（例如路由未同时配置 `ai-proxy` 或 `ai-proxy-multi`）的行为。取值为 `skip` 时，请求将不经检查直接放行。取值为 `warn` 时，请求将放行并记录一条警告日志。取值为 `error` 时，请求将以 HTTP 500 被拒绝。

* bypass\_on

  array\[object]

  ***

  一组请求头匹配规则。如果某个请求匹配任意一条规则，则绕过缓存，并将响应的 `X-AI-Cache-Status` 标记为 `BYPASS`。

  * header

    string

    必填

    有效值：

    非空

    ***

    要匹配的请求头名称。

  * equals

    string

    必填

    ***

    规则匹配时请求头必须等于的值。

* policy

  string

  默认值：`redis`

  有效值：

  `redis`

  ***

  缓存存储后端。目前仅支持 `redis`。即使网关 Lua schema 定义了此默认值，API7 控制面 API 仍要求显式配置 `policy`。

* layers

  array\[string]

  默认值：`["exact"]`

  有效值：

  `exact`，或同时使用 `exact` 和 `semantic`

  ***

  要启用的缓存层。`exact` 必须保留。添加 `semantic` 后，插件会在精确匹配未命中时通过向量嵌入和向量搜索查找相似提示词。

  语义缓存自 API7 企业版 3.9.16 和 3.10.3 以及 APISIX 3.18.0 起可用。

* semantic

  object

  ***

  语义缓存设置。当 `layers` 包含 `semantic` 时必填。

  自 API7 企业版 3.9.16 和 3.10.3 以及 APISIX 3.18.0 起可用。

  * similarity\_threshold

    number

    默认值：`0.95`

    有效值：

    介于 0 和 1 之间（含边界值）

    ***

    判定为语义缓存命中所需的最小相似度分数。

  * top\_k

    integer

    默认值：`1`

    有效值：

    大于或等于 1

    ***

    要获取的最近向量匹配数量。

  * distance\_metric

    string

    默认值：`cosine`

    有效值：

    `cosine`

    ***

    向量搜索使用的距离度量。

  * ttl

    integer

    默认值：`86400`

    有效值：

    大于或等于 1

    ***

    语义缓存条目的存活时间，单位为秒。

  * match

    object

    ***

    控制哪些对话内容会被用于生成语义匹配向量嵌入的设置。

    * message\_countback

      integer

      默认值：`1`

      有效值：

      大于或等于 1

      ***

      用作向量嵌入输入的最近的 `user` 消息轮数。

    * ignore\_system\_prompts

      boolean

      默认值：`true`

      ***

      如果为 true，系统提示词会从向量嵌入输入中排除。

    * ignore\_assistant\_prompts

      boolean

      默认值：`true`

      ***

      如果为 true，`assistant` 消息会从向量嵌入输入中排除。

    * ignore\_tool\_prompts

      boolean

      默认值：`true`

      ***

      如果为 true，`tool` 消息会从向量嵌入输入中排除。

  * embedding

    object

    必填

    ***

    向量嵌入服务提供方配置。只能配置 `openai` 或 `azure_openai` 之一。

    * openai

      object

      ***

      OpenAI 兼容的向量嵌入服务提供方设置。需要 `model` 和 `api_key`。

      * endpoint

        string

        ***

        OpenAI 兼容的向量嵌入 API 端点。未配置时使用公开 OpenAI 向量嵌入端点。

      * model

        string

        必填

        ***

        向量嵌入模型名称，例如 `text-embedding-3-small`。

      * api\_key

        string

        必填

        ***

        用于对向量嵌入服务提供方进行身份认证的 API Key。该值在存储到 etcd 前会使用 AES 加密。

      * dimensions

        integer

        有效值：

        大于或等于 1

        ***

        向量嵌入输出的维度数。仅对支持覆盖输出维度的模型配置此项。

      * ssl\_verify

        boolean

        默认值：`true`

        ***

        如果为 true，验证向量嵌入服务提供方的 TLS 证书。

      * timeout

        integer

        默认值：`5000`

        有效值：

        大于或等于 1

        ***

        向该向量嵌入服务提供方发送请求的超时时间，单位为毫秒。

    * azure\_openai

      object

      ***

      Azure OpenAI 向量嵌入服务提供方设置。需要 `endpoint` 和 `api_key`。

      * endpoint

        string

        必填

        ***

        Azure OpenAI 向量嵌入端点。

      * api\_key

        string

        必填

        ***

        用于向 Azure OpenAI 进行身份认证的 API Key。该值在存储到 etcd 前会使用 AES 加密。

      * dimensions

        integer

        有效值：

        大于或等于 1

        ***

        向量嵌入输出的维度数。仅对支持覆盖输出维度的模型配置此项。

      * ssl\_verify

        boolean

        默认值：`true`

        ***

        如果为 true，验证 Azure OpenAI 端点的 TLS 证书。

      * timeout

        integer

        默认值：`5000`

        有效值：

        大于或等于 1

        ***

        向 Azure OpenAI 发送请求的超时时间，单位为毫秒。

  * vector\_search

    object

    必填

    ***

    向量搜索后端配置。

    * redis

      object

      必填

      ***

      Redis Search 向量索引设置。

      * index

        string

        默认值：`ai-cache`

        ***

        语义缓存使用的 Redis Search 索引名称。

* redis\_host

  string

  必填

  有效值：

  至少 2 个字符

  ***

  Redis 服务器的地址。当 `policy` 为 `redis` 时必填。

* redis\_port

  integer

  默认值：`6379`

  有效值：

  大于或等于 1

  ***

  Redis 服务器的端口。

* redis\_username

  string

  ***

  使用 Redis ACL 时用于 Redis 认证的用户名。

* redis\_password

  string

  ***

  用于 Redis 认证的密码。

  在 API7 网关 3.10.x 系列的 3.10.2 及更高版本，以及 3.9.x 系列的 3.9.16 及更高版本中，该值在保存到数据库前会使用 AES256 加密。

  在 APISIX 3.18.0 及更高版本中，该值在存储到 etcd 前会使用 AES 加密。

* redis\_database

  integer

  默认值：`0`

  有效值：

  大于或等于 0

  ***

  Redis 服务器的数据库编号。

* redis\_timeout

  integer

  默认值：`1000`

  有效值：

  大于或等于 1

  ***

  Redis 操作的超时时间，单位为毫秒。

* redis\_ssl

  boolean

  默认值：`false`

  ***

  如果为 true，使用 TLS 连接 Redis。

* redis\_ssl\_verify

  boolean

  默认值：`false`

  ***

  如果为 true，验证 Redis 服务器的 TLS 证书。

* redis\_server\_name

  string

  ***

  用于 SNI 的 TLS 服务器名称；启用证书验证时，该名称也用于主机名验证。当 `redis_ssl` 为 `true` 时适用。默认使用 `redis_host`。如果所选值为 IP 地址，则不发送服务器名称。通过 IP 地址连接但需要验证以 DNS 名称签发的证书时，请将该字段设置为证书的 DNS 名称并启用 `redis_ssl_verify`。

  引入于 API7 企业版 3.9.21、3.10.8 和 APISIX 3.19.0。该字段仅适用于单节点 Redis 连接器，不适用于 Redis Cluster 或 Sentinel。

* redis\_keepalive\_timeout

  integer

  默认值：`10000`

  有效值：

  大于或等于 1000

  ***

  Redis 连接池的保活超时时间，单位为毫秒。自 API7 企业版 3.9.x 系列的 3.9.17 版本、3.10.x 系列的 3.10.4 版本以及 APISIX 3.18.0 起可用。

* redis\_keepalive\_pool

  integer

  默认值：`100`

  有效值：

  大于或等于 1

  ***

  Redis 连接的保活连接池大小。自 API7 企业版 3.9.x 系列的 3.9.17 版本、3.10.x 系列的 3.10.4 版本以及 APISIX 3.18.0 起可用。
