AI-大语言模型LLM-LangGraphV1.0学习笔记-stream_mode参数详解

目的

为避免一学就会、一用就废，这里做下笔记

内容

在 LangGraph 中，stream_mode 参数用于控制调用 graph.stream() 或 graph.astream() 方法时，流式输出（Streaming Output）的内容粒度 与类型。它允许你实时获取图执行过程中的中间状态、LLM 生成内容或自定义数据，而不是等待整个图执行完毕。

该参数接受一个字符串或字符串列表，指定要监听的流模式。以下是所有可用模式的详细说明：

1. 核心流模式详解

模式值	输出内容	适用场景	备注
`"values"`	图的完整状态（State）。在每个节点执行后，返回当前 State 的所有键值对。	需要监控图状态在每一步的完整快照。	数据量大，包含未变化的字段。
`"updates"`	状态的增量更新。在每个节点执行后，返回该节点具体修改了哪些字段（键值对）。	最常用。用于前端实时渲染进度、显示哪个节点做了什么。	只包含变化的字段，结构为 `{node_name: {field: value}}`。
`"messages"`	LLM 的 Token 流。在LLM 生成过程中，实时返回单个 Token 及其元数据。	实现打字机效果（Typewriter Effect），实时显示 AI 回复。	输出格式为 `(token, metadata)` 元组。
`"custom"`	自定义数据。捕获节点内部通过 `get_stream_writer()` 发出的任意数据。	输出进度条、内部日志、工具执行中间结果。	需在节点代码中主动调用 `writer.write(data)`。
`"debug"`	详细的调试信息。包括节点开始/结束、状态变化、LLM 调用详情等。	深度调试图执行流程，分析性能瓶颈。	信息最全，但结构复杂，通常用于开发阶段。
`"checkpoints"`	检查点事件。当图创建或加载检查点时触发。	配合持久化存储（Checkpointer），用于状态恢复监听。	输出格式与 `get_state()` 类似。
`"tasks"`	任务事件。当任务（节点）开始和完成时触发，包含结果和错误信息。	监控异步任务的执行生命周期。	事件类型包括 `start` 和 `end`。

2. 使用示例

单模式使用（仅监听状态更新）

python 复制代码

for chunk in graph.stream(
    {"input": "Hello"},
    stream_mode="updates"  # 或 ["updates"]
):
    print(chunk)
# 输出示例: {'node_1': {'response': 'Hi there!'}}

多模式组合（监听状态更新 + LLM Token）

python 复制代码

for mode, chunk in graph.stream(
    {"input": "Hello"},
    stream_mode=["updates", "messages"]  # 返回元组 (mode, chunk)
):
    if mode == "updates":
        print(f"State updated: {chunk}")
    elif mode == "messages":
        token, meta = chunk
        print(f"Token: {token}")

自定义流写入（在节点函数中）

python 复制代码

from langgraph.config import get_stream_writer

def my_node(state):
    writer = get_stream_writer("custom")
    writer.write("Starting heavy computation...")  # 这行内容会被 stream_mode="custom" 捕获
    # ... 节点逻辑
    return {"result": "done"}

3. 注意事项

异步兼容性 ：astream() 是异步方法，需在 async for 循环中使用。
默认行为 ：如果不指定 stream_mode，方法将阻塞执行，直到图运行结束才返回最终状态。
性能影响 ：启用 "messages" 或 "debug" 模式可能会增加内存和网络开销，尤其是在处理长文本时。
版本差异 ："checkpoints" 和 "tasks" 等模式在较新版本（如 0.2.x 之后）中引入，请确保 LangGraph 版本支持。