参数
有关所有插件均可使用的配置项，请参阅插件通用配置。
该插件支持使用 env:// 前 缀从环境变量引用敏感参数值，也支持使用 secret:// 前缀从密钥管理器（例如 HashiCorp Vault 的 KV 密钥引擎）引用敏感参数值。有关更多信息，请参阅插件中的环境变量和密钥。
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。layers
array[string]
默认值：
["exact"]有效值：
exact，或同时使用exact和semantic要启用的缓存层。
exact必须保留。添加semantic后，插件会在精确匹配未命中时通过 embedding 和向量搜索查找相似提示词。语义缓存自 API7 企业版 3.9.x 系列的 3.9.16 版本起可用。
semantic
object
语义缓存设置。当
layers包含semantic时必填。自 API7 企业版 3.9.x 系列的 3.9.16 版本起可用。
similarity_threshold
number
默认值：
0.95有效值：
介于 0 和 1 之间（含边界值）
判定为语义缓存命中所需的最小相似度分数。
top_k
integer
默认值：
1有效值：
大于或等于 1
要获取的最近向量匹配数量。
distance_metric
string
默认值：
cosine有效值：
cosine向量搜索使用的距离度量。
ttl
integer
默认值：
86400有效值：
大于或等于 1
语义缓存条目的存活时间，单位为秒。
match
object
控制哪些对话内容会被用于语义匹配 embedding 的设置。
message_countback
integer
默认值：
1有效值：
大于或等于 1
用作 embedding 输入的最近 user 消息轮次数量。
ignore_system_prompts
boolean
默认值：
true如果为 true，system prompt 会从 embedding 输入中排除。
ignore_assistant_prompts
boolean
默认值：
true如果为 true，assistant 消息会从 embedding 输入中排除。
ignore_tool_prompts
boolean
默认值：
true如果为 true，tool 消息会从 embedding 输入中排除。
embedding
object
必填
Embedding provider 配置。只能配置
openai或azure_openai之一。openai
object
OpenAI 兼容 embedding provider 设置。需要
model和api_key。azure_openai
object
Azure OpenAI embedding provider 设置。需要
endpoint和api_key。
vector_search
object
必填
向量搜索后端配置。
redis
object
必填
RediSearch 向量索引设置。
index
string
默认值：
ai-cache语义缓存使用的 RediSearch 索引名称。
redis_host
string
必填
有效值：
至少 2 个字符
Redis 服务器的地址。当
policy为redis时必填。redis_port
integer
默认值：
6379有效值：
大于或等于 1
Redis 服务器的端口。
redis_username
string
使用 Redis ACL 时用于 Redis 认证的用户名。
redis_password
string
用于 Redis 认证的密码。
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 证书。