跳到主要内容
版本：Dev

请求参数处理

发给 AISIX 的请求经常带着一些参数，所选上游对它们的处理方式与客户端原本面向的 API 不同：某个模型不接受的惩罚参数、某个模型系列拒绝的 stop，或者 Anthropic 没有对应字段的 OpenAI 字段。本页说明 AISIX 如何处理每个请求参数，帮助你预先判断一个参数是会到达模型、被丢弃，还是让请求失败。

AISIX 如何决定​

AISIX 按目标平台自身 API 对字段的定义来处理调用方发送的每个字段。无论请求使用上游本身的协议，还是由 AISIX 做协议转换，规则都相同：

  1. 目标定义了该字段，且取值符合定义。 AISIX 按调用方发送的值写入；当目标对该字段的命名或位置不同时，写入含义相同的字段，例如 OpenAI 的 stop 写为 Gemini 的 stopSequences。AISIX 不会丢弃、改写这个值，也不会代替上游预先校验它。模型拒绝时，上游的状态码和错误信息会返回给调用方。
  2. 目标没有可以放置该字段或取值的位置。 AISIX 静默丢弃，不记录日志、不添加响应头，也不计入指标。
  3. 该取值在调用方自身的协议里就不合法，且目标无法按原样接收。 AISIX 以 400 invalid_request_error 拒绝请求，错误信息会点名该字段。
  4. 上游返回的内容完整返回。 参见完整返回上游答复。

AISIX 可以根据对某个模型或模型系列的了解，决定一个值写到哪里：哪个字段、哪条上游路由、用什么名称。它不会据此决定一个值是否被丢弃、拒绝或改写。因此，你发给某个模型、而该模型不支持的参数会到达模型，你会收到服务提供方自己的错误。

不做协议转换时​

当调用方的协议就是上游的协议时，例如 /v1/chat/completions 发往 OpenAI 兼容服务提供方，或 /v1/messages 发往 Anthropic，客户端能发送的每个字段都由目标定义。AISIX 按原样转发请求体，包括 AISIX 自身不认识的字段，由上游判断每个字段。AISIX 仍会做的改动只有服务提供方页面中记录的那些，例如 OpenAI 上的推理模型 Token 上限，以及运维人员在服务提供方密钥上配置的改动，例如 request.param_renames。

做协议转换时​

当 AISIX 转换请求时，例如把 OpenAI 风格的请求发往 Claude 或 Gemini，或把 /v1/messages 请求发往 OpenAI 兼容模型，每个字段都会映射到目标中含义相同的字段。目标协议中没有对应字段的字段会被丢弃。调用方协议本身就不允许的取值，例如数字形式的 stop，会以点名该字段的 400 拒绝，因为转换后的请求没有地方能把它原样交给上游判断。

各转换的映射关系见以下页面：

有意保留的例外​

以下四种行为有意偏离上述规则：

  • Claude 客户端添加到 system 中的 Anthropic 归属标识行，对 Anthropic 自有 API 以外的所有上游都会被移除。参见 Anthropic 归属标识行。
  • 集成模型的裁判调用使用网关设置的采样参数，而不是调用方的参数。
  • 单个空字符串 stop 不会发送给 Amazon Bedrock Converse，因为 Converse 会拒绝它。
  • Responses 桥接承载 Codex 等编码智能体发送的 Responses API 字段，其余 Responses API 字段不在其范围内。

调用方会收到什么​

情况结果
目标接受该参数。参数到达模型。
目标定义了该参数，但模型拒绝该参数或其取值。上游的状态码和错误信息，例如 Amazon Bedrock 返回的 400，信息为 This model doesn't support the stopSequences field. Remove stopSequences and try again.
目标没有放置该参数的位置。请求成功，参数不生效。
在转换路径上，取值在调用方协议中不合法。400 invalid_request_error，错误信息点名该字段。
请求体是合法 JSON，但不符合端点的请求格式。400 invalid_request_error，错误信息以 invalid request body: 开头并点名字段路径，例如 max_tokens 或 messages[0]。消息 content 为数字、布尔值或对象时也会这样拒绝。

需要提前规划的后果：过去在网关静默忽略某个参数的情况下成功的请求，现在可能收到上游的 400。请停止向该模型发送这个参数，或改用接受它的模型。1.7.0 及更早版本的网关会自行丢弃其中一些参数；发生变化的情况列在现在会失败的请求中。

完整返回上游答复​

在 /v1/chat/completions 上，AISIX 返回上游答复的全部内容：

  • 每个 choice，因此 n 大于 1 的请求会收到所有 choice。流式 chunk 保留各 choice 的 index。
  • 每个 choice 的 logprobs。
  • refusal、annotations、旧版 function_call，以及上游发送的其他所有 message 或 delta 字段。
  • 上游以内容分段数组形式发送的消息 content，按该数组返回。content 为分段数组的流式 delta 会按上游顺序返回：其文本放在 delta.content 中，其中的 Mistral thinking 和 Databricks reasoning 部件放在 delta.reasoning_content 中。Chat delta 中没有承载部件 signature 的字段，因此不会返回签名。

这适用于所有以 OpenAI Chat Completions 格式答复的上游，包括 OpenAI 兼容服务提供方、Azure OpenAI、Vertex AI 上的 OpenAI 兼容模型，以及 Amazon Bedrock 的 Chat Completions 端点。Vertex AI 上的 Gemini 会把每个 candidate 作为一个 choice 返回。/v1/messages 和 /v1/responses 每个响应只承载一个答复，因此只读取第一个 choice。答复的 content 是部件数组时，无论是否流式，它们都会返回其中的文本，并把 Mistral thinking 和 Databricks reasoning 部件作为推理内容返回：在 /v1/messages 上是 thinking 块，在 /v1/responses 上是 reasoning 项。参见 Mistral。

输出安全护栏会扫描每个 choice、refusal 文本和旧版 function_call 的参数，脱敏安全护栏会改写它们。脱敏不会改写 logprobs，因此请求了 logprobs 的调用方会收到未脱敏的上游 token 文本。参见 Choice、拒答与对数概率。

上游已经给出的答复不会再执行一次。当模型返回 AISIX 无法读取的 2xx 时，调用方收到 502，AISIX 不会重试、不会故障转移到其他目标，也不会把这次失败计入冷却。/v1/images/edits 同样如此。凭证交换返回无法读取的响应时，例如 Azure AD 或 Vertex AI 服务账号的 token 请求，仍会重试并可能触发冷却，因为它没有给出任何答复。

旧版函数调用​

已弃用的 functions、function_call 请求字段和 function 消息角色在所有上游上都可用。以 null 发送的 functions 或 function_call 视为未发送。

  • 使用 OpenAI Chat Completions 格式的上游按原样接收这些字段和 function 轮次。
  • 所有平台上的 Claude、Vertex AI 上的 Gemini，以及通过 InvokeModel 或 Converse 提供服务的所有 Amazon Bedrock 模型，会把 functions 作为 tools、function_call 作为 tool_choice、助手的 function_call 作为工具调用、function 轮次作为该调用的工具结果接收。

当调用方声明了 functions 而没有 tools 时，答复以旧版形式返回：message.function_call，流式时为 delta.function_call，并带 finish_reason: "function_call"。旧版形式每轮只容纳一个调用，因此每个 choice 只返回第一个工具调用。

现在会失败的请求​

1.7.0 及更早版本的网关会自行丢弃或调整以下参数。现在它们会到达上游，由上游作答：

  • Amazon Bedrock 上：发给 gpt-oss、Grok 和 GPT 5.6 及更高版本的 stop；Chat Completions 端点过去会丢弃的参数；发给不支持 strict 的模型的工具 strict；现在会进入模型 additionalModelRequestFields 的 OpenAI 字段；低于 16 的输出上限；以及没有 user 或 assistant 消息的请求。
  • Gemini 上：AISIX 现在发送的 generationConfig 设置和 parametersJsonSchema，以及超过 Gemini 2.5 模型思考上限的 /v1/messages thinking.budget_tokens。
  • 所有转换路径上：调用方协议不允许的取值，例如类型错误的 stop、max_tokens、temperature、tool_choice、reasoning_effort 或 service_tier，格式错误的工具，或缺少 id 或函数名的回放工具调用，现在 AISIX 会点名字段拒绝。

调用方或运维人员还能观察到的其他行为：

  • 调用方发送的 strict json_schema 会原样到达 OpenAI 兼容上游，因此不完整的 strict schema 会收到上游的校验错误，与直接调用服务提供方时一致。只有在 AISIX 转换 /v1/messages 结构化输出请求、由它自己设置 strict 时，AISIX 才会闭合 schema。
  • content: null 的助手消息按 null 发送，temperature 和 top_p 保留调用方的十进制取值。
  • 在 /v1/messages 上，调用方的 anthropic-beta 请求头会到达 Anthropic 和 Anthropic 兼容端点。参见转发客户端请求头。
  • /v1/embeddings 接受 token ID 输入，并转发 user 等字段。参见向量嵌入。
  • 含有多个 choice 或 logprobs 的响应缓存条目，无法被共享同一 Redis 的 1.7.0 及更早版本网关读取。参见使用 Redis 共享缓存条目。

下一步​

你已经了解 AISIX 如何处理每个请求参数。参见服务提供方兼容性了解各服务提供方支持哪些端点，参见代理错误与重试了解如何处理本页描述的错误。