持久性¶

LangGraph 具有内置的持久性层，通过检查点程序实现。当您使用检查点程序编译图时，检查点程序会在每个超步保存图状态的checkpoint（检查点）。这些检查点保存在一个thread（线程）中，可以在图执行后访问。由于threads（线程）允许在执行后访问图的状态，因此包括人机协作、内存、时间旅行和容错等多种强大功能都成为可能。有关如何向图中添加和使用检查点程序的端到端示例，请参阅本操作指南。下面，我们将更详细地讨论这些概念。

Checkpoints

线程¶

线程是分配给检查点程序保存的每个检查点的唯一 ID 或线程标识符。当使用检查点程序调用图时，您必须将 thread_id 指定为 config（配置）的 configurable 部分

{"configurable": {"thread_id": "1"}}

检查点¶

检查点是在每个超步保存的图状态的快照，由 StateSnapshot 对象表示，具有以下关键属性

config：与此检查点关联的配置。
metadata：与此检查点关联的元数据。
values：此时刻状态通道的值。
next：图中接下来要执行的节点名称的元组。
tasks：PregelTask 对象的元组，其中包含有关要执行的下一个任务的信息。如果之前尝试过该步骤，则将包含错误信息。如果图是从节点内部动态中断的，则任务将包含与中断相关的其他数据。

让我们看看当如下调用简单图时，会保存哪些检查点

from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver
from typing import Annotated
from typing_extensions import TypedDict
from operator import add

class State(TypedDict):
    foo: str
    bar: Annotated[list[str], add]

def node_a(state: State):
    return {"foo": "a", "bar": ["a"]}

def node_b(state: State):
    return {"foo": "b", "bar": ["b"]}


workflow = StateGraph(State)
workflow.add_node(node_a)
workflow.add_node(node_b)
workflow.add_edge(START, "node_a")
workflow.add_edge("node_a", "node_b")
workflow.add_edge("node_b", END)

checkpointer = MemorySaver()
graph = workflow.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "1"}}
graph.invoke({"foo": ""}, config)

API 参考：StateGraph | START | END | MemorySaver

在我们运行图之后，我们期望看到正好 4 个检查点

以 START 作为要执行的下一个节点的空检查点
以用户输入 {'foo': '', 'bar': []} 和 node_a 作为要执行的下一个节点的检查点
以 node_a 的输出 {'foo': 'a', 'bar': ['a']} 和 node_b 作为要执行的下一个节点的检查点
以 node_b 的输出 {'foo': 'b', 'bar': ['a', 'b']} 和没有要执行的下一个节点的检查点

请注意，由于我们为 bar 通道设置了 reducer（归约器），因此 bar 通道值包含来自两个节点的输出。

获取状态¶

当与已保存的图状态交互时，您必须指定一个线程标识符。您可以通过调用 graph.get_state(config) 来查看图的最新状态。这将返回一个 StateSnapshot 对象，该对象对应于与 config（配置）中提供的线程 ID 关联的最新检查点，或者如果提供了检查点 ID，则对应于与该线程的检查点 ID 关联的检查点。

# get the latest state snapshot
config = {"configurable": {"thread_id": "1"}}
graph.get_state(config)

# get a state snapshot for a specific checkpoint_id
config = {"configurable": {"thread_id": "1", "checkpoint_id": "1ef663ba-28fe-6528-8002-5a559208592c"}}
graph.get_state(config)

在我们的示例中，get_state 的输出将如下所示

StateSnapshot(
    values={'foo': 'b', 'bar': ['a', 'b']},
    next=(),
    config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28fe-6528-8002-5a559208592c'}},
    metadata={'source': 'loop', 'writes': {'node_b': {'foo': 'b', 'bar': ['b']}}, 'step': 2},
    created_at='2024-08-29T19:19:38.821749+00:00',
    parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f9-6ec4-8001-31981c2c39f8'}}, tasks=()
)

获取状态历史¶

您可以通过调用 graph.get_state_history(config) 来获取给定线程的图执行的完整历史记录。这将返回一个与 config（配置）中提供的线程 ID 关联的 StateSnapshot 对象列表。重要的是，检查点将按时间顺序排列，最新的检查点 / StateSnapshot 在列表的最前面。

config = {"configurable": {"thread_id": "1"}}
list(graph.get_state_history(config))

在我们的示例中，get_state_history 的输出将如下所示

[
    StateSnapshot(
        values={'foo': 'b', 'bar': ['a', 'b']},
        next=(),
        config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28fe-6528-8002-5a559208592c'}},
        metadata={'source': 'loop', 'writes': {'node_b': {'foo': 'b', 'bar': ['b']}}, 'step': 2},
        created_at='2024-08-29T19:19:38.821749+00:00',
        parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f9-6ec4-8001-31981c2c39f8'}},
        tasks=(),
    ),
    StateSnapshot(
        values={'foo': 'a', 'bar': ['a']}, next=('node_b',),
        config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f9-6ec4-8001-31981c2c39f8'}},
        metadata={'source': 'loop', 'writes': {'node_a': {'foo': 'a', 'bar': ['a']}}, 'step': 1},
        created_at='2024-08-29T19:19:38.819946+00:00',
        parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f4-6b4a-8000-ca575a13d36a'}},
        tasks=(PregelTask(id='6fb7314f-f114-5413-a1f3-d37dfe98ff44', name='node_b', error=None, interrupts=()),),
    ),
    StateSnapshot(
        values={'foo': '', 'bar': []},
        next=('node_a',),
        config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f4-6b4a-8000-ca575a13d36a'}},
        metadata={'source': 'loop', 'writes': None, 'step': 0},
        created_at='2024-08-29T19:19:38.817813+00:00',
        parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f0-6c66-bfff-6723431e8481'}},
        tasks=(PregelTask(id='f1b14528-5ee5-579c-949b-23ef9bfbed58', name='node_a', error=None, interrupts=()),),
    ),
    StateSnapshot(
        values={'bar': []},
        next=('__start__',),
        config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f0-6c66-bfff-6723431e8481'}},
        metadata={'source': 'input', 'writes': {'foo': ''}, 'step': -1},
        created_at='2024-08-29T19:19:38.816205+00:00',
        parent_config=None,
        tasks=(PregelTask(id='6d27aa2e-d72b-5504-a36f-8620e54a76dd', name='__start__', error=None, interrupts=()),),
    )
]

State

重放¶

也可以回放之前的图执行。如果我们使用 thread_id 和 checkpoint_id 调用图，那么我们将重放与 checkpoint_id 对应的检查点之前的先前执行的步骤，并且仅执行检查点之后的步骤。

thread_id 是线程的 ID。
checkpoint_id 是指线程内特定检查点的标识符。

当调用图时，您必须将这些作为 config（配置）的 configurable 部分传递

config = {"configurable": {"thread_id": "1", "checkpoint_id": "0c62ca34-ac19-445d-bbb0-5b4984975b2a"}}
graph.invoke(None, config=config)

重要的是，LangGraph 知道特定的步骤是否之前已执行过。如果已执行过，LangGraph 只需重放图中的特定步骤，而不会重新执行该步骤，但这仅适用于 checkpoint_id 之前的步骤。 checkpoint_id 之后的所有步骤都将被执行（即，新的分支），即使它们之前已执行过。有关重放的更多信息，请参阅此关于时间旅行的操作指南。

Replay

更新状态¶

除了从特定的 checkpoints（检查点）重放图之外，我们还可以编辑图状态。我们使用 graph.update_state() 来执行此操作。此方法接受三个不同的参数

`config`¶

config（配置）应包含 thread_id，用于指定要更新的线程。当仅传递 thread_id 时，我们将更新（或分支）当前状态。或者，如果我们包含 checkpoint_id 字段，那么我们将分支所选的检查点。

`values`¶

这些是将用于更新状态的值。请注意，此更新的处理方式与来自节点的任何更新的处理方式完全相同。这意味着这些值将被传递给reducer（归约器）函数（如果它们是为图状态中的某些通道定义的）。这意味着 update_state 不会自动覆盖每个通道的通道值，而仅覆盖没有 reducer（归约器）的通道。让我们来看一个例子。

假设您已使用以下架构定义了图的状态（请参阅上面的完整示例）

from typing import Annotated
from typing_extensions import TypedDict
from operator import add

class State(TypedDict):
    foo: int
    bar: Annotated[list[str], add]

现在假设图的当前状态是

{"foo": 1, "bar": ["a"]}

如果您如下更新状态

graph.update_state(config, {"foo": 2, "bar": ["b"]})

那么图的新状态将是

{"foo": 2, "bar": ["a", "b"]}

foo 键（通道）已完全更改（因为没有为该通道指定 reducer（归约器），因此 update_state 会覆盖它）。但是，为 bar 键指定了 reducer（归约器），因此它会将 "b" 附加到 bar 的状态。

`as_node`¶

当调用 update_state 时，您可以选择指定的最后一件事是 as_node。如果您提供了它，则更新将应用，就好像它来自节点 as_node 一样。如果未提供 as_node，则会将其设置为最后一个更新状态的节点（如果不是模棱两可）。这很重要的原因是，要执行的后续步骤取决于最后一个给出更新的节点，因此这可以用于控制接下来执行哪个节点。有关分支状态的更多信息，请参阅此关于时间旅行的操作指南。

Update

内存存储¶

Model of shared state

状态架构指定在执行图时填充的一组键。如上所述，状态可以由检查点程序写入线程中的每个图步骤，从而实现状态持久性。

但是，如果我们想在线程之间保留一些信息怎么办？考虑一下聊天机器人的情况，我们希望保留有关用户在与该用户的所有聊天对话（例如，线程）中的特定信息！

仅使用检查点程序，我们无法在线程之间共享信息。这促使我们需要 Store 接口。作为示例，我们可以定义一个 InMemoryStore 来存储有关用户在线程之间的信息。我们只需像以前一样使用检查点程序和新的 in_memory_store 变量编译我们的图。

基本用法¶

首先，让我们在不使用 LangGraph 的情况下单独展示这一点。

from langgraph.store.memory import InMemoryStore
in_memory_store = InMemoryStore()

内存按 tuple（元组）命名空间，在本例中，它将是 (<user_id>, "memories")。命名空间可以是任意长度，可以表示任何内容，不必是用户特定的。

user_id = "1"
namespace_for_memory = (user_id, "memories")

我们使用 store.put 方法将内存保存到存储中的命名空间。当我们这样做时，我们指定命名空间（如上定义）和一个用于内存的键值对：键只是内存的唯一标识符 (memory_id)，值（字典）是内存本身。

memory_id = str(uuid.uuid4())
memory = {"food_preference" : "I like pizza"}
in_memory_store.put(namespace_for_memory, memory_id, memory)

我们可以使用 store.search 方法在我们的命名空间中读取内存，这将返回给定用户的所有内存作为列表。最新的内存是列表中的最后一个。

memories = in_memory_store.search(namespace_for_memory)
memories[-1].dict()
{'value': {'food_preference': 'I like pizza'},
 'key': '07e0caf4-1631-47b7-b15f-65515d4c1843',
 'namespace': ['1', 'memories'],
 'created_at': '2024-10-02T17:22:31.590602+00:00',
 'updated_at': '2024-10-02T17:22:31.590605+00:00'}

每种内存类型都是一个 Python 类 (Item)，具有某些属性。我们可以通过 .dict 转换为字典来访问它，如上所示。它具有的属性是

value：此内存的值（本身是一个字典）
key：此内存在此命名空间中的唯一键
namespace：字符串列表，此内存类型的命名空间
created_at：创建此内存的时间戳
updated_at：更新此内存的时间戳

语义搜索¶

除了简单的检索之外，存储还支持语义搜索，允许您根据含义而不是完全匹配来查找内存。要启用此功能，请使用嵌入模型配置存储

from langchain.embeddings import init_embeddings

store = InMemoryStore(
    index={
        "embed": init_embeddings("openai:text-embedding-3-small"),  # Embedding provider
        "dims": 1536,                              # Embedding dimensions
        "fields": ["food_preference", "$"]              # Fields to embed
    }
)

API 参考：init_embeddings

现在搜索时，您可以使用自然语言查询来查找相关内存

# Find memories about food preferences
# (This can be done after putting memories into the store)
memories = store.search(
    namespace_for_memory,
    query="What does the user like to eat?",
    limit=3  # Return top 3 matches
)

您可以通过配置 fields 参数或在存储内存时指定 index 参数来控制嵌入内存的哪些部分

# Store with specific fields to embed
store.put(
    namespace_for_memory,
    str(uuid.uuid4()),
    {
        "food_preference": "I love Italian cuisine",
        "context": "Discussing dinner plans"
    },
    index=["food_preference"]  # Only embed "food_preferences" field
)

# Store without embedding (still retrievable, but not searchable)
store.put(
    namespace_for_memory,
    str(uuid.uuid4()),
    {"system_info": "Last updated: 2024-01-01"},
    index=False
)

在 LangGraph 中使用¶

有了这一切，我们在 LangGraph 中使用 in_memory_store。 in_memory_store 与检查点程序协同工作：检查点程序将状态保存到线程，如上所述，而 in_memory_store 允许我们存储任意信息以供跨线程访问。我们使用检查点程序和 in_memory_store 编译图，如下所示。

from langgraph.checkpoint.memory import MemorySaver

# We need this because we want to enable threads (conversations)
checkpointer = MemorySaver()

# ... Define the graph ...

# Compile the graph with the checkpointer and store
graph = graph.compile(checkpointer=checkpointer, store=in_memory_store)

API 参考：MemorySaver

我们像以前一样使用 thread_id 调用图，并且还使用 user_id，我们将使用它来将我们的内存命名空间限定到这个特定用户，如上所示。

# Invoke the graph
user_id = "1"
config = {"configurable": {"thread_id": "1", "user_id": user_id}}

# First let's just say hi to the AI
for update in graph.stream(
    {"messages": [{"role": "user", "content": "hi"}]}, config, stream_mode="updates"
):
    print(update)

我们可以通过传递 store: BaseStore 和 config: RunnableConfig 作为节点参数来访问任何节点中的 in_memory_store 和 user_id。以下是如何在节点中使用语义搜索来查找相关内存的示例

def update_memory(state: MessagesState, config: RunnableConfig, *, store: BaseStore):

    # Get the user id from the config
    user_id = config["configurable"]["user_id"]

    # Namespace the memory
    namespace = (user_id, "memories")

    # ... Analyze conversation and create a new memory

    # Create a new memory ID
    memory_id = str(uuid.uuid4())

    # We create a new memory
    store.put(namespace, memory_id, {"memory": memory})

如上所示，我们还可以在任何节点中访问存储，并使用 store.search 方法来获取内存。回想一下，内存作为可以转换为字典的对象列表返回。

memories[-1].dict()
{'value': {'food_preference': 'I like pizza'},
 'key': '07e0caf4-1631-47b7-b15f-65515d4c1843',
 'namespace': ['1', 'memories'],
 'created_at': '2024-10-02T17:22:31.590602+00:00',
 'updated_at': '2024-10-02T17:22:31.590605+00:00'}

我们可以访问内存并在我们的模型调用中使用它们。

def call_model(state: MessagesState, config: RunnableConfig, *, store: BaseStore):
    # Get the user id from the config
    user_id = config["configurable"]["user_id"]

    # Search based on the most recent message
    memories = store.search(
        namespace,
        query=state["messages"][-1].content,
        limit=3
    )
    info = "\n".join([d.value["memory"] for d in memories])

    # ... Use memories in the model call

如果我们创建一个新线程，只要 user_id 相同，我们仍然可以访问相同的内存。

# Invoke the graph
config = {"configurable": {"thread_id": "2", "user_id": "1"}}

# Let's say hi again
for update in graph.stream(
    {"messages": [{"role": "user", "content": "hi, tell me about my memories"}]}, config, stream_mode="updates"
):
    print(update)

当我们使用 LangGraph 平台时，无论是在本地（例如，在 LangGraph Studio 中）还是使用 LangGraph Cloud，默认情况下都可以使用基本存储，并且在图编译期间不需要指定。但是，要启用语义搜索，您需要在 langgraph.json 文件中配置索引设置。例如

{
    ...
    "store": {
        "index": {
            "embed": "openai:text-embeddings-3-small",
            "dims": 1536,
            "fields": ["$"]
        }
    }
}

有关更多详细信息和配置选项，请参阅部署指南。

检查点库¶

在底层，检查点由符合 BaseCheckpointSaver 接口的检查点程序对象提供支持。LangGraph 提供了几种检查点程序实现，所有实现都通过独立的、可安装的库实现

langgraph-checkpoint：检查点程序保存器的基本接口 (BaseCheckpointSaver) 和序列化/反序列化接口 (SerializerProtocol)。包括用于实验的内存检查点程序实现 (InMemorySaver)。LangGraph 附带了 langgraph-checkpoint。
langgraph-checkpoint-sqlite：LangGraph 检查点程序的实现，它使用 SQLite 数据库 (SqliteSaver / AsyncSqliteSaver)。非常适合实验和本地工作流程。需要单独安装。
langgraph-checkpoint-postgres：高级检查点程序，它使用 Postgres 数据库 (PostgresSaver / AsyncPostgresSaver)，在 LangGraph Cloud 中使用。非常适合在生产中使用。需要单独安装。

检查点接口¶

每个检查点程序都符合 BaseCheckpointSaver 接口，并实现以下方法

.put - 存储具有其配置和元数据的检查点。
.put_writes - 存储链接到检查点的中间写入（即待处理写入）。
.get_tuple - 使用给定配置（thread_id 和 checkpoint_id）获取检查点元组。这用于在 graph.get_state() 中填充 StateSnapshot。
.list - 列出与给定配置和筛选条件匹配的检查点。这用于在 graph.get_state_history() 中填充状态历史记录

如果检查点程序与异步图执行一起使用（即通过 .ainvoke、.astream、.abatch 执行图），将使用上述方法的异步版本 (.aput、.aput_writes、.aget_tuple、.alist)。

注意

对于异步运行图，您可以使用 MemorySaver，或 Sqlite/Postgres 检查点程序的异步版本 -- AsyncSqliteSaver / AsyncPostgresSaver 检查点程序。

序列化器¶

当检查点程序保存图状态时，它们需要序列化状态中的通道值。这是使用序列化器对象完成的。 langgraph_checkpoint 定义了用于实现序列化器的协议，并提供了一个默认实现 (JsonPlusSerializer)，它可以处理各种类型，包括 LangChain 和 LangGraph 原语、日期时间、枚举等等。

功能

人机协作¶

首先，检查点程序通过允许人类检查、中断和批准图步骤来促进人机协作工作流程。这些工作流程需要检查点程序，因为人类必须能够随时查看图的状态，并且图必须能够在人类对状态进行任何更新后恢复执行。有关具体示例，请参阅这些操作指南。

内存¶

其次，检查点程序允许交互之间存在“内存”。在重复的人工交互（如对话）的情况下，任何后续消息都可以发送到该线程，该线程将保留其先前消息的内存。有关如何使用检查点程序添加和管理对话内存的端到端示例，请参阅本操作指南。

时间旅行¶

第三，检查点程序允许“时间旅行”，允许用户重放之前的图执行以查看和/或调试特定的图步骤。此外，检查点程序使在任意检查点分支图状态以探索替代轨迹成为可能。

容错¶

最后，检查点程序还提供容错和错误恢复：如果一个或多个节点在给定的超步中失败，您可以从上次成功的步骤重新启动图。此外，当图节点在给定的超步中执行期间失败时，LangGraph 会存储来自在该超步中成功完成的任何其他节点的待处理检查点写入，以便每当我们从该超步恢复图执行时，我们都不会重新运行成功的节点。

待处理写入¶

此外，当图节点在给定的超步中执行期间失败时，LangGraph 会存储来自在该超步中成功完成的任何其他节点的待处理检查点写入，以便每当我们从该超步恢复图执行时，我们都不会重新运行成功的节点。