存储¶
持久化键值存储的基类和类型。
存储提供了可在线程和对话之间持久存在的长期记忆。支持分层命名空间、键值存储和可选的向量搜索。
核心类型
- BaseStore:具有同步/异步操作的存储接口
- Item:带有元数据的已存储键值对
- Op:Get/Put/Search/List 操作
模块
名称 | 描述 |
---|---|
batch |
用于在后台任务中批量处理操作的实用程序。 |
embed |
用于处理嵌入函数和 LangChain 的 Embeddings 接口的实用程序。 |
类
名称 | 描述 |
---|---|
Embeddings |
嵌入模型的接口。 |
项 |
表示一个带有元数据的存储项。 |
GetOp |
通过其命名空间和键来检索特定项的操作。 |
SearchOp |
在指定的命名空间层级中搜索项的操作。 |
MatchCondition |
表示用于匹配存储中命名空间的模式。 |
ListNamespacesOp |
列出和过滤存储中命名空间的操作。 |
PutOp |
在存储中存储、更新或删除项的操作。 |
基础存储 |
用于持久化键值存储的抽象基类。 |
函数
名称 | 描述 |
---|---|
ensure_embeddings |
确保嵌入函数符合 LangChain 的 Embeddings 接口。 |
get_text_at_path |
使用路径表达式或预分词的路径从对象中提取文本。 |
tokenize_path |
将路径分词为组件。 |
属性
名称 | 类型 | 描述 |
---|---|---|
NamespacePath |
一个表示命名空间路径的元组,可以包含通配符。 |
|
NamespaceMatchType |
指定如何匹配命名空间路径。 |
NamespacePath module-attribute
¶
NamespaceMatchType module-attribute
¶
NamespaceMatchType = Literal['prefix', 'suffix']
指定如何匹配命名空间路径。
值
"prefix":从命名空间的开头匹配 "suffix":从命名空间的末尾匹配
Embeddings ¶
基类:ABC
嵌入模型的接口。
这是一个用于实现文本嵌入模型的接口。
文本嵌入模型用于将文本映射到一个向量(n 维空间中的一个点)。
相似的文本通常会被映射到该空间中彼此接近的点。具体什么是“相似”以及如何在该空间中测量“距离”的细节,取决于具体的嵌入模型。
此抽象包含一个用于嵌入文档列表的方法和一个用于嵌入查询文本的方法。查询文本的嵌入预期为单个向量,而文档列表的嵌入预期为向量列表。
通常,查询嵌入与文档嵌入相同,但该抽象允许独立处理它们。
除了同步方法,该接口还提供了方法的异步版本。
默认情况下,异步方法是使用同步方法实现的;但是,实现可以选择用异步原生实现来覆盖异步方法以提高性能。
方法
名称 | 描述 |
---|---|
embed_documents |
嵌入搜索文档。 |
embed_query |
嵌入查询文本。 |
aembed_documents |
异步嵌入搜索文档。 |
aembed_query |
异步嵌入查询文本。 |
NotProvided ¶
哨兵单例。
Item ¶
SearchItem ¶
GetOp ¶
SearchOp ¶
基类:NamedTuple
在指定的命名空间层级中搜索项的操作。
此操作支持在给定的命名空间前缀内进行结构化筛选和自然语言搜索。它通过 limit 和 offset 参数提供分页功能。
注意
自然语言搜索支持取决于您的存储实现。
示例
带筛选和分页的搜索
SearchOp(
namespace_prefix=("documents",),
filter={"type": "report", "status": "active"},
limit=5,
offset=10
)
自然语言搜索
属性
名称 | 类型 | 描述 |
---|---|---|
namespace_prefix |
tuple[str, ...]
|
定义搜索范围的分层路径前缀。 |
过滤器 |
dict[str, Any] | None
|
用于根据精确匹配或比较运算符筛选结果的键值对。 |
限制 |
整数
|
在搜索结果中返回的最大项数。 |
offset |
整数
|
用于分页的要跳过的匹配项数。 |
查询 |
str | None
|
用于语义搜索功能的自然语言搜索查询。 |
refresh_ttl |
bool
|
是否刷新返回项的 TTL。 |
MatchCondition ¶
基类:NamedTuple
表示用于匹配存储中命名空间的模式。
此类将匹配类型(前缀或后缀)与可包含通配符的命名空间路径模式相结合,以灵活匹配不同的命名空间层级。
示例
前缀匹配
带通配符的后缀匹配
简单后缀匹配
属性
名称 | 类型 | 描述 |
---|---|---|
match_type |
NamespaceMatchType
|
要执行的命名空间匹配类型。 |
path |
NamespacePath
|
可以包含通配符的命名空间路径模式。 |
ListNamespacesOp ¶
基类:NamedTuple
列出和过滤存储中命名空间的操作。
此操作允许探索数据组织、查找特定集合以及导航命名空间层级。
示例
列出“documents”路径下的所有命名空间
ListNamespacesOp(
match_conditions=(MatchCondition(match_type="prefix", path=("documents",)),),
max_depth=2
)
列出所有以“v1”结尾的命名空间
属性
名称 | 类型 | 描述 |
---|---|---|
match_conditions |
tuple[MatchCondition, ...] | None
|
用于筛选命名空间的可选条件。 |
max_depth |
int | None
|
要返回的命名空间层级的最大深度。 |
限制 |
整数
|
要返回的最大命名空间数量。 |
offset |
整数
|
用于分页的要跳过的命名空间数量。 |
match_conditions class-attribute
instance-attribute
¶
match_conditions: tuple[MatchCondition, ...] | None = None
PutOp ¶
基类:NamedTuple
在存储中存储、更新或删除项的操作。
此类表示一个修改存储内容的单一操作,无论是添加新项、更新现有项还是删除它们。
属性
名称 | 类型 | 描述 |
---|---|---|
namespace |
tuple[str, ...]
|
标识项位置的分层路径。 |
键 |
str
|
项在其命名空间内的唯一标识符。 |
值 |
dict[str, Any] | None
|
要存储的数据,或为 None 以标记要删除的项。 |
index |
Literal[False] | list[str] | None
|
控制项的字段如何为搜索操作建立索引。 |
生存时间 |
float | None
|
控制项的 TTL(生存时间),以分钟为单位。 |
namespace instance-attribute
¶
key instance-attribute
¶
key: str
项在其命名空间内的唯一标识符。
键在特定命名空间内必须是唯一的,以避免冲突。它与命名空间一起构成了项的完整路径。
示例
如果命名空间是 ("documents", "user123") 且键是 "report1",则完整路径实际上是 "documents/user123/report1"
value instance-attribute
¶
要存储的数据,或为 None 以标记要删除的项。
值必须是具有字符串键和 JSON 可序列化值的字典。将其设置为 None 表示该项应被删除。
示例
{ "field1": "string value", "field2": 123, "nested": {"can": "contain", "any": "serializable data"} }
index class-attribute
instance-attribute
¶
控制项的字段如何为搜索操作建立索引。
索引配置决定了如何通过搜索找到该项
- None(默认):使用存储的默认索引配置(如果提供)
- False:禁用此项的索引
- list[str]:指定要为搜索建立索引的 json 路径字段
无论索引如何,该项仍然可以通过直接的 get() 操作访问。当被索引时,可以通过向量相似性搜索(如果存储实现支持)使用自然语言查询来搜索字段。
路径语法
- 简单字段访问:"field"
- 嵌套字段:"parent.child.grandchild"
- 数组索引
- 特定索引:"array[0]"
- 最后一个元素:"array[-1]"
- 所有元素(每个单独):"array[*]"
示例
- None - 使用存储默认值(整个项)
- list[str] - 要索引的字段列表
[
"metadata.title", # Nested field access
"context[*].content", # Index content from all context as separate vectors
"authors[0].name", # First author's name
"revisions[-1].changes", # Most recent revision's changes
"sections[*].paragraphs[*].text", # All text from all paragraphs in all sections
"metadata.tags[*]", # All tags in metadata
]
InvalidNamespaceError ¶
基类:ValueError
提供的命名空间无效。
TTLConfig ¶
基础类: TypedDict
存储中 TTL(生存时间)行为的配置。
属性
名称 | 类型 | 描述 |
---|---|---|
refresh_on_read |
bool
|
在读取操作(GET 和 SEARCH)上刷新 TTL 的默认行为。 |
default_ttl |
float | None
|
新项的默认 TTL(生存时间),以分钟为单位。 |
sweep_interval_minutes |
int | None
|
TTL 清扫操作之间的间隔,以分钟为单位。 |
refresh_on_read instance-attribute
¶
refresh_on_read: bool
在读取操作(GET 和 SEARCH)上刷新 TTL 的默认行为。
如果为 True,TTL 将在读取操作(get/search)时默认刷新。这可以通过显式设置 refresh_ttl 来为每个操作覆盖。如果未配置,则默认为 True。
IndexConfig ¶
基础类: TypedDict
用于在存储中为语义搜索索引文档的配置。
如果未提供给存储,存储将不支持向量搜索。在这种情况下,所有对 put() 和 aput() 操作的 `index` 参数都将被忽略。
属性
名称 | 类型 | 描述 |
---|---|---|
dims |
整数
|
嵌入向量中的维度数。 |
embed |
Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str
|
用于从文本生成嵌入的可选函数。 |
fields |
list[str] | None
|
用于提取文本以生成嵌入的字段。 |
embed instance-attribute
¶
embed: Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str
用于从文本生成嵌入的可选函数。
可以通过三种方式指定
- 一个 LangChain Embeddings 实例
- 一个同步嵌入函数 (EmbeddingsFunc)
- 一个异步嵌入函数 (AEmbeddingsFunc)
- 一个提供商字符串(例如,"openai:text-embedding-3-small")
示例
使用 LangChain 的初始化与 InMemoryStore
from langchain.embeddings import init_embeddings
from langgraph.store.memory import InMemoryStore
store = InMemoryStore(
index={
"dims": 1536,
"embed": init_embeddings("openai:text-embedding-3-small")
}
)
使用自定义嵌入函数与 InMemoryStore
from openai import OpenAI
from langgraph.store.memory import InMemoryStore
client = OpenAI()
def embed_texts(texts: list[str]) -> list[list[float]]:
response = client.embeddings.create(
model="text-embedding-3-small",
input=texts
)
return [e.embedding for e in response.data]
store = InMemoryStore(
index={
"dims": 1536,
"embed": embed_texts
}
)
使用异步嵌入函数与 InMemoryStore
from openai import AsyncOpenAI
from langgraph.store.memory import InMemoryStore
client = AsyncOpenAI()
async def aembed_texts(texts: list[str]) -> list[list[float]]:
response = await client.embeddings.create(
model="text-embedding-3-small",
input=texts
)
return [e.embedding for e in response.data]
store = InMemoryStore(
index={
"dims": 1536,
"embed": aembed_texts
}
)
fields instance-attribute
¶
用于提取文本以生成嵌入的字段。
控制存储项的哪些部分被嵌入以进行语义搜索。遵循 JSON 路径语法
- ["$"]: Embeds the entire JSON object as one vector (default)
- ["field1", "field2"]: Embeds specific top-level fields
- ["parent.child"]: Embeds nested fields using dot notation
- ["array[*].field"]: Embeds field from each array element separately
注意
您始终可以在存储项时使用 `put` 或 `aput` 操作中的 `index` 参数来覆盖此行为。
示例
# Embed entire document (default)
fields=["$"]
# Embed specific fields
fields=["text", "summary"]
# Embed nested fields
fields=["metadata.title", "content.body"]
# Embed from arrays
fields=["messages[*].content"] # Each message content separately
fields=["context[0].text"] # First context item's text
注意
- 文档中缺少的字段将被跳过
- 数组表示法为每个元素创建单独的嵌入
- 支持复杂的嵌套路径(例如,"a.b[*].c.d")
BaseStore ¶
基类:ABC
用于持久化键值存储的抽象基类。
存储实现了持久性和内存,可以在线程之间共享,范围可以是用户 ID、助手 ID 或其他任意命名空间。某些实现可能通过可选的 `index` 配置支持语义搜索功能。
注意
语义搜索功能因实现而异,通常默认禁用。支持此功能的存储可以通过在创建时提供 `index` 配置来进行配置。如果没有此配置,语义搜索将被禁用,并且任何传递给存储操作的 `index` 参数都将无效。
同样,TTL(生存时间)支持默认是禁用的。子类必须显式设置 `supports_ttl = True` 来启用此功能。
方法
名称 | 描述 |
---|---|
batch |
在单个批处理中同步执行多个操作。 |
abatch |
在单个批处理中异步执行多个操作。 |
获取 |
检索单个项。 |
search |
在命名空间前缀内搜索项。 |
放置 |
在存储中存储或更新一个项目。 |
delete |
删除项。 |
list_namespaces |
在存储中列出和筛选命名空间。 |
异步获取 |
异步检索单个项。 |
asearch |
在命名空间前缀内异步搜索项目。 |
aput |
异步存储或更新一个项目。 |
adelete |
异步删除一个项目。 |
alist_namespaces |
异步地在存储中列出和筛选命名空间。 |
batch abstractmethod
¶
abatch abstractmethod
async
¶
get ¶
search ¶
search(
namespace_prefix: tuple[str, ...],
/,
*,
query: str | None = None,
filter: dict[str, Any] | None = None,
limit: int = 10,
offset: int = 0,
refresh_ttl: bool | None = None,
) -> list[SearchItem]
在命名空间前缀内搜索项。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
namespace_prefix
|
tuple[str, ...]
|
要搜索的分层路径前缀。 |
必填 |
查询
|
str | None
|
用于自然语言搜索的可选查询。 |
None
|
过滤器
|
dict[str, Any] | None
|
用于筛选结果的键值对。 |
None
|
限制
|
整数
|
返回的最大项数。 |
10
|
offset
|
整数
|
在返回结果之前跳过的项数。 |
0
|
refresh_ttl
|
bool | None
|
是否刷新返回项的 TTL。如果未指定 TTL,此参数将被忽略。 |
None
|
返回
类型 | 描述 |
---|---|
list[SearchItem]
|
匹配搜索条件的项列表。 |
示例
基本筛选
# Search for documents with specific metadata
results = store.search(
("docs",),
filter={"type": "article", "status": "published"}
)
自然语言搜索(需要向量存储实现)
# Initialize store with embedding configuration
store = YourStore( # e.g., InMemoryStore, AsyncPostgresStore
index={
"dims": 1536, # embedding dimensions
"embed": your_embedding_function, # function to create embeddings
"fields": ["text"] # fields to embed. Defaults to ["$"]
}
)
# Search for semantically similar documents
results = store.search(
("docs",),
query="machine learning applications in healthcare",
filter={"type": "research_paper"},
limit=5
)
注意:自然语言搜索的支持取决于您的存储实现,并需要正确的嵌入配置。
put ¶
put(
namespace: tuple[str, ...],
key: str,
value: dict[str, Any],
index: Literal[False] | list[str] | None = None,
*,
ttl: float | None | NotProvided = NOT_PROVIDED
) -> None
在存储中存储或更新一个项目。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
namespace
|
tuple[str, ...]
|
项的分层路径,表示为字符串元组。示例:("documents", "user123") |
必填 |
键
|
str
|
命名空间内的唯一标识符。与命名空间一起构成项的完整路径。 |
必填 |
值
|
dict[str, Any]
|
包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。 |
必填 |
index
|
Literal[False] | list[str] | None
|
控制项的字段如何为搜索建立索引
|
None
|
生存时间
|
float | None | NotProvided
|
生存时间(以分钟为单位)。此参数的支持取决于您的存储适配器。如果指定,该项将在最后一次访问后的这么多分钟后过期。None 表示永不过期。过期的运行将择机删除。默认情况下,过期计时器在读取操作(get/search)和写入操作(put/update)时都会刷新,只要该项包含在操作中。 |
NOT_PROVIDED
|
注意
索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,`index` 参数将被忽略。
同样,TTL 支持取决于具体的存储实现。一些实现可能不支持项的过期。
delete ¶
list_namespaces ¶
list_namespaces(
*,
prefix: NamespacePath | None = None,
suffix: NamespacePath | None = None,
max_depth: int | None = None,
limit: int = 100,
offset: int = 0
) -> list[tuple[str, ...]]
在存储中列出和筛选命名空间。
用于探索数据组织、查找特定集合或导航命名空间层次结构。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
prefix
|
NamespacePath | None
|
筛选以此路径开头的命名空间。 |
None
|
suffix
|
NamespacePath | None
|
筛选以此路径结尾的命名空间。 |
None
|
max_depth
|
int | None
|
返回层次结构中此深度以下的命名空间。比此级别更深的命名空间将被截断。 |
None
|
限制
|
整数
|
要返回的最大命名空间数量(默认为 100)。 |
100
|
offset
|
整数
|
用于分页的要跳过的命名空间数量(默认为 0)。 |
0
|
返回
类型 | 描述 |
---|---|
list[tuple[str, ...]]
|
List[Tuple[str, ...]]:匹配条件的命名空间元组列表。 |
list[tuple[str, ...]]
|
每个元组代表一个完整的命名空间路径,直到 `max_depth`。 |
???+ 示例 "示例":设置 max_depth=3。给定命名空间
aget async
¶
asearch async
¶
asearch(
namespace_prefix: tuple[str, ...],
/,
*,
query: str | None = None,
filter: dict[str, Any] | None = None,
limit: int = 10,
offset: int = 0,
refresh_ttl: bool | None = None,
) -> list[SearchItem]
在命名空间前缀内异步搜索项目。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
namespace_prefix
|
tuple[str, ...]
|
要搜索的分层路径前缀。 |
必填 |
查询
|
str | None
|
用于自然语言搜索的可选查询。 |
None
|
过滤器
|
dict[str, Any] | None
|
用于筛选结果的键值对。 |
None
|
限制
|
整数
|
返回的最大项数。 |
10
|
offset
|
整数
|
在返回结果之前跳过的项数。 |
0
|
refresh_ttl
|
bool | None
|
是否为返回的项刷新 TTL。如果为 None(默认),则使用存储的 TTLConfig.refresh_default 设置。如果未提供 TTLConfig 或未指定 TTL,则此参数将被忽略。 |
None
|
返回
类型 | 描述 |
---|---|
list[SearchItem]
|
匹配搜索条件的项列表。 |
示例
基本筛选
# Search for documents with specific metadata
results = await store.asearch(
("docs",),
filter={"type": "article", "status": "published"}
)
自然语言搜索(需要向量存储实现)
# Initialize store with embedding configuration
store = YourStore( # e.g., InMemoryStore, AsyncPostgresStore
index={
"dims": 1536, # embedding dimensions
"embed": your_embedding_function, # function to create embeddings
"fields": ["text"] # fields to embed
}
)
# Search for semantically similar documents
results = await store.asearch(
("docs",),
query="machine learning applications in healthcare",
filter={"type": "research_paper"},
limit=5
)
注意:自然语言搜索的支持取决于您的存储实现,并需要正确的嵌入配置。
aput async
¶
aput(
namespace: tuple[str, ...],
key: str,
value: dict[str, Any],
index: Literal[False] | list[str] | None = None,
*,
ttl: float | None | NotProvided = NOT_PROVIDED
) -> None
异步存储或更新一个项目。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
namespace
|
tuple[str, ...]
|
项的分层路径,表示为字符串元组。示例:("documents", "user123") |
必填 |
键
|
str
|
命名空间内的唯一标识符。与命名空间一起构成项的完整路径。 |
必填 |
值
|
dict[str, Any]
|
包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。 |
必填 |
index
|
Literal[False] | list[str] | None
|
控制项的字段如何为搜索建立索引
|
None
|
生存时间
|
float | None | NotProvided
|
生存时间(以分钟为单位)。此参数的支持取决于您的存储适配器。如果指定,该项将在最后一次访问后的这么多分钟后过期。None 表示永不过期。过期的运行将择机删除。默认情况下,过期计时器在读取操作(get/search)和写入操作(put/update)时都会刷新,只要该项包含在操作中。 |
NOT_PROVIDED
|
注意
索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,`index` 参数将被忽略。
同样,TTL 支持取决于具体的存储实现。一些实现可能不支持项的过期。
示例
存储项。索引取决于您如何配置存储。
不要为语义搜索索引项。仍然可以通过 get() 和 search() 操作访问,但不会有向量表示。
为搜索索引特定字段(如果存储配置为索引项)
adelete async
¶
alist_namespaces async
¶
alist_namespaces(
*,
prefix: NamespacePath | None = None,
suffix: NamespacePath | None = None,
max_depth: int | None = None,
limit: int = 100,
offset: int = 0
) -> list[tuple[str, ...]]
异步地在存储中列出和筛选命名空间。
用于探索数据组织、查找特定集合或导航命名空间层次结构。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
prefix
|
NamespacePath | None
|
筛选以此路径开头的命名空间。 |
None
|
suffix
|
NamespacePath | None
|
筛选以此路径结尾的命名空间。 |
None
|
max_depth
|
int | None
|
返回层次结构中此深度以下的命名空间。比此级别更深的命名空间将被截断至此深度。 |
None
|
限制
|
整数
|
要返回的最大命名空间数量(默认为 100)。 |
100
|
offset
|
整数
|
用于分页的要跳过的命名空间数量(默认为 0)。 |
0
|
返回
类型 | 描述 |
---|---|
list[tuple[str, ...]]
|
List[Tuple[str, ...]]:匹配条件的命名空间元组列表。 |
list[tuple[str, ...]]
|
每个元组代表一个完整的命名空间路径,直到 `max_depth`。 |
ensure_embeddings ¶
ensure_embeddings(
embed: (
Embeddings
| EmbeddingsFunc
| AEmbeddingsFunc
| str
| None
),
) -> Embeddings
确保嵌入函数符合 LangChain 的 Embeddings 接口。
此函数包装任意嵌入函数,使其与 LangChain 的 Embeddings 接口兼容。它处理同步和异步函数。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
embed
|
Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str | None
|
可以是现有的 Embeddings 实例,也可以是将文本转换为嵌入的函数。如果函数是异步的,它将用于同步和异步操作。 |
必填 |
返回
类型 | 描述 |
---|---|
Embeddings
|
一个包装了所提供函数的 Embeddings 实例。 |
示例
包装一个同步嵌入函数
def my_embed_fn(texts):
return [[0.1, 0.2] for _ in texts]
embeddings = ensure_embeddings(my_embed_fn)
result = embeddings.embed_query("hello") # Returns [0.1, 0.2]
包装一个异步嵌入函数
async def my_async_fn(texts):
return [[0.1, 0.2] for _ in texts]
embeddings = ensure_embeddings(my_async_fn)
result = await embeddings.aembed_query("hello") # Returns [0.1, 0.2]
使用提供商字符串初始化嵌入
get_text_at_path ¶
模块
名称 | 描述 |
---|---|
aio |
|
base |
|
类
名称 | 描述 |
---|---|
AsyncPostgresStore |
使用 pgvector 的异步 Postgres 支持的存储,可选向量搜索。 |
PostgresStore |
使用 pgvector 的 Postgres 支持的存储,可选向量搜索。 |
AsyncPostgresStore ¶
基类:AsyncBatchedBaseStore
, BasePostgresStore[Conn]
使用 pgvector 的异步 Postgres 支持的存储,可选向量搜索。
示例
基本设置和用法
from langgraph.store.postgres import AsyncPostgresStore
conn_string = "postgresql://user:pass@localhost:5432/dbname"
async with AsyncPostgresStore.from_conn_string(conn_string) as store:
await store.setup() # Run migrations. Done once
# Store and retrieve data
await store.aput(("users", "123"), "prefs", {"theme": "dark"})
item = await store.aget(("users", "123"), "prefs")
使用 LangChain 嵌入进行向量搜索
from langchain.embeddings import init_embeddings
from langgraph.store.postgres import AsyncPostgresStore
conn_string = "postgresql://user:pass@localhost:5432/dbname"
async with AsyncPostgresStore.from_conn_string(
conn_string,
index={
"dims": 1536,
"embed": init_embeddings("openai:text-embedding-3-small"),
"fields": ["text"] # specify which fields to embed. Default is the whole serialized value
}
) as store:
await store.setup() # Run migrations. Done once
# Store documents
await store.aput(("docs",), "doc1", {"text": "Python tutorial"})
await store.aput(("docs",), "doc2", {"text": "TypeScript guide"})
await store.aput(("docs",), "doc3", {"text": "Other guide"}, index=False) # don't index
# Search by similarity
results = await store.asearch(("docs",), query="programming guides", limit=2)
使用连接池以获得更好的性能
from langgraph.store.postgres import AsyncPostgresStore, PoolConfig
conn_string = "postgresql://user:pass@localhost:5432/dbname"
async with AsyncPostgresStore.from_conn_string(
conn_string,
pool_config=PoolConfig(
min_size=5,
max_size=20
)
) as store:
await store.setup() # Run migrations. Done once
# Use store with connection pooling...
警告
请确保:1. 在首次使用前调用 `setup()` 以创建必要的表和索引 2. pgvector 扩展可用以使用向量搜索 3. 使用 Python 3.10+ 以支持异步功能
注意
默认情况下,语义搜索是禁用的。您可以在创建存储时提供一个 `index` 配置来启用它。如果没有这个配置,所有传递给 `put` 或 `aput` 的 `index` 参数都将无效。
注意
如果您提供了 TTL 配置,则必须显式调用 `start_ttl_sweeper()` 来启动删除过期项的后台任务。在完成存储使用后,调用 `stop_ttl_sweeper()` 以正确清理资源。
方法
名称 | 描述 |
---|---|
from_conn_string |
从连接字符串创建一个新的 AsyncPostgresStore 实例。 |
setup |
异步设置存储数据库。 |
sweep_ttl |
根据 TTL 删除过期的存储项。 |
start_ttl_sweeper |
根据 TTL 定期删除过期的存储项。 |
stop_ttl_sweeper |
如果 TTL 清理器任务正在运行,则停止它。 |
from_conn_string async
classmethod
¶
from_conn_string(
conn_string: str,
*,
pipeline: bool = False,
pool_config: PoolConfig | None = None,
index: PostgresIndexConfig | None = None,
ttl: TTLConfig | None = None
) -> AsyncIterator[AsyncPostgresStore]
从连接字符串创建一个新的 AsyncPostgresStore 实例。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
conn_string
|
str
|
Postgres 连接信息字符串。 |
必填 |
pipeline
|
bool
|
是否使用 AsyncPipeline(仅适用于单个连接) |
False
|
pool_config
|
PoolConfig | None
|
连接池的配置。如果提供,将创建一个连接池并使用它而不是单个连接。这将覆盖 `pipeline` 参数。 |
None
|
index
|
PostgresIndexConfig | None
|
嵌入配置。 |
None
|
返回
名称 | 类型 | 描述 |
---|---|---|
AsyncPostgresStore |
AsyncIterator[AsyncPostgresStore]
|
一个新的 AsyncPostgresStore 实例。 |
setup async
¶
异步设置存储数据库。
此方法在 Postgres 数据库中创建必要的表(如果它们尚不存在)并运行数据库迁移。用户在首次使用存储时必须直接调用此方法。
start_ttl_sweeper async
¶
PostgresStore ¶
基类:BaseStore
, BasePostgresStore[Conn]
使用 pgvector 的 Postgres 支持的存储,可选向量搜索。
示例
基本设置和用法
from langgraph.store.postgres import PostgresStore
from psycopg import Connection
conn_string = "postgresql://user:pass@localhost:5432/dbname"
# Using direct connection
with Connection.connect(conn_string) as conn:
store = PostgresStore(conn)
store.setup() # Run migrations. Done once
# Store and retrieve data
store.put(("users", "123"), "prefs", {"theme": "dark"})
item = store.get(("users", "123"), "prefs")
或使用方便的 from_conn_string 辅助函数
from langgraph.store.postgres import PostgresStore
conn_string = "postgresql://user:pass@localhost:5432/dbname"
with PostgresStore.from_conn_string(conn_string) as store:
store.setup()
# Store and retrieve data
store.put(("users", "123"), "prefs", {"theme": "dark"})
item = store.get(("users", "123"), "prefs")
使用 LangChain 嵌入进行向量搜索
from langchain.embeddings import init_embeddings
from langgraph.store.postgres import PostgresStore
conn_string = "postgresql://user:pass@localhost:5432/dbname"
with PostgresStore.from_conn_string(
conn_string,
index={
"dims": 1536,
"embed": init_embeddings("openai:text-embedding-3-small"),
"fields": ["text"] # specify which fields to embed. Default is the whole serialized value
}
) as store:
store.setup() # Do this once to run migrations
# Store documents
store.put(("docs",), "doc1", {"text": "Python tutorial"})
store.put(("docs",), "doc2", {"text": "TypeScript guide"})
store.put(("docs",), "doc2", {"text": "Other guide"}, index=False) # don't index
# Search by similarity
results = store.search(("docs",), query="programming guides", limit=2)
注意
默认情况下,语义搜索是禁用的。您可以通过在创建存储时提供 `index` 配置来启用它。如果没有此配置,所有传递给 `put` 或 `aput` 的 `index` 参数都将无效。
警告
请确保在首次使用前调用 `setup()` 以创建必要的表和索引。必须有 pgvector 扩展才能使用向量搜索。
注意
如果您提供 TTL 配置,则必须显式调用 `start_ttl_sweeper()` 以启动删除过期项的后台线程。当您完成存储的使用时,请调用 `stop_ttl_sweeper()` 以正确清理资源。
方法
名称 | 描述 |
---|---|
获取 |
检索单个项。 |
search |
在命名空间前缀内搜索项。 |
放置 |
在存储中存储或更新一个项目。 |
delete |
删除项。 |
list_namespaces |
在存储中列出和筛选命名空间。 |
异步获取 |
异步检索单个项。 |
asearch |
在命名空间前缀内异步搜索项目。 |
aput |
异步存储或更新一个项目。 |
adelete |
异步删除一个项目。 |
alist_namespaces |
异步地在存储中列出和筛选命名空间。 |
from_conn_string |
从连接字符串创建一个新的 PostgresStore 实例。 |
sweep_ttl |
根据 TTL 删除过期的存储项。 |
start_ttl_sweeper |
根据 TTL 定期删除过期的存储项。 |
stop_ttl_sweeper |
如果 TTL 清理器线程正在运行,则停止它。 |
__del__ |
确保在对象被垃圾回收时停止 TTL 清理器线程。 |
setup |
设置存储数据库。 |
get ¶
search ¶
search(
namespace_prefix: tuple[str, ...],
/,
*,
query: str | None = None,
filter: dict[str, Any] | None = None,
limit: int = 10,
offset: int = 0,
refresh_ttl: bool | None = None,
) -> list[SearchItem]
在命名空间前缀内搜索项。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
namespace_prefix
|
tuple[str, ...]
|
要搜索的分层路径前缀。 |
必填 |
查询
|
str | None
|
用于自然语言搜索的可选查询。 |
None
|
过滤器
|
dict[str, Any] | None
|
用于筛选结果的键值对。 |
None
|
限制
|
整数
|
返回的最大项数。 |
10
|
offset
|
整数
|
在返回结果之前跳过的项数。 |
0
|
refresh_ttl
|
bool | None
|
是否刷新返回项的 TTL。如果未指定 TTL,此参数将被忽略。 |
None
|
返回
类型 | 描述 |
---|---|
list[SearchItem]
|
匹配搜索条件的项列表。 |
示例
基本筛选
# Search for documents with specific metadata
results = store.search(
("docs",),
filter={"type": "article", "status": "published"}
)
自然语言搜索(需要向量存储实现)
# Initialize store with embedding configuration
store = YourStore( # e.g., InMemoryStore, AsyncPostgresStore
index={
"dims": 1536, # embedding dimensions
"embed": your_embedding_function, # function to create embeddings
"fields": ["text"] # fields to embed. Defaults to ["$"]
}
)
# Search for semantically similar documents
results = store.search(
("docs",),
query="machine learning applications in healthcare",
filter={"type": "research_paper"},
limit=5
)
注意:自然语言搜索的支持取决于您的存储实现,并需要正确的嵌入配置。
put ¶
put(
namespace: tuple[str, ...],
key: str,
value: dict[str, Any],
index: Literal[False] | list[str] | None = None,
*,
ttl: float | None | NotProvided = NOT_PROVIDED
) -> None
在存储中存储或更新一个项目。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
namespace
|
tuple[str, ...]
|
项的分层路径,表示为字符串元组。示例:("documents", "user123") |
必填 |
键
|
str
|
命名空间内的唯一标识符。与命名空间一起构成项的完整路径。 |
必填 |
值
|
dict[str, Any]
|
包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。 |
必填 |
index
|
Literal[False] | list[str] | None
|
控制项的字段如何为搜索建立索引
|
None
|
生存时间
|
float | None | NotProvided
|
生存时间(以分钟为单位)。此参数的支持取决于您的存储适配器。如果指定,该项将在最后一次访问后的这么多分钟后过期。None 表示永不过期。过期的运行将择机删除。默认情况下,过期计时器在读取操作(get/search)和写入操作(put/update)时都会刷新,只要该项包含在操作中。 |
NOT_PROVIDED
|
注意
索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,`index` 参数将被忽略。
同样,TTL 支持取决于具体的存储实现。一些实现可能不支持项的过期。
delete ¶
list_namespaces ¶
list_namespaces(
*,
prefix: NamespacePath | None = None,
suffix: NamespacePath | None = None,
max_depth: int | None = None,
limit: int = 100,
offset: int = 0
) -> list[tuple[str, ...]]
在存储中列出和筛选命名空间。
用于探索数据组织、查找特定集合或导航命名空间层次结构。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
prefix
|
NamespacePath | None
|
筛选以此路径开头的命名空间。 |
None
|
suffix
|
NamespacePath | None
|
筛选以此路径结尾的命名空间。 |
None
|
max_depth
|
int | None
|
返回层次结构中此深度以下的命名空间。比此级别更深的命名空间将被截断。 |
None
|
限制
|
整数
|
要返回的最大命名空间数量(默认为 100)。 |
100
|
offset
|
整数
|
用于分页的要跳过的命名空间数量(默认为 0)。 |
0
|
返回
类型 | 描述 |
---|---|
list[tuple[str, ...]]
|
List[Tuple[str, ...]]:匹配条件的命名空间元组列表。 |
list[tuple[str, ...]]
|
每个元组代表一个完整的命名空间路径,直到 `max_depth`。 |
???+ 示例 "示例":设置 max_depth=3。给定命名空间
aget async
¶
asearch async
¶
asearch(
namespace_prefix: tuple[str, ...],
/,
*,
query: str | None = None,
filter: dict[str, Any] | None = None,
limit: int = 10,
offset: int = 0,
refresh_ttl: bool | None = None,
) -> list[SearchItem]
在命名空间前缀内异步搜索项目。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
namespace_prefix
|
tuple[str, ...]
|
要搜索的分层路径前缀。 |
必填 |
查询
|
str | None
|
用于自然语言搜索的可选查询。 |
None
|
过滤器
|
dict[str, Any] | None
|
用于筛选结果的键值对。 |
None
|
限制
|
整数
|
返回的最大项数。 |
10
|
offset
|
整数
|
在返回结果之前跳过的项数。 |
0
|
refresh_ttl
|
bool | None
|
是否为返回的项刷新 TTL。如果为 None(默认),则使用存储的 TTLConfig.refresh_default 设置。如果未提供 TTLConfig 或未指定 TTL,则此参数将被忽略。 |
None
|
返回
类型 | 描述 |
---|---|
list[SearchItem]
|
匹配搜索条件的项列表。 |
示例
基本筛选
# Search for documents with specific metadata
results = await store.asearch(
("docs",),
filter={"type": "article", "status": "published"}
)
自然语言搜索(需要向量存储实现)
# Initialize store with embedding configuration
store = YourStore( # e.g., InMemoryStore, AsyncPostgresStore
index={
"dims": 1536, # embedding dimensions
"embed": your_embedding_function, # function to create embeddings
"fields": ["text"] # fields to embed
}
)
# Search for semantically similar documents
results = await store.asearch(
("docs",),
query="machine learning applications in healthcare",
filter={"type": "research_paper"},
limit=5
)
注意:自然语言搜索的支持取决于您的存储实现,并需要正确的嵌入配置。
aput async
¶
aput(
namespace: tuple[str, ...],
key: str,
value: dict[str, Any],
index: Literal[False] | list[str] | None = None,
*,
ttl: float | None | NotProvided = NOT_PROVIDED
) -> None
异步存储或更新一个项目。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
namespace
|
tuple[str, ...]
|
项的分层路径,表示为字符串元组。示例:("documents", "user123") |
必填 |
键
|
str
|
命名空间内的唯一标识符。与命名空间一起构成项的完整路径。 |
必填 |
值
|
dict[str, Any]
|
包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。 |
必填 |
index
|
Literal[False] | list[str] | None
|
控制项的字段如何为搜索建立索引
|
None
|
生存时间
|
float | None | NotProvided
|
生存时间(以分钟为单位)。此参数的支持取决于您的存储适配器。如果指定,该项将在最后一次访问后的这么多分钟后过期。None 表示永不过期。过期的运行将择机删除。默认情况下,过期计时器在读取操作(get/search)和写入操作(put/update)时都会刷新,只要该项包含在操作中。 |
NOT_PROVIDED
|
注意
索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,`index` 参数将被忽略。
同样,TTL 支持取决于具体的存储实现。一些实现可能不支持项的过期。
示例
存储项。索引取决于您如何配置存储。
不要为语义搜索索引项。仍然可以通过 get() 和 search() 操作访问,但不会有向量表示。
为搜索索引特定字段(如果存储配置为索引项)
adelete async
¶
alist_namespaces async
¶
alist_namespaces(
*,
prefix: NamespacePath | None = None,
suffix: NamespacePath | None = None,
max_depth: int | None = None,
limit: int = 100,
offset: int = 0
) -> list[tuple[str, ...]]
异步地在存储中列出和筛选命名空间。
用于探索数据组织、查找特定集合或导航命名空间层次结构。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
prefix
|
NamespacePath | None
|
筛选以此路径开头的命名空间。 |
None
|
suffix
|
NamespacePath | None
|
筛选以此路径结尾的命名空间。 |
None
|
max_depth
|
int | None
|
返回层次结构中此深度以下的命名空间。比此级别更深的命名空间将被截断至此深度。 |
None
|
限制
|
整数
|
要返回的最大命名空间数量(默认为 100)。 |
100
|
offset
|
整数
|
用于分页的要跳过的命名空间数量(默认为 0)。 |
0
|
返回
类型 | 描述 |
---|---|
list[tuple[str, ...]]
|
List[Tuple[str, ...]]:匹配条件的命名空间元组列表。 |
list[tuple[str, ...]]
|
每个元组代表一个完整的命名空间路径,直到 `max_depth`。 |
from_conn_string classmethod
¶
from_conn_string(
conn_string: str,
*,
pipeline: bool = False,
pool_config: PoolConfig | None = None,
index: PostgresIndexConfig | None = None,
ttl: TTLConfig | None = None
) -> Iterator[PostgresStore]
从连接字符串创建一个新的 PostgresStore 实例。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
conn_string
|
str
|
Postgres 连接信息字符串。 |
必填 |
pipeline
|
bool
|
是否使用 Pipeline |
False
|
pool_config
|
PoolConfig | None
|
连接池的配置。如果提供,将创建一个连接池并使用它而不是单个连接。这将覆盖 `pipeline` 参数。 |
None
|
index
|
PostgresIndexConfig | None
|
存储的索引配置。 |
None
|
生存时间
|
TTLConfig | None
|
存储的 TTL 配置。 |
None
|
返回
名称 | 类型 | 描述 |
---|---|---|
PostgresStore |
Iterator[PostgresStore]
|
一个新的 PostgresStore 实例。 |