# AI Proxy Multi 配置选项

ai-proxy-multi 插件在 OpenAI、DeepSeek 及其他兼容 API 之间分发 AI 请求，并提供负载均衡、重试、故障回退和健康检查。<!-- --> <!-- -->配置涵盖静态设置和插件参数。

## 静态配置[​](#静态配置 "静态配置的直接链接")

APISIX 默认使用 `ngx_http_ffi_client` 处理 `ai-proxy`、`ai-proxy-multi` 和 `ai-request-rewrite` 发起的上游请求。如需改用 Lua 客户端，请将 `http_client` 设置为 `lua-resty-http`。此配置项自 APISIX 3.18.0 起可用。API7 网关 3.9 和 3.10 使用 Lua 客户端，且不提供此配置项。

* Host or Docker
* Kubernetes (Helm)

在主机或 Docker 部署的 APISIX 中使用 Lua 客户端，请配置以下设置：

config.yaml

```
plugin_attr:

  ai-proxy:

    http_client: lua-resty-http
```

然后重新加载 APISIX，使更改生效。

导出已安装 APISIX release 的完整生效 values：

```
helm get values <release-name> -n <namespace> --all -o yaml > values.yaml
```

新增或更新以下值：

values.yaml

```
apisix:

  pluginAttrs:

    ai-proxy:

      http_client: lua-resty-http
```

然后使用当前 APISIX release 对应的 Chart 应用该 values 文件：

```
helm upgrade <release-name> apisix/apisix -n <namespace> -f values.yaml
```

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

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

* fallback\_strategy

  string or array

  有效值：

  字符串：`instance_health_and_rate_limiting`、`http_429` 或 `http_5xx`

  <br />

  数组：`rate_limiting`、`http_429` 和 `http_5xx` 的任意组合

  ***

  回退策略。选项 `instance_health_and_rate_limiting` 是为向后兼容保留的，功能上与 `rate_limiting` 相同。

  当设置为 `rate_limiting` 或 `instance_health_and_rate_limiting` 时，如果当前实例的配额已用完，请求将转发到下一个实例（无论优先级如何）。当设置为 `http_429` 时，如果某个实例返回状态码 429，则请求会在其他实例上重试。当设置为 `http_5xx` 时，如果某个实例返回 5xx 状态码，则请求会在其他实例上重试。如果所有实例都失败，插件将返回最后一个上游状态码、响应体和 `Content-Type`。

  当未设置时，如果高优先级实例的 Token 用尽，插件不会将请求转发到低优先级实例。

* max\_retries

  integer

  有效值：

  大于或等于 0

  ***

  初始请求失败后的最大回退重试次数。该配置限制由 `fallback_strategy` 或 `fallback_http_statuses` 触发的重试次数，避免单个请求耗尽所有已配置的实例。当未设置时，没有明确上限，插件会一直重试，直到某个实例成功或所有实例都已尝试。引入于 API7 企业版 3.9.14 和 APISIX 3.17.0。

* retry\_on\_failure\_within\_ms

  integer

  有效值：

  大于或等于 1

  ***

  只有当失败尝试在此毫秒数内完成，且其状态符合 `fallback_strategy` 或 `fallback_http_statuses` 的重试条件时，才回退到另一个实例。耗时更长的失败会直接返回给客户端，以免总等待时间翻倍。该配置限制的是每次失败尝试，而不是请求总时长。未设置时，重试不受已用时间限制。引入于 API7 企业版 3.9.14 和 APISIX 3.17.0。

* fallback\_http\_statuses

  array\[integer]

  有效值：

  每项介于 400 与 599 之间，且不重复

  ***

  触发在另一个实例上重试的上游 HTTP 状态码。该列表可独立于 `fallback_strategy` 工作，也可以补充其中的 `http_429` 和 `http_5xx`。重试次数和每次尝试的时间限制仍然适用。

  请选择能够表示实例自身问题的状态码，例如服务提供方凭据已过期。不要重试所有 4xx 响应；无效的客户端请求通常会在每个实例上失败。

  引入于 API7 企业版 3.9.19、3.10.6 和 APISIX 3.19.0。

* balancer

  object

  ***

  负载均衡配置。

  * algorithm

    string

    默认值：`roundrobin`

    有效值：

    `roundrobin`、`chash` 或 `semantic`

    ***

    负载均衡算法。设置为 `roundrobin` 时，使用加权轮询算法。设置为 `chash` 时，使用一致性哈希算法。设置为 `semantic` 时，选择 `examples` 与提示词语义最接近的实例，相关配置位于 `semantic_opts` 下。

    启用语义选择时，不会使用已配置的健康检查设置，且发生上游失败后不会重试。因此，`fallback_strategy`、`fallback_http_statuses` 和 `max_retries` 不会影响语义选择。所选实例的上游失败会直接返回给客户端。没有实例达到各自生效的阈值、缺少用户提示词、向量嵌入处理失败或向量维度不匹配时，语义选择会使用回退实例。

    `semantic` 自 API7 企业版 3.9.x 系列的 3.9.18 版本起可用，3.10.x 系列自 3.10.5 版本起可用；在 APISIX 中自 3.18.0 版本起可用。

  * hash\_on

    string

    默认值：`vars`

    有效值：

    `vars`、`header`、`cookie`、`consumer` 或 `vars_combinations`

    ***

    当 `balancer.algorithm` 为 `chash` 时使用。支持基于[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)、请求头、Cookie、消费者或[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)的组合进行哈希。

  * key

    string

    ***

    当 `balancer.algorithm` 为 `chash` 时使用。当 `hash_on` 设置为 `header` 或 `cookie` 时，`key` 为必填。当 `hash_on` 设置为 `consumer` 时，`key` 不是必需的，因为消费者名称将自动用作键。

* semantic\_opts

  object

  ***

  `semantic` 负载均衡算法的配置。当 `balancer.algorithm` 为 `semantic` 时必填，其它情况下会被忽略。

  自 API7 企业版 3.9.x 系列的 3.9.18 版本起可用，3.10.x 系列自 3.10.5 版本起可用；在 APISIX 中自 3.18.0 版本起可用。

  * embeddings

    object

    必填

    ***

    用于把提示词和各实例的 `examples` 转换为向量的嵌入服务。每次请求都会对提示词做嵌入，因此该服务位于请求路径上。

    * provider

      string

      必填

      有效值：

      `openai` 或 `azure-openai`

      ***

      嵌入服务提供商。

    * model

      string

      必填

      ***

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

    * endpoint

      string

      ***

      嵌入 API 端点。对 `openai` 为可选，默认使用其公共 API；对 `azure-openai` 为必填，且必须是完整 URL，例如 `https://{resource}.openai.azure.com/openai/deployments/{deployment}/embeddings?api-version={version}`。

    * auth

      object

      必填

      ***

      嵌入服务的认证信息，通过请求头或查询参数携带。

      * header

        object

        ***

        以请求头形式发送给嵌入服务的键值对。

      * query

        object

        ***

        以查询参数形式发送给嵌入服务的键值对。

    * timeout

      integer

      默认值：`3000`

      有效值：

      大于或等于 1

      ***

      嵌入请求的超时时间，单位为毫秒。由于提示词是同步嵌入的，该值决定了嵌入服务变慢时每个请求最多额外增加的延迟。超时后请求会被路由到 fallback 实例，而不是直接失败。

    * ssl\_verify

      boolean

      默认值：`true`

      ***

      如果为 true，则校验嵌入服务的 TLS 证书。

  * threshold

    number

    默认值：`0`

    有效值：

    -1 到 1 之间（含）

    ***

    选择实例所需的全局最低余弦相似度。实例自身的 `threshold` 会覆盖该值。分数必须大于或等于实际生效的阈值。默认值 `0` 接受非负分数；`-1` 接受余弦相似度的整个取值范围。如果没有实例达到各自生效的阈值，则使用回退实例。缺少用户提示词、向量嵌入失败或维度不匹配时，任何阈值下都会使用回退实例。

  * fallback

    string

    ***

    当没有实例达到阈值或嵌入请求失败时，请求路由到的实例名称。该实例同样参与正常排名，因此也需要配置自己的 `examples`。未设置时默认使用第一个实例。

  * debugging

    boolean

    默认值：`false`

    ***

    如果为 true，则通过 `X-AI-Semantic-Scores` 和 `X-AI-Semantic-Picked-Instance` 响应头返回各实例的相似度得分与路由结果。该选项用于调优 `examples` 和阈值，不建议在生产流量上开启。

* instances

  array\[object]

  必填

  ***

  LLM 实例配置。

  * name

    string

    必填

    ***

    LLM 服务实例的名称。整个 `instances` 数组中的名称必须唯一，包括优先级不同的实例。API7 企业版 3.9.19、3.10.6 和 APISIX 3.19.0 的配置校验会拒绝重复名称。重命名实例时，请根据实际配置更新 `ai-rate-limiting.instances` 和 `semantic_opts.fallback` 中的引用。

  * examples

    array\[string]

    有效值：

    1 到 64 个元素

    ***

    用于表示该实例所处理意图的示例语句。每条示例会被嵌入为各自的参考向量，语义负载均衡算法会把请求路由到示例与提示词最相似的那个实例。

    当 `balancer.algorithm` 为 `semantic` 时，每个实例都必须配置该字段，包括 `semantic_opts.fallback` 指定的实例；其它算法会忽略该字段。

    自 API7 企业版 3.9.x 系列的 3.9.18 版本起可用，3.10.x 系列自 3.10.5 版本起可用；在 APISIX 中自 3.18.0 版本起可用。

  * threshold

    number

    有效值：

    -1 到 1 之间（含）

    ***

    语义负载均衡算法选中该实例所需的最小余弦相似度。该值会针对该实例覆盖 `semantic_opts.threshold`。

    自 API7 企业版 3.9.x 系列的 3.9.18 版本起可用，3.10.x 系列自 3.10.5 版本起可用；在 APISIX 中自 3.18.0 版本起可用。

  * provider

    string

    必填

    有效值：

    `openai`、`deepseek`、`azure-openai`、`aimlapi`、`gemini`、`vertex-ai`、`anthropic`、`openrouter`、`bedrock`、`openai-compatible`

    ***

    LLM 模型服务提供方。

    当设置为 `openai` 时，插件会将检测到的 Chat Completions、Responses API 和 Embeddings 请求发送到对应的 OpenAI 端点。

    当设置为 `deepseek` 时，插件会将请求代理到 `https://api.deepseek.com/chat/completions`。

    当设置为 `gemini`（自 APISIX 3.15.0 和 API7 企业版 3.9.2 起可用）时，插件会将请求代理到 `https://generativelanguage.googleapis.com/v1beta/openai/chat/completions`。如果要将请求代理到向量嵌入模型，应在 `override` 中配置向量嵌入模型端点。

    当设置为 `vertex-ai`（自 APISIX 3.15.0 和 API7 企业版 3.9.2 起可用）时，插件会将请求代理到 Google Cloud Vertex AI。对于聊天补全，插件会将请求代理到 `https://{region}-aiplatform.googleapis.com/v1beta1/projects/{project_id}/locations/{region}/endpoints/openapi/chat/completions`。对于向量嵌入，插件会将请求代理到 `https://{region}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{region}/publishers/google/models/{model}:predict`。这些端点要求在 `provider_conf` 中配置 `project_id` 和 `region`；也可以配置 `override` 使用自定义端点。

    当设置为 `anthropic`（自 APISIX 3.15.0 和 API7 企业版 3.9.2 起可用）时，插件会将检测到的 Chat Completions 请求发送到 `https://api.anthropic.com/v1/chat/completions`，并将原生 Anthropic Messages 请求发送到 `https://api.anthropic.com/v1/messages`。

    当设置为 `openrouter`（自 APISIX 3.15.0 和 API7 企业版 3.9.2 起可用）时，插件会将请求代理到 `https://openrouter.ai/api/v1/chat/completions`。

    当设置为 `bedrock`（自 API7 企业版 3.9.12 和 APISIX 3.17.0 起可用）时，插件使用 Converse API 将请求代理到 AWS Bedrock。

    当设置为 `aimlapi`（自 APISIX 3.14.0 和 API7 企业版 3.8.17 起可用）时，插件使用 OpenAI 兼容驱动并将请求代理到 `https://api.aimlapi.com/v1/chat/completions`。

    当设置为 `openai-compatible` 时，插件会将请求代理到 `override` 中配置的自定义端点。

    当设置为 `azure-openai` 时，插件同样会将请求代理到 `override` 中配置的自定义端点，并从用户请求中移除 `model` 参数。

  * priority

    integer

    默认值：`0`

    ***

    负载均衡中 LLM 实例的优先级。`priority` 优先于 `weight`。

  * weight

    integer

    必填

    有效值：

    大于或等于 0

    ***

    负载均衡中 LLM 实例的权重。

  * auth

    object

    必填

    ***

    认证配置。

    * header

      object

      ***

      认证请求头。`header` 和 `query` 至少需配置其中之一。你可以配置额外的自定义请求头，这些请求头将被转发到上游 LLM 服务。

    * query

      object

      ***

      认证查询参数。`header` 和 `query` 至少需配置其中之一。

    * gcp

      object

      ***

      Vertex AI 的 GCP 服务账号认证。自 API7 企业版 3.9.2 和 APISIX 3.17.0 起可用。

      * service\_account\_json

        string

        ***

        用于认证的 GCP 服务账号 JSON 内容。可以通过此参数配置，或通过设置 `GCP_SERVICE_ACCOUNT` 环境变量配置。

      * max\_ttl

        integer

        ***

        GCP 访问 Token 缓存的最大 TTL，单位为秒。

      * expire\_early\_secs

        integer

        默认值：`60`

        ***

        访问 Token 在其实际过期时间之前提前过期的时间（秒）。这可以防止在活跃请求期间 Token 过期的边缘情况。

    * aws

      object

      ***

      AWS IAM 凭证，用于 SigV4 签名。当 `provider` 为 `bedrock` 时必填（对于 Bedrock，`auth.aws` 即可满足认证需求，无需配置 `auth.header`/`auth.query`）。自 API7 企业版 3.9.12 和 APISIX 3.17.0 起可用。

      * access\_key\_id

        string

        必填

        ***

        AWS IAM Access Key ID。

      * secret\_access\_key

        string

        必填

        ***

        AWS IAM Secret Access Key。

      * session\_token

        string

        ***

        临时凭证（例如来自 STS AssumeRole）的 AWS 会话 Token。

  * options

    object

    ***

    模型配置。

    除了 `model`，你还可以配置其他参数，这些参数将在请求体中转发到上游 LLM 服务。例如，如果你使用 OpenAI 或 DeepSeek，可以配置其他参数，如 `max_tokens`、`temperature`、`top_p` 和 `stream`。有关更多可用选项，请参阅你的模型服务提供方的 API 文档。

    * model

      string

      ***

      LLM 模型的名称，例如 `gpt-4` 或 `gpt-3.5`。有关更多可用模型，请参阅你的模型服务提供方的 API 文档。

  * provider\_conf

    object

    ***

    服务提供方专属配置。当 `provider` 为 `bedrock` 时必填；当 `provider` 为 `vertex-ai` 时，需配置 `provider_conf` 或 `override.endpoint`。

    自 API7 企业版 3.9.2 和 APISIX 3.17.0 起可用。

    * project\_id

      string

      ***

      Vertex AI 的 Google Cloud 项目 ID。

    * region

      string

      必填

      ***

      云区域。对于 `vertex-ai`，这是 GCP 区域；对于 `bedrock`，这是 AWS 区域（例如 `us-east-1`）。

  * override

    object

    ***

    覆盖设置。

    * endpoint

      string

      ***

      端点覆盖。如果该值只包含协议和主机，插件会追加根据此实例的服务提供方及检测到的请求协议选择的路径。如果该值包含路径或查询参数，插件会直接使用这些值。

      当 `provider` 为 `openai-compatible` 或 `azure-openai` 时必填。

      对于其他服务提供方，省略该字段时，插件会根据此实例的 `provider`、检测到的请求协议以及适用的 `provider_conf` 推导端点，不会使用路由或服务上配置的上游。

    * llm\_options

      object

      ***

      面向服务提供方的 LLM 选项覆盖。自 API7 企业版 3.9.10 和 APISIX 3.17.0 起可用。

      * max\_tokens

        integer

        ***

        输出 Token 的最大数量。网关会根据目标服务提供方自动映射到正确的字段名，例如 OpenAI Chat 使用 `max_completion_tokens`，OpenAI Responses API 使用 `max_output_tokens`，并覆盖客户端传入的值。

    * request\_body

      object

      ***

      按目标协议覆盖请求体。键可以是 `openai-chat`、`openai-responses`、`openai-embeddings`、`anthropic-messages`、`bedrock-converse` 和 `passthrough` 等目标协议名称。值是会深度合并到发送请求体中的部分请求体。自 API7 企业版 3.9.10 和 APISIX 3.17.0 起可用。

    * request\_body\_force\_override

      boolean

      默认值：`false`

      ***

      为 `false`（默认值）时，客户端请求体字段优先，`request_body` 只填充缺失字段。为 `true` 时，`request_body` 中的值会覆盖客户端字段。自 API7 企业版 3.9.10 和 APISIX 3.17.0 起可用。

  * checks

    object

    ***

    此实例的健康检查配置。这些检查独立于路由或服务上所配置上游的健康检查。

    仅当至少配置两个实例时，`roundrobin` 和 `chash` 负载均衡器才会使用实例健康检查。只有一个实例时，插件会向该实例发送请求，但不会启动其主动健康检查。`semantic` 负载均衡器不使用实例健康检查。

    请注意，目前 OpenAI 和 DeepSeek 没有提供官方的健康检查端点。你在 `openai-compatible` 服务提供方下配置的其他 LLM 服务可能有可用的健康检查端点。

    * active

      object

      必填

      ***

      主动健康检查配置。

      * type

        string

        默认值：`http`

        有效值：

        `http`、`https` 或 `tcp`

        ***

        健康检查连接类型。

      * timeout

        number

        默认值：`1`

        ***

        健康检查超时时间，单位为秒。

      * concurrency

        integer

        默认值：`10`

        ***

        同时检查的上游节点数量。

      * host

        string

        ***

        HTTP 主机。

      * port

        integer

        有效值：

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

        ***

        HTTP 端口。

      * http\_path

        string

        默认值：`/`

        ***

        HTTP 探测请求的路径。

      * http\_method

        string

        默认值：`GET`

        有效值：

        `CONNECT`、`DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST`、`PURGE`、`PUT` 或 `TRACE`

        ***

        主动健康检查探测请求的 HTTP 方法。在 API7 企业版以及 APISIX 3.18.0 及更高版本中可用。

      * http\_req\_body

        string

        ***

        主动健康检查探测请求中发送的请求体。当 `http_method` 设置为 `POST` 时非常有用。默认为空字符串。在 API7 企业版以及 APISIX 3.18.0 及更高版本中可用。

      * https\_verify\_certificate

        boolean

        默认值：`true`

        ***

        如果为 true，则验证节点的 TLS 证书。

      * healthy

        object

        ***

        健康节点配置。

        * interval

          integer

          默认值：`1`

          ***

          检查健康节点的时间间隔，单位为秒。

        * http\_statuses

          array\[integer]

          默认值：`[200,302]`

          有效值：

          介于 200 和 599 之间的状态码（含边界值）

          ***

          定义健康节点的 HTTP 状态码数组。

        * successes

          integer

          默认值：`2`

          有效值：

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

          ***

          定义健康节点所需的成功探测次数。

      * req\_headers

        array\[string]

        ***

        健康检查探测请求中发送的额外 HTTP 头列表，格式为 `"Header: Value"`。

      * unhealthy

        object

        ***

        不健康节点配置。

        * interval

          integer

          默认值：`1`

          ***

          检查不健康节点的时间间隔，单位为秒。

        * http\_statuses

          array\[integer]

          默认值：`[429,404,500,501,502,503,504,505]`

          有效值：

          介于 200 和 599 之间的状态码（含边界值）

          ***

          定义不健康节点的 HTTP 状态码数组。

        * http\_failures

          integer

          默认值：`5`

          有效值：

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

          ***

          定义不健康节点所需的 HTTP 失败次数。

        * tcp\_failures

          integer

          默认值：`2`

          有效值：

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

          ***

          定义不健康节点所需的 TCP 失败次数。

        * timeouts

          integer

          默认值：`3`

          有效值：

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

          ***

          定义不健康节点所需的探测超时次数。

* logging

  object

  ***

  日志配置。该配置适用于访问日志和发送到日志插件的日志，不影响错误日志。

  * summaries

    boolean

    默认值：`false`

    ***

    如果为 true，则向日志条目添加 `llm_summary` 对象，其中包含模型、延迟和 Token 用量。在 API7 企业版 3.9.16、3.10.2 以及 APISIX 3.18.0 中，可用时该摘要还包含流状态、工具数量及使用情况、最终用户 ID、缓存读取与创建 Token 数、推理 Token 数和内容风险级别。

  * payloads

    boolean

    默认值：`false`

    ***

    如果为 true，则记录请求和响应的负载。

* timeout

  integer

  默认值：`30000`

  有效值：

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

  ***

  对 LLM 服务进行每次连接、发送或阻塞读取操作的超时时间，单位为毫秒。该配置不限制流式响应的总持续时间；如需限制总持续时间，请使用 `max_stream_duration_ms`。

* max\_req\_body\_size

  integer

  默认值：`67108864`

  有效值：

  大于或等于 1

  ***

  插件读入内存的最大请求体大小，单位为字节。超过该大小的请求将以 HTTP 413 拒绝。该配置可防止大请求体导致的无限内存缓冲。默认值为 67108864 字节（64 MiB）。自 API7 企业版 3.9.x 版本线的 3.9.14、3.10.x 版本线的 3.10.1，以及 APISIX 3.17.0 起可用。

* max\_stream\_duration\_ms

  integer

  有效值：

  大于或等于 1

  ***

  流式 AI 响应允许占用的最长实际时间（毫秒）。该限制为可选配置。达到限制时，网关会关闭连接；若已开始输出，响应流会直接结束，不会附带 `[DONE]`、`message_stop` 或 `response.completed` 等协议终止标记。限制在两次上游读取之间执行，因此最后一个数据块可能超过配置的时长。自 API7 企业版 3.9.10 和 APISIX 3.17.0 起可用。

* max\_response\_bytes

  integer

  有效值：

  大于或等于 1

  ***

  单个流式或非流式 AI 响应从上游读取的最大总字节数。该限制为可选配置，并在两次上游读取之间检查，因此最后一个数据块可能超过限制。如果输出开始前超过限制，网关返回 `502 Bad Gateway`；输出开始后超过限制，网关直接关闭响应流且不发送协议终止标记。自 API7 企业版 3.9.10 和 APISIX 3.17.0 起可用。

* streaming\_flush\_interval\_ms

  integer

  默认值：`10`

  有效值：

  大于或等于 0

  ***

  流式响应的后台刷新间隔，单位为毫秒。正值会定期刷新缓冲输出，以便在上游突发发送 Token 时限制客户端延迟。设置为 0 时同步刷新每个数据块。自 API7 企业版 3.9.13 和 APISIX 3.17.0 起可用。

* keepalive

  boolean

  默认值：`true`

  ***

  如果为 true，则在请求 LLM 服务时保持连接活跃。

* keepalive\_timeout

  integer

  默认值：`60000`

  有效值：

  大于或等于 1000

  ***

  请求 LLM 服务时的 Keepalive 超时时间（毫秒）。

* keepalive\_pool

  integer

  默认值：`30`

  有效值：

  大于或等于 1

  ***

  连接 LLM 服务时的 Keepalive 连接池大小。

* ssl\_verify

  boolean

  默认值：`true`

  ***

  如果为 true，则验证 LLM 服务的证书。
