- 流式传输图状态 — 使用
updates和values模式获取状态更新/值。 - 流式传输子图输出 — 同时包含父图和任何嵌套子图的输出。
- 流式传输 LLM 令牌 — 从任意位置捕获令牌流:节点内部、子图或工具中。
- 流式传输自定义数据 — 从工具函数中直接发送自定义更新或进度信号。
- 使用多种流式传输模式 — 可选择
values(完整状态)、updates(状态增量)、messages(LLM 令牌 + 元数据)、custom(任意用户数据)或debug(详细追踪信息)。
支持的流式传输模式
将以下一个或多个流式传输模式作为列表传递给stream() 或 astream() 方法:
| 模式 | 描述 |
|---|---|
values | 在图的每一步执行后,流式传输状态的完整值。 |
updates | 在图的每一步执行后,流式传输状态的更新内容。如果同一步骤中进行了多次更新(例如,运行了多个节点),这些更新将被分别流式传输。 |
custom | 从图节点内部流式传输自定义数据。 |
messages | 从调用 LLM 的任何图节点中流式传输二元组(LLM 令牌, 元数据)。 |
debug | 在图执行过程中尽可能多地流式传输信息。 |
基本用法示例
LangGraph 图暴露了.stream()(同步)和 .astream()(异步)方法,以迭代器形式生成流式输出。
扩展示例:流式传输更新
扩展示例:流式传输更新
stream()方法返回一个迭代器,用于生成流式输出。- 设置
stream_mode="updates"以仅流式传输每个节点执行后对图状态的更新。也可使用其他流式传输模式。详情请参阅支持的流式传输模式。
流式传输多种模式
你可以将stream_mode 参数设置为一个列表,以同时流式传输多种模式。
流式输出将是 (mode, chunk) 形式的元组,其中 mode 是流式传输模式的名称,chunk 是该模式流式传输的数据。
流式传输图状态
使用updates 和 values 流式传输模式在图执行时流式传输其状态。
updates在图的每一步执行后流式传输状态的更新。values在图的每一步执行后流式传输状态的完整值。
- updates
- values
使用此模式仅流式传输每个步骤后节点返回的状态更新。流式输出包含节点名称及其更新内容。
流式传输子图输出
为了在流式输出中包含子图的输出,你可以在父图的.stream() 方法中设置 subgraphs=True。这将同时流式传输父图和任何子图的输出。
输出将以 (namespace, data) 元组的形式流式传输,其中 namespace 是一个元组,表示调用子图的节点路径,例如 ("parent_node:<task_id>", "child_node:<task_id>")。
- 设置
subgraphs=True以流式传输子图的输出。
扩展示例:从子图流式传输
扩展示例:从子图流式传输
- 设置
subgraphs=True以流式传输子图的输出。
调试
使用debug 流式传输模式在图执行过程中尽可能多地流式传输信息。流式输出包括节点名称和完整状态。
LLM 令牌
使用messages 流式传输模式,从图的任何部分(包括节点、工具、子图或任务)逐令牌流式传输大语言模型(LLM)的输出。
messages 模式 的流式输出是一个元组 (message_chunk, metadata),其中:
message_chunk:来自 LLM 的令牌或消息片段。metadata:包含有关图节点和 LLM 调用详细信息的字典。
如果你的 LLM 没有 LangChain 集成,可以改用 custom 模式流式传输其输出。详情请参阅与任意 LLM 一起使用。
- 注意,即使使用
.invoke而不是.stream运行 LLM,也会发出消息事件。 - “messages” 流式传输模式返回一个
(message_chunk, metadata)元组的迭代器,其中message_chunk是 LLM 流式传输的令牌,metadata是包含调用 LLM 的图节点信息及其他信息的字典。
按 LLM 调用过滤
你可以为 LLM 调用关联tags,以按 LLM 调用过滤流式传输的令牌。
- llm_1 被标记为 “joke”。
- llm_2 被标记为 “poem”。
stream_mode设置为 “messages” 以流式传输 LLM 令牌。metadata包含有关 LLM 调用的信息,包括标签。- 通过
metadata中的tags字段过滤流式传输的令牌,仅包含标记为 “joke” 的 LLM 调用的令牌。
扩展示例:按标签过滤
扩展示例:按标签过滤
joke_model被标记为 “joke”。poem_model被标记为 “poem”。- 显式传递
config以确保上下文变量正确传播。这在 Python < 3.11 中使用异步代码时是必需的。详情请参阅异步部分。 stream_mode设置为 “messages” 以流式传输 LLM 令牌。metadata包含有关 LLM 调用的信息,包括标签。
按节点过滤
要仅从特定节点流式传输令牌,请使用stream_mode="messages" 并通过流式传输元数据中的 langgraph_node 字段过滤输出:
- “messages” 流式传输模式返回一个
(message_chunk, metadata)元组,其中message_chunk是 LLM 流式传输的令牌,metadata是包含调用 LLM 的图节点信息及其他信息的字典。 - 通过
metadata中的langgraph_node字段过滤流式传输的令牌,仅包含来自write_poem节点的令牌。
扩展示例:从特定节点流式传输 LLM 令牌
扩展示例:从特定节点流式传输 LLM 令牌
- “messages” 流式传输模式返回一个
(message_chunk, metadata)元组,其中message_chunk是 LLM 流式传输的令牌,metadata是包含调用 LLM 的图节点信息及其他信息的字典。 - 通过
metadata中的langgraph_node字段过滤流式传输的令牌,仅包含来自write_poem节点的令牌。
流式传输自定义数据
要从 LangGraph 节点或工具内部发送自定义用户定义数据,请按照以下步骤操作:- 使用
get_stream_writer()访问流式写入器并发出自定义数据。 - 在调用
.stream()或.astream()时设置stream_mode="custom"以在流中获取自定义数据。你可以组合多种模式(例如,["updates", "custom"]),但至少必须包含"custom"。
- 节点
- 工具
- 获取流式写入器以发送自定义数据。
- 发出一个自定义键值对(例如,进度更新)。
3. 设置
stream_mode="custom"以在流中接收自定义数据。
与任意 LLM 一起使用
你可以使用stream_mode="custom" 从任意 LLM API 流式传输数据 —— 即使该 API 未实现 LangChain 聊天模型接口。
这使你可以集成原始 LLM 客户端或提供自身流式接口的外部服务,使 LangGraph 对于自定义设置具有高度灵活性。
- 获取流式写入器以发送自定义数据。
- 使用你的自定义流式客户端生成 LLM 令牌。
- 使用写入器将自定义数据发送到流中。
- 设置
stream_mode="custom"以在流中接收自定义数据。
扩展示例:流式传输任意聊天模型
扩展示例:流式传输任意聊天模型
为特定聊天模型禁用流式传输
如果你的应用程序混合了支持流式传输和不支持流式传输的模型,你可能需要显式地为不支持流式传输的模型禁用流式传输。 在初始化模型时设置disable_streaming=True。
- init_chat_model
- 聊天模型接口
- 设置
disable_streaming=True以禁用聊天模型的流式传输。
Python < 3.11 的异步
在 Python 版本 < 3.11 中,asyncio 任务不支持context 参数。
这限制了 LangGraph 自动传播上下文的能力,并以两种关键方式影响 LangGraph 的流式传输机制:
- 你必须在异步 LLM 调用(例如,
ainvoke())中显式传递RunnableConfig,因为回调不会自动传播。 - 你不能在异步节点或工具中使用
get_stream_writer()—— 你必须直接传递一个writer参数。
扩展示例:带手动配置的异步 LLM 调用
扩展示例:带手动配置的异步 LLM 调用
- 在异步节点函数中接受
config作为参数。 - 将
config传递给llm.ainvoke()以确保上下文正确传播。 - 设置
stream_mode="messages"以流式传输 LLM 令牌。
扩展示例:带流式写入器的异步自定义流式传输
扩展示例:带流式写入器的异步自定义流式传输
- 在异步节点或工具的函数签名中添加
writer作为参数。LangGraph 将自动将流式写入器传递给函数。 - 设置
stream_mode="custom"以在流中接收自定义数据。