AI Agent / 系统课时
选择合适的流式输出模式
选择合适的流式输出模式
LangGraph 的流式接口可以同时暴露完整状态、节点增量、模型消息片段和自定义进度事件。选择错误的模式,常见结果是前端收到过多数据、聊天 token 无法实时显示,或把临时进度误当成持久状态。本篇用消费者需求来区分四种常用模式。
学习目标
- 区分
values、updates、messages与custom的数据含义 - 使用 v2 流格式按
type统一处理多种事件 - 为聊天界面、进度反馈和后台任务选择合适的模式组合
先按消费者需要选模式
| 模式 | 每次收到什么 | 典型用途 |
|---|---|---|
values |
当前完整状态快照 | 调试状态演进、需要完整视图的观察器 |
updates |
某个节点本步写入的状态增量 | 步骤进度、后台任务状态、低带宽 UI |
messages |
LLM 消息片段与调用元数据 | 聊天文字逐 token/片段渲染 |
custom |
节点或工具主动发送的任意业务事件 | 百分比进度、阶段提示、外部流式数据 |
values 与 updates 都来自图状态,但粒度不同;messages 来自图中的模型调用;custom 则由应用代码主动发出。一个界面可以同时订阅多种模式,不必在四者中只选一个。
用 v2 统一读取流事件
下面的可运行示例让节点先发送一条自定义进度,再返回状态更新。使用 version="v2" 后,无论订阅一种还是多种模式,每个事件都可以通过 type、ns 和 data 读取。
from typing_extensions import TypedDict
from langgraph.config import get_stream_writer
from langgraph.graph import END, START, StateGraph
class State(TypedDict):
topic: str
draft: str
def write_draft(state: State):
writer = get_stream_writer()
# custom 适合发送不属于持久业务状态的实时进度。
writer({"stage": "write_draft", "progress": 50})
return {"draft": f"{state['topic']}:已生成草稿"}
graph = (
StateGraph(State)
.add_node("write_draft", write_draft)
.add_edge(START, "write_draft")
.add_edge("write_draft", END)
.compile()
)
for part in graph.stream(
{"topic": "LangGraph", "draft": ""},
stream_mode=["updates", "custom"],
version="v2",
):
if part["type"] == "custom":
print("custom:", part["data"])
elif part["type"] == "updates":
print("updates:", part["data"])预期输出
custom: {'stage': 'write_draft', 'progress': 50}
updates: {'write_draft': {'draft': 'LangGraph:已生成草稿'}}如果改成 stream_mode="values",消费者会收到完整状态快照;如果图中的节点调用 LangChain 集成的聊天模型,改用 stream_mode="messages" 就能读取模型消息片段及其元数据。需要同时展示 token 和节点状态时,可以直接组合 ["messages", "updates"]。
理解四种模式的边界
values 最直观,但状态越大,每次传输完整快照的成本越高。生产界面如果只关心“哪个节点刚完成、改了哪些字段”,通常优先用 updates,再由前端维护自己的展示状态。
messages 面向模型输出流。它表示 LLM 产生的消息片段,不等同于图状态已经提交;不要仅凭最后一个 token 判断节点已经完成。若使用的模型客户端不是 LangChain 集成,或需要流式传递非模型数据,更适合把数据转换成 custom 事件。
custom 不会自动变成持久业务状态。进度百分比、阶段提示和工具内部的扫描进度可以只发事件;真正需要在恢复后继续使用的数据,仍应通过节点返回值写入 State。
为前端和后台任务组合模式
聊天应用常用 ["messages", "updates"]:前者持续渲染回答文字,后者在工具调用、审核节点或工作流阶段结束时更新 UI。长时间后台任务更适合 ["updates", "custom"],既能看到状态变化,又能发送细粒度进度。
如果目标是故障诊断,还可以进一步使用检查点、任务或调试类流事件;但它们不应替代面向用户的四种基本输出。选择流模式时先确定消费者要展示什么,再决定数据粒度,这比把所有事件一股脑推给前端更稳定。