# AI返回字段: 思考相关

# AI 返回字段：思考相关

本文区分三种协议：NiceRouter 的 OpenAI 兼容 Chat Completions、OpenAI 官方 Responses API、Anthropic 官方 Messages API。字段名和语义不同，不能混用。

> **重要：模型内部进行推理，不代表 API 会返回原始思维链。** 应只使用协议明确提供的思考摘要或思考块，并始终把最终答案作为业务主输出。

## 1. NiceRouter：OpenAI 兼容 Chat Completions

请求地址：`POST /v1/chat/completions`。

NiceRouter 的兼容响应中：

- 最终答案：非流式为 `choices[0].message.content`，流式为 `choices[0].delta.content`。
- 思考信息（若当前模型和渠道返回）：非流式通常为 `choices[0].message.reasoning_content`，流式通常为 `choices[0].delta.reasoning_content`。
- `reasoning_content` 是 NiceRouter/上游兼容扩展，**不是 OpenAI 官方 Chat Completions 的标准字段**。客户端必须允许其缺失、为空或分多个流式片段返回。

### 非流式响应示例

```json
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning_content": "（渠道返回的思考信息）",
        "content": "这是最终答案。"
      },
      "finish_reason": "stop"
    }
  ]
}
```

```python
message = response["choices"][0]["message"]
answer = message.get("content", "")
reasoning = message.get("reasoning_content")  # 可选，可能为 None
```

### 流式响应示例

```text
data: {"choices":[{"index":0,"delta":{"role":"assistant","reasoning_content":"（思考片段）","content":""}}]}

data: {"choices":[{"index":0,"delta":{"content":"这是最终答案。"}}]}

data: [DONE]
```

处理流式响应时，应分别累积 `delta.reasoning_content` 与 `delta.content`；收到 `[DONE]` 后结束。不要依赖思考字段判断响应是否完成。

部分 Gemini 兼容适配可能使用 `reasoning`，部分逆向或旧适配可能把内容以 `<think>...</think>` 混在文本中。这些都不是 OpenAI 或 Anthropic 官方字段，只能按当前渠道实测兼容。

## 2. 对齐 OpenAI 官方 Responses API

OpenAI 官方推理模型优先使用 `POST /v1/responses`。推理配置放在 `reasoning` 对象中：

```json
{
  "model": "gpt-5.4",
  "input": "比较两个方案并给出结论",
  "reasoning": {
    "effort": "medium",
    "summary": "auto",
    "context": "auto",
    "mode": "standard"
  }
}
```

OpenAI 官方**确实提供顶层 `reasoning` 对象**，但它属于 Responses API，并不是旧版 `/v1/completions` 的参数。当前官方 SDK 类型仅标注适用于 GPT-5 与 o-series 推理模型。

- `reasoning.effort`：控制推理投入。当前类型为 `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`；并非每个模型支持全部值。
- `reasoning.summary`：请求可公开的推理摘要，可用 `auto`、`concise`、`detailed`；这不是原始思维链。
- `reasoning.context`：控制后续轮次把哪些 reasoning items 重新呈现给模型，可用 `auto`、`current_turn`、`all_turns`；响应中为实际生效模式。
- `reasoning.mode`：控制推理执行模式，官方已知值为 `standard`、`pro`；实际支持依模型，响应中为实际生效模式。
- `reasoning.generate_summary`：已弃用，仅为兼容旧客户端；应改用 `reasoning.summary`。
- 响应 `output` 中 `type: "reasoning"` 的项目可包含 `summary`；摘要项为 `{"type":"summary_text","text":"..."}`。
- `encrypted_content` 是供无状态、多轮上下文延续使用的加密推理内容，不是展示给用户的可读思考文本。
- 最终答案位于 `type: "message"` 项的 `output_text` 中；不要把 reasoning item 当作最终答案。

官方 Responses 结构示意：

```json
{
  "output": [
    {
      "type": "reasoning",
      "summary": [
        {"type": "summary_text", "text": "推理摘要"}
      ]
    },
    {
      "type": "message",
      "content": [
        {"type": "output_text", "text": "最终答案"}
      ]
    }
  ]
}
```

Chat Completions 中可见 `usage.completion_tokens_details.reasoning_tokens`，它是用量统计，不是可展示的思考内容。

## 3. 对齐 Anthropic 官方 Messages API

Anthropic 官方使用 `POST /v1/messages`。扩展思考通过顶层 `thinking` 配置。支持方式取决于具体 Claude 模型：

### 自适应思考

```json
{
  "model": "claude-opus-4-7",
  "max_tokens": 4096,
  "thinking": {
    "type": "adaptive"
  },
  "messages": [
    {"role": "user", "content": "比较两个方案并给出结论"}
  ]
}
```

### 固定预算思考

```json
{
  "model": "claude-opus-4-7",
  "max_tokens": 4096,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 2048
  },
  "messages": [
    {"role": "user", "content": "比较两个方案并给出结论"}
  ]
}
```

固定预算模式下，`budget_tokens` 至少为 1024，且必须小于 `max_tokens`。官方新类型还提供 `display: "summarized" | "omitted"`；是否可用以具体模型和渠道为准。

Anthropic 响应的 `content` 是有序内容块数组：

```json
{
  "content": [
    {
      "type": "thinking",
      "thinking": "（返回的思考内容或摘要）",
      "signature": "..."
    },
    {
      "type": "text",
      "text": "最终答案"
    }
  ]
}
```

- `type: "thinking"` 块包含 `thinking` 和 `signature`。
- 安全系统可能返回 `type: "redacted_thinking"` 与加密 `data`；客户端应原样保留用于后续上下文，不要尝试解密或展示。
- 最终答案是 `type: "text"` 块。
- 流式事件中，思考增量类型是 `thinking_delta`，文本增量类型是 `text_delta`。
- 多轮对话或工具调用时，应完整、原样回传上一轮 assistant 的思考块及签名，保持块顺序，不要修改签名。

## 4. 三个模型如何处理

| 模型 ID | 官方规范状态 | NiceRouter 兼容接口的处理方式 |
| --- | --- | --- |
| `gpt-5.4` | OpenAI 官方 SDK/规范列出的模型；官方推理控制使用 Responses API 的 `reasoning` 对象 | 调用 `/v1/chat/completions` 时，按 NiceRouter 实际响应读取可选 `reasoning_content`；不要假定等同官方 reasoning item |
| `gpt-5.5` | 当前已查到的 OpenAI 官方 SDK模型列表未列出该 ID | 仅在 NiceRouter 控制台或 `/v1/models` 确认存在时使用；参数和返回字段必须实测 |
| `claude-opus-4-7` | Anthropic 官方 SDK列出的模型；官方 Messages API 使用 `thinking` 和内容块 | NiceRouter `/v1/messages` 是否完整透传 `thinking`、`signature`、`redacted_thinking` 需实测；OpenAI 兼容接口可能映射为 `reasoning_content` |

`/v1/models` 中存在模型 ID，只证明当前渠道暴露了该 ID，不能证明它支持某个推理参数或返回某种思考字段。

## 5. 最小验证流程

API Key 只放环境变量，不要写进脚本、文档或仓库。对每个模型分别验证非流式和流式请求：

```bash
export NICEROUTER_API_KEY='你的 API Key'
export MODEL='gpt-5.4'

curl -sS https://api.nicerouter.com/v1/chat/completions \
  -H "Authorization: Bearer $NICEROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"计算 27×43，只给出最终结果。\"}],\"stream\":false}"
```

检查：

1. HTTP 状态码和实际返回的 `model`。
2. 最终答案字段是否符合所用协议。
3. 思考字段/思考块是存在、空值、缺失还是被适配。
4. 将 `stream` 改为 `true` 后，增量事件结构是否一致。
5. 分别做“不传推理参数”和“传推理参数”的对照请求；HTTP 200 不代表未知参数生效，上游可能忽略它。

## 6. 兼容与安全建议

- 业务逻辑只依赖最终答案；思考摘要或思考块视为可选诊断信息。
- 按协议解析：Chat Completions、Responses、Anthropic Messages 使用不同的数据模型。
- 不要向最终用户承诺返回原始思维链，也不要用思考字段是否存在判断模型是否具备推理能力。
- 不建议持久化或公开思考信息；其中可能包含不稳定内容、敏感上下文或上游保留信息。
- 模型、渠道或适配方式变更后，重新执行验证流程。

## 参考：官方规范

- OpenAI API 文档：<https://developers.openai.com/api/docs/guides/reasoning>
- OpenAI 官方 OpenAPI：<https://github.com/openai/openai-openapi>
- Anthropic Extended Thinking：<https://platform.claude.com/docs/en/build-with-claude/extended-thinking>
- Anthropic 官方 Python SDK 类型：<https://github.com/anthropics/anthropic-sdk-python/tree/main/src/anthropic/types>