跳到主要内容

推理力度映射

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

该映射默认关闭。仅当请求包含推理力度字符串，且该字符串与配置的键完全匹配时，AISIX 才会修改请求。

映射的工作方式​

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

端点请求字段
POST /v1/chat/completionsreasoning_effort
POST /v1/responsesreasoning.effort
POST /v1/messagesoutput_config.effort
POST /v1/messages/count_tokensoutput_config.effort

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

对于以下映射：

{
  "medium": "high",
  "high": "max"
}
  • medium 会变为 high。AISIX 不会再次查找结果中的 high，因此不会继续变为 max。
  • high 会变为 max。
  • low 等未配置的值仍保持为 low。
  • 未携带推理力度字段的请求保持不变；映射不会主动添加该字段。

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

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

配置 AISIX Cloud​

在控制台中创建或编辑直接模型，展开推理力度映射，然后逐项添加请求力度与上游力度。删除所有映射项并保存即可关闭映射。

也可以通过 Admin API 设置映射。以下请求创建一个直接模型，将 medium 改为 high，并将 high 改为 max：

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": {
      "medium": "high",
      "high": "max"
    }
  }'

更新模型时，省略 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:
      medium: high
      high: max

省略 effort_mapping 或将其设为空对象即可关闭改写。

发送请求​

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

export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
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。