AI Cache | API 网关文档

参数

请参阅插件通用配置了解所有插件可用的配置选项。

该插件支持使用 env:// 前缀引用环境变量中的敏感参数值，或使用 secret:// 前缀引用 Secret 管理器（如 HashiCorp Vault 的 KV 密钥引擎中的值。更多信息，请参阅环境变量中的插件和Secrets。

exact
object
精确匹配缓存的设置；仅当规范化后的请求与此前缓存的某个请求完全相同时，才复用其响应。
- ttl
  integer
  default: 3600
  vaild vaule:
  大于或等于 1
  缓存条目的存活时间（TTL），单位为秒。
cache_key
object
用于控制缓存键作用范围的设置。
- share_across_routes
  boolean
  default: false
  如果为 true，缓存键不包含路由 ID，因此不同路由上的相同请求可以共享缓存的响应。如果为 false，每个路由拥有各自独立的缓存作用范围。
- include_consumer
  boolean
  default: false
  如果为 true，缓存键中包含消费者名称，因此缓存的响应按消费者隔离。
- include_vars
  array[string]
  default: []
  要纳入缓存键作用范围的额外上下文变量名称，使这些变量取值不同的请求不会共享缓存的响应。
max_cache_body_size
integer
default: 1048576
vaild vaule:
大于或等于 0
允许缓存的响应体最大大小，单位为字节。超过该大小的响应不会被缓存。
cache_headers
boolean
default: true
如果为 true，插件会添加 X-AI-Cache-Status 响应头（缓存命中时还会添加 X-AI-Cache-Age）。设置为 false 可省略这些响应头。
fail_mode
string
default: skip
vaild vaule:
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
  required
  vaild vaule:
  非空
  要匹配的请求头名称。
- equals
  string
  required
  规则匹配时请求头必须等于的值。
policy
string
default: redis
vaild vaule:
redis
缓存存储后端。目前仅支持 redis。
layers
array[string]
default: ["exact"]
vaild vaule:
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
  default: 0.95
  vaild vaule:
  0 到 1 之间（含边界）
  判定为语义缓存命中所需的最小相似度分数。
- top_k
  integer
  default: 1
  vaild vaule:
  大于或等于 1
  要获取的最近向量匹配数量。
- distance_metric
  string
  default: cosine
  vaild vaule:
  cosine
  向量搜索使用的距离度量。
- ttl
  integer
  default: 86400
  vaild vaule:
  大于或等于 1
  语义缓存条目的存活时间，单位为秒。
- match
  object
  控制哪些对话内容会被用于语义匹配 embedding 的设置。
  message_countback
  integer
  default: 1
  vaild vaule:
  大于或等于 1
  用作 embedding 输入的最近 user 消息轮次数量。
  ignore_system_prompts
  boolean
  default: true
  如果为 true，system prompt 会从 embedding 输入中排除。
  ignore_assistant_prompts
  boolean
  default: true
  如果为 true，assistant 消息会从 embedding 输入中排除。
  ignore_tool_prompts
  boolean
  default: true
  如果为 true，tool 消息会从 embedding 输入中排除。
- embedding
  object
  required
  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
  required
  向量搜索后端配置。
  redis
  object
  required
  RediSearch 向量索引设置。
  index
  string
  default: ai-cache
  语义缓存使用的 RediSearch 索引名称。
redis_host
string
required
vaild vaule:
至少 2 个字符
Redis 服务器的地址。当 policy 为 redis 时必填。
redis_port
integer
default: 6379
vaild vaule:
大于或等于 1
Redis 服务器的端口。
redis_username
string
使用 Redis ACL 时用于 Redis 认证的用户名。
redis_password
string
用于 Redis 认证的密码。
redis_database
integer
default: 0
vaild vaule:
大于或等于 0
Redis 服务器的数据库编号。
redis_timeout
integer
default: 1000
vaild vaule:
大于或等于 1
Redis 操作的超时时间，单位为毫秒。
redis_ssl
boolean
default: false
如果为 true，使用 TLS 连接 Redis。
redis_ssl_verify
boolean
default: false
如果为 true，验证 Redis 服务器的 TLS 证书。

参数​

参数