第10章 推理轨迹
完整的文档索引请参阅 llms.txt,本页也支持 Markdown 格式。
推理轨迹
处理多轮对话中的推理轨迹
Trinity-Large-Thinking 在生成最终回复前,会先输出位于 `
` 标签内的显式思维链推理。通过 vLLM 提供服务时,这些标签块会被解析到 API 响应的专用字段 `reasoning_content` 中,与 `content` 和 `tool_calls` 彼此独立。
在多轮对话中保留推理轨迹对可靠的多步骤工具调用和 agentic 工作流至关重要。本指南将介绍如何正确实现这一点。
推理在对话中的流转
第 1 轮:用户发送消息 ↓ 模型生成:`
` 内容 + `tool_calls` ↓ vLLM 解析为:`{ reasoning_content, content, tool_calls }` ↓
第 2 轮:客户端将完整的助手消息(`reasoning_content` + `content` + `tool_calls`)追加到历史中 客户端追加工具执行结果 客户端发送更新后的对话历史 ↓ Chat 模板在 tokenize 阶段将 `reasoning_content` 重新包装为 `
` ↓ 模型感知到上一轮的思维链 → 正确生成下一步
如果客户端在轮次间丢弃了 `reasoning_content`,模型就会失去之前的思维链上下文,从而可能生成格式错误的输出。
快速参考:助手消息结构
对于调用工具的助手消息,追加回对话历史时需包含以下三个字段:
| 字段 | 是否必需 | 说明 | |---|---|---| | `content` | 是 | 若模型返回 null,则使用空字符串 `""`。切勿传入 null。 | | `reasoning_content` | 强烈建议 | 取自 API 响应的 `reasoning_content` 字段。输入端也接受 `reasoning` 作为别名。 | | `tool_calls` | 条件 | 模型发起工具调用时包含;最终的非工具调用助手轮次可省略。 |
字段命名:`reasoning` vs `reasoning_content`
不同层使用不同名称,容易混淆:
| 层 | 字段名 | 方向 | |---|---|---| | Arcee API / vLLM API 响应 | `reasoning_content` | 输出 | | OpenAI Python SDK | `reasoning_content` | 输出(属性名) | | Arcee API 输入(助手消息) | `reasoning_content`(也接受 `reasoning`) | 输入 | | 自托管 vLLM 输入 | `reasoning`(部分版本不接受 `reasoning_content`) | 输入 | | Chat 模板(Jinja) | `reasoning` 和 `reasoning_content` 均可 | 输入 |
安全准则: 构建输入端助手消息时,使用 `reasoning_content`。这与 API 返回的字段一致,可直接原样传回。后端输入端也接受 `reasoning` 并会自动转换。
自托管 vLLM 用户注意: 部分 vLLM 版本的输入消息仅识别 `reasoning`(vllm#38488)。若直接调用 vLLM(而非通过 Arcee API),可能需要在助手消息上将 `reasoning_content` 映射为 `reasoning`。
Python 实现
* 安装 * 完整 agentic 循环
TypeScript 实现
* 安装 * 完整 agentic 循环
OpenRouter 集成
通过 OpenRouter 使用 Trinity 时,推理结果封装在 `reasoning_details` 对象中(OpenRouter 的统一推理结构)。在多轮对话中,将 `reasoning_details` 原样传回助手消息即可——OpenRouter 会自动完成模型特有的上游转换。
调试上游请求
若要验证推理是否被正确发送至上游,可启用 echo 模式:
详见 OpenRouter 调试文档。
常见陷阱
1. `xml_in_reasoning` —— 工具调用 XML 混入推理字段
现象: 响应中 `tool_calls: []`(空数组),而 `reasoning_content` 中包含原始 XML,如 `
原因: 之前的助手轮次很可能丢失了推理上下文(或消息结构无效),导致模型将工具调用写进了思维块而非结构化输出。
修复: 确保对话历史中每条助手消息都包含来自上一次 API 响应的 `reasoning_content`。
2. 自托管 vLLM 忽略了 `reasoning_content`
现象: 向自托管 vLLM 实例的助手消息传入 `reasoning_content`,但模型表现如同推理缺失。
原因: 部分 vLLM 版本的输入消息只识别 `reasoning`(不识别 `reasoning_content`)(vllm#38488)。此问题不影响 Arcee 托管 API,后者两者均接受。
修复: 若直接调用 vLLM,请在输入端将 `reasoning_content` 映射为 `reasoning`:
3. 工具调用轮次中 `content: null`
现象: 后续轮次工具调用质量下降或输出格式错误。
原因: 模型发起工具调用时,API 响应中的 `content` 可能为 null。原样传回 null 在某些集成中会加剧后续的格式错误。
修复: 将 null 规范化为空字符串:
4. 缺失 vLLM 服务标志
现象: 推理内容泄漏至 `content`,可见 `
` 标签;或工具调用以原始 XML 形式出现,而非结构化 `tool_calls`。
修复: 确保 vLLM 启动时包含正确参数:
| 参数 | 作用 | |---|---| | `--reasoning-parser deepseek_r1` | 将 `
` 块分离至 `reasoning_content` 字段 | | `--enable-auto-tool-choice` | 启用工具调用解析 | | `--tool-call-parser qwen3_coder` | 将工具调用解析为结构化 `tool_calls` 数组 |
注意: vLLM 0.18 之前的版本可能还需 `--enable-reasoning`。若该参数未被识别,则仅配置 `--reasoning-parser` 即可。
vLLM 服务参考
* 最简启动命令 * 生产启动命令(仅供参考)
上下文长度建议
根据实际对话长度、工具链深度和 GPU 显存预算设置 `--max-model-len`。数值越大,启动时预分配的 KV cache 越多。建议采取保守起步、监控截断情况(`finish_reason: "length"`)、再逐步上调的策略。
---
上一篇:结构化输出 下一篇:硬件前置条件 最后更新:1 个月前