[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 相关: Event Type, Streaming Renderer

Text Delta

一句话定义

Text Delta 是 LLM 流式输出中文本增量的事件类型。LLM 逐 token 生成文本，每个 token 包装成一个 text_delta 事件推送到前端。

核心原理

数据格式

{
  "event": "text_delta",
  "data": {
    "delta": "你好"
  }
}

前端处理

function handleTextDelta(data: { delta: string }) {
  // 追加到当前 assistant 消息
  setMessages(prev => {
    const last = prev[prev.length - 1];
    if (last.role === 'assistant') {
      return [
        ...prev.slice(0, -1),
        { ...last, content: last.content + data.delta }
      ];
    }
    return [...prev, { role: 'assistant', content: data.delta }];
  });
}

累积 vs 增量

模式	data 结构	说明
增量	{delta: "你好"}	只传新增的文本
累积	{accumulated: "你好世界"}	传到目前为止的全部文本

增量模式更常用，因为数据量更小。

常见坑

1. 不做防抖: 每个 delta 都触发 re-render，性能差
2. 不处理空 delta: 有些 delta 是空字符串
3. 增量和累积混用: 前端逻辑不一致

参考资料

• Event Type
• Streaming Renderer