存储¶
用于持久化键值存储的基础类和类型。
存储提供跨线程和对话的长期记忆。支持分层命名空间、键值存储和可选的向量搜索。
核心类型
- BaseStore: 支持同步/异步操作的存储接口
- Item: 带有元数据的存储键值对
- Op: 获取/放置/搜索/列表操作
模块
名称 | 描述 |
---|---|
批量 |
用于在后台任务中批量处理操作的实用工具。 |
嵌入 |
用于处理嵌入函数和LangChain嵌入接口的实用工具。 |
类
名称 | 描述 |
---|---|
嵌入 |
嵌入模型的接口。 |
项 |
表示带有元数据的存储项。 |
获取操作 |
根据命名空间和键检索特定项的操作。 |
搜索操作 |
在指定的命名空间层次结构中搜索项的操作。 |
匹配条件 |
表示存储中命名空间匹配的模式。 |
列出命名空间操作 |
列出和过滤存储中命名空间的操作。 |
放置操作 |
在存储中存储、更新或删除项的操作。 |
基础存储 |
用于持久化键值存储的抽象基类。 |
函数
名称 | 描述 |
---|---|
确保嵌入 |
确保嵌入函数符合LangChain的嵌入接口。 |
按路径获取文本 |
使用路径表达式或预标记化路径从对象中提取文本。 |
标记化路径 |
将路径标记化为组件。 |
属性
名称 | 类型 | 描述 |
---|---|---|
命名空间路径 |
表示可包含通配符的命名空间路径的元组。 |
|
命名空间匹配类型 |
指定如何匹配命名空间路径。 |
NamespacePath module-attribute
¶
NamespaceMatchType module-attribute
¶
NamespaceMatchType = Literal['prefix', 'suffix']
指定如何匹配命名空间路径。
值
"prefix": 从命名空间的开头匹配 "suffix": 从命名空间的末尾匹配
Embeddings ¶
基础类: ABC
嵌入模型的接口。
这是一个用于实现文本嵌入模型的接口。
文本嵌入模型用于将文本映射到向量(n维空间中的一个点)。
相似的文本通常会被映射到该空间中彼此靠近的点。关于什么是“相似”以及如何测量该空间中的“距离”的具体细节取决于特定的嵌入模型。
此抽象包含一个用于嵌入文档列表的方法和一个用于嵌入查询文本的方法。查询文本的嵌入预期是一个单一向量,而文档列表的嵌入预期是一个向量列表。
通常查询嵌入与文档嵌入相同,但此抽象允许独立处理它们。
除了同步方法之外,此接口还提供了这些方法的异步版本。
默认情况下,异步方法是使用同步方法实现的;但是,为了性能原因,实现可以选择用异步原生实现覆盖异步方法。
方法
名称 | 描述 |
---|---|
嵌入文档 |
嵌入搜索文档。 |
嵌入查询 |
嵌入查询文本。 |
异步嵌入文档 |
异步嵌入搜索文档。 |
异步嵌入查询 |
异步嵌入查询文本。 |
NotProvided ¶
哨兵单例。
Item ¶
SearchItem ¶
GetOp ¶
SearchOp ¶
基础类: NamedTuple
在指定的命名空间层次结构中搜索项的操作。
此操作支持在给定命名空间前缀内进行结构化过滤和自然语言搜索。它通过limit和offset参数提供分页功能。
注意
自然语言搜索支持取决于您的存储实现。
示例
带过滤器和分页的搜索
SearchOp(
namespace_prefix=("documents",),
filter={"type": "report", "status": "active"},
limit=5,
offset=10
)
自然语言搜索
属性
名称 | 类型 | 描述 |
---|---|---|
命名空间前缀 |
tuple[str, ...]
|
定义搜索范围的分层路径前缀。 |
过滤器 |
dict[str, Any] | None
|
用于根据精确匹配或比较运算符过滤结果的键值对。 |
限制 |
int
|
搜索结果中返回的最大项数。 |
偏移 |
int
|
分页时跳过的匹配项数。 |
查询 |
str | None
|
用于语义搜索功能的自然语言搜索查询。 |
刷新TTL |
bool
|
是否刷新返回项的TTL。 |
MatchCondition ¶
基础类: NamedTuple
表示存储中命名空间匹配的模式。
此类结合了匹配类型(前缀或后缀)和可包含通配符的命名空间路径模式,以灵活匹配不同的命名空间层次结构。
示例
前缀匹配
带通配符的后缀匹配
简单后缀匹配
属性
名称 | 类型 | 描述 |
---|---|---|
匹配类型 |
命名空间匹配类型
|
要执行的命名空间匹配类型。 |
路径 |
命名空间路径
|
可包含通配符的命名空间路径模式。 |
ListNamespacesOp ¶
基础类: NamedTuple
列出和过滤存储中命名空间的操作。
此操作允许探索数据的组织、查找特定集合以及导航命名空间层次结构。
示例
列出“documents”路径下的所有命名空间
ListNamespacesOp(
match_conditions=(MatchCondition(match_type="prefix", path=("documents",)),),
max_depth=2
)
列出所有以“v1”结尾的命名空间
属性
名称 | 类型 | 描述 |
---|---|---|
匹配条件 |
tuple[MatchCondition, ...] | None
|
用于过滤命名空间的可选条件。 |
最大深度 |
int | None
|
返回命名空间层次结构的最大深度。 |
限制 |
int
|
返回的最大命名空间数量。 |
偏移 |
int
|
分页时跳过的命名空间数量。 |
match_conditions class-attribute
instance-attribute
¶
match_conditions: tuple[MatchCondition, ...] | None = None
PutOp ¶
基础类: NamedTuple
在存储中存储、更新或删除项的操作。
此类表示修改存储内容(无论是添加新项、更新现有项还是删除项)的单个操作。
属性
名称 | 类型 | 描述 |
---|---|---|
命名空间 |
tuple[str, ...]
|
标识项位置的分层路径。 |
键 |
str
|
项在其命名空间内的唯一标识符。 |
值 |
dict[str, Any] | None
|
要存储的数据,或None以标记项待删除。 |
索引 |
Literal[False] | list[str] | None
|
控制项的字段如何为搜索操作编制索引。 |
TTL |
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(生存时间)行为的配置。
属性
名称 | 类型 | 描述 |
---|---|---|
读取时刷新 |
bool
|
读取操作(GET和SEARCH)时刷新TTL的默认行为。 |
默认TTL |
float | None
|
新项的默认TTL(生存时间,以分钟为单位)。 |
清理间隔(分钟) |
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
参数都将被忽略。
属性
名称 | 类型 | 描述 |
---|---|---|
维度 |
int
|
嵌入向量中的维度数量。 |
嵌入 |
Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str
|
从文本生成嵌入的可选函数。 |
字段 |
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 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]
在命名空间前缀内搜索项。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
命名空间前缀
|
tuple[str, ...]
|
要搜索的分层路径前缀。 |
必填 |
查询
|
str | None
|
用于自然语言搜索的可选查询。 |
None
|
过滤器
|
dict[str, Any] | None
|
用于过滤结果的键值对。 |
None
|
限制
|
int
|
要返回的最大项数。 |
10
|
偏移
|
int
|
在返回结果之前要跳过的项数。 |
0
|
刷新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
在存储中存储或更新项。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
命名空间
|
tuple[str, ...]
|
项的分层路径,表示为字符串元组。示例:("documents", "user123") |
必填 |
键
|
str
|
命名空间内的唯一标识符。与命名空间一起构成项的完整路径。 |
必填 |
值
|
dict[str, Any]
|
包含项数据的字典。必须包含字符串键和JSON可序列化值。 |
必填 |
索引
|
Literal[False] | list[str] | None
|
控制项的字段如何为搜索编制索引
|
None
|
TTL
|
float | None | NotProvided
|
生存时间,以分钟为单位。对此参数的支持取决于您的存储适配器。如果指定,该项将在上次访问后在此分钟数内过期。None表示永不过期。过期运行将被机会性删除。默认情况下,只要该项包含在操作中,过期计时器就会在读取操作(get/search)和写入操作(put/update)时刷新。 |
未提供
|
注意
索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,则 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, ...]]
列出并过滤存储中的命名空间。
用于探索数据的组织、查找特定集合或导航命名空间层次结构。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
前缀
|
NamespacePath | None
|
过滤以该路径开头的命名空间。 |
None
|
后缀
|
NamespacePath | None
|
过滤以该路径结尾的命名空间。 |
None
|
最大深度
|
int | None
|
返回层次结构中直到此深度的命名空间。深度超过此级别的命名空间将被截断。 |
None
|
限制
|
int
|
要返回的最大命名空间数量(默认100)。 |
100
|
偏移
|
int
|
分页时要跳过的命名空间数量(默认0)。 |
0
|
返回
类型 | 描述 |
---|---|
list[tuple[str, ...]]
|
List[Tuple[str, ...]]:符合条件的命名空间元组列表。 |
list[tuple[str, ...]]
|
每个元组表示一个完整命名空间路径,直到 |
???+ 示例 "Examples":设置 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]
在命名空间前缀内异步搜索项。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
命名空间前缀
|
tuple[str, ...]
|
要搜索的分层路径前缀。 |
必填 |
查询
|
str | None
|
用于自然语言搜索的可选查询。 |
None
|
过滤器
|
dict[str, Any] | None
|
用于过滤结果的键值对。 |
None
|
限制
|
int
|
要返回的最大项数。 |
10
|
偏移
|
int
|
在返回结果之前要跳过的项数。 |
0
|
刷新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
异步存储或更新存储中的项。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
命名空间
|
tuple[str, ...]
|
项的分层路径,表示为字符串元组。示例:("documents", "user123") |
必填 |
键
|
str
|
命名空间内的唯一标识符。与命名空间一起构成项的完整路径。 |
必填 |
值
|
dict[str, Any]
|
包含项数据的字典。必须包含字符串键和JSON可序列化值。 |
必填 |
索引
|
Literal[False] | list[str] | None
|
控制项的字段如何为搜索编制索引
|
None
|
TTL
|
float | None | NotProvided
|
生存时间,以分钟为单位。对此参数的支持取决于您的存储适配器。如果指定,该项将在上次访问后在此分钟数内过期。None表示永不过期。过期运行将被机会性删除。默认情况下,只要该项包含在操作中,过期计时器就会在读取操作(get/search)和写入操作(put/update)时刷新。 |
未提供
|
注意
索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,则 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, ...]]
异步列出并过滤存储中的命名空间。
用于探索数据的组织、查找特定集合或导航命名空间层次结构。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
前缀
|
NamespacePath | None
|
过滤以该路径开头的命名空间。 |
None
|
后缀
|
NamespacePath | None
|
过滤以该路径结尾的命名空间。 |
None
|
最大深度
|
int | None
|
返回层次结构中直到此深度的命名空间。深度超过此级别的命名空间将被截断到此深度。 |
None
|
限制
|
int
|
要返回的最大命名空间数量(默认100)。 |
100
|
偏移
|
int
|
分页时要跳过的命名空间数量(默认0)。 |
0
|
返回
类型 | 描述 |
---|---|
list[tuple[str, ...]]
|
List[Tuple[str, ...]]:符合条件的命名空间元组列表。 |
list[tuple[str, ...]]
|
每个元组表示一个完整命名空间路径,直到 |
ensure_embeddings ¶
ensure_embeddings(
embed: (
Embeddings
| EmbeddingsFunc
| AEmbeddingsFunc
| str
| None
),
) -> Embeddings
确保嵌入函数符合LangChain的嵌入接口。
此函数包装任意嵌入函数,使其与LangChain的嵌入接口兼容。它处理同步和异步函数。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
嵌入
|
Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str | None
|
现有Embeddings实例,或将文本转换为嵌入的函数。如果函数是异步的,它将用于同步和异步操作。 |
必填 |
返回
类型 | 描述 |
---|---|
嵌入
|
包装所提供函数(S)的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 |
|
类
名称 | 描述 |
---|---|
异步Postgres存储 |
基于异步Postgres的存储,可选择使用pgvector进行向量搜索。 |
Postgres存储 |
基于Postgres的存储,可选择使用pgvector进行向量搜索。 |
AsyncPostgresStore ¶
基础类: AsyncBatchedBaseStore
, BasePostgresStore[Conn]
基于异步Postgres的存储,可选择使用pgvector进行向量搜索。
示例
基本设置和用法
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()
以正确清理资源。
方法
名称 | 描述 |
---|---|
从连接字符串创建 |
从连接字符串创建新的AsyncPostgresStore实例。 |
设置 |
异步设置存储数据库。 |
清理TTL |
根据TTL删除过期存储项。 |
启动TTL清理器 |
根据TTL定期删除过期存储项。 |
停止TTL清理器 |
如果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实例。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
连接字符串
|
str
|
Postgres连接信息字符串。 |
必填 |
管道
|
bool
|
是否使用AsyncPipeline(仅适用于单个连接) |
False
|
连接池配置
|
PoolConfig | None
|
连接池的配置。如果提供,将创建一个连接池并使用它而不是单个连接。这将覆盖 |
None
|
索引
|
PostgresIndexConfig | None
|
嵌入配置。 |
None
|
返回
名称 | 类型 | 描述 |
---|---|---|
异步Postgres存储 |
AsyncIterator[AsyncPostgresStore]
|
新的AsyncPostgresStore实例。 |
setup async
¶
异步设置存储数据库。
此方法在Postgres数据库中创建必要的表(如果它们尚不存在)并运行数据库迁移。首次使用存储时,用户必须直接调用此方法。
start_ttl_sweeper async
¶
PostgresStore ¶
基础类: BaseStore
, BasePostgresStore[Conn]
基于Postgres的存储,可选择使用pgvector进行向量搜索。
示例
基本设置和用法
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()
以正确清理资源。
方法
名称 | 描述 |
---|---|
获取 |
检索单个项。 |
搜索 |
在命名空间前缀内搜索项。 |
放置 |
在存储中存储或更新项。 |
删除 |
删除项。 |
列出命名空间 |
列出并过滤存储中的命名空间。 |
异步获取 |
异步检索单个项。 |
异步搜索 |
在命名空间前缀内异步搜索项。 |
异步放置 |
异步存储或更新存储中的项。 |
异步删除 |
异步删除项。 |
异步列出命名空间 |
异步列出并过滤存储中的命名空间。 |
从连接字符串创建 |
从连接字符串创建新的PostgresStore实例。 |
清理TTL |
根据TTL删除过期存储项。 |
启动TTL清理器 |
根据TTL定期删除过期存储项。 |
停止TTL清理器 |
如果TTL清理线程正在运行,则停止它。 |
__del__ |
确保当对象被垃圾回收时,TTL清理线程停止。 |
设置 |
设置存储数据库。 |
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]
在命名空间前缀内搜索项。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
命名空间前缀
|
tuple[str, ...]
|
要搜索的分层路径前缀。 |
必填 |
查询
|
str | None
|
用于自然语言搜索的可选查询。 |
None
|
过滤器
|
dict[str, Any] | None
|
用于过滤结果的键值对。 |
None
|
限制
|
int
|
要返回的最大项数。 |
10
|
偏移
|
int
|
在返回结果之前要跳过的项数。 |
0
|
刷新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
在存储中存储或更新项。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
命名空间
|
tuple[str, ...]
|
项的分层路径,表示为字符串元组。示例:("documents", "user123") |
必填 |
键
|
str
|
命名空间内的唯一标识符。与命名空间一起构成项的完整路径。 |
必填 |
值
|
dict[str, Any]
|
包含项数据的字典。必须包含字符串键和JSON可序列化值。 |
必填 |
索引
|
Literal[False] | list[str] | None
|
控制项的字段如何为搜索编制索引
|
None
|
TTL
|
float | None | NotProvided
|
生存时间,以分钟为单位。对此参数的支持取决于您的存储适配器。如果指定,该项将在上次访问后在此分钟数内过期。None表示永不过期。过期运行将被机会性删除。默认情况下,只要该项包含在操作中,过期计时器就会在读取操作(get/search)和写入操作(put/update)时刷新。 |
未提供
|
注意
索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,则 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, ...]]
列出并过滤存储中的命名空间。
用于探索数据的组织、查找特定集合或导航命名空间层次结构。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
前缀
|
NamespacePath | None
|
过滤以该路径开头的命名空间。 |
None
|
后缀
|
NamespacePath | None
|
过滤以该路径结尾的命名空间。 |
None
|
最大深度
|
int | None
|
返回层次结构中直到此深度的命名空间。深度超过此级别的命名空间将被截断。 |
None
|
限制
|
int
|
要返回的最大命名空间数量(默认100)。 |
100
|
偏移
|
int
|
分页时要跳过的命名空间数量(默认0)。 |
0
|
返回
类型 | 描述 |
---|---|
list[tuple[str, ...]]
|
List[Tuple[str, ...]]:符合条件的命名空间元组列表。 |
list[tuple[str, ...]]
|
每个元组表示一个完整命名空间路径,直到 |
???+ 示例 "Examples":设置 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]
在命名空间前缀内异步搜索项。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
命名空间前缀
|
tuple[str, ...]
|
要搜索的分层路径前缀。 |
必填 |
查询
|
str | None
|
用于自然语言搜索的可选查询。 |
None
|
过滤器
|
dict[str, Any] | None
|
用于过滤结果的键值对。 |
None
|
限制
|
int
|
要返回的最大项数。 |
10
|
偏移
|
int
|
在返回结果之前要跳过的项数。 |
0
|
刷新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
异步存储或更新存储中的项。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
命名空间
|
tuple[str, ...]
|
项的分层路径,表示为字符串元组。示例:("documents", "user123") |
必填 |
键
|
str
|
命名空间内的唯一标识符。与命名空间一起构成项的完整路径。 |
必填 |
值
|
dict[str, Any]
|
包含项数据的字典。必须包含字符串键和JSON可序列化值。 |
必填 |
索引
|
Literal[False] | list[str] | None
|
控制项的字段如何为搜索编制索引
|
None
|
TTL
|
float | None | NotProvided
|
生存时间,以分钟为单位。对此参数的支持取决于您的存储适配器。如果指定,该项将在上次访问后在此分钟数内过期。None表示永不过期。过期运行将被机会性删除。默认情况下,只要该项包含在操作中,过期计时器就会在读取操作(get/search)和写入操作(put/update)时刷新。 |
未提供
|
注意
索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,则 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, ...]]
异步列出并过滤存储中的命名空间。
用于探索数据的组织、查找特定集合或导航命名空间层次结构。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
前缀
|
NamespacePath | None
|
过滤以该路径开头的命名空间。 |
None
|
后缀
|
NamespacePath | None
|
过滤以该路径结尾的命名空间。 |
None
|
最大深度
|
int | None
|
返回层次结构中直到此深度的命名空间。深度超过此级别的命名空间将被截断到此深度。 |
None
|
限制
|
int
|
要返回的最大命名空间数量(默认100)。 |
100
|
偏移
|
int
|
分页时要跳过的命名空间数量(默认0)。 |
0
|
返回
类型 | 描述 |
---|---|
list[tuple[str, ...]]
|
List[Tuple[str, ...]]:符合条件的命名空间元组列表。 |
list[tuple[str, ...]]
|
每个元组表示一个完整命名空间路径,直到 |
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实例。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
连接字符串
|
str
|
Postgres连接信息字符串。 |
必填 |
管道
|
bool
|
是否使用管道 |
False
|
连接池配置
|
PoolConfig | None
|
连接池的配置。如果提供,将创建一个连接池并使用它而不是单个连接。这将覆盖 |
None
|
索引
|
PostgresIndexConfig | None
|
存储的索引配置。 |
None
|
TTL
|
TTLConfig | None
|
存储的TTL配置。 |
None
|
返回
名称 | 类型 | 描述 |
---|---|---|
Postgres存储 |
Iterator[PostgresStore]
|
新的PostgresStore实例。 |