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 的标准字段。客户端必须允许其缺失、为空或分多个流式片段返回。

非流式响应示例

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

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

流式响应示例

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 对象中：

{
  "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 结构示意：

{
  "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 模型：

自适应思考

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

固定预算思考

{
  "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 是有序内容块数组：

{
  "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 只放环境变量，不要写进脚本、文档或仓库。对每个模型分别验证非流式和流式请求：

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}"

检查：

HTTP 状态码和实际返回的 model。
最终答案字段是否符合所用协议。
思考字段/思考块是存在、空值、缺失还是被适配。
将 stream 改为 true 后，增量事件结构是否一致。
分别做“不传推理参数”和“传推理参数”的对照请求；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

AI返回字段: 思考相关