langchain_community.vectorstores.duckdb.DuckDB

class langchain_community.vectorstores.duckdb.DuckDB(*, connection: Optional[Any] = None, embedding: Embeddings, vector_key: str = 'embedding', id_key: str = 'id', text_key: str = 'text', table_name: str = 'embeddings')[source]

DuckDB 向量存储。

此类为使用 DuckDB 添加文本和执行相似性搜索提供了向量存储接口。

有关 DuckDB 的更多信息,请参阅: https://duckdb.org/

此集成需要 duckdb Python 包。您可以使用 pip install duckdb 安装它。

安全注意事项:默认 DuckDB 配置不安全。

默认情况下,DuckDB 可以与整个文件系统中的文件进行交互,包括读取、写入和列出文件和目录的功能。它还可以访问全局命名空间中存在的一些 python 变量。

当使用此 DuckDB 向量存储时,我们建议您使用安全配置初始化 DuckDB 连接。

例如,您可以在连接配置中将 enable_external_access 设置为 false,以禁用对 DuckDB 连接的外部访问。

您可以在此处查看 DuckDB 配置选项

https://duckdb.org/docs/configuration/overview.html

请查看 DuckDB 文档中的其他相关安全注意事项。(例如,“autoinstall_known_extensions”:“false”,“autoload_known_extensions”:“false”)

有关更多信息,请参阅 https://python.langchain.ac.cn/docs/security

参数
  • connection (Optional[Any]) – 可选的 DuckDB 连接

  • embedding (Embeddings) – 用于生成嵌入的嵌入函数或模型。

  • vector_key (str) – 用于存储向量的列名。默认为 embedding

  • id_key (str) – 用于存储唯一标识符的列名。默认为 id

  • text_key (str) – 用于存储文本的列名。默认为 text

  • table_name (str) – 用于存储嵌入的表名。默认为 embeddings

示例

import duckdb
conn = duckdb.connect(database=':memory:',
    config={
        # Sample configuration to restrict some DuckDB capabilities
        # List is not exhaustive. Please review DuckDB documentation.
            "enable_external_access": "false",
            "autoinstall_known_extensions": "false",
            "autoload_known_extensions": "false"
        }
)
embedding_function = ... # Define or import your embedding function here
vector_store = DuckDB(conn, embedding_function)
vector_store.add_texts(['text1', 'text2'])
result = vector_store.similarity_search('text1')

使用 DuckDB 连接初始化并设置向量存储。

属性

embeddings

返回向量存储使用的嵌入对象。

方法

__init__(*[, connection, vector_key, ...])

使用 DuckDB 连接初始化并设置向量存储。

aadd_documents(documents, **kwargs)

异步运行更多文档通过嵌入并添加到向量存储。

aadd_texts(texts[, metadatas])

异步运行更多文本通过嵌入并添加到向量存储。

add_documents(documents, **kwargs)

在向量存储中添加或更新文档。

add_texts(texts[, metadatas])

将文本转换为嵌入并使用 Pandas DataFrame 添加到数据库中

adelete([ids])

异步按向量 ID 或其他条件删除。

afrom_documents(documents, embedding, **kwargs)

异步返回从文档和嵌入初始化的 VectorStore。

afrom_texts(texts, embedding[, metadatas])

异步返回从文本和嵌入初始化的 VectorStore。

aget_by_ids(ids, /)

异步按 ID 获取文档。

amax_marginal_relevance_search(query[, k, ...])

异步返回使用最大边际相关性选择的文档。

amax_marginal_relevance_search_by_vector(...)

异步返回使用最大边际相关性选择的文档。

as_retriever(**kwargs)

返回从该 VectorStore 初始化的 VectorStoreRetriever。

asearch(query, search_type, **kwargs)

异步返回与使用指定搜索类型查询最相似的文档。

asimilarity_search(query[, k])

异步返回与查询最相似的文档。

asimilarity_search_by_vector(embedding[, k])

异步返回与嵌入向量最相似的文档。

asimilarity_search_with_relevance_scores(query)

异步返回范围 [0, 1] 内的文档和相关性分数。

asimilarity_search_with_score(*args, **kwargs)

异步运行带距离的相似性搜索。

astreaming_upsert(items, /, batch_size, **kwargs)

aupsert(items, /, **kwargs)

delete([ids])

按向量 ID 或其他条件删除。

from_documents(documents, embedding, **kwargs)

返回从文档和嵌入初始化的 VectorStore。

from_texts(texts, embedding[, metadatas])

创建 DuckDB 实例并使用文本填充它,以及

get_by_ids(ids, /)

按 ID 获取文档。

max_marginal_relevance_search(query[, k, ...])

返回使用最大边际相关性选择的文档。

max_marginal_relevance_search_by_vector(...)

返回使用最大边际相关性选择的文档。

search(query, search_type, **kwargs)

返回与使用指定搜索类型查询最相似的文档。

similarity_search(query[, k])

对给定的查询字符串执行相似性搜索。

similarity_search_by_vector(embedding[, k])

返回与嵌入向量最相似的文档。

similarity_search_with_relevance_scores(query)

返回范围 [0, 1] 内的文档和相关性分数。

similarity_search_with_score(*args, **kwargs)

运行带距离的相似性搜索。

streaming_upsert(items, /, batch_size, **kwargs)

upsert(items, /, **kwargs)

__init__(*, connection: Optional[Any] = None, embedding: Embeddings, vector_key: str = 'embedding', id_key: str = 'id', text_key: str = 'text', table_name: str = 'embeddings')[source]

使用 DuckDB 连接初始化并设置向量存储。

参数
  • connection (Optional[Any]) –

  • embedding (Embeddings) –

  • vector_key (str) –

  • id_key (str) –

  • text_key (str) –

  • table_name (str) –

async aadd_documents(documents: List[Document], **kwargs: Any) List[str]

异步运行更多文档通过嵌入并添加到向量存储。

参数
  • documents (List[Document]) – 要添加到向量存储的文档。

  • kwargs (Any) – 附加关键字参数。

返回

添加文本的 ID 列表。

引发

ValueError – 如果 ID 数量与文档数量不匹配。

返回类型

List[str]

async aadd_texts(texts: Iterable[str], metadatas: Optional[List[dict]] = None, **kwargs: Any) List[str]

异步运行更多文本通过嵌入并添加到向量存储。

参数
  • texts (Iterable[str]) – 要添加到向量存储的字符串迭代器。

  • metadatas (Optional[List[dict]]) – 与文本关联的可选元数据列表。默认为 None。

  • **kwargs (Any) – 向量存储特定的参数。

返回

从将文本添加到向量存储中获取的 id 列表。

引发
  • ValueError – 如果元数据数量与文本数量不匹配。

  • ValueError – 如果 id 数量与文本数量不匹配。

返回类型

List[str]

add_documents(documents: List[Document], **kwargs: Any) List[str]

在向量存储中添加或更新文档。

参数
  • documents (List[Document]) – 要添加到向量存储的文档。

  • kwargs (Any) – 附加关键字参数。如果 kwargs 包含 ids 且文档包含 ids,则 kwargs 中的 ids 将优先。

返回

添加文本的 ID 列表。

引发

ValueError – 如果 id 数量与文档数量不匹配。

返回类型

List[str]

add_texts(texts: Iterable[str], metadatas: Optional[List[dict]] = None, **kwargs: Any) List[str][source]

将文本转换为嵌入并使用 Pandas DataFrame 添加到数据库中

参数
  • texts (Iterable[str]) – 要添加到向量存储的字符串迭代器。

  • metadatas (Optional[List[dict]]) – 与文本关联的可选元数据列表。

  • kwargs (Any) – 附加参数,包括与文本关联的可选 ‘ids’。

返回

添加文本的 id 列表。

返回类型

List[str]

async adelete(ids: Optional[List[str]] = None, **kwargs: Any) Optional[bool]

异步按向量 ID 或其他条件删除。

参数
  • ids (Optional[List[str]]) – 要删除的 id 列表。如果为 None,则删除全部。默认为 None。

  • **kwargs (Any) – 子类可能使用的其他关键字参数。

返回

如果删除成功,则为 True,否则为 False,如果未实现,则为 None。

返回类型

Optional[bool]

async classmethod afrom_documents(documents: List[Document], embedding: Embeddings, **kwargs: Any) VST

异步返回从文档和嵌入初始化的 VectorStore。

参数
  • documents (List[Document]) – 要添加到向量存储的文档列表。

  • embedding (Embeddings) – 要使用的嵌入函数。

  • kwargs (Any) – 附加关键字参数。

返回

从文档和嵌入初始化的 VectorStore。

返回类型

VectorStore

async classmethod afrom_texts(texts: List[str], embedding: Embeddings, metadatas: Optional[List[dict]] = None, **kwargs: Any) VST

异步返回从文本和嵌入初始化的 VectorStore。

参数
  • texts (List[str]) – 要添加到向量存储的文本。

  • embedding (Embeddings) – 要使用的嵌入函数。

  • metadatas (Optional[List[dict]]) – 与文本关联的可选元数据列表。默认为 None。

  • kwargs (Any) – 附加关键字参数。

返回

从文本和嵌入初始化的 VectorStore。

返回类型

VectorStore

async aget_by_ids(ids: Sequence[str], /) List[Document]

异步按 ID 获取文档。

返回的文档应设置 ID 字段为向量存储中文档的 ID。

如果某些 ID 未找到或存在重复 ID,则返回的文档可能少于请求的文档数。

用户不应假设返回文档的顺序与输入 ID 的顺序匹配。相反,用户应依赖返回文档的 ID 字段。

如果对于某些 ID 没有找到文档,此方法不应引发异常。

参数

ids (Sequence[str]) – 要检索的 ID 列表。

返回

文档列表。

返回类型

List[Document]

0.2.11 版本新增。

异步返回使用最大边际相关性选择的文档。

最大边际相关性优化查询的相似性和所选文档之间的多样性。

参数
  • query (str) – 用于查找相似文档的文本。

  • k (int) – 要返回的文档数量。默认为 4。

  • fetch_k (int) – 要获取并传递给 MMR 算法的文档数量。默认为 20。

  • lambda_mult (float) – 介于 0 和 1 之间的数字,用于确定结果之间多样性的程度,其中 0 对应于最大多样性,1 对应于最小多样性。默认为 0.5。

  • kwargs (Any) –

返回

通过最大边际相关性选择的文档列表。

返回类型

List[Document]

async amax_marginal_relevance_search_by_vector(embedding: List[float], k: int = 4, fetch_k: int = 20, lambda_mult: float = 0.5, **kwargs: Any) List[Document]

异步返回使用最大边际相关性选择的文档。

最大边际相关性优化查询的相似性和所选文档之间的多样性。

参数
  • embedding (List[float]) – 用于查找相似文档的嵌入向量。

  • k (int) – 要返回的文档数量。默认为 4。

  • fetch_k (int) – 要获取并传递给 MMR 算法的文档数量。默认为 20。

  • lambda_mult (float) – 介于 0 和 1 之间的数字,用于确定结果之间多样性的程度,其中 0 对应于最大多样性,1 对应于最小多样性。默认为 0.5。

  • **kwargs (Any) – 传递给搜索方法的参数。

返回

通过最大边际相关性选择的文档列表。

返回类型

List[Document]

as_retriever(**kwargs: Any) VectorStoreRetriever

返回从该 VectorStore 初始化的 VectorStoreRetriever。

参数

**kwargs (Any) –

传递给搜索函数的关键字参数。可以包括: search_type (Optional[str]): 定义检索器应执行的搜索类型。

可以是 “similarity”(默认)、“mmr” 或 “similarity_score_threshold”。

search_kwargs (Optional[Dict]): 传递给搜索函数的关键字参数。
可以包括如下内容

k: 要返回的文档数量 (默认: 4) score_threshold: 相似度分数阈值的最小相关性阈值

用于 similarity_score_threshold

fetch_k: 传递给 MMR 算法的文档数量

(默认: 20)

lambda_mult: MMR 返回结果的多样性;

1 代表最小多样性,0 代表最大多样性。(默认: 0.5)

filter: 按文档元数据过滤

返回

VectorStore 的检索器类。

返回类型

VectorStoreRetriever

示例

# Retrieve more documents with higher diversity
# Useful if your dataset has many similar documents
docsearch.as_retriever(
    search_type="mmr",
    search_kwargs={'k': 6, 'lambda_mult': 0.25}
)

# Fetch more documents for the MMR algorithm to consider
# But only return the top 5
docsearch.as_retriever(
    search_type="mmr",
    search_kwargs={'k': 5, 'fetch_k': 50}
)

# Only retrieve documents that have a relevance score
# Above a certain threshold
docsearch.as_retriever(
    search_type="similarity_score_threshold",
    search_kwargs={'score_threshold': 0.8}
)

# Only get the single most similar document from the dataset
docsearch.as_retriever(search_kwargs={'k': 1})

# Use a filter to only retrieve documents from a specific paper
docsearch.as_retriever(
    search_kwargs={'filter': {'paper_title':'GPT-4 Technical Report'}}
)
async asearch(query: str, search_type: str, **kwargs: Any) List[Document]

异步返回与使用指定搜索类型查询最相似的文档。

参数
  • query (str) – 输入文本。

  • search_type (str) – 要执行的搜索类型。可以是 “similarity”、“mmr” 或 “similarity_score_threshold”。

  • **kwargs (Any) – 传递给搜索方法的参数。

返回

与查询最相似的文档列表。

引发

ValueError – 如果 search_type 不是 “similarity”、“mmr” 或 “similarity_score_threshold” 之一。

返回类型

List[Document]

异步返回与查询最相似的文档。

参数
  • query (str) – 输入文本。

  • k (int) – 要返回的文档数量。默认为 4。

  • **kwargs (Any) – 传递给搜索方法的参数。

返回

与查询最相似的文档列表。

返回类型

List[Document]

async asimilarity_search_by_vector(embedding: List[float], k: int = 4, **kwargs: Any) List[Document]

异步返回与嵌入向量最相似的文档。

参数
  • embedding (List[float]) – 用于查找相似文档的嵌入向量。

  • k (int) – 要返回的文档数量。默认为 4。

  • **kwargs (Any) – 传递给搜索方法的参数。

返回

与查询向量最相似的文档列表。

返回类型

List[Document]

async asimilarity_search_with_relevance_scores(query: str, k: int = 4, **kwargs: Any) List[Tuple[Document, float]]

异步返回范围 [0, 1] 内的文档和相关性分数。

0 表示不相似,1 表示最相似。

参数
  • query (str) – 输入文本。

  • k (int) – 要返回的文档数量。默认为 4。

  • **kwargs (Any) –

    传递给相似性搜索的 kwargs。应包括: score_threshold: 可选,介于 0 到 1 之间的浮点值,用于

    过滤检索到的文档结果集

返回

由 (文档, 相似度分数) 元组组成的列表

返回类型

List[Tuple[Document, float]]

async asimilarity_search_with_score(*args: Any, **kwargs: Any) List[Tuple[Document, float]]

异步运行带距离的相似性搜索。

参数
  • *args (Any) – 传递给搜索方法的参数。

  • **kwargs (Any) – 传递给搜索方法的参数。

返回

由 (文档, 相似度分数) 元组组成的列表。

返回类型

List[Tuple[Document, float]]

astreaming_upsert(items: AsyncIterable[Document], /, batch_size: int, **kwargs: Any) AsyncIterator[UpsertResponse]

Beta

0.2.11 版本新增。API 可能会发生变化。

以流式方式进行文档的 Upsert 操作。streaming_upsert 的异步版本。

参数
  • items (AsyncIterable[Document]) – 要添加到向量存储的文档的可迭代对象。

  • batch_size (int) – 每次 upsert 的批量大小。

  • kwargs (Any) – 额外的关键字参数。 kwargs 应仅包含所有文档通用的参数。(例如,索引超时、重试策略等)kwargs 不应包含 ids 以避免语义模糊。相反,ID 应作为 Document 对象的一部分提供。

Yields

UpsertResponse – 响应对象,其中包含已成功添加到或更新到向量存储中的 ID 列表,以及未能添加或更新的 ID 列表。

返回类型

AsyncIterator[UpsertResponse]

0.2.11 版本新增。

async aupsert(items: Sequence[Document], /, **kwargs: Any) UpsertResponse

Beta

0.2.11 版本新增。API 可能会发生变化。

在向量存储中添加或更新文档。upsert 的异步版本。

如果提供了 Document 对象的 ID 字段,则 upsert 功能应使用该字段。如果未提供 ID,则 upsert 方法可以自由地为文档生成 ID。

当指定了 ID 并且文档已存在于向量存储中时,upsert 方法应使用新数据更新文档。如果文档不存在,则 upsert 方法应将文档添加到向量存储中。

参数
  • items (Sequence[Document]) – 要添加到向量存储的文档序列。

  • kwargs (Any) – 附加关键字参数。

返回

响应对象,其中包含已成功添加到或更新到向量存储中的 ID 列表,以及未能添加或更新的 ID 列表。

返回类型

UpsertResponse

0.2.11 版本新增。

delete(ids: Optional[List[str]] = None, **kwargs: Any) Optional[bool]

按向量 ID 或其他条件删除。

参数
  • ids (Optional[List[str]]) – 要删除的 id 列表。如果为 None,则删除全部。默认为 None。

  • **kwargs (Any) – 子类可能使用的其他关键字参数。

返回

如果删除成功,则为 True,否则为 False,如果未实现,则为 None。

返回类型

Optional[bool]

classmethod from_documents(documents: List[Document], embedding: Embeddings, **kwargs: Any) VST

返回从文档和嵌入初始化的 VectorStore。

参数
  • documents (List[Document]) – 要添加到向量存储的文档列表。

  • embedding (Embeddings) – 要使用的嵌入函数。

  • kwargs (Any) – 附加关键字参数。

返回

从文档和嵌入初始化的 VectorStore。

返回类型

VectorStore

classmethod from_texts(texts: List[str], embedding: Embeddings, metadatas: Optional[List[dict]] = None, **kwargs: Any) DuckDB[source]
创建 DuckDB 实例并使用文本填充它,以及

它们的嵌入。

参数
  • texts (List[str]) – 要添加到向量存储的字符串列表。

  • embedding (Embeddings) – 用于生成嵌入的嵌入函数或模型。

  • metadatas (Optional[List[dict]]) – 与文本关联的可选元数据字典列表。

  • kwargs (Any) –

    额外的关键字参数,包括: - connection: DuckDB 连接。如果未提供,将创建一个新连接。

    将被创建。

    • vector_key: 用于存储向量的列名。默认为 “vector”。

    • id_key: 用于存储唯一标识符的列名。默认为 “id”。

    • text_key: 用于存储文本的列名。默认为 “text”。

    • table_name: 用于存储嵌入的表名。

      默认为 “embeddings”。

返回

DuckDB 的一个实例,其中添加了提供的文本及其嵌入。

返回类型

DuckDB

get_by_ids(ids: Sequence[str], /) List[Document]

按 ID 获取文档。

返回的文档应设置 ID 字段为向量存储中文档的 ID。

如果某些 ID 未找到或存在重复 ID,则返回的文档可能少于请求的文档数。

用户不应假设返回文档的顺序与输入 ID 的顺序匹配。相反,用户应依赖返回文档的 ID 字段。

如果对于某些 ID 没有找到文档,此方法不应引发异常。

参数

ids (Sequence[str]) – 要检索的 ID 列表。

返回

文档列表。

返回类型

List[Document]

0.2.11 版本新增。

返回使用最大边际相关性选择的文档。

最大边际相关性优化查询的相似性和所选文档之间的多样性。

参数
  • query (str) – 用于查找相似文档的文本。

  • k (int) – 要返回的文档数量。默认为 4。

  • fetch_k (int) – 要获取并传递给 MMR 算法的文档数量。默认为 20。

  • lambda_mult (float) – 介于 0 和 1 之间的数字,用于确定结果之间多样性的程度,其中 0 对应于最大多样性,1 对应于最小多样性。默认为 0.5。

  • **kwargs (Any) – 传递给搜索方法的参数。

返回

通过最大边际相关性选择的文档列表。

返回类型

List[Document]

max_marginal_relevance_search_by_vector(embedding: List[float], k: int = 4, fetch_k: int = 20, lambda_mult: float = 0.5, **kwargs: Any) List[Document]

返回使用最大边际相关性选择的文档。

最大边际相关性优化查询的相似性和所选文档之间的多样性。

参数
  • embedding (List[float]) – 用于查找相似文档的嵌入向量。

  • k (int) – 要返回的文档数量。默认为 4。

  • fetch_k (int) – 要获取并传递给 MMR 算法的文档数量。默认为 20。

  • lambda_mult (float) – 介于 0 和 1 之间的数字,用于确定结果之间多样性的程度,其中 0 对应于最大多样性,1 对应于最小多样性。默认为 0.5。

  • **kwargs (Any) – 传递给搜索方法的参数。

返回

通过最大边际相关性选择的文档列表。

返回类型

List[Document]

search(query: str, search_type: str, **kwargs: Any) List[Document]

返回与使用指定搜索类型查询最相似的文档。

参数
  • query (str) – 输入文本

  • search_type (str) – 要执行的搜索类型。可以是 “similarity”、“mmr” 或 “similarity_score_threshold”。

  • **kwargs (Any) – 传递给搜索方法的参数。

返回

与查询最相似的文档列表。

引发

ValueError – 如果 search_type 不是 “similarity”、“mmr” 或 “similarity_score_threshold” 之一。

返回类型

List[Document]

对给定的查询字符串执行相似性搜索。

参数
  • query (str) – 要搜索的查询字符串。

  • k (int) – 要返回的相似文本的数量。

  • kwargs (Any) –

返回

与查询最相似的文档列表。

返回类型

List[Document]

similarity_search_by_vector(embedding: List[float], k: int = 4, **kwargs: Any) List[Document]

返回与嵌入向量最相似的文档。

参数
  • embedding (List[float]) – 用于查找相似文档的嵌入向量。

  • k (int) – 要返回的文档数量。默认为 4。

  • **kwargs (Any) – 传递给搜索方法的参数。

返回

与查询向量最相似的文档列表。

返回类型

List[Document]

similarity_search_with_relevance_scores(query: str, k: int = 4, **kwargs: Any) List[Tuple[Document, float]]

返回范围 [0, 1] 内的文档和相关性分数。

0 表示不相似,1 表示最相似。

参数
  • query (str) – 输入文本。

  • k (int) – 要返回的文档数量。默认为 4。

  • **kwargs (Any) –

    传递给相似性搜索的 kwargs。应包括: score_threshold: 可选,介于 0 到 1 之间的浮点值,用于

    过滤检索结果集。

返回

由 (文档, 相似度分数) 元组组成的列表。

返回类型

List[Tuple[Document, float]]

similarity_search_with_score(*args: Any, **kwargs: Any) List[Tuple[Document, float]]

运行带距离的相似性搜索。

参数
  • *args (Any) – 传递给搜索方法的参数。

  • **kwargs (Any) – 传递给搜索方法的参数。

返回

由 (文档, 相似度分数) 元组组成的列表。

返回类型

List[Tuple[Document, float]]

streaming_upsert(items: Iterable[Document], /, batch_size: int, **kwargs: Any) Iterator[UpsertResponse]

Beta

0.2.11 版本新增。API 可能会发生变化。

以流式方式 Upsert 文档。

参数
  • items (Iterable[Document]) – 要添加到向量存储的可迭代文档。

  • batch_size (int) – 每次 upsert 的批量大小。

  • kwargs (Any) – 额外的关键字参数。 kwargs 应该只包含所有文档通用的参数。(例如,索引超时、重试策略等)kwargs 不应包含 ids 以避免语义模糊。相反,ID 应该作为 Document 对象的一部分提供。

Yields

UpsertResponse – 响应对象,其中包含已成功添加到或更新到向量存储中的 ID 列表,以及未能添加或更新的 ID 列表。

返回类型

Iterator[UpsertResponse]

0.2.11 版本新增。

upsert(items: Sequence[Document], /, **kwargs: Any) UpsertResponse

Beta

0.2.11 版本新增。API 可能会发生变化。

在向量存储中添加或更新文档。

如果提供了 Document 对象的 ID 字段,则 upsert 功能应使用该字段。如果未提供 ID,则 upsert 方法可以自由地为文档生成 ID。

当指定了 ID 并且文档已存在于向量存储中时,upsert 方法应使用新数据更新文档。如果文档不存在,则 upsert 方法应将文档添加到向量存储中。

参数
  • items (Sequence[Document]) – 要添加到向量存储的文档序列。

  • kwargs (Any) – 附加关键字参数。

返回

响应对象,其中包含已成功添加到或更新到向量存储中的 ID 列表,以及未能添加或更新的 ID 列表。

返回类型

UpsertResponse

0.2.11 版本新增。

DuckDB 使用示例