Pregel¶

Pregel ¶

基类: PregelProtocol

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

概述¶

Pregel 将 **actor（参与者）** 和**通道**组合成一个单一的应用程序。**Actor（参与者）**从通道读取数据并向通道写入数据。Pregel 遵循 **Pregel 算法**/**批量同步并行 (Bulk Synchronous Parallel)** 模型，将应用程序的执行组织成多个步骤。

每个步骤包含三个阶段：

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

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

Actor（参与者）¶

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

通道¶

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

基本通道：LastValue 和 Topic¶

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

高级通道：Context 和 BinaryOperatorAggregate¶

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

示例¶

大多数用户将通过 StateGraph (图 API) 或入口点 (函数式 API) 与 Pregel 交互。

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

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

单节点应用程序

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

node1 = (
    Channel.subscribe_to("a")
    | (lambda x: x + x)
    | Channel.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, Channel, ChannelWriteEntry

node1 = (
    Channel.subscribe_to("a")
    | (lambda x: x + x)
    | Channel.write_to("b")
)

node2 = (
    Channel.subscribe_to("b")
    | (lambda x: x + x)
    | Channel.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, Channel, ChannelWriteEntry

node1 = (
    Channel.subscribe_to("a")
    | (lambda x: x + x)
    | {
        "b": Channel.write_to("b"),
        "c": Channel.write_to("c")
    }
)

node2 = (
    Channel.subscribe_to("b")
    | (lambda x: x + x)
    | {
        "c": Channel.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, Channel


node1 = (
    Channel.subscribe_to("a")
    | (lambda x: x + x)
    | {
        "b": Channel.write_to("b"),
        "c": Channel.write_to("c")
    }
)

node2 = (
    Channel.subscribe_to("b")
    | (lambda x: x + x)
    | {
        "c": Channel.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, Channel, ChannelWrite, ChannelWriteEntry

example_node = (
    Channel.subscribe_to("value")
    | (lambda x: x + x if len(x) < 10 else None)
    | ChannelWrite(writes=[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: dict[str, Any] | Any,
    config: RunnableConfig | None = None,
    *,
    stream_mode: (
        StreamMode | list[StreamMode] | None
    ) = None,
    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`	`dict[str, Any] \| Any`	图的输入。	必需
`config`	`RunnableConfig \| None`	运行所用的配置。	`无`
`stream_mode`	`StreamMode \| list[StreamMode] \| None`	流式输出的模式，默认为 `self.stream_mode`。选项包括： `"values"`：在每个步骤之后（包括中断），发出状态中的所有值。与函数式 API 一起使用时，值在工作流结束时一次性发出。 `"updates"`：在每个步骤之后，仅发出节点或任务名称以及节点或任务返回的更新。如果在同一步骤中进行多次更新（例如，运行多个节点），则这些更新将单独发出。 `"custom"`：使用 `StreamWriter` 从节点或任务内部发出自定义数据。 `"messages"`：逐个 token 发出 LLM 消息，以及节点或任务内部任何 LLM 调用的元数据。将以 2 元组 `(LLM token, metadata)` 的形式发出。 `"debug"`：为每个步骤发出包含尽可能多信息的调试事件。您可以将列表作为 `stream_mode` 参数传递，以同时流式传输多种模式。流式输出将是 `(mode, data)` 的元组。有关更多详细信息，请参阅 LangGraph 流式传输指南。	`无`
`output_keys`	`str \| Sequence[str] \| None`	要流式传输的键，默认为所有非上下文通道。	`无`
`interrupt_before`	`All \| Sequence[str] \| None`	中断前要中断的节点，默认为图中的所有节点。	`无`
`interrupt_after`	`All \| Sequence[str] \| None`	中断后要中断的节点，默认为图中的所有节点。	`无`
`checkpoint_during`	`bool \| None`	是否检查点中间步骤，默认为 True。如果为 False，则只保存最终检查点。	`无`
`debug`	`bool \| None`	执行期间是否打印调试信息，默认为 False。	`无`
`subgraphs`	`bool`	是否从子图内部流式传输事件，默认为 False。如果为 True，事件将以元组 `(namespace, data)` 的形式发出，如果 `stream_mode` 是一个列表，则为 `(namespace, mode, data)`，其中 `namespace` 是一个元组，包含调用子图的节点的路径，例如 `("parent_node:<task_id>", "child_node:<task_id>")`。有关更多详细信息，请参阅 LangGraph 流式传输指南。	`False`

返回

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

astream `async` ¶

astream(
    input: dict[str, Any] | Any,
    config: RunnableConfig | None = None,
    *,
    stream_mode: (
        StreamMode | list[StreamMode] | None
    ) = None,
    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`	`dict[str, Any] \| Any`	图的输入。	必需
`config`	`RunnableConfig \| None`	运行所用的配置。	`无`
`stream_mode`	`StreamMode \| list[StreamMode] \| None`	流式输出的模式，默认为 `self.stream_mode`。选项包括： `"values"`：在每个步骤之后（包括中断），发出状态中的所有值。与函数式 API 一起使用时，值在工作流结束时一次性发出。 `"updates"`：在每个步骤之后，仅发出节点或任务名称以及节点或任务返回的更新。如果在同一步骤中进行多次更新（例如，运行多个节点），则这些更新将单独发出。 `"custom"`：使用 `StreamWriter` 从节点或任务内部发出自定义数据。 `"messages"`：逐个 token 发出 LLM 消息，以及节点或任务内部任何 LLM 调用的元数据。将以 2 元组 `(LLM token, metadata)` 的形式发出。 `"debug"`：为每个步骤发出包含尽可能多信息的调试事件。您可以将列表作为 `stream_mode` 参数传递，以同时流式传输多种模式。流式输出将是 `(mode, data)` 的元组。有关更多详细信息，请参阅 LangGraph 流式传输指南。	`无`
`output_keys`	`str \| Sequence[str] \| None`	要流式传输的键，默认为所有非上下文通道。	`无`
`interrupt_before`	`All \| Sequence[str] \| None`	中断前要中断的节点，默认为图中的所有节点。	`无`
`interrupt_after`	`All \| Sequence[str] \| None`	中断后要中断的节点，默认为图中的所有节点。	`无`
`checkpoint_during`	`bool \| None`	是否检查点中间步骤，默认为 True。如果为 False，则只保存最终检查点。	`无`
`debug`	`bool \| None`	执行期间是否打印调试信息，默认为 False。	`无`
`subgraphs`	`bool`	是否从子图内部流式传输事件，默认为 False。如果为 True，事件将以元组 `(namespace, data)` 的形式发出，如果 `stream_mode` 是一个列表，则为 `(namespace, mode, data)`，其中 `namespace` 是一个元组，包含调用子图的节点的路径，例如 `("parent_node:<task_id>", "child_node:<task_id>")`。有关更多详细信息，请参阅 LangGraph 流式传输指南。	`False`

返回

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

invoke ¶

invoke(
    input: dict[str, Any] | Any,
    config: RunnableConfig | None = None,
    *,
    stream_mode: StreamMode = "values",
    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,
    **kwargs: Any
) -> dict[str, Any] | Any

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

参数

名称	类型	描述	默认值
`input`	`dict[str, Any] \| Any`	图的输入数据。它可以是字典或任何其他类型。	必需
`config`	`RunnableConfig \| None`	可选。图运行的配置。	`无`
`stream_mode`	`流模式`	可选[str]。图运行的流模式。默认为 "values"。	`'values'`
`output_keys`	`str \| Sequence[str] \| None`	可选。要从图运行中检索的输出键。	`无`
`interrupt_before`	`All \| Sequence[str] \| None`	可选。在图运行之前中断的节点。	`无`
`interrupt_after`	`All \| Sequence[str] \| None`	可选。在图运行之后中断的节点。	`无`
`debug`	`bool \| None`	可选。为图运行启用调试模式。	`无`
`**kwargs`	`任意类型`	要传递给图运行的额外关键字参数。	`{}`

返回

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

ainvoke `async` ¶

ainvoke(
    input: dict[str, Any] | Any,
    config: RunnableConfig | None = None,
    *,
    stream_mode: StreamMode = "values",
    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,
    **kwargs: Any
) -> dict[str, Any] | Any

在单个输入上异步调用图。

参数

名称	类型	描述	默认值
`input`	`dict[str, Any] \| Any`	计算的输入数据。它可以是字典或任何其他类型。	必需
`config`	`RunnableConfig \| None`	可选。计算的配置。	`无`
`stream_mode`	`流模式`	可选。计算的流模式。默认为 "values"。	`'values'`
`output_keys`	`str \| Sequence[str] \| None`	可选。结果中要包含的输出键。默认为 None。	`无`
`interrupt_before`	`All \| Sequence[str] \| None`	可选。在此之前中断的节点。默认为 None。	`无`
`interrupt_after`	`All \| Sequence[str] \| None`	可选。在此之后中断的节点。默认为 None。	`无`
`debug`	`bool \| None`	可选。是否启用调试模式。默认为 None。	`无`
`**kwargs`	`任意类型`	额外的关键字参数。	`{}`

返回

类型	描述
`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,
) -> RunnableConfig

使用给定值更新图的状态，如同它们来自节点 as_node。如果未提供 as_node，则在不模糊的情况下，它将被设置为最后更新状态的节点。

aupdate_state `async` ¶

aupdate_state(
    config: RunnableConfig,
    values: dict[str, Any] | Any,
    as_node: 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)` 形式的元组。	必需

引发

类型	描述
`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)` 形式的元组。	必需

引发

类型	描述
`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]]

获取图的子图。

参数

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

返回

类型	描述
`Iterator[tuple[str, PregelProtocol]]`	Iterator[tuple[str, PregelProtocol]]：(命名空间, 子图) 对的迭代器。

aget_subgraphs `async` ¶

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

获取图的子图。

参数

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

返回

类型	描述
`AsyncIterator[tuple[str, PregelProtocol]]`	AsyncIterator[tuple[str, PregelProtocol]]：(命名空间, 子图) 对的异步迭代器。

with_config ¶

with_config(
    config: RunnableConfig | None = None, **kwargs: Any
) -> Self

创建 Pregel 对象的副本并更新配置。