跳到主要内容

参数​

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

  • 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。如果代理请求到 Embedding 模型，则应在 override 中配置 Embedding 模型端点。

    当设置为 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。对于 Embedding，插件将请求代理到 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 Enterprise 3.9.12 和 APISIX 3.17.0 起可用）时，插件使用 Converse API 将请求代理到 AWS Bedrock。需要在 auth.aws 中配置 IAM 凭证，在 provider_conf.region 中配置 AWS 区域。支持非流式和流式（ConverseStream）两种模式，当请求体中 stream 设为 true 时启用流式响应。

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

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

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

  • auth

    object

    必填

    认证配置。

    • header

      object

      身份认证请求头。

    • query

      object

      认证查询参数。

    • 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 Enterprise 3.9.12 和 APISIX 3.17.0 起可用。

      • access_key_id

        string

        必填

        AWS IAM 访问密钥 ID。

      • secret_access_key

        string

        必填

        AWS IAM 秘密访问密钥。

      • session_token

        string

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

  • options

    object

    模型配置。

    除了 model 之外，你还可以配置其他参数，它们将在请求体中转发到上游 LLM 服务。例如，如果你使用 OpenAI，你可以配置 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

      Google Cloud Project ID。当 provider 为 vertex-ai 时必填。

    • region

      string

      必填

      云区域。对于 vertex-ai，为 GCP 区域。对于 bedrock，为 AWS 区域（如 us-east-1）。

  • override

    object

    覆盖设置。

    • endpoint

      string

      模型服务提供方端点。当 provider 为 openai-compatible 时必填。

    • llm_options

      object

      感知提供商的 LLM 选项覆盖。自 API7 Enterprise 版本 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 Enterprise 版本 3.9.10 和 APISIX 3.17.0 起可用。

  • logging

    object

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

    • summaries

      boolean

      默认值：false

      如果为 true，记录请求 LLM 模型、持续时间、请求和响应 Token。

    • payloads

      boolean

      默认值：false

      如果为 true，记录请求和响应 Payload。

  • timeout

    integer

    默认值：30000

    有效值：

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

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

  • max_req_body_size

    integer

    默认值：67108864

    插件读取到内存中的最大请求体大小，单位为字节（默认 67108864 字节，即 64 MB）。请求体大于此限制时将以 HTTP 413 被拒绝，从而避免大请求体造成无限制内存缓冲。自 API7 企业版 3.10.1 和 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 服务的证书。

  • max_stream_duration_ms

    integer

    流式 AI 响应的最长实际持续时间（毫秒）。如果上游超过该期限仍在发送数据，连接将关闭。未设置表示不限制。此参数可防止上游缺陷导致无限生成 Token。自 API7 企业版 3.9.10 和 APISIX 3.17.0 起可用。

  • max_response_bytes

    integer

    单个 AI 响应从上游读取的最大总字节数，包括流式和非流式响应。响应超过该值时，网关会关闭连接。自 API7 Enterprise 3.9.10 和 APISIX 3.17.0 起可用。

  • streaming_flush_interval_ms

    integer

    默认值：10

    流式响应的后台 flush 间隔，单位为毫秒。正整数会启动后台线程周期性 flush 输出，用于在上游一次性突发多个 token 时限制客户端侧延迟。设置为 0 时禁用后台线程，并对每个 chunk 执行同步 inline flush。自 API7 企业版 3.9.13 和 APISIX 3.17.0 起可用。