Pregel¶

NodeBuilder ¶

方法

名称	描述
`subscribe_only`	订阅单个通道。
`subscribe_to`	添加要订阅的通道。当其中任何一个通道
`read_from`	添加要读取的指定通道，但不订阅它们。
`do`	添加指定的节点。
`write_to`	添加通道写入。
`meta`	为节点添加标签或元数据。
`build`	构建节点。

subscribe_only ¶

subscribe_only(channel: str) -> Self

订阅单个通道。

subscribe_to ¶

subscribe_to(*channels: str, read: bool = True) -> Self

添加要订阅的通道。当其中任何通道更新时，节点将被调用，输入为一个包含通道值的字典。

参数

名称	类型	描述	默认值
`channels`	`str`	要订阅的通道名称	`()`
`read`	`bool`	如果为 True，通道将包含在节点的输入中。否则，它们将触发节点而不作为输入发送。	`True`

返回

类型	描述
`Self`	用于链式调用的 Self

read_from ¶

read_from(*channels: str) -> Self

添加要读取的指定通道，但不订阅它们。

do ¶

do(node: RunnableLike) -> Self

添加指定的节点。

write_to ¶

write_to(
    *channels: str | ChannelWriteEntry, **kwargs: WriteValue
) -> Self

添加通道写入。

参数

名称	类型	描述	默认值
`*channels`	`str \| ChannelWriteEntry`	要写入的通道名称	`()`
`**kwargs`	`WriteValue`	通道名称和值映射	`{}`

返回

类型	描述
`Self`	用于链式调用的 Self

meta ¶

meta(*tags: str, **metadata: Any) -> Self

为节点添加标签或元数据。

build ¶

build() -> PregelNode

构建节点。

Pregel ¶

基类: PregelProtocol[StateT, InputT, OutputT], Generic[StateT, InputT, OutputT]

Pregel 管理 LangGraph 应用程序的运行时行为。

概述¶

Pregel 将 **参与者** 和 **通道** 组合到单个应用程序中。**参与者**从通道读取数据并向通道写入数据。Pregel 按照 **Pregel 算法**/**批量同步并行**模型将应用程序的执行组织成多个步骤。

每个步骤包括三个阶段

**规划**：确定在此步骤中要执行的**参与者**。例如，在第一步中，选择订阅特殊**输入**通道的**参与者**；在后续步骤中，选择订阅前一步骤中更新的通道的**参与者**。
**执行**：并行执行所有选定的**参与者**，直到所有完成，或其中一个失败，或达到超时。在此阶段，通道更新在下一步之前对参与者不可见。
**更新**：使用此步骤中**参与者**写入的值更新通道。

重复此过程，直到没有**参与者**被选中执行，或达到最大步骤数。

参与者¶

一个**参与者**是一个 `PregelNode`。它订阅通道，从通道读取数据，并向通道写入数据。它可以被视为 Pregel 算法中的**参与者**。`PregelNodes` 实现了 LangChain 的 Runnable 接口。

通道¶

通道用于参与者（`PregelNodes`）之间通信。每个通道都有一个值类型、一个更新类型和一个更新函数——该函数接收一个更新序列并修改存储的值。通道可用于将数据从一个链发送到另一个链，或在未来的步骤中将数据从一个链发送到自身。LangGraph 提供了多种内置通道：

基本通道：LastValue 和 Topic¶

LastValue：默认通道，存储发送到通道的最后一个值，适用于输入和输出值，或用于将数据从一个步骤发送到下一个步骤。
Topic：可配置的 PubSub 主题，适用于在*参与者*之间发送多个值，或用于累积输出。可以配置为去重值，和/或在多个步骤中累积值。

高级通道：Context 和 BinaryOperatorAggregate¶

Context：公开上下文管理器的值，管理其生命周期。适用于访问需要设置和/或拆卸的外部资源。例如：`client = Context(httpx.Client)`
BinaryOperatorAggregate：存储一个持久值，通过对当前值和发送到通道的每个更新应用二元运算符来更新，适用于在多个步骤中计算聚合。例如：`total = BinaryOperatorAggregate(int, operator.add)`

示例¶

大多数用户将通过 StateGraph（图 API）或通过 entrypoint（函数式 API）与 Pregel 交互。

然而，对于**高级**用例，可以直接使用 Pregel。如果您不确定是否需要直接使用 Pregel，那么答案可能是不需要——您应该使用图 API 或函数式 API。这些是更高级别的接口，在底层会编译为 Pregel。

以下是一些示例，可让您了解其工作原理：

单节点应用程序

from langgraph.channels import EphemeralValue
from langgraph.pregel import Pregel, NodeBuilder

node1 = (
    NodeBuilder().subscribe_only("a")
    .do(lambda x: x + x)
    .write_to("b")
)

app = Pregel(
    nodes={"node1": node1},
    channels={
        "a": EphemeralValue(str),
        "b": EphemeralValue(str),
    },
    input_channels=["a"],
    output_channels=["b"],
)

app.invoke({"a": "foo"})

{'b': 'foofoo'}

使用多个节点和多个输出通道

from langgraph.channels import LastValue, EphemeralValue
from langgraph.pregel import Pregel, NodeBuilder

node1 = (
    NodeBuilder().subscribe_only("a")
    .do(lambda x: x + x)
    .write_to("b")
)

node2 = (
    NodeBuilder().subscribe_to("b")
    .do(lambda x: x["b"] + x["b"])
    .write_to("c")
)


app = Pregel(
    nodes={"node1": node1, "node2": node2},
    channels={
        "a": EphemeralValue(str),
        "b": LastValue(str),
        "c": EphemeralValue(str),
    },
    input_channels=["a"],
    output_channels=["b", "c"],
)

app.invoke({"a": "foo"})

{'b': 'foofoo', 'c': 'foofoofoofoo'}

使用 Topic 通道

from langgraph.channels import LastValue, EphemeralValue, Topic
from langgraph.pregel import Pregel, NodeBuilder

node1 = (
    NodeBuilder().subscribe_only("a")
    .do(lambda x: x + x)
    .write_to("b", "c")
)

node2 = (
    NodeBuilder().subscribe_only("b")
    .do(lambda x: x + x)
    .write_to("c")
)


app = Pregel(
    nodes={"node1": node1, "node2": node2},
    channels={
        "a": EphemeralValue(str),
        "b": EphemeralValue(str),
        "c": Topic(str, accumulate=True),
    },
    input_channels=["a"],
    output_channels=["c"],
)

app.invoke({"a": "foo"})

{'c': ['foofoo', 'foofoofoofoo']}

使用 BinaryOperatorAggregate 通道

from langgraph.channels import EphemeralValue, BinaryOperatorAggregate
from langgraph.pregel import Pregel, NodeBuilder


node1 = (
    NodeBuilder().subscribe_only("a")
    .do(lambda x: x + x)
    .write_to("b", "c")
)

node2 = (
    NodeBuilder().subscribe_only("b")
    .do(lambda x: x + x)
    .write_to("c")
)


def reducer(current, update):
    if current:
        return current + " | " + update
    else:
        return update

app = Pregel(
    nodes={"node1": node1, "node2": node2},
    channels={
        "a": EphemeralValue(str),
        "b": EphemeralValue(str),
        "c": BinaryOperatorAggregate(str, operator=reducer),
    },
    input_channels=["a"],
    output_channels=["c"]
)

app.invoke({"a": "foo"})

{'c': 'foofoo | foofoofoofoo'}

引入循环

此示例演示了如何在图中引入循环，通过让一个链写入其订阅的通道。执行将继续，直到向该通道写入 None 值。

from langgraph.channels import EphemeralValue
from langgraph.pregel import Pregel, NodeBuilder, ChannelWriteEntry

example_node = (
    NodeBuilder().subscribe_only("value")
    .do(lambda x: x + x if len(x) < 10 else None)
    .write_to(ChannelWriteEntry(channel="value", skip_none=True))
)

app = Pregel(
    nodes={"example_node": example_node},
    channels={
        "value": EphemeralValue(str),
    },
    input_channels=["value"],
    output_channels=["value"]
)

app.invoke({"value": "a"})

{'value': 'aaaaaaaaaaaaaaaa'}

方法

名称	描述
`stream`	流式传输单个输入的图步骤。
`astream`	异步流式传输单个输入的图步骤。
`invoke`	使用单个输入和配置运行图。
`ainvoke`	异步调用图的单个输入。
`get_state`	获取图的当前状态。
`aget_state`	获取图的当前状态。
`get_state_history`	获取图的状态历史记录。
`aget_state_history`	异步获取图的状态历史记录。
`update_state`	使用给定值更新图的状态，如同它们来自
`aupdate_state`	异步使用给定值更新图的状态，如同它们来自
`bulk_update_state`	批量应用更新到图状态。需要设置检查点。
`abulk_update_state`	异步批量应用更新到图状态。需要设置检查点。
`get_graph`	返回计算图的可绘制表示。
`aget_graph`	返回计算图的可绘制表示。
`get_subgraphs`	获取图的子图。
`aget_subgraphs`	获取图的子图。
`with_config`	创建一个带有更新配置的 Pregel 对象副本。

stream ¶

stream(
    input: InputT | Command | None,
    config: RunnableConfig | None = None,
    *,
    stream_mode: (
        StreamMode | Sequence[StreamMode] | None
    ) = None,
    print_mode: StreamMode | Sequence[StreamMode] = (),
    output_keys: str | Sequence[str] | None = None,
    interrupt_before: All | Sequence[str] | None = None,
    interrupt_after: All | Sequence[str] | None = None,
    checkpoint_during: bool | None = None,
    debug: bool | None = None,
    subgraphs: bool = False
) -> Iterator[dict[str, Any] | Any]

流式传输单个输入的图步骤。

参数

名称	类型	描述	默认值
`input`	`InputT \| Command \| None`	图的输入。	必填
`config`	`RunnableConfig \| None`	运行使用的配置。	`None`
`stream_mode`	`StreamMode \| Sequence[StreamMode] \| None`	输出的流模式，默认为 `self.stream_mode`。选项包括： `"values"`：在每个步骤后发出状态中的所有值，包括中断。与函数式 API 一起使用时，值在工作流结束时一次性发出。 `"updates"`：仅在每个步骤后发出节点或任务名称以及由节点或任务返回的更新。如果同一步骤中进行了多次更新（例如运行了多个节点），则这些更新将单独发出。 `"custom"`：使用 `StreamWriter` 从节点或任务内部发出自定义数据。 `"messages"`：逐令牌发出 LLM 消息，以及节点或任务内部任何 LLM 调用的元数据。将以 2 元组 `(LLM 令牌, 元数据)` 的形式发出。 `"checkpoints"`：在创建检查点时发出事件，格式与 `get_state()` 返回的相同。 `"tasks"`：在任务开始和结束时发出事件，包括其结果和错误。您可以将列表作为 `stream_mode` 参数传递，以同时流式传输多种模式。流式输出将是 `(mode, data)` 的元组。有关详细信息，请参阅 LangGraph 流式传输指南。	`None`
`print_mode`	`StreamMode \| Sequence[StreamMode]`	接受与 `stream_mode` 相同的值，但仅将输出打印到控制台，用于调试目的。不以任何方式影响图的输出。	`()`
`output_keys`	`str \| Sequence[str] \| None`	要流式传输的键，默认为所有非上下文通道。	`None`
`interrupt_before`	`All \| Sequence[str] \| None`	要中断之前的节点，默认为图中的所有节点。	`None`
`interrupt_after`	`All \| Sequence[str] \| None`	要中断之后的节点，默认为图中的所有节点。	`None`
`checkpoint_during`	`bool \| None`	是否检查点中间步骤，默认为 False。如果为 False，则仅保存最终检查点。	`None`
`subgraphs`	`bool`	是否从子图内部流式传输事件，默认为 False。如果为 True，事件将以元组 `(namespace, data)` 的形式发出；如果 `stream_mode` 是列表，则以 `(namespace, mode, data)` 的形式发出，其中 `namespace` 是一个元组，包含调用子图的节点的路径，例如 `("parent_node:", "child_node:")`。有关详细信息，请参阅 LangGraph 流式传输指南。	`False`

返回

类型	描述
`dict[str, Any] \| Any`	图中每个步骤的输出。输出形状取决于 `stream_mode`。

astream `async` ¶

astream(
    input: InputT | Command | None,
    config: RunnableConfig | None = None,
    *,
    stream_mode: (
        StreamMode | Sequence[StreamMode] | None
    ) = None,
    print_mode: StreamMode | Sequence[StreamMode] = (),
    output_keys: str | Sequence[str] | None = None,
    interrupt_before: All | Sequence[str] | None = None,
    interrupt_after: All | Sequence[str] | None = None,
    checkpoint_during: bool | None = None,
    debug: bool | None = None,
    subgraphs: bool = False
) -> AsyncIterator[dict[str, Any] | Any]

异步流式传输单个输入的图步骤。

参数

名称	类型	描述	默认值
`input`	`InputT \| Command \| None`	图的输入。	必填
`config`	`RunnableConfig \| None`	运行使用的配置。	`None`
`stream_mode`	`StreamMode \| Sequence[StreamMode] \| None`	输出的流模式，默认为 `self.stream_mode`。选项包括： `"values"`：在每个步骤后发出状态中的所有值，包括中断。与函数式 API 一起使用时，值在工作流结束时一次性发出。 `"updates"`：仅在每个步骤后发出节点或任务名称以及由节点或任务返回的更新。如果同一步骤中进行了多次更新（例如运行了多个节点），则这些更新将单独发出。 `"custom"`：使用 `StreamWriter` 从节点或任务内部发出自定义数据。 `"messages"`：逐令牌发出 LLM 消息，以及节点或任务内部任何 LLM 调用的元数据。将以 2 元组 `(LLM 令牌, 元数据)` 的形式发出。 `"debug"`：为每个步骤发出包含尽可能多信息的调试事件。您可以将列表作为 `stream_mode` 参数传递，以同时流式传输多种模式。流式输出将是 `(mode, data)` 的元组。有关详细信息，请参阅 LangGraph 流式传输指南。	`None`
`print_mode`	`StreamMode \| Sequence[StreamMode]`	接受与 `stream_mode` 相同的值，但仅将输出打印到控制台，用于调试目的。不以任何方式影响图的输出。	`()`
`output_keys`	`str \| Sequence[str] \| None`	要流式传输的键，默认为所有非上下文通道。	`None`
`interrupt_before`	`All \| Sequence[str] \| None`	要中断之前的节点，默认为图中的所有节点。	`None`
`interrupt_after`	`All \| Sequence[str] \| None`	要中断之后的节点，默认为图中的所有节点。	`None`
`checkpoint_during`	`bool \| None`	是否检查点中间步骤，默认为 False。如果为 False，则仅保存最终检查点。	`None`
`subgraphs`	`bool`	是否从子图内部流式传输事件，默认为 False。如果为 True，事件将以元组 `(namespace, data)` 的形式发出；如果 `stream_mode` 是列表，则以 `(namespace, mode, data)` 的形式发出，其中 `namespace` 是一个元组，包含调用子图的节点的路径，例如 `("parent_node:", "child_node:")`。有关详细信息，请参阅 LangGraph 流式传输指南。	`False`

返回

类型	描述
`AsyncIterator[dict[str, Any] \| Any]`	图中每个步骤的输出。输出形状取决于 `stream_mode`。

invoke ¶

invoke(
    input: InputT | Command | None,
    config: RunnableConfig | None = None,
    *,
    stream_mode: StreamMode = "values",
    print_mode: StreamMode | Sequence[StreamMode] = (),
    output_keys: str | Sequence[str] | None = None,
    interrupt_before: All | Sequence[str] | None = None,
    interrupt_after: All | Sequence[str] | None = None,
    **kwargs: Any
) -> dict[str, Any] | Any

使用单个输入和配置运行图。

参数

名称	类型	描述	默认值
`input`	`InputT \| Command \| None`	图的输入数据。它可以是字典或任何其他类型。	必填
`config`	`RunnableConfig \| None`	可选。图运行的配置。	`None`
`stream_mode`	`StreamMode`	可选[str]。图运行的流模式。默认为 "values"。	`'values'`
`print_mode`	`StreamMode \| Sequence[StreamMode]`	接受与 `stream_mode` 相同的值，但仅将输出打印到控制台，用于调试目的。不以任何方式影响图的输出。	`()`
`output_keys`	`str \| Sequence[str] \| None`	可选。要从图运行中检索的输出键。	`None`
`interrupt_before`	`All \| Sequence[str] \| None`	可选。在图运行之前中断的节点。	`None`
`interrupt_after`	`All \| Sequence[str] \| None`	可选。在图运行之后中断的节点。	`None`
`**kwargs`	`Any`	要传递给图运行的其他关键字参数。	`{}`

返回

类型	描述
`dict[str, Any] \| Any`	图运行的输出。如果 `stream_mode` 为 "values"，则返回最新输出。
`dict[str, Any] \| Any`	如果 `stream_mode` 不为 "values"，则返回输出块列表。

ainvoke `async` ¶

ainvoke(
    input: InputT | Command | None,
    config: RunnableConfig | None = None,
    *,
    stream_mode: StreamMode = "values",
    print_mode: StreamMode | Sequence[StreamMode] = (),
    output_keys: str | Sequence[str] | None = None,
    interrupt_before: All | Sequence[str] | None = None,
    interrupt_after: All | Sequence[str] | None = None,
    **kwargs: Any
) -> dict[str, Any] | Any

异步调用图的单个输入。

参数

名称	类型	描述	默认值
`input`	`InputT \| Command \| None`	计算的输入数据。它可以是字典或任何其他类型。	必填
`config`	`RunnableConfig \| None`	可选。计算的配置。	`None`
`stream_mode`	`StreamMode`	可选。计算的流模式。默认为 "values"。	`'values'`
`print_mode`	`StreamMode \| Sequence[StreamMode]`	接受与 `stream_mode` 相同的值，但仅将输出打印到控制台，用于调试目的。不以任何方式影响图的输出。	`()`
`output_keys`	`str \| Sequence[str] \| None`	可选。要包含在结果中的输出键。默认为 None。	`None`
`interrupt_before`	`All \| Sequence[str] \| None`	可选。之前中断的节点。默认为 None。	`None`
`interrupt_after`	`All \| Sequence[str] \| None`	可选。之后中断的节点。默认为 None。	`None`
`**kwargs`	`Any`	其他关键字参数。	`{}`

返回

类型	描述
`dict[str, Any] \| Any`	计算结果。如果 `stream_mode` 为 "values"，则返回最新值。
`dict[str, Any] \| Any`	如果 `stream_mode` 为 "chunks"，则返回块列表。

get_state ¶

get_state(
    config: RunnableConfig, *, subgraphs: bool = False
) -> StateSnapshot

获取图的当前状态。

aget_state `async` ¶

aget_state(
    config: RunnableConfig, *, subgraphs: bool = False
) -> StateSnapshot

获取图的当前状态。

get_state_history ¶

get_state_history(
    config: RunnableConfig,
    *,
    filter: dict[str, Any] | None = None,
    before: RunnableConfig | None = None,
    limit: int | None = None
) -> Iterator[StateSnapshot]

获取图的状态历史记录。

aget_state_history `async` ¶

aget_state_history(
    config: RunnableConfig,
    *,
    filter: dict[str, Any] | None = None,
    before: RunnableConfig | None = None,
    limit: int | None = None
) -> AsyncIterator[StateSnapshot]

异步获取图的状态历史记录。

update_state ¶

update_state(
    config: RunnableConfig,
    values: dict[str, Any] | Any | None,
    as_node: str | None = None,
    task_id: str | None = None,
) -> RunnableConfig

使用给定值更新图的状态，如同它们来自节点 `as_node`。如果未提供 `as_node`，它将设置为更新状态的最后一个节点（如果不是模棱两可）。

aupdate_state `async` ¶

aupdate_state(
    config: RunnableConfig,
    values: dict[str, Any] | Any,
    as_node: str | None = None,
    task_id: str | None = None,
) -> RunnableConfig

异步使用给定值更新图的状态，如同它们来自节点 `as_node`。如果未提供 `as_node`，它将设置为更新状态的最后一个节点（如果不是模棱两可）。

bulk_update_state ¶

bulk_update_state(
    config: RunnableConfig,
    supersteps: Sequence[Sequence[StateUpdate]],
) -> RunnableConfig

批量应用更新到图状态。需要设置检查点。

参数

名称	类型	描述	默认值
`config`	`RunnableConfig`	应用更新的配置。	必填
`supersteps`	`Sequence[Sequence[StateUpdate]]`	超级步骤列表，每个列表包含要按顺序应用于图状态的更新列表。每个更新都是 `(values, as_node, task_id)` 形式的元组，其中 `task_id` 是可选的。	必填

抛出

类型	描述
`ValueError`	如果未设置检查点或未提供更新。
`InvalidUpdateError`	如果提供了无效更新。

返回

名称	类型	描述
`RunnableConfig`	`RunnableConfig`	更新后的配置。

abulk_update_state `async` ¶

abulk_update_state(
    config: RunnableConfig,
    supersteps: Sequence[Sequence[StateUpdate]],
) -> RunnableConfig

异步批量应用更新到图状态。需要设置检查点。

参数

名称	类型	描述	默认值
`config`	`RunnableConfig`	应用更新的配置。	必填
`supersteps`	`Sequence[Sequence[StateUpdate]]`	超级步骤列表，每个列表包含要按顺序应用于图状态的更新列表。每个更新都是 `(values, as_node, task_id)` 形式的元组，其中 `task_id` 是可选的。	必填

抛出

类型	描述
`ValueError`	如果未设置检查点或未提供更新。
`InvalidUpdateError`	如果提供了无效更新。

返回

名称	类型	描述
`RunnableConfig`	`RunnableConfig`	更新后的配置。

get_graph ¶

get_graph(
    config: RunnableConfig | None = None,
    *,
    xray: int | bool = False
) -> Graph

返回计算图的可绘制表示。

aget_graph `async` ¶

aget_graph(
    config: RunnableConfig | None = None,
    *,
    xray: int | bool = False
) -> Graph

返回计算图的可绘制表示。

get_subgraphs ¶

get_subgraphs(
    *, namespace: str | None = None, recurse: bool = False
) -> Iterator[tuple[str, PregelProtocol]]

获取图的子图。

参数

名称	类型	描述	默认值
`namespace`	`str \| None`	用于过滤子图的命名空间。	`None`
`recurse`	`bool`	是否递归进入子图。如果为 False，则只返回直接子图。	`False`

返回

类型	描述
`Iterator[tuple[str, PregelProtocol]]`	Iterator[tuple[str, PregelProtocol]]：`(namespace, subgraph)` 对的迭代器。

aget_subgraphs `async` ¶

aget_subgraphs(
    *, namespace: str | None = None, recurse: bool = False
) -> AsyncIterator[tuple[str, PregelProtocol]]