参数
有关所有插件均可使用的配置项，请参阅插件通用配置。
fallback_strategy
string or array
有效值：
字符串：
instance_health_and_rate_limiting、http_429或http_5xx
数组：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 状态码，则请求会与其他实例重试。如果所有实例都失败，插件将返回最后一个错误响应码。当未设置时，如果高优先级实例的 Token 用尽，插件不会将请求转发到低优先级实例。
max_retries
integer
有效值：
大于或等于 0
初始请求失败后的最大回退重试次数。该配置限制单个请求最多尝试多少个额外实例，避免耗尽所有已配置的实例。仅在与
fallback_strategy一起使用时生效。当未设置时，没有明确上限，插件会一直重试，直到某个实例成功或所有实例都已尝试。自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。retry_on_failure_within_ms
integer
有效值：
大于或等于 1
仅当上游在此毫秒数内失败时才回退到另一个实例。快速失败（例如连接错误以及快速返回的 429 或 5xx 响应）会被重试，而耗时超过该值的慢速失败会直接返回给客户端，以避免总等待时间翻倍。仅在与
fallback_strategy一起使用时生效。当未设置时，无论失败尝试耗时多久，插件都会重试。自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。balancer
object
负载均衡配置。
algorithm
string
默认值：
roundrobin有效值：
roundrobin或chash负载均衡算法。设置为
roundrobin时，使用加权轮询算法。设置为chash时，使用一致性哈希算法。key
string
当
type为chash时使用。当hash_on设置为header或cookie时，key为必填。当hash_on设置为consumer时，key不是必需的，因为消费者名称将自动用作键。
instances
array[object]
必填
LLM 实例配置。
name
string
必填
LLM 服务实例的名称。
provider
string
必填
有效值：
openai、deepseek、azure-openai、aimlapi、gemini、vertex-ai、anthropic、openrouter、bedrock、openai-compatible模型服务提供方。
当设置为
openai时，插件会将请求代理到https://api.openai.com/v1/chat/completions。当设置为
deepseek时，插件会将请求代理到https://api.deepseek.com/chat/completions。当设置为
gemini（自 APISIX 3.15.0 和企业版 3.9.2 起可用）时，插件会将请求代理到https://generativelanguage.googleapis.com/v1beta/openai/chat/completions。如果要将请求代理到向量嵌入模型，应在override中配置向量嵌入模型端点。当设置为
vertex-ai（自 APISIX 3.15.0 和企业版 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 和企业版 3.9.2 起可用）时，插件会将请求代理到https://api.anthropic.com/v1/chat/completions。当设置为
openrouter（自 APISIX 3.15.0 和企业版 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 和企业版 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 访问令牌缓存的最大 TTL，单位为秒。
expire_early_secs
integer
默认值：
60访问令牌在其实际过期时间之前提前过期的时间（秒）。这可以防止在活跃请求期间令牌过期的边缘情况。
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 会话令牌。
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
用于替换默认端点的 模型服务提供方端点。如果未配置，插件将使用默认的 OpenAI 端点
https://api.openai.com/v1/chat/completions。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
健康检查配置。
请注意，目前 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 中暂不可用。
http_req_body
string
主动健康检查探测请求中发送的请求体。当
http_method设置为POST时非常有用。默认为空字符串。仅在 API7 企业版中可用，APISIX 中暂不可用。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 模型、持续时间、请求和响应 Token 数。
payloads
boolean
默认值：
false如果为 true，则记录请求和响应的负载。
timeout
integer
默认值：
30000有效值：
介于 1 和 600000 之间（含边界值）
请求 LLM 服务时的请求超时时间（毫秒）。
max_req_body_size
integer
默认值：
67108864有效值：
大于或等于 1
插件读入内存的最大请求体大小，单位为字节。超过该大小的请求将以 HTTP 413 拒绝。该配置可防止大请求体导致的无限内存缓冲。默认值为 67108864 字节（64 MB）。自 API7 企业版 3.9.14 和 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 响应从上游读取的最大总字节数，适用于流式和非流式响应。如果响应超过该值，网关将关闭连接。自 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 服务的证书。