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 读取。

python
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"])

预期输出

text
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"],既能看到状态变化,又能发送细粒度进度。

如果目标是故障诊断,还可以进一步使用检查点、任务或调试类流事件;但它们不应替代面向用户的四种基本输出。选择流模式时先确定消费者要展示什么,再决定数据粒度,这比把所有事件一股脑推给前端更稳定。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

选择合适的流式输出模式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通