# 推理模型与 Thinking

区分推理控制参数、Thinking 内容和最终回答，理解不同协议的转换差异。

## 能力与输出的区别 [#能力与输出的区别]

推理模型可能使用额外计算处理复杂任务，也可能返回推理用量或可见的 Thinking 内容。这些是不同能力：支持推理不代表一定返回可见思考文本，返回推理字段也不代表所有推理控制参数都有效。

选型时核对 [模型库](/models) 的能力信息，再确认具体通道。本文使用 GFW 模型 ID `deepseek-v4-pro` 展示兼容参数，参数能否生效由模型和上游决定；本文不提供实际速度、准确率或成本对比。

## 端点与参数转换 [#端点与参数转换]

| 协议 | 参数 | 当前网关行为 |
| --- | --- | --- |
| Chat Completions | `reasoning_effort` 等扩展参数 | 请求 JSON 转发；取值支持由模型及通道决定 |
| Responses | `reasoning`、`reasoning_effort` | 转发至内部 Chat 请求，不构成原生 Responses 推理项支持承诺 |
| Anthropic Messages | `thinking: {"type":"enabled","budget_tokens":...}` | 转发 `thinking`，同时设置内部 `reasoning_effort=high` |
| Anthropic Messages | `max_tokens` | 请求必填且大于 0；`thinking.budget_tokens` 不得超过它，建议严格小于它以给最终回答留出预算；两者都受模型限制 |
| 任一协议 | 输出长度参数 | 受模型限制；推理可能占用预算，不能保证全部用于最终文本 |

Anthropic 转换器只处理 `thinking.type=enabled` 的兼容路径。不要据此假定 `adaptive`、禁用参数或厂商专属开关都被实现。Responses 对部分 GLM 模型在桥接时主动设置关闭 Thinking，不能用这一端点承诺它们返回完整思考内容。

## 完整 Thinking 示例 [#完整-thinking-示例]

以下使用 `POST /v1/messages`。请先确认该模型与通道接受 Thinking 请求；若不支持，应移除参数或选择确认支持的模型。Python 依赖 `anthropic` 包，密钥来自 `GFW_API_KEY`。



**cURL**


```bash
curl --fail-with-body --silent --show-error \
  --max-time 120 \
  https://api.gfw.net/v1/messages \
  -H "x-api-key: ${GFW_API_KEY:?请先设置 GFW_API_KEY}" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "deepseek-v4-pro",
    "max_tokens": 2048,
    "thinking": {"type": "enabled", "budget_tokens": 1024},
    "messages": [{"role": "user", "content": "比较重试与幂等设计的作用，给出一个订单创建的例子。"}],
    "stream": false
  }'
```



**Python**


```python
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["GFW_API_KEY"],
    base_url="https://api.gfw.net",
    timeout=120.0,
    max_retries=0,
)
response = client.messages.create(
    model="deepseek-v4-pro",
    max_tokens=2048,
    thinking={"type": "enabled", "budget_tokens": 1024},
    messages=[{
        "role": "user",
        "content": "比较重试与幂等设计的作用，给出一个订单创建的例子。",
    }],
    stream=False,
)

final_text = []
thinking_received = False
for block in response.content:
    if block.type == "text":
        final_text.append(block.text)
    elif block.type == "thinking":
        thinking_received = True
# 默认只输出最终文本，不把 Thinking 混入业务回复。
print("".join(final_text))
print("thinking_received:", thinking_received)
print("stop_reason:", response.stop_reason)
print("usage:", response.usage)
if response.stop_reason == "max_tokens":
    raise RuntimeError("输出预算耗尽，请检查最终回答是否完整")
```




## 响应字段与转换限制 [#响应字段与转换限制]

下面是 Anthropic 桥接可能输出的内容块结构示意，不是实际推理文本：

```json
{
  "content": [
    {"type": "thinking", "thinking": "示意：比较两种机制的作用范围。"},
    {"type": "text", "text": "重试处理临时失败，幂等防止重复操作。"}
  ],
  "stop_reason": "end_turn"
}
```

| 字段 | 说明 |
| --- | --- |
| Chat `message.reasoning_content` | 部分上游的扩展推理字段；不是所有模型的统一格式 |
| Chat `message.content` | 最终文本字段；应用应与推理字段分开处理 |
| Chat `usage.completion_tokens_details.reasoning_tokens` | 若上游提供，可用于观察推理用量；缺失或为 0 不应解释为确定未发生推理 |
| Messages `content[].thinking` | 当前桥接从 `reasoning_content` 转换而来，不保证原生签名或全部语义 |
| Responses `output` | 当前转换只构造文本消息，不提供完整推理项 |


**提示**

当前 Messages 非流式转换在上游只有 `reasoning_content`、没有 `content` 时，会把推理文本作为 `text` 返回。因此不能仅凭内容块类型保证返回的是独立最终回答。对结果敏感的应用应选择确认输出行为的模型和协议，并校验是否完成任务。


## 预算、流式与结果处理 [#预算流式与结果处理]

输出预算要同时考虑模型的推理和最终回复规则。请求中的 `thinking.budget_tokens` 应不超过 `max_tokens`，并建议严格小于 `max_tokens`，为最终回答留出空间；两者都受模型 limits 约束。部分兼容转换为处理差异可能自动扩大内部 `max_tokens`，但这只是适配回退，不能依赖它控制输出长度或费用。增大预算可能增加等待时间与用量，并不保证提高答案质量。先从适合业务的上限开始，用实际调用记录评估，不要假定所有模型都接受相同的 `reasoning_effort` 枚举。

Messages 流式路径会把 `reasoning_content` 转成 `thinking_delta`，普通文本转成 `text_delta`。界面可以分别展示，但业务处理应保持分离。Responses 流式桥接主要读取 `delta.content`，不适合要求保留推理事件的应用。

Token 用量是计量字段，不是货币金额；推理费用是否已包含在输出用量及价格规则中，应以具体模型和 [计费与充值](/docs/billing) 为准，不要重复加总推理明细。账单核对使用 [用量与调用日志](/docs/usage-logs)。

## 注意事项与相关文档 [#注意事项与相关文档]

Thinking 内容属于模型输出，可能不完整或不正确，不应直接作为系统操作依据。保存日志时遵循应用的数据最小化规则，避免把推理文本当作必须长期存储的调试信息。

相关文档：[Anthropic 兼容 API](/docs/anthropic-api)、[Responses API](/docs/responses)、[流式输出](/docs/streaming)、[结构化输出](/docs/structured-output)、[错误码与重试](/docs/errors)。