[拆解LangChain执行引擎]支持自然语言查询的长期存储

Pregel的Checkpointer采用基于Checkpoint的持久化记录下一个以Thread ID标识的对话历史，这种基于会话的持久化属于短期存储。复杂的流程在运行的时候还需要跨越多个对话的长期甚至永久存储，这类存储被抽象成一个BaseStore类型，采用内存存储的InMemoryStore它的常用实现。
1. BaseStore

Pregel的长期存储不再仅仅是存储简单的键值对，它具有一个支持层次化命名空间，还支持基于向量检索的自然语言查询，以及生命周期管理（TTL）。

1. class BaseStore(ABC):
2.     supports_ttl: bool = False
3. ttl_config: TTLConfig | None = None
4. …
6. class TTLConfig(TypedDict, total=False):
7.     refresh_on_read: bool
8.     default_ttl: float | None
9.     sweep_interval_minutes: int | None

复制代码

我们先来是说基于生命周期的TTL如何使用，存储是否提供针对TTL的支持可以利用其supports_ttl字段来判断，而ttl_config字段返回的TTLConfig提供了TTL的相关配置，它包括如下的配置项：

• refresh_on_read（bool）：决定了 “读取” 动作是否会延长数据的寿命，类似于滑动窗口缓存机制。如果不显式配置，通常默认为True。当执行get或search方法时，系统会自动重置该数据条目的过期计时器。开启此选项适用于 “活跃用户会话” ，只要用户还在持续提问或交互，其长期记忆就一直保留。只有当用户长时间不使用时，数据才会被清理。否则数据寿命自创建起固定，无论读取多少次，到期即删。
  
• default_ttl（float | None）：定义 数据项默认过期时间，单位为分钟。默认为None，意味着数据永久有效。当新的数据项被存入时，它会被赋予一个初始倒计时。为存储的数据设置一个合理的生命周期有助于防止数据库随着时间推移被无用的僵尸数据填满。
  
• sweep_interval_minutes（int | None）：该配置决定了后端引擎清理过期数据的频率。默认为None，表示不执行定期扫描。系统会维护一个异步数据清除任务，以设定的频率扫描数据库，删除那些倒计时归零的条目。如果没有配置此项，某些后端可能只在读取时发现数据过期（惰性删除），而不会主动回收磁盘空间。对于InMemoryStore，这非常关键，定期清理能防止内存会持续膨胀。对于支持原生 TTL 的数据库（如 Redis），此配置可能被忽略，因为数据库引擎具有自己的清理策略。
  数据项的存入利用如下所示的put/aput方法完成，数据以“键值对”+“命名空间”的形式被存储，其中值以字典的形式提供字段和值的映射关系，具有层级的命名空间以字符串元组的形式提供。ttl参数可以为存入的数据指定一个针对性的过期时间。
  

1. class BaseStore(ABC):
2.    def put(
3.         self,
4.         namespace: tuple[str, ...],
5.         key: str,
6.         value: dict[str, Any],
7.         index: Literal[False] | list[str] | None = None,
8.         *,
9.         ttl: float | None | NotProvided = NOT_PROVIDED,
10. ) -> None:
12.     async def aput(
13.         self,
14.         namespace: tuple[str, ...],
15.         key: str,
16.         value: dict[str, Any],
17.         index: Literal[False] | list[str] | None = None,
18.         *,
19.         ttl: float | None | NotProvided = NOT_PROVIDED,
20.     ) -> None

复制代码

put/aput方法的参数index决定该数据项是否进入向量索引。如果我们只是简单地存入数据而不指定index，这些数据就像锁在保险箱里，只能通过精确的命名空间和键取回。如果我们采用list[str]的形式之定义多个索引字段，系统会提取这些字段的内容利用LLM生成嵌入（Embedding）向量进行存储，那么后续就能针对它们进行语义搜索。
get/aget方法根据提供的命名空间+键 的组合将对应的数据项提取出来，refresh_ttl参数决定是否重置该数据项的过期时间。方法返回的是一个Item对象，我们可以从中提取数据项的键、值、命名空间以及创建和最近修改的时间戳。Item类型的dict方法将自身转换成字典，两个时间类型会转换成ISO格式的字符串，相当于提供序列化的能力（datetime对象能直接被序列化）。

1. class BaseStore(ABC):
2.     def get(
3.         self,
4.         namespace: tuple[str, ...],
5.         key: str,
6.         *,
7.         refresh_ttl: bool | None = None,
8. ) -> Item | None
10.     async def aget(
11.         self,
12.         namespace: tuple[str, ...],
13.         key: str,
14.         *,
15.         refresh_ttl: bool | None = None,
16. ) -> Item | None
17. …
19. class Item:
20.     __slots__ = ("value", "key", "namespace", "created_at", "updated_at")
21.     def dict(self) -> dict
22.     …

复制代码

BaseStore提供了用于查询的search/asearch方法，我们调用这两个方法是时必须指定命名空间前缀。我们可以利用query参数实施基于自然语言的查询，它会触发底层存储的向量相似度搜索。filter参数以字典的形式提供基于多个字段的组合查询条件。limit和offset参数作为典型的分页参数，前者指定本次搜索返回结果的最大条目数，后者指定在返回结果集之前要跳过的条目数量。至于refresh_ttl参数，同样是用于决定是否重置过期时间。

1. class BaseStore(ABC):
2.     def search(
3.         self,
4.         namespace_prefix: tuple[str, ...],
5.         /,
6.         *,
7.         query: str | None = None,
8.         filter: dict[str, Any] | None = None,
9.         limit: int = 10,
10.         offset: int = 0,
11.         refresh_ttl: bool | None = None,
12. ) -> list[SearchItem]:   
14.     async def asearch(
15.         self,
16.         namespace_prefix: tuple[str, ...],
17.         /,
18.         *,
19.         query: str | None = None,
20.         filter: dict[str, Any] | None = None,
21.         limit: int = 10,
22.         offset: int = 0,
23.         refresh_ttl: bool | None = None,
24.     ) -> list[SearchItem]
25.     …
27. class SearchItem(Item):
28.     __slots__ = ("score",)
29.     def dict(self) -> dict:
30.         result = super().dict()
31.         result["score"] = self.score
32.         return result

复制代码

search/asearch方法返回的不是迭代器，而是一个固化的SearchItem列表。SearchItem继承自Item，字段score是该类型存在的唯一理由，它代表搜索结果与查询之间的相关程度。具体数值取决于底层的向量存储 ，通常会采用余弦相似度或欧氏距离。它的dict方法会在基类返回的字典上将score代表的相似度得分添加进去。
除了上述的这些常规方法，BaseStore还提供用于删除指定数据项的delete方法，和get/aget方法一样，我们调用此方法时需要指定准确的命名空间和键。list_namespaces/alist_namespaces方法会根据指定的前缀/后缀查询命名空间的。

1. class BaseStore(ABC):
2.     def delete(self, namespace: tuple[str, ...], key: str) -> None        
4.     def list_namespaces(
5.         self,
6.         *,
7.         prefix: NamespacePath | None = None,
8.         suffix: NamespacePath | None = None,
9.         max_depth: int | None = None,
10.         limit: int = 100,
11.         offset: int = 0,
12.     ) -> list[tuple[str, ...]]
14.     async def alist_namespaces(
15.         self,
16.         *,
17.         prefix: NamespacePath | None = None,
18.         suffix: NamespacePath | None = None,
19.         max_depth: int | None = None,
20.         limit: int = 100,
21.         offset: int = 0,
22. ) -> list[tuple[str, ...]]
23. …
25. NamespacePath = tuple[str | Literal["*"], ...]

复制代码

BaseStore的实现类型必须实现它的batch/abatch方法。这两个抽象方法也是BaseStore最核心的方法，因为其他的快捷方法（如get、put、search）在底层通常都是封装成一个单操作的batch来执行的。在分布式图计算中， 工作 Node可能位于不同的服务器，合并多个操作对于较少时延尤为重要。

1. class BaseStore(ABC):
2.     @abstractmethod
3.     def batch(self, ops: Iterable[Op]) -> list[Result]
4.     @abstractmethod
5.     async def abatch(self, ops: Iterable[Op]) -> list[Result]   
6. ...
8. Op = GetOp | SearchOp | PutOp | ListNamespacesOp
9. Result = Item | list[Item] | list[SearchItem] | list[tuple[str, ...]] | None

复制代码

被batch/abatch方法打包的四个操作（get、search、put和list_namespaces）分别定义成如下的类型，各自的字段基本上对应这个快捷方法的参数。batch/abatch返回的是元素类型为Result的列表。

1. class GetOp(NamedTuple):
2.     namespace: tuple[str, ...]
3.     key: str
4.     refresh_ttl: bool = True
5. class SearchOp(NamedTuple):
6.     namespace_prefix: tuple[str, ...]
7.     filter: dict[str, Any] | None = None
8.     limit: int = 10
9.     offset: int = 0
10.     query: str | None = None
11. refresh_ttl: bool = True
13. class MatchCondition(NamedTuple):
14.     match_type: NamespaceMatchType
15.     path: NamespacePath
17. class ListNamespacesOp(NamedTuple):
18.     match_conditions: tuple[MatchCondition, ...] | None = None
19.     max_depth: int | None = None
20.     limit: int = 100
21.     offset: int = 0
23. class PutOp(NamedTuple):
24.     namespace: tuple[str, ...]
25.     key: str
26.     value: dict[str, Any] | None
27.     index: Literal[False] | list[str] | None =
28.     ttl: float | None = None

复制代码

2.InMemoryStore

InMemoryStore在内部利用一个字典来存储数据项（即众多具有命名空间的键值对），并针对这个结构提供单记录的读取和多记录的查询。由于需要提供自然语言查询功能，InMemoryStore需要利用语言模型将文本转换成多维嵌入向量的能力。
我们知道嵌入（Embedding）是语言模型的一项核心概念，它来源于拓扑学和几何学，它表示的是将一个低维的对象，“嵌入”到一个高维的连续空间中并保持其结构不变。基本的原理是：定义一个N维的语义空间，将文本根据其表达的语义转换成该空间的一个点，并通过N维的向量来表示。我们一般将这个语义空间称为嵌入空间，对应点的向量称为嵌入向量。嵌入的原则很明确，那就是让具有相似语义的文本对应的点在嵌入空间尽量靠近，否则使它们尽量远离。
如果我们将数据库记录相关的文本字段转换成对应的嵌入向量，那么实现基于自然语言的查询就很容易实现：将查询文本采用相同的嵌入规则转换成向量，以两个点在嵌入空间的距离（比如欧氏距离）或者向量之间的夹角（余弦相似度）作为相似语义的度量对数据项实施查询。我们将这种查询方式称为向量检索。InMemoryStore采用的是基于余弦相似度的检索方式。
初始化InMemoryStore对象的时候，需要提供一个IndexConfig对象来对采用的向量索引进行配置。IndexConfig的dims字段表示嵌入空间的温度，而fields字段提供参与嵌入转换的字段。嵌入功能可以由一个Embeddings对象提供，它利用两组方法embed_documents/aembed_documents和embed_query/aembed_query提供了针对待检索的文档（针对数据项）和查询文本实施嵌入。EmbeddingsFunc和AEmbeddingsFunc以可执行对象的形式提供了相同的功能表达。这三种形式对embed字段的设置都是支持的。

1. class InMemoryStore(BaseStore):
3.     def __init__(self, *, index: IndexConfig | None = None) -> None:
5. class IndexConfig(TypedDict, total=False):
6.     dims: int
7.     embed: Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str       
8. fields: list[str] | None
10. class Embeddings(ABC):
11.     @abstractmethod
12.     def embed_documents(self, texts: list[str]) -> list[list[float]]:
13.     @abstractmethod
14.     def embed_query(self, text: str) -> list[float]:
15.     async def aembed_documents(self, texts: list[str]) -> list[list[float]]:
16. async def aembed_query(self, text: str) -> list[float]:
17. EmbeddingsFunc = Callable[[Sequence[str]], list[list[float]]]
18. AEmbeddingsFunc = Callable[[Sequence[str]], Awaitable[list[list[float]]]]

复制代码

对于2.0之前的版本还支持将其设置为一个预定义的Embeddings名称，内部会调用langchain.embeddings.init_embeddings函数提取内部的映射得到对应的Embeddings对象，但是这个langchain.embeddings包已经与最新版本的LangChain不兼容了。指定的Embeddings应该与嵌入空间维度相匹配，而嵌入是语言模型提供的能力，我们可以根据选择的语言模型和版本指定对应的维度。比如我们可以通过如下的方式得到 “text-embedding-3-small” 这个模型采用的嵌入空间维度是1536。

1. from langchain_openai import OpenAIEmbeddings
3. embeddings = OpenAIEmbeddings(
4.     model="text-embedding-3-small",
5.     api_key= ,
6.     base_url=<base_url>,
7. )
9. vector = embeddings.embed_query("Hello world")
10. print(1536==len(vector))

复制代码

在如下的演示程序中，我们针对模型text-embedding-3-small创建了一个OpenAIEmbeddings，并据此创建了一个InMemoryStore对象。然后我们以命名空间profile.instrests存入了两个分别针对饮食和运动喜好的数据项。

1. from langchain_openai import OpenAIEmbeddings
2. from langgraph.store.base import IndexConfig
3. from langgraph.store.memory import InMemoryStore
4. import json
6. base_url = "base URL of you deployed model"
7. model_name = "text-embedding-3-small"
8. api_key ="your api key"
10. embeddings = OpenAIEmbeddings(
11.     model="text-embedding-3-small",
12.     api_key=api_key,
13.     base_url=base_url,
14. )
16. store = InMemoryStore(
17.     index=IndexConfig(
18.         embed=embeddings,
19.         dims=1536
20.     )
21. )
23. namespace = ("profile", "interests")
24. store.put(namespace, "foods", {"text": "I love eating spicy Sichuan food."})
25. store.put(namespace, "sports", {"text": "My favorite sport is swimming."})
27. results = store.search(namespace, query="What are my food preferences?", limit=1)
29. for item  in results:   
30.     print(json.dumps(item.dict(), indent=2))   

复制代码

我们指定命名空间调用InMemoryStore对象的search方法以自然语言的形式（“What are my food preferences?”）实施查询。由于我们只有两条数据，所以我们将limit参数设置为1返回匹配度最高的那一条，我们会得到希望的第一条数据。如下所示的是查询结果。

1. {
2.   "namespace": [
3.     "profile",
4.     "interests"
5.   ],
6.   "key": "foods",
7.   "value": {
8.     "text": "I love eating spicy Sichuan food."
9.   },
10.   "created_at": "2026-01-28T02:53:58.641680+00:00",
11.   "updated_at": "2026-01-28T02:53:58.641682+00:00",
12.   "score": 0.3216021020504674
13. }

复制代码

3. 在Pregel中的使用

如果需要在Pregel中使用长期存储，需要在初始化Pregel对象的时候提供对应的BaseStore对象。由于Node处理函数不支持针对BaseStore的直接注入，我们还得像使用静态上下文和StreamWriter一样，从注入的RunnableConfig配置中得到当前的Runtime对象，它的store字段返回的就是我们指定的BaseStore对象。
我们使用上面创建用于存储用于个人喜好的InMemoryStore编写了如下这个演示程序，这次我们将用户ID放进命名空间（{user_id}.{interests}）。我们使用静态上下文类型User来传递用户ID，所以在初始化Pregel对象的时候，除了需要指定store之外，还需要将User类型设置为context_schema。

1. from langchain_openai import OpenAIEmbeddings
2. from langgraph.store.base import BaseStore, IndexConfig
3. from langgraph.store.memory import InMemoryStore
4. from langgraph.types import RunnableConfig
5. from langgraph.runtime import Runtime
6. from langgraph.pregel import Pregel, NodeBuilder
7. from langgraph.channels import LastValue
9. class User:
10.     user_id: str
11.     def __init__(self, user_id:str):
12.         self.user_id = user_id
14. def handle(query: str, config:RunnableConfig) -> str:
15.     runtime: Runtime = config["configurable"].get("__pregel_runtime")
16.     store:BaseStore = runtime.store
17.     user_id = runtime.context.user_id
18.     namespace = (user_id, "interests")
19.     results = store.search(namespace, query=query, limit=1)
20.     if len(results) > 0:
21.         return results[0].value["text"]
22.     return "No interests found."   
24. node =(NodeBuilder()
25.        .subscribe_only("query")
26.        .do(handle)
27.        .write_to("answer"))
29. def build_store() -> BaseStore:
30.     embeddings = OpenAIEmbeddings(
31.         model="text-embedding-3-small",
32.         api_key="your api key",
33.         base_url=" base URL of you deployed model"
34.     )
35.     store = InMemoryStore(
36.         index=IndexConfig(
37.             embed=embeddings,
38.             dims=1536
39.         )
40.     )
42.     namespace = ("jyden", "interests")
43.     store.put(namespace, "foods", {"text": "I love eating spicy Sichuan food."})
44.     store.put(namespace, "sports", {"text": "My favorite sport is swimming."})
45.     return store
47. app = Pregel(
48.     nodes={"body": node},
49.     channels={"query": LastValue(str), "answer": LastValue(str)},
50.     input_channels=["query"],
51.     output_channels=["answer"],
52.     store= build_store(),
53.     context_schema=User)
55. result = app.invoke(
56.     input={"query": "What is my favorite sport?"},
57.     context=User(user_id="jyden"))
58. assert result == {"answer": "My favorite sport is swimming."}
60. result = app.invoke(
61.     input={"query": "What are my food preferences?"},
62.     context=User(user_id="jyden"))
63. assert result == {"answer": "I love eating spicy Sichuan food."}

复制代码

调用Pregel对象时利用指定的静态上下文指定用户ID，并将针对用户喜好的查询文本写入输入Channel“query”，并触发唯一的用于响应查询的Node。在Node的处理函数中，我们直接将查询文本中作为参数，并从另一个RunnableConfig类型的参数中提取静态上下文和BaseStore对象。在从静态上下文得到用户ID后，我们用它生成对应的命名空间针对得到BaseStore对象实施查询，并返回最终的查询结果。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！