跳到内容

存储

用于持久化键值存储的基础类和类型。

存储提供跨线程和对话的长期记忆。支持分层命名空间、键值存储和可选的向量搜索。

核心类型
  • BaseStore: 支持同步/异步操作的存储接口
  • Item: 带有元数据的存储键值对
  • Op: 获取/放置/搜索/列表操作

模块

名称 描述
批量

用于在后台任务中批量处理操作的实用工具。

嵌入

用于处理嵌入函数和LangChain嵌入接口的实用工具。

名称 描述
嵌入

嵌入模型的接口。

表示带有元数据的存储项。

获取操作

根据命名空间和键检索特定项的操作。

搜索操作

在指定的命名空间层次结构中搜索项的操作。

匹配条件

表示存储中命名空间匹配的模式。

列出命名空间操作

列出和过滤存储中命名空间的操作。

放置操作

在存储中存储、更新或删除项的操作。

基础存储

用于持久化键值存储的抽象基类。

函数

名称 描述
确保嵌入

确保嵌入函数符合LangChain的嵌入接口。

按路径获取文本

使用路径表达式或预标记化路径从对象中提取文本。

标记化路径

将路径标记化为组件。

属性

名称 类型 描述
命名空间路径

表示可包含通配符的命名空间路径的元组。

命名空间匹配类型

指定如何匹配命名空间路径。

NamespacePath module-attribute

NamespacePath = tuple[Union[str, Literal['*']], ...]

表示可包含通配符的命名空间路径的元组。

示例
("users",)  # Exact users namespace
("documents", "*")  # Any sub-namespace under documents
("cache", "*", "v1")  # Any cache category with v1 version

NamespaceMatchType module-attribute

NamespaceMatchType = Literal['prefix', 'suffix']

指定如何匹配命名空间路径。

"prefix": 从命名空间的开头匹配 "suffix": 从命名空间的末尾匹配

Embeddings

基础类: ABC

嵌入模型的接口。

这是一个用于实现文本嵌入模型的接口。

文本嵌入模型用于将文本映射到向量(n维空间中的一个点)。

相似的文本通常会被映射到该空间中彼此靠近的点。关于什么是“相似”以及如何测量该空间中的“距离”的具体细节取决于特定的嵌入模型。

此抽象包含一个用于嵌入文档列表的方法和一个用于嵌入查询文本的方法。查询文本的嵌入预期是一个单一向量,而文档列表的嵌入预期是一个向量列表。

通常查询嵌入与文档嵌入相同,但此抽象允许独立处理它们。

除了同步方法之外,此接口还提供了这些方法的异步版本。

默认情况下,异步方法是使用同步方法实现的;但是,为了性能原因,实现可以选择用异步原生实现覆盖异步方法。

方法

名称 描述
嵌入文档

嵌入搜索文档。

嵌入查询

嵌入查询文本。

异步嵌入文档

异步嵌入搜索文档。

异步嵌入查询

异步嵌入查询文本。

embed_documents abstractmethod

embed_documents(texts: list[str]) -> list[list[float]]

嵌入搜索文档。

参数

名称 类型 描述 默认值
文本 list[str]

要嵌入的文本列表。

必填

返回

类型 描述
list[list[float]]

嵌入列表。

embed_query abstractmethod

embed_query(text: str) -> list[float]

嵌入查询文本。

参数

名称 类型 描述 默认值
文本 str

要嵌入的文本。

必填

返回

类型 描述
list[float]

嵌入。

aembed_documents async

aembed_documents(texts: list[str]) -> list[list[float]]

异步嵌入搜索文档。

参数

名称 类型 描述 默认值
文本 list[str]

要嵌入的文本列表。

必填

返回

类型 描述
list[list[float]]

嵌入列表。

aembed_query async

aembed_query(text: str) -> list[float]

异步嵌入查询文本。

参数

名称 类型 描述 默认值
文本 str

要嵌入的文本。

必填

返回

类型 描述
list[float]

嵌入。

NotProvided

哨兵单例。

Item

表示带有元数据的存储项。

参数

名称 类型 描述 默认值
dict[str, Any]

存储的数据以字典形式存在。键可用于过滤。

必填
str

命名空间内的唯一标识符。

必填
命名空间 tuple[str, ...]

定义此文档所在集合的分层路径。表示为字符串元组,允许嵌套分类。例如:("documents", 'user123')

必填
created_at datetime

项创建的时间戳。

必填
updated_at datetime

最后更新的时间戳。

必填

SearchItem

基础类: Item

表示从搜索操作返回的带有额外元数据的项。

方法

名称 描述
__init__

初始化结果项。

__init__

__init__(
    namespace: tuple[str, ...],
    key: str,
    value: dict[str, Any],
    created_at: datetime,
    updated_at: datetime,
    score: float | None = None,
) -> None

初始化结果项。

参数

名称 类型 描述 默认值
命名空间 tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填
dict[str, Any]

存储的值。

必填
created_at datetime

项首次创建的时间。

必填
updated_at datetime

项最后更新的时间。

必填
分数 float | None

如果来自排名操作,则为相关性/相似性分数。

None

GetOp

基础类: NamedTuple

根据命名空间和键检索特定项的操作。

此操作允许使用存储项的完整路径(命名空间)和唯一标识符(键)组合来精确检索。

示例

基本项检索

GetOp(namespace=("users", "profiles"), key="user123")
GetOp(namespace=("cache", "embeddings"), key="doc456")

属性

名称 类型 描述
命名空间 tuple[str, ...]

唯一标识项位置的分层路径。

str

项在其特定命名空间内的唯一标识符。

刷新TTL bool

是否刷新返回项的TTL。

namespace instance-attribute

namespace: tuple[str, ...]

唯一标识项位置的分层路径。

示例
("users",)  # Root level users namespace
("users", "profiles")  # Profiles within users namespace

key instance-attribute

key: str

项在其特定命名空间内的唯一标识符。

示例
"user123"  # For a user profile
"doc456"  # For a document

refresh_ttl class-attribute instance-attribute

refresh_ttl: bool = True

是否刷新返回项的TTL。

如果原始项未指定TTL,或者您的适配器未启用TTL支持,则此参数将被忽略。

SearchOp

基础类: NamedTuple

在指定的命名空间层次结构中搜索项的操作。

此操作支持在给定命名空间前缀内进行结构化过滤和自然语言搜索。它通过limit和offset参数提供分页功能。

注意

自然语言搜索支持取决于您的存储实现。

示例

带过滤器和分页的搜索

SearchOp(
    namespace_prefix=("documents",),
    filter={"type": "report", "status": "active"},
    limit=5,
    offset=10
)

自然语言搜索

SearchOp(
    namespace_prefix=("users", "content"),
    query="technical documentation about APIs",
    limit=20
)

属性

名称 类型 描述
命名空间前缀 tuple[str, ...]

定义搜索范围的分层路径前缀。

过滤器 dict[str, Any] | None

用于根据精确匹配或比较运算符过滤结果的键值对。

限制 int

搜索结果中返回的最大项数。

偏移 int

分页时跳过的匹配项数。

查询 str | None

用于语义搜索功能的自然语言搜索查询。

刷新TTL bool

是否刷新返回项的TTL。

namespace_prefix instance-attribute

namespace_prefix: tuple[str, ...]

定义搜索范围的分层路径前缀。

示例
()  # Search entire store
("documents",)  # Search all documents
("users", "content")  # Search within user content

filter class-attribute instance-attribute

filter: dict[str, Any] | None = None

用于根据精确匹配或比较运算符过滤结果的键值对。

过滤器支持精确匹配和基于运算符的比较。

支持的运算符
  • $eq: 等于(与直接值比较相同)
  • $ne: 不等于
  • $gt: 大于
  • $gte: 大于或等于
  • $lt: 小于
  • $lte: 小于或等于
示例

简单精确匹配

{"status": "active"}

比较运算符

{"score": {"$gt": 4.99}}  # Score greater than 4.99

多个条件

{
    "score": {"$gte": 3.0},
    "color": "red"
}

limit class-attribute instance-attribute

limit: int = 10

搜索结果中返回的最大项数。

offset class-attribute instance-attribute

offset: int = 0

分页时跳过的匹配项数。

query class-attribute instance-attribute

query: str | None = None

用于语义搜索功能的自然语言搜索查询。

示例
  • "关于REST API的技术文档"
  • "2023年的机器学习论文"

refresh_ttl class-attribute instance-attribute

refresh_ttl: bool = True

是否刷新返回项的TTL。

如果原始项未指定TTL,或者您的适配器未启用TTL支持,则此参数将被忽略。

MatchCondition

基础类: NamedTuple

表示存储中命名空间匹配的模式。

此类结合了匹配类型(前缀或后缀)和可包含通配符的命名空间路径模式,以灵活匹配不同的命名空间层次结构。

示例

前缀匹配

MatchCondition(match_type="prefix", path=("users", "profiles"))

带通配符的后缀匹配

MatchCondition(match_type="suffix", path=("cache", "*"))

简单后缀匹配

MatchCondition(match_type="suffix", path=("v1",))

属性

名称 类型 描述
匹配类型 命名空间匹配类型

要执行的命名空间匹配类型。

路径 命名空间路径

可包含通配符的命名空间路径模式。

match_type instance-attribute

match_type: NamespaceMatchType

要执行的命名空间匹配类型。

path instance-attribute

可包含通配符的命名空间路径模式。

ListNamespacesOp

基础类: NamedTuple

列出和过滤存储中命名空间的操作。

此操作允许探索数据的组织、查找特定集合以及导航命名空间层次结构。

示例

列出“documents”路径下的所有命名空间

ListNamespacesOp(
    match_conditions=(MatchCondition(match_type="prefix", path=("documents",)),),
    max_depth=2
)

列出所有以“v1”结尾的命名空间

ListNamespacesOp(
    match_conditions=(MatchCondition(match_type="suffix", path=("v1",)),),
    limit=50
)

属性

名称 类型 描述
匹配条件 tuple[MatchCondition, ...] | None

用于过滤命名空间的可选条件。

最大深度 int | None

返回命名空间层次结构的最大深度。

限制 int

返回的最大命名空间数量。

偏移 int

分页时跳过的命名空间数量。

match_conditions class-attribute instance-attribute

match_conditions: tuple[MatchCondition, ...] | None = None

用于过滤命名空间的可选条件。

示例

所有用户命名空间

(MatchCondition(match_type="prefix", path=("users",)),)

所有以“docs”开头并以“draft”结尾的命名空间

(
    MatchCondition(match_type="prefix", path=("docs",)),
    MatchCondition(match_type="suffix", path=("draft",))
) 

max_depth class-attribute instance-attribute

max_depth: int | None = None

返回命名空间层次结构的最大深度。

注意

深度超过此级别的命名空间将被截断。

limit class-attribute instance-attribute

limit: int = 100

返回的最大命名空间数量。

offset class-attribute instance-attribute

offset: int = 0

分页时跳过的命名空间数量。

PutOp

基础类: NamedTuple

在存储中存储、更新或删除项的操作。

此类表示修改存储内容(无论是添加新项、更新现有项还是删除项)的单个操作。

属性

名称 类型 描述
命名空间 tuple[str, ...]

标识项位置的分层路径。

str

项在其命名空间内的唯一标识符。

dict[str, Any] | None

要存储的数据,或None以标记项待删除。

索引 Literal[False] | list[str] | None

控制项的字段如何为搜索操作编制索引。

TTL float | None

控制项的TTL(生存时间,以分钟为单位)。

namespace instance-attribute

namespace: tuple[str, ...]

标识项位置的分层路径。

命名空间充当类似文件夹的结构来组织项。元组中的每个元素代表层次结构中的一个级别。

示例

根级别文档

("documents",)

用户特定文档

("documents", "user123")

嵌套缓存结构

("cache", "embeddings", "v1")

key instance-attribute

key: str

项在其命名空间内的唯一标识符。

键在特定命名空间内必须唯一,以避免冲突。它与命名空间一起构成了项的完整路径。

示例

如果命名空间是 ("documents", "user123") 且键是 "report1",则完整路径实际上是 "documents/user123/report1"

value instance-attribute

value: dict[str, Any] | None

要存储的数据,或None以标记项待删除。

值必须是带有字符串键和JSON可序列化值的字典。将其设置为 None 表示该项应被删除。

示例

{ "field1": "string value", "field2": 123, "nested": {"can": "contain", "any": "serializable data"} }

index class-attribute instance-attribute

index: Literal[False] | list[str] | None = None

控制项的字段如何为搜索操作编制索引。

无论是否索引,该项都可以通过直接的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
]

ttl class-attribute instance-attribute

ttl: float | None = None

控制项的TTL(生存时间,以分钟为单位)。

如果提供此参数,并且您使用的存储支持此功能,则该项将在上次访问后在此分钟数内过期。过期计时器在读取操作(get/search)和写入操作(put/update)时都会刷新。当TTL过期时,该项将以最大努力原则计划删除。默认为 None(永不过期)。

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。

default_ttl instance-attribute

default_ttl: float | None

新项的默认TTL(生存时间,以分钟为单位)。

如果提供此参数,新项将在最后一次访问后在此分钟数内过期。过期计时器在读取和写入操作时都会刷新。默认为 None(永不过期)。

sweep_interval_minutes instance-attribute

sweep_interval_minutes: int | None

TTL清理操作之间的间隔(分钟)。

如果提供此参数,存储将根据TTL定期删除过期项。默认为 None(不清理)。

IndexConfig

基础类: TypedDict

用于在存储中索引文档以进行语义搜索的配置。

如果未提供给存储,存储将不支持向量搜索。在这种情况下,put() 和 aput() 操作的所有 index 参数都将被忽略。

属性

名称 类型 描述
维度 int

嵌入向量中的维度数量。

嵌入 Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str

从文本生成嵌入的可选函数。

字段 list[str] | None

用于从其中提取文本以生成嵌入的字段。

dims instance-attribute

dims: int

嵌入向量中的维度数量。

常见的嵌入模型具有以下维度
  • openai:text-embedding-3-large: 3072
  • openai:text-embedding-3-small: 1536
  • openai:text-embedding-ada-002: 1536
  • cohere:embed-english-v3.0: 1024
  • cohere:embed-english-light-v3.0: 384
  • cohere:embed-multilingual-v3.0: 1024
  • cohere:embed-multilingual-light-v3.0: 384

embed instance-attribute

embed: Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str

从文本生成嵌入的可选函数。

可以通过三种方式指定
  1. 一个LangChain Embeddings实例
  2. 一个同步嵌入函数(EmbeddingsFunc)
  3. 一个异步嵌入函数(AEmbeddingsFunc)
  4. 一个提供者字符串(例如:"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

fields: list[str] | None

用于从其中提取文本以生成嵌入的字段。

控制存储项的哪些部分被嵌入以进行语义搜索。遵循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
注意

在使用 putaput 操作中的 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

batch(ops: Iterable[Op]) -> list[Result]

在单个批次中同步执行多个操作。

参数

名称 类型 描述 默认值
操作 Iterable[Op]

要执行的操作的可迭代对象。

必填

返回

类型 描述
list[Result]

结果列表,其中每个结果对应于输入中的一个操作。

list[Result]

结果的顺序与输入操作的顺序匹配。

abatch abstractmethod async

abatch(ops: Iterable[Op]) -> list[Result]

在单个批次中异步执行多个操作。

参数

名称 类型 描述 默认值
操作 Iterable[Op]

要执行的操作的可迭代对象。

必填

返回

类型 描述
list[Result]

结果列表,其中每个结果对应于输入中的一个操作。

list[Result]

结果的顺序与输入操作的顺序匹配。

get

get(
    namespace: tuple[str, ...],
    key: str,
    *,
    refresh_ttl: bool | None = None
) -> Item | None

检索单个项。

参数

名称 类型 描述 默认值
命名空间 tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填
刷新TTL bool | None

是否刷新返回项的TTL。如果为 None(默认),则使用存储的默认refresh_ttl设置。如果未指定TTL,则此参数将被忽略。

None

返回

类型 描述
Item | None

检索到的项,如果未找到则为 None。

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(默认):使用您在创建存储时配置的 fields (如果有)如果您没有使用索引功能初始化存储,则 index 参数将被忽略
  • False:禁用此项的索引
  • list[str]:要索引的字段路径列表,支持
    • 嵌套字段:"metadata.title"
    • 数组访问:"chapters[*].content"(每个单独索引)
    • 特定索引:"authors[0].name"
None
TTL float | None | NotProvided

生存时间,以分钟为单位。对此参数的支持取决于您的存储适配器。如果指定,该项将在上次访问后在此分钟数内过期。None表示永不过期。过期运行将被机会性删除。默认情况下,只要该项包含在操作中,过期计时器就会在读取操作(get/search)和写入操作(put/update)时刷新。

未提供
注意

索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,则 index 参数将被忽略。

同样,TTL支持取决于特定的存储实现。某些实现可能不支持项的过期。

示例

存储项。索引取决于您如何配置存储。

store.put(("docs",), "report", {"memory": "Will likes ai"})

不为语义搜索索引项。仍然可以通过get()和search()操作访问,但不会有向量表示。

store.put(("docs",), "report", {"memory": "Will likes ai"}, index=False)

为搜索索引特定字段。

store.put(("docs",), "report", {"memory": "Will likes ai"}, index=["memory"])

delete

delete(namespace: tuple[str, ...], key: str) -> None

删除项。

参数

名称 类型 描述 默认值
命名空间 tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

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, ...]]

每个元组表示一个完整命名空间路径,直到 max_depth

???+ 示例 "Examples":设置 max_depth=3。给定命名空间

# Example if you have the following namespaces:
# ("a", "b", "c")
# ("a", "b", "d", "e")
# ("a", "b", "d", "i")
# ("a", "b", "f")
# ("a", "c", "f")
store.list_namespaces(prefix=("a", "b"), max_depth=3)
# [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")]

aget async

aget(
    namespace: tuple[str, ...],
    key: str,
    *,
    refresh_ttl: bool | None = None
) -> Item | None

异步检索单个项。

参数

名称 类型 描述 默认值
命名空间 tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

返回

类型 描述
Item | None

检索到的项,如果未找到则为 None。

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(默认):使用您在创建存储时配置的 fields (如果有)如果您没有使用索引功能初始化存储,则 index 参数将被忽略
  • False:禁用此项的索引
  • list[str]:要索引的字段路径列表,支持
    • 嵌套字段:"metadata.title"
    • 数组访问:"chapters[*].content"(每个单独索引)
    • 特定索引:"authors[0].name"
None
TTL float | None | NotProvided

生存时间,以分钟为单位。对此参数的支持取决于您的存储适配器。如果指定,该项将在上次访问后在此分钟数内过期。None表示永不过期。过期运行将被机会性删除。默认情况下,只要该项包含在操作中,过期计时器就会在读取操作(get/search)和写入操作(put/update)时刷新。

未提供
注意

索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,则 index 参数将被忽略。

同样,TTL支持取决于特定的存储实现。某些实现可能不支持项的过期。

示例

存储项。索引取决于您如何配置存储。

await store.aput(("docs",), "report", {"memory": "Will likes ai"})

不为语义搜索索引项。仍然可以通过get()和search()操作访问,但不会有向量表示。

await store.aput(("docs",), "report", {"memory": "Will likes ai"}, index=False)

为搜索索引特定字段(如果存储配置为索引项)

await store.aput(
    ("docs",),
    "report",
    {
        "memory": "Will likes ai",
        "context": [{"content": "..."}, {"content": "..."}]
    },
    index=["memory", "context[*].content"]
)

adelete async

adelete(namespace: tuple[str, ...], key: str) -> None

异步删除项。

参数

名称 类型 描述 默认值
命名空间 tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

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, ...]]

每个元组表示一个完整命名空间路径,直到 max_depth

示例

设置max_depth=3和现有命名空间

# Given the following namespaces:
# ("a", "b", "c")
# ("a", "b", "d", "e")
# ("a", "b", "d", "i")
# ("a", "b", "f")
# ("a", "c", "f")

await store.alist_namespaces(prefix=("a", "b"), max_depth=3)
# Returns: [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")]

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]

使用提供者字符串初始化嵌入

# Requires langchain>=0.3.9 and langgraph-checkpoint>=2.0.11
embeddings = ensure_embeddings("openai:text-embedding-3-small")
result = embeddings.embed_query("hello")

get_text_at_path

get_text_at_path(
    obj: Any, path: str | list[str]
) -> list[str]

使用路径表达式或预标记化路径从对象中提取文本。

参数

名称 类型 描述 默认值
obj Any

要从中提取文本的对象

必填
路径 str | list[str]

路径字符串或预标记化路径列表。

必填

处理的路径类型

  • 简单路径:"field1.field2"
  • 数组索引:"[0]", "[*]", "[-1]"
  • 通配符:"*"
  • 多字段选择:"{field1,field2}"
  • 多字段中的嵌套路径:"{field1,nested.field2}"

tokenize_path

tokenize_path(path: str) -> list[str]

将路径标记化为组件。

处理的类型

  • 简单路径:"field1.field2"
  • 数组索引:"[0]", "[*]", "[-1]"
  • 通配符:"*"
  • 多字段选择:"{field1,field2}"

模块

名称 描述
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 配置来启用它。如果没有此配置,所有传递给 putaputindex 参数将不起作用。

注意

如果您提供了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

连接池的配置。如果提供,将创建一个连接池并使用它而不是单个连接。这将覆盖 pipeline 参数。

None
索引 PostgresIndexConfig | None

嵌入配置。

None

返回

名称 类型 描述
异步Postgres存储 AsyncIterator[AsyncPostgresStore]

新的AsyncPostgresStore实例。

setup async

setup() -> None

异步设置存储数据库。

此方法在Postgres数据库中创建必要的表(如果它们尚不存在)并运行数据库迁移。首次使用存储时,用户必须直接调用此方法。

sweep_ttl async

sweep_ttl() -> int

根据TTL删除过期存储项。

返回

名称 类型 描述
int int

删除的项数。

start_ttl_sweeper async

start_ttl_sweeper(
    sweep_interval_minutes: int | None = None,
) -> Task[None]

根据TTL定期删除过期存储项。

返回

类型 描述
Task[None]

可以等待或取消的任务。

stop_ttl_sweeper async

stop_ttl_sweeper(timeout: float | None = None) -> bool

如果TTL清理任务正在运行,则停止它。

参数

名称 类型 描述 默认值
超时 float | None

等待任务停止的最大时间,以秒为单位。如果为 None,则无限期等待。

None

返回

名称 类型 描述
bool bool

如果任务成功停止或未运行,则为 True;如果任务停止前达到超时,则为 False。

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 配置来启用它。如果没有此配置,所有传递给 putaputindex 参数将不起作用。

警告

确保在首次使用前调用 setup() 来创建必要的表和索引。必须有pgvector扩展才能使用向量搜索。

注意

如果您提供了TTL配置,则必须显式调用 start_ttl_sweeper() 来启动删除过期项的后台线程。当您使用完存储后,调用 stop_ttl_sweeper() 以正确清理资源。

方法

名称 描述
获取

检索单个项。

搜索

在命名空间前缀内搜索项。

放置

在存储中存储或更新项。

删除

删除项。

列出命名空间

列出并过滤存储中的命名空间。

异步获取

异步检索单个项。

异步搜索

在命名空间前缀内异步搜索项。

异步放置

异步存储或更新存储中的项。

异步删除

异步删除项。

异步列出命名空间

异步列出并过滤存储中的命名空间。

从连接字符串创建

从连接字符串创建新的PostgresStore实例。

清理TTL

根据TTL删除过期存储项。

启动TTL清理器

根据TTL定期删除过期存储项。

停止TTL清理器

如果TTL清理线程正在运行,则停止它。

__del__

确保当对象被垃圾回收时,TTL清理线程停止。

设置

设置存储数据库。

get

get(
    namespace: tuple[str, ...],
    key: str,
    *,
    refresh_ttl: bool | None = None
) -> Item | None

检索单个项。

参数

名称 类型 描述 默认值
命名空间 tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填
刷新TTL bool | None

是否刷新返回项的TTL。如果为 None(默认),则使用存储的默认refresh_ttl设置。如果未指定TTL,则此参数将被忽略。

None

返回

类型 描述
Item | None

检索到的项,如果未找到则为 None。

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(默认):使用您在创建存储时配置的 fields (如果有)如果您没有使用索引功能初始化存储,则 index 参数将被忽略
  • False:禁用此项的索引
  • list[str]:要索引的字段路径列表,支持
    • 嵌套字段:"metadata.title"
    • 数组访问:"chapters[*].content"(每个单独索引)
    • 特定索引:"authors[0].name"
None
TTL float | None | NotProvided

生存时间,以分钟为单位。对此参数的支持取决于您的存储适配器。如果指定,该项将在上次访问后在此分钟数内过期。None表示永不过期。过期运行将被机会性删除。默认情况下,只要该项包含在操作中,过期计时器就会在读取操作(get/search)和写入操作(put/update)时刷新。

未提供
注意

索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,则 index 参数将被忽略。

同样,TTL支持取决于特定的存储实现。某些实现可能不支持项的过期。

示例

存储项。索引取决于您如何配置存储。

store.put(("docs",), "report", {"memory": "Will likes ai"})

不为语义搜索索引项。仍然可以通过get()和search()操作访问,但不会有向量表示。

store.put(("docs",), "report", {"memory": "Will likes ai"}, index=False)

为搜索索引特定字段。

store.put(("docs",), "report", {"memory": "Will likes ai"}, index=["memory"])

delete

delete(namespace: tuple[str, ...], key: str) -> None

删除项。

参数

名称 类型 描述 默认值
命名空间 tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

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, ...]]

每个元组表示一个完整命名空间路径,直到 max_depth

???+ 示例 "Examples":设置 max_depth=3。给定命名空间

# Example if you have the following namespaces:
# ("a", "b", "c")
# ("a", "b", "d", "e")
# ("a", "b", "d", "i")
# ("a", "b", "f")
# ("a", "c", "f")
store.list_namespaces(prefix=("a", "b"), max_depth=3)
# [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")]

aget async

aget(
    namespace: tuple[str, ...],
    key: str,
    *,
    refresh_ttl: bool | None = None
) -> Item | None

异步检索单个项。

参数

名称 类型 描述 默认值
命名空间 tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

返回

类型 描述
Item | None

检索到的项,如果未找到则为 None。

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(默认):使用您在创建存储时配置的 fields (如果有)如果您没有使用索引功能初始化存储,则 index 参数将被忽略
  • False:禁用此项的索引
  • list[str]:要索引的字段路径列表,支持
    • 嵌套字段:"metadata.title"
    • 数组访问:"chapters[*].content"(每个单独索引)
    • 特定索引:"authors[0].name"
None
TTL float | None | NotProvided

生存时间,以分钟为单位。对此参数的支持取决于您的存储适配器。如果指定,该项将在上次访问后在此分钟数内过期。None表示永不过期。过期运行将被机会性删除。默认情况下,只要该项包含在操作中,过期计时器就会在读取操作(get/search)和写入操作(put/update)时刷新。

未提供
注意

索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,则 index 参数将被忽略。

同样,TTL支持取决于特定的存储实现。某些实现可能不支持项的过期。

示例

存储项。索引取决于您如何配置存储。

await store.aput(("docs",), "report", {"memory": "Will likes ai"})

不为语义搜索索引项。仍然可以通过get()和search()操作访问,但不会有向量表示。

await store.aput(("docs",), "report", {"memory": "Will likes ai"}, index=False)

为搜索索引特定字段(如果存储配置为索引项)

await store.aput(
    ("docs",),
    "report",
    {
        "memory": "Will likes ai",
        "context": [{"content": "..."}, {"content": "..."}]
    },
    index=["memory", "context[*].content"]
)

adelete async

adelete(namespace: tuple[str, ...], key: str) -> None

异步删除项。

参数

名称 类型 描述 默认值
命名空间 tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

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, ...]]

每个元组表示一个完整命名空间路径,直到 max_depth

示例

设置max_depth=3和现有命名空间

# Given the following namespaces:
# ("a", "b", "c")
# ("a", "b", "d", "e")
# ("a", "b", "d", "i")
# ("a", "b", "f")
# ("a", "c", "f")

await store.alist_namespaces(prefix=("a", "b"), max_depth=3)
# Returns: [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")]

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

连接池的配置。如果提供,将创建一个连接池并使用它而不是单个连接。这将覆盖 pipeline 参数。

None
索引 PostgresIndexConfig | None

存储的索引配置。

None
TTL TTLConfig | None

存储的TTL配置。

None

返回

名称 类型 描述
Postgres存储 Iterator[PostgresStore]

新的PostgresStore实例。

sweep_ttl

sweep_ttl() -> int

根据TTL删除过期存储项。

返回

名称 类型 描述
int int

删除的项数。

start_ttl_sweeper

start_ttl_sweeper(
    sweep_interval_minutes: int | None = None,
) -> Future[None]

根据TTL定期删除过期存储项。

返回

类型 描述
Future[None]

可以等待或取消的Future。

stop_ttl_sweeper

stop_ttl_sweeper(timeout: float | None = None) -> bool

如果TTL清理线程正在运行,则停止它。

参数

名称 类型 描述 默认值
超时 float | None

等待线程停止的最大时间,以秒为单位。如果为 None,则无限期等待。

None

返回

名称 类型 描述
bool bool

如果线程成功停止或未运行,则为 True;如果线程停止前达到超时,则为 False。

__del__

__del__() -> None

确保当对象被垃圾回收时,TTL清理线程停止。

setup

setup() -> None

设置存储数据库。

此方法在Postgres数据库中创建必要的表(如果它们尚不存在)并运行数据库迁移。首次使用存储时,用户必须直接调用此方法。