[!info] related notes

• 所属 MOC: LLM Streaming MOC
• 实现层: Semantic Router
• 组合: Structured Streaming, Event Sourcing AI
• 综合: Streaming 高级协议模式
• 基础协议: Delta Stream, Append Event Stream

Multi-channel Stream

一句话定义

Multi-channel Stream 是 LLM Streaming 的高级协议模式——在同一个事件流中通过 channel 字段区分不同类型的输出（文本、推理、工具调用、结构化数据），让不同类型的内容走不同的逻辑通道。

核心机制

解决什么问题

LLM 生成过程中，输出不只是”回答文本”。还有：

• 模型的推理/思考过程
• 工具调用请求
• 结构化提取结果
• 引用来源
• 流程状态

如果所有内容混在同一个流里，前端无法区分哪些是展示给用户的文本，哪些是调试信息，哪些需要后端处理。

协议结构

每个事件增加 channel 字段：

{ "channel": "text",       "delta": "你好" }
{ "channel": "reasoning",  "delta": "用户在问协议设计" }
{ "channel": "tool",       "name": "search", "args": {...} }
{ "channel": "structured", "data": { "symptoms": ["头痛"] } }
{ "channel": "status",     "data": { "step": "analyzing" } }

前端消费

// 按 channel 分发到不同的 buffer / 状态
switch (event.channel) {
  case "text":
    textBuffer += event.delta
    break
  case "reasoning":
    reasoningBuffer += event.delta  // 可以隐藏或折叠展示
    break
  case "tool":
    handleToolCall(event)
    break
  case "structured":
    updateStructuredData(event.data)
    break
}

标准通道定义

channel	语义	前端处理
text	面向用户的回答文本	主聊天 UI，打字机效果
reasoning	模型推理/思考过程	折叠面板，可展开查看
tool	工具调用	工具状态 UI + 后端执行
structured	结构化数据	专用 UI 组件
citation	引用来源	引用面板
status	流程状态	状态指示器
error	错误/警告	错误提示

最小场景

{ "channel": "text", "type": "message.delta", "data": { "content": "我帮你查一下天气。" } }
{ "channel": "reasoning", "type": "thinking.delta", "data": { "content": "用户想知道今天的天气..." } }
{ "channel": "tool", "type": "tool_call.started", "data": { "name": "get_weather" } }
{ "channel": "text", "type": "message.delta", "data": { "content": "今天北京晴，25°C。" } }

前端：用户看到”我帮你查一下天气。今天北京晴，25°C。“，推理过程隐藏在折叠面板，工具调用显示为一个状态卡片。

与基础协议的关系

Multi-channel 不是 Delta / Append 的替代，而是它们的叠加维度：

• Delta Stream + channel = 带通道的文本增量
• Append Stream + channel = 带通道的事件追加

{
  "type": "message.delta",    // ← Delta 语义
  "channel": "text",          // ← Multi-channel 维度
  "data": { "content": "你好" }
}

边界与易混淆点

• Multi-channel 不是多条连接：所有 channel 共用同一个 SSE/WebSocket 连接，只是事件上带有 channel 标记。
• channel 和 event type 的区别：channel 是”这个内容给谁用”，type 是”这个事件是什么”。一个 channel 可以有多种 type。
• 不需要所有 channel 都用：简单场景只用 text 就够了，按需启用其他 channel。
• 前端可以忽略不需要的 channel：比如不展示 reasoning 的前端可以直接跳过 channel: "reasoning" 的事件。