Skip to main content

011-5-ReasoningTokens

需要手动维护渲染 思考过程 的逻辑

心智模型​

推理令牌（Reasoning tokens） 模式的核心是将模型回复解构为两种不同性质的内容块（contentBlocks），并在 UI 上进行差异化呈现：

  1. 内容分层：具备推理能力的模型会将回复分为两类：
    • 推理块 (Reasoning blocks)：模型的内部思考过程，如思维链、问题分解。
    • 文本块 (Text blocks)：提供给用户的最终答案。
  2. 按需展示：通过分析 AIMessage 对象中的 contentBlocks 数组，将推理过程提取出来，默认折叠在一个样式独特的组件（如 ThinkingBubble）中，而最终文本则正常渲染。这实现了“先给结论，再看过程”的体验。

关键实践提示​

  • 【数据提取】Extracting reasoning and text blocks：要从 msg.contentBlocks 中筛选出 type === "reasoning" 和 type === "text" 的块。注意，一条消息可能包含多个或是交替出现的这两种块。
  • 【UI 状态处理】
    • 流式加载指示器：在模型仍在生成推理内容时，ThinkingBubble 应显示动画图标和 "Thinking..." 文字。
    • 默认折叠与预览：推理气泡应默认折叠，显示一个简短的字符计数和内容预览，让用户决定是否展开。
    • 避免流时展开：由于流式更新可能导致布局抖动，建议在推理阶段禁止展开，等完成后才允许用户操作。
  • 【边界情况】Handling edge cases：
    • 无推理内容：并非所有模型或所有回复都包含推理块。当 contentBlocks 中只有文本块时，应回退到标准的消息气泡渲染。
    • 空推理块：一些模型可能产生空的推理占位符，应过滤掉 reasoning.trim().length === 0 的无效块。
    • 交替内容：若需保留推理和文本的交错顺序，应按 contentBlocks 的顺序遍历，而不是预先分组。
  • 【视觉与无障碍】
    • 视觉区分：为推理气泡使用独特的背景色、边框或排版，使其与标准文本回复形成鲜明对比。
    • 无障碍访问：确保展开/折叠按钮具有正确的 ARIA 属性，如 aria-expanded 和 aria-controls。

总结自检​

  • 性能相关：文档提到流式传输中禁止展开，以避免因 DOM 更新导致的布局跳动，这是主要的性能注意点。
  • 安全相关：无直接安全内容。
  • 技术细节：已涵盖 contentBlocks 数据结构、ThinkingBubble 的展开/折叠逻辑与样式、流式状态的处理，以及多种边界情况（无推理、空块、交替块）的处理策略。