跳到主要内容

参数​

有关所有插件均可使用的配置项，请参阅插件通用配置。

该插件支持使用 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 后，插件会在精确匹配未命中时通过向量嵌入和向量搜索查找相似提示词。

    语义缓存自 API7 企业版 3.9.16 或 3.10.3 起可用。

  • semantic

    object

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

    自 API7 企业版 3.9.16 或 3.10.3 起可用。

    • 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

        必填

        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 证书。

  • redis_keepalive_timeout

    integer

    默认值：10000

    有效值：

    大于或等于 1000

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

  • redis_keepalive_pool

    integer

    默认值：100

    有效值：

    大于或等于 1

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