> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 推理与思考

> o3 / GPT-5 / Claude thinking / Gemini thinking 系列模型的使用

推理模型在生成回答前会先进行 **内部思考**,在数学、代码、规划、逻辑题等任务上显著强于普通模型,但延迟与成本也更高。

## 支持的模型

| 厂商        | 模型 / 后缀                                                  | 启用方式                          |
| --------- | -------------------------------------------------------- | ----------------------------- |
| OpenAI    | `o3-mini-low/medium/high`、`o3`、`gpt-5.5-low/medium/high` | 模型 ID 自带 / `reasoning_effort` |
| Anthropic | `claude-*-thinking`、原始模型 + `thinking` 参数                 | 模型 ID 自带 / `thinking` 参数      |
| Google    | `gemini-2.5-pro-thinking`、`-low/medium/high`             | 模型 ID 自带 / `thinking_budget`  |
| DeepSeek  | `deepseek-r1`                                            | 直接使用模型 ID                     |

## OpenAI

### 通过模型 ID

```python theme={null}
resp = client.chat.completions.create(
    model="o3-mini-high",
    messages=[{"role": "user", "content": "证明 √2 是无理数"}],
    max_completion_tokens=4096,
)
print(resp.usage.completion_tokens_details.reasoning_tokens)
```

### 通过参数(Responses API)

```python theme={null}
resp = client.responses.create(
    model="o3-mini",
    input="证明 √2 是无理数",
    reasoning={"effort": "high"},
    max_output_tokens=4096,
)
```

注意:

* 推理模型 **不支持** `temperature`、`top_p`、`presence_penalty` 等部分参数。
* 使用 `max_completion_tokens`(新)而非 `max_tokens`。
* `reasoning_tokens` 不可见但会计费,务必留足预算。

## Claude

```python theme={null}
resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    thinking={"type": "enabled", "budget_tokens": 8000},
    messages=[{"role": "user", "content": "证明费马小定理"}],
)

for block in resp.content:
    if block.type == "thinking":
        print("[思考]", block.thinking)
    elif block.type == "text":
        print("[回答]", block.text)
```

* `budget_tokens`:思考预算上限,典型 1024-32000。
* 思考块默认 **可见** —— 与 OpenAI 不同,你可以读到推理过程。
* 计费:thinking\_tokens 按输出价格 **额外** 计费。

## Gemini

```python theme={null}
resp = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents="证明哥德巴赫猜想",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=8000),
    ),
)
print(resp.usage_metadata.thoughts_token_count)
```

或使用预置 ID:

| ID                            | 行为              |
| ----------------------------- | --------------- |
| `gemini-2.5-pro-thinking`     | 默认中等思考预算        |
| `gemini-2.5-pro-thinking-128` | 强制 128 思考 token |
| `gemini-2.5-flash-nothinking` | 关闭思考(更便宜)       |
| `gemini-2.5-pro-high`         | 高推理强度           |

## 什么时候用推理模型

<CardGroup cols={2}>
  <Card title="✅ 适合" icon="check">
    * 数学证明、复杂逻辑题
    * 代码重构、Bug 定位
    * 多步骤规划、Agent 决策
    * 长文档分析、研究综述
  </Card>

  <Card title="❌ 不必" icon="xmark">
    * 普通问答、闲聊
    * 翻译、摘要、改写
    * 简单分类、信息抽取
  </Card>
</CardGroup>

## 计费提醒

* 推理 token **不在 `content` 中显示** 但仍按输出价格扣费。
* 控制台日志会拆分展示 thinking / answer 两部分。
* 设置 `max_completion_tokens` / `max_output_tokens` 时 **务必留足**(建议 ≥ 4096),否则可能因 token 耗尽返回空答案。

## 流式

推理模型可以流式输出,但 **思考阶段没有 delta 内容**,客户端会先看到一段空白(可能数秒),然后才开始接收答案。
建议在 UI 上加 loading 状态。Claude / Gemini 流式可以收到 thinking block 的 delta,实现 "思考过程可视化"。