跳到内容

存储

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

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

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

模块

名称 描述
batch

用于在后台任务中批处理操作的实用程序。

embed

用于处理嵌入函数和 LangChain 嵌入接口的实用程序。

名称 描述
Embeddings

嵌入模型接口。

Item

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

GetOp

通过命名空间和键检索特定项的操作。

SearchOp

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

MatchCondition

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

ListNamespacesOp

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

PutOp

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

BaseStore

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

函数

名称 描述
ensure_embeddings

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

get_text_at_path

使用路径表达式或预分词路径从对象中提取文本。

tokenize_path

将路径分词为组件。

属性

名称 类型 描述
NamespacePath

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

NamespaceMatchType

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

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

嵌入搜索文档。

embed_query

嵌入查询文本。

aembed_documents

异步嵌入搜索文档。

aembed_query

异步嵌入查询文本。

embed_documents abstractmethod

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

嵌入搜索文档。

参数

名称 类型 描述 默认
texts list[str]

要嵌入的文本列表。

必填

返回

类型 描述
list[list[float]]

嵌入列表。

embed_query abstractmethod

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

嵌入查询文本。

参数

名称 类型 描述 默认
text str

要嵌入的文本。

必填

返回

类型 描述
list[float]

嵌入。

aembed_documents async

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

异步嵌入搜索文档。

参数

名称 类型 描述 默认
texts list[str]

要嵌入的文本列表。

必填

返回

类型 描述
list[list[float]]

嵌入列表。

aembed_query async

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

异步嵌入查询文本。

参数

名称 类型 描述 默认
text str

要嵌入的文本。

必填

返回

类型 描述
list[float]

嵌入。

NotProvided

哨兵单例。

Item

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

参数

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

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

必填
key str

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

必填
namespace 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: Optional[float] = None,
) -> None

初始化一个结果项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径。

必填
key str

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

必填
value dict[str, Any]

存储的值。

必填
created_at datetime

项首次创建时间。

必填
updated_at datetime

项最后更新时间。

必填
score Optional[float]

如果是排名操作,则为相关性/相似度得分。

GetOp

基类:NamedTuple

通过命名空间和键检索特定项的操作。

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

示例

基本项检索

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

属性

名称 类型 描述
namespace tuple[str, ...]

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

key str

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

refresh_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
)

属性

名称 类型 描述
namespace_prefix tuple[str, ...]

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

filter Optional[dict[str, Any]]

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

limit int

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

offset int

为分页要跳过的匹配项数。

query Optional[str]

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

refresh_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: Optional[dict[str, Any]] = 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: Optional[str] = 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 NamespaceMatchType

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

path NamespacePath

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

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
)

属性

名称 类型 描述
match_conditions Optional[tuple[MatchCondition, ...]]

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

max_depth Optional[int]

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

limit int

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

offset int

为分页要跳过的命名空间数。

match_conditions class-attribute instance-attribute

match_conditions: Optional[tuple[MatchCondition, ...]] = (
    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: Optional[int] = None

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

注意

深于此级别的命名空间将被截断。

limit class-attribute instance-attribute

limit: int = 100

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

offset class-attribute instance-attribute

offset: int = 0

为分页要跳过的命名空间数。

PutOp

基类:NamedTuple

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

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

属性

名称 类型 描述
namespace tuple[str, ...]

标识项位置的分层路径。

key str

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

value Optional[dict[str, Any]]

要存储的数据,或 None 表示将项标记为删除。

index Optional[Union[Literal[False], list[str]]]

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

ttl Optional[float]

控制项的 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: Optional[dict[str, Any]]

要存储的数据,或 None 表示将项标记为删除。

该值必须是一个字典,其键为字符串,值为 JSON 可序列化。将其设置为 None 表示应删除该项。

示例

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

index class-attribute instance-attribute

index: Optional[Union[Literal[False], list[str]]] = 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: Optional[float] = None

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

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

InvalidNamespaceError

基类:ValueError

提供的命名空间无效。

TTLConfig

基类:TypedDict

存储中 TTL(生存时间)行为的配置。

属性

名称 类型 描述
refresh_on_read bool

读取操作(GET 和 SEARCH)时刷新 TTL 的默认行为。

default_ttl Optional[float]

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

sweep_interval_minutes Optional[int]

TTL 扫描操作之间的时间间隔(单位:分钟)。

refresh_on_read instance-attribute

refresh_on_read: bool

读取操作(GET 和 SEARCH)时刷新 TTL 的默认行为。

如果为 True,则默认情况下,在读取操作(get/search)时会刷新 TTL。这可以通过显式设置 refresh_ttl 来按操作覆盖。如果未配置,则默认为 True。

default_ttl instance-attribute

default_ttl: Optional[float]

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

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

sweep_interval_minutes instance-attribute

sweep_interval_minutes: Optional[int]

TTL 扫描操作之间的时间间隔(单位:分钟)。

如果提供,存储将根据 TTL 定期删除过期项。默认为 None(不扫描)。

IndexConfig

基类:TypedDict

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

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

属性

名称 类型 描述
dims int

嵌入向量的维度数。

embed Union[Embeddings, EmbeddingsFunc, AEmbeddingsFunc, str]

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

fields Optional[list[str]]

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

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: Union[
    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: Optional[list[str]]

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

控制存储项的哪些部分用于语义搜索的嵌入。遵循 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

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

abatch

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

get

检索单个项。

search

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

put

在存储中存储或更新项。

delete

删除项。

list_namespaces

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

aget

异步检索单个项。

asearch

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

aput

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

adelete

异步删除项。

alist_namespaces

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

batch abstractmethod

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

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

参数

名称 类型 描述 默认
ops Iterable[Op]

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

必填

返回

类型 描述
list[Result]

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

list[Result]

结果顺序与输入操作的顺序一致。

abatch abstractmethod async

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

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

参数

名称 类型 描述 默认
ops Iterable[Op]

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

必填

返回

类型 描述
list[Result]

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

list[Result]

结果顺序与输入操作的顺序一致。

get

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

检索单个项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径。

必填
key str

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

必填
refresh_ttl Optional[bool]

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

返回

类型 描述
Optional[Item]

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

search

search(
    namespace_prefix: tuple[str, ...],
    /,
    *,
    query: Optional[str] = None,
    filter: Optional[dict[str, Any]] = None,
    limit: int = 10,
    offset: int = 0,
    refresh_ttl: Optional[bool] = None,
) -> list[SearchItem]

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

参数

名称 类型 描述 默认
namespace_prefix tuple[str, ...]

要搜索的分层路径前缀。

必填
query Optional[str]

自然语言搜索的可选查询。

filter Optional[dict[str, Any]]

用于过滤结果的键值对。

limit int

要返回的最大项数。

10
offset int

返回结果前要跳过的项数。

0
refresh_ttl Optional[bool]

是否刷新返回项的 TTL。如果未指定 TTL,则此参数将被忽略。

返回

类型 描述
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: Optional[
        Union[Literal[False], list[str]]
    ] = None,
    *,
    ttl: Union[Optional[float], NotProvided] = NOT_PROVIDED
) -> None

在存储中存储或更新项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径,表示为字符串元组。示例:("documents", "user123")

必填
key str

命名空间内的唯一标识符。与命名空间一起构成项的完整路径。

必填
value dict[str, Any]

包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。

必填
index Optional[Union[Literal[False], list[str]]]

控制项的字段如何进行搜索索引

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

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

NOT_PROVIDED
注意

索引支持取决于您的存储实现。如果您在初始化存储时未启用索引功能,则 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

删除项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径。

必填
key str

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

必填

list_namespaces

list_namespaces(
    *,
    prefix: Optional[NamespacePath] = None,
    suffix: Optional[NamespacePath] = None,
    max_depth: Optional[int] = None,
    limit: int = 100,
    offset: int = 0
) -> list[tuple[str, ...]]

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

用于探索数据组织、查找特定集合或导航命名空间层次结构。

参数

名称 类型 描述 默认
prefix Optional[NamespacePath]

过滤以该路径开头的命名空间。

suffix Optional[NamespacePath]

过滤以该路径结尾的命名空间。

max_depth Optional[int]

返回此层次结构深度以下的命名空间。深于此级别的命名空间将被截断。

limit int

要返回的最大命名空间数(默认 100)。

100
offset int

为分页要跳过的命名空间数(默认 0)。

0

返回

类型 描述
list[tuple[str, ...]]

List[Tuple[str, ...]]: 匹配条件的命名空间元组列表。

list[tuple[str, ...]]

每个元组表示达到 max_depth 的完整命名空间路径。

???+ example "示例":设置 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: Optional[bool] = None
) -> Optional[Item]

异步检索单个项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径。

必填
key str

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

必填

返回

类型 描述
Optional[Item]

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

asearch async

asearch(
    namespace_prefix: tuple[str, ...],
    /,
    *,
    query: Optional[str] = None,
    filter: Optional[dict[str, Any]] = None,
    limit: int = 10,
    offset: int = 0,
    refresh_ttl: Optional[bool] = None,
) -> list[SearchItem]

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

参数

名称 类型 描述 默认
namespace_prefix tuple[str, ...]

要搜索的分层路径前缀。

必填
query Optional[str]

自然语言搜索的可选查询。

filter Optional[dict[str, Any]]

用于过滤结果的键值对。

limit int

要返回的最大项数。

10
offset int

返回结果前要跳过的项数。

0
refresh_ttl Optional[bool]

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

返回

类型 描述
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: Optional[
        Union[Literal[False], list[str]]
    ] = None,
    *,
    ttl: Union[Optional[float], NotProvided] = NOT_PROVIDED
) -> None

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

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径,表示为字符串元组。示例:("documents", "user123")

必填
key str

命名空间内的唯一标识符。与命名空间一起构成项的完整路径。

必填
value dict[str, Any]

包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。

必填
index Optional[Union[Literal[False], list[str]]]

控制项的字段如何进行搜索索引

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

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

NOT_PROVIDED
注意

索引支持取决于您的存储实现。如果您在初始化存储时未启用索引功能,则 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

异步删除项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径。

必填
key str

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

必填

alist_namespaces async

alist_namespaces(
    *,
    prefix: Optional[NamespacePath] = None,
    suffix: Optional[NamespacePath] = None,
    max_depth: Optional[int] = None,
    limit: int = 100,
    offset: int = 0
) -> list[tuple[str, ...]]

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

用于探索数据组织、查找特定集合或导航命名空间层次结构。

参数

名称 类型 描述 默认
prefix Optional[NamespacePath]

过滤以该路径开头的命名空间。

suffix Optional[NamespacePath]

过滤以该路径结尾的命名空间。

max_depth Optional[int]

返回此层次结构深度以下的命名空间。深于此级别的命名空间将被截断到此深度。

limit int

要返回的最大命名空间数(默认 100)。

100
offset 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: Union[
        Embeddings,
        EmbeddingsFunc,
        AEmbeddingsFunc,
        str,
        None,
    ],
) -> Embeddings

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

此函数包装任意嵌入函数,使其与 LangChain 的 Embeddings 接口兼容。它处理同步和异步函数。

参数

名称 类型 描述 默认
embed Union[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]

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

# 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: Union[str, list[str]]
) -> list[str]

使用路径表达式或预分词路径从对象中提取文本。

参数

名称 类型 描述 默认
obj Any

要从中提取文本的对象

必填
path Union[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

名称 描述
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 配置来启用它。如果没有此配置,则传递给 putaput 的所有 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: Optional[PoolConfig] = None,
    index: Optional[PostgresIndexConfig] = None,
    ttl: Optional[TTLConfig] = None
) -> AsyncIterator[AsyncPostgresStore]

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

参数

名称 类型 描述 默认
conn_string str

Postgres 连接信息字符串。

必填
pipeline bool

是否使用 AsyncPipeline(仅适用于单个连接)

False
pool_config Optional[PoolConfig]

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

index Optional[PostgresIndexConfig]

嵌入配置。

返回

名称 类型 描述
AsyncPostgresStore 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: Optional[int] = None,
) -> Task[None]

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

返回

类型 描述
Task[None]

可等待或取消的任务。

stop_ttl_sweeper async

stop_ttl_sweeper(timeout: Optional[float] = None) -> bool

如果 TTL 扫描任务正在运行,则停止它。

参数

名称 类型 描述 默认
等待任务停止的最大时间,单位:秒。如果为 None,则无限期等待。 Optional[float]

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

返回

名称 类型 描述
bool bool

PostgresStore

基类:BaseStore, BasePostgresStore[Conn]

或者使用方便的 from_conn_string 助手

使用 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")

语义搜索默认禁用。您可以通过在创建存储时提供 index 配置来启用它。如果没有此配置,则传递给 putaput 的所有 index 参数将不起作用。

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)

注意

首次使用前请务必调用 setup() 来创建必要的表和索引。要使用向量搜索,必须提供 pgvector 扩展。

警告

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

注意

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

方法

名称 描述
get

检索单个项。

search

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

put

在存储中存储或更新项。

delete

删除项。

list_namespaces

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

aget

异步检索单个项。

asearch

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

aput

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

adelete

异步删除项。

alist_namespaces

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

from_conn_string

如果 TTL 扫描器线程正在运行,则停止它。

sweep_ttl

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

start_ttl_sweeper

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

stop_ttl_sweeper

__del__

确保在对象被垃圾回收时停止 TTL 扫描器线程。

设置存储数据库。

setup

get

search

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

检索单个项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径。

必填
key str

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

必填
refresh_ttl Optional[bool]

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

返回

类型 描述
Optional[Item]

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

put

search(
    namespace_prefix: tuple[str, ...],
    /,
    *,
    query: Optional[str] = None,
    filter: Optional[dict[str, Any]] = None,
    limit: int = 10,
    offset: int = 0,
    refresh_ttl: Optional[bool] = None,
) -> list[SearchItem]

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

参数

名称 类型 描述 默认
namespace_prefix tuple[str, ...]

要搜索的分层路径前缀。

必填
query Optional[str]

自然语言搜索的可选查询。

filter Optional[dict[str, Any]]

用于过滤结果的键值对。

limit int

要返回的最大项数。

10
offset int

返回结果前要跳过的项数。

0
refresh_ttl Optional[bool]

是否刷新返回项的 TTL。如果未指定 TTL,则此参数将被忽略。

返回

类型 描述
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
)

注意:自然语言搜索支持取决于您的存储实现,并且需要正确的嵌入配置。

delete

put(
    namespace: tuple[str, ...],
    key: str,
    value: dict[str, Any],
    index: Optional[
        Union[Literal[False], list[str]]
    ] = None,
    *,
    ttl: Union[Optional[float], NotProvided] = NOT_PROVIDED
) -> None

在存储中存储或更新项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径,表示为字符串元组。示例:("documents", "user123")

必填
key str

命名空间内的唯一标识符。与命名空间一起构成项的完整路径。

必填
value dict[str, Any]

包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。

必填
index Optional[Union[Literal[False], list[str]]]

控制项的字段如何进行搜索索引

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

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

NOT_PROVIDED
注意

索引支持取决于您的存储实现。如果您在初始化存储时未启用索引功能,则 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"])

list_namespaces

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

删除项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径。

必填
key str

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

必填

aget async

list_namespaces(
    *,
    prefix: Optional[NamespacePath] = None,
    suffix: Optional[NamespacePath] = None,
    max_depth: Optional[int] = None,
    limit: int = 100,
    offset: int = 0
) -> list[tuple[str, ...]]

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

用于探索数据组织、查找特定集合或导航命名空间层次结构。

参数

名称 类型 描述 默认
prefix Optional[NamespacePath]

过滤以该路径开头的命名空间。

suffix Optional[NamespacePath]

过滤以该路径结尾的命名空间。

max_depth Optional[int]

返回此层次结构深度以下的命名空间。深于此级别的命名空间将被截断。

limit int

要返回的最大命名空间数(默认 100)。

100
offset int

为分页要跳过的命名空间数(默认 0)。

0

返回

类型 描述
list[tuple[str, ...]]

List[Tuple[str, ...]]: 匹配条件的命名空间元组列表。

list[tuple[str, ...]]

每个元组表示达到 max_depth 的完整命名空间路径。

???+ example "示例":设置 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")]

asearch async

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

异步检索单个项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径。

必填
key str

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

必填

返回

类型 描述
Optional[Item]

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

aput async

asearch(
    namespace_prefix: tuple[str, ...],
    /,
    *,
    query: Optional[str] = None,
    filter: Optional[dict[str, Any]] = None,
    limit: int = 10,
    offset: int = 0,
    refresh_ttl: Optional[bool] = None,
) -> list[SearchItem]

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

参数

名称 类型 描述 默认
namespace_prefix tuple[str, ...]

要搜索的分层路径前缀。

必填
query Optional[str]

自然语言搜索的可选查询。

filter Optional[dict[str, Any]]

用于过滤结果的键值对。

limit int

要返回的最大项数。

10
offset int

返回结果前要跳过的项数。

0
refresh_ttl Optional[bool]

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

返回

类型 描述
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
)

注意:自然语言搜索支持取决于您的存储实现,并且需要正确的嵌入配置。

adelete async

aput(
    namespace: tuple[str, ...],
    key: str,
    value: dict[str, Any],
    index: Optional[
        Union[Literal[False], list[str]]
    ] = None,
    *,
    ttl: Union[Optional[float], NotProvided] = NOT_PROVIDED
) -> None

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

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径,表示为字符串元组。示例:("documents", "user123")

必填
key str

命名空间内的唯一标识符。与命名空间一起构成项的完整路径。

必填
value dict[str, Any]

包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。

必填
index Optional[Union[Literal[False], list[str]]]

控制项的字段如何进行搜索索引

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

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

NOT_PROVIDED
注意

索引支持取决于您的存储实现。如果您在初始化存储时未启用索引功能,则 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"]
)

alist_namespaces async

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

异步删除项。

参数

名称 类型 描述 默认
namespace tuple[str, ...]

项的分层路径。

必填
key str

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

必填

from_conn-string classmethod

alist_namespaces(
    *,
    prefix: Optional[NamespacePath] = None,
    suffix: Optional[NamespacePath] = None,
    max_depth: Optional[int] = None,
    limit: int = 100,
    offset: int = 0
) -> list[tuple[str, ...]]

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

用于探索数据组织、查找特定集合或导航命名空间层次结构。

参数

名称 类型 描述 默认
prefix Optional[NamespacePath]

过滤以该路径开头的命名空间。

suffix Optional[NamespacePath]

过滤以该路径结尾的命名空间。

max_depth Optional[int]

返回此层次结构深度以下的命名空间。深于此级别的命名空间将被截断到此深度。

limit int

要返回的最大命名空间数(默认 100)。

100
offset 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")]

是否使用 Pipeline

from_conn_string(
    conn_string: str,
    *,
    pipeline: bool = False,
    pool_config: Optional[PoolConfig] = None,
    index: Optional[PostgresIndexConfig] = None,
    ttl: Optional[TTLConfig] = None
) -> Iterator[PostgresStore]

如果 TTL 扫描器线程正在运行,则停止它。

参数

名称 类型 描述 默认
conn_string str

Postgres 连接信息字符串。

必填
pipeline bool

存储的索引配置。

False
pool_config Optional[PoolConfig]

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

index Optional[PostgresIndexConfig]

返回

名称 类型 描述
PostgresStore 一个新的 PostgresStore 实例。

sweep_ttl

start_ttl_sweeper

sweep_ttl() -> int

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

返回

名称 类型 描述
int int

已删除项的数量。

Future[None]

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

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

返回

类型 描述
可以等待或取消的 Future。

stop_ttl_sweeper

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

stop_ttl_sweeper(timeout: Optional[float] = None) -> bool

__del__

参数

名称 类型 描述 默认
等待任务停止的最大时间,单位:秒。如果为 None,则无限期等待。 Optional[float]

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

返回

名称 类型 描述
bool bool

__del__

setup

__del__() -> None

设置存储数据库。

回到顶部

setup() -> None

get

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