版本：1.4.0

推理力度映射

支持推理的模型并不总是使用相同的力度取值。客户端可能发送 medium，而所选上游模型只接受 high 或 max。在直接模型上配置 effort_mapping，即可由网关改写这些值。

该映射默认关闭，未匹配任何条目的请求会原样发往上游。除了把一个值改写成另一个值，映射还可以为未设置力度的请求补上力度、覆盖所有没有单独条目的取值，以及彻底移除力度字段。参见保留条目。

映射的工作方式

AISIX 根据调用方使用的规范化端点，从以下位置读取推理力度：

端点	请求字段
`POST /v1/chat/completions`	`reasoning_effort`
`POST /v1/responses`	`reasoning.effort`
`POST /v1/messages`	`output_config.effort`
`POST /v1/messages/count_tokens`	`output_config.effort`

AISIX 选出最终的直接模型后、序列化服务提供方请求前，会对请求力度执行一次查找：先匹配区分大小写的精确条目，再匹配 * 条目。查找结果不会再次参与匹配。流式与非流式请求的行为相同；AISIX 在 OpenAI 与 Anthropic 请求格式之间转换时也会应用该映射。

对于以下映射：

{
  "medium": "high",
  "high": "max"
}

medium 会变为 high。AISIX 不会再次查找结果中的 high，因此不会继续变为 max。
high 会变为 max。
low 等未配置的值仍保持为 low。
未携带推理力度字段的请求保持不变。该映射没有 "" 条目，因此不会补上任何值。

映射属于最终的直接模型，而不是调用方请求的别名。当路由模型或语义路由器选择某个直接模型时，会应用该目标自身的映射。每个合议成员使用各自的映射，直接评审模型也会对合成请求应用自己的映射。不要在路由、语义、合议或向量嵌入模型资源上配置该字段；AISIX 会拒绝这些配置。

改写后仍受服务提供方和具体模型的能力限制。目标值只能使用所选上游模型接受的取值。对于不支持的值，服务提供方适配器可能根据其规范化端点行为进行转换、省略或拒绝。透传路由不使用模型资源，因此不会应用推理力度映射。

保留条目

有三类条目的含义并非某个具体的力度取值：

条目	含义
键 `""`（空字符串）	匹配完全未设置力度的请求，即端点对应的力度字段缺失、为 `null` 或为空。该条目的值会被写入发往上游的请求。
键 `*`	匹配其他所有已设置但没有单独条目的取值，永远不会匹配未设置力度的请求。
值 `null`	从发往上游的请求中移除力度字段，改用服务提供方自身的默认值。

这两个键属于彼此独立的查找："" 只匹配未设置力度的请求，* 只匹配已设置力度的请求。因此把 * 映射为 null，会移除所有没有单独条目的取值的力度字段，而未设置力度的请求不受影响。

保存模型时会拒绝以下两种写法：

"": null —— 未设置力度的请求没有可移除的字段。
任何键的值为空。

以下映射同时用到了三类保留条目：

{
  "": "low",
  "medium": "high",
  "xhigh": null,
  "*": null
}

未设置力度的请求会以 low 发往上游。
medium 会以 high 发往上游。
xhigh 发往上游时不带力度字段，改用服务提供方的默认值。
其他所有已设置的取值（minimal、high 等）也会因 * 条目而失去力度字段。

携带 `thinking` 的 Anthropic 请求

在 POST /v1/messages 与 POST /v1/messages/count_tokens 上，AISIX 只读取和改写 output_config.effort。对该映射而言，thinking 块并不是力度设置。因此，携带 thinking 但没有 output_config.effort 的请求属于未设置力度，"" 条目对它生效。

Claude Code 的请求通常就是这种形态：它总是发送 thinking，只有配置了力度级别时才发送 output_config.effort。配置 "" 条目后，这类请求就会使用你配置的力度，而不是完全不带力度。

当这类请求被分发到不接受 Anthropic 协议的服务提供方时，上游力度取自改写后的 output_config.effort（如果存在），否则取自 thinking；但如果某个条目移除了力度，则完全不发送力度。

设置了 thinking.type: disabled 的请求永远不会被该映射赋予力度：在 Anthropic 协议上，没有任何条目会为它写入力度级别，但移除力度的条目仍然会移除；在其他协议上，它始终发送 none 力度。

升级兼容性

保留键和 null 值需要网关版本支持。只要目标环境中仍有已注册的网关运行较旧版本，保存使用了 ""、* 或 null 值的映射就会返回 HTTP 422 和错误码 DP_INCOMPATIBLE，且不会写入任何内容。请升级这些网关，或在升级完成前不要使用这些条目。该检查的工作方式参见控制面在混合版本窗口期间的检查。

配置 AISIX Cloud

在控制台中创建或编辑直接模型，展开推理力度映射。每一行的两侧都是下拉选择：

请求力度 —— 指定值（填写调用方的取值）、未设置（对应 "" 条目）或其他任意值（对应 * 条目）。
上游力度 —— 指定值（填写要发送的取值）或移除（使用供应商默认值）（对应 null 值）。

未设置与其他任意值规则各自最多只能有一条，且未设置规则不能选择移除。只有选择指定值时才需要在文本框中填写取值；在文本框中直接输入 * 会被拒绝，因为它就是其他任意值规则。删除所有映射项并保存即可关闭映射。

也可以通过 Admin API 设置映射。以下请求创建一个直接模型：调用方未设置力度时补上 low，把 medium 改为 high，并移除其他所有请求的力度：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "direct",
    "display_name": "reasoning-prod",
    "model_name": "YOUR_UPSTREAM_MODEL",
    "provider_key_id": "'"$PROVIDER_KEY_ID"'",
    "effort_mapping": {
      "": "low",
      "medium": "high",
      "*": null
    }
  }'

更新模型时，省略 effort_mapping 表示保持不变；发送 null 或空对象可将其清除：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/models/$MODEL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"effort_mapping": null}'

配置开源网关

在完整的 resources.yaml 快照中，为直接模型添加 effort_mapping：

resources.yaml（直接模型）
models:
  - display_name: reasoning-prod
    provider: openai
    model_name: YOUR_UPSTREAM_MODEL
    provider_key: openai-prod
    effort_mapping:
      "": low
      medium: high
      xhigh: null
      "*": null

在 YAML 中要给 "" 和 "*" 加引号，它们才会被识别为保留条目；移除力度写作 null。省略 effort_mapping 或将其设为空对象即可关闭改写。

发送请求

像往常一样调用模型，应用无需使用服务提供方专属的力度设置：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

curl -sS "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "reasoning-prod",
    "messages": [{"role": "user", "content": "Solve this problem."}],
    "reasoning_effort": "medium"
  }'

对于此请求，AISIX 会向所选直接模型发送 high。如果完全不带 reasoning_effort，AISIX 会依据 "" 条目发送 low。

映射的工作方式​

保留条目​

携带 thinking 的 Anthropic 请求​

升级兼容性​

配置 AISIX Cloud​

配置开源网关​

发送请求​