> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Astra DB 集成

> 集成 Astra DB 向量存储，使用 LangChain Python。

本页面提供了使用 Astra DB 作为向量存储的快速入门指南。

> [DataStax Astra DB](https://docs.datastax.com/en/astra-db-serverless/index.html) 是一个无服务器的 AI 就绪型数据库，基于 `Apache Cassandra®` 构建，并通过易于使用的 JSON API 方便地提供。

## 设置

### 依赖项

使用此集成需要 `langchain-astradb` 合作伙伴包：

```python theme={null}
!pip install \
    "langchain>=0.3.23,<0.4" \
    "langchain-core>=0.3.52,<0.4" \
    "langchain-astradb>=0.6,<0.7"
```

### 凭证

要使用 AstraDB 向量存储，您必须首先前往 [AstraDB 网站](https://astra.datastax.com)，创建一个账户，然后创建一个新的数据库——初始化可能需要几分钟。

数据库初始化完成后，请获取您的 [连接密钥](https://docs.datastax.com/en/astra-db-serverless/get-started/quickstart.html#create-a-database-and-store-your-credentials)，您稍后会用到。这些包括：

* 一个 **`API Endpoint`**，例如 `"https://01234567-89ab-cdef-0123-456789abcdef-us-east1.apps.astra.datastax.com/"`
* 以及一个 **`Database Token`**，例如 `"AstraCS:aBcD123......"`

您可以选择提供一个 **`keyspace`**（在 LangChain 组件中称为 "namespace"），您可以在数据库控制面板的 `Data Explorer` 选项卡中管理它。如果您愿意，可以在下面的提示词中将其留空，并回退到默认的键空间。

```python theme={null}
import getpass

ASTRA_DB_API_ENDPOINT = input("ASTRA_DB_API_ENDPOINT = ").strip()
ASTRA_DB_APPLICATION_TOKEN = getpass.getpass("ASTRA_DB_APPLICATION_TOKEN = ").strip()

desired_keyspace = input("(optional) ASTRA_DB_KEYSPACE = ").strip()
if desired_keyspace:
    ASTRA_DB_KEYSPACE = desired_keyspace
else:
    ASTRA_DB_KEYSPACE = None
```

```text theme={null}
ASTRA_DB_API_ENDPOINT =  https://01234567-89ab-cdef-0123-456789abcdef-us-east1.apps.astra.datastax.com
ASTRA_DB_APPLICATION_TOKEN =  ········
(optional) ASTRA_DB_KEYSPACE =
```

如果您希望获得最顶级的模型调用自动跟踪，您也可以通过取消注释以下内容来设置您的 [LangSmith](https://docs.langchain.com/langsmith/observability) API 密钥：

```python theme={null}
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"
```

## 初始化

创建 Astra DB 向量存储有多种方法：

#### 方法 1：显式嵌入

您可以单独实例化 `langchain_core.embeddings.Embeddings` 类并将其传递给 `AstraDBVectorStore` 构造函数，就像大多数其他 LangChain 向量存储一样。

#### 方法 2：服务器端嵌入（'vectorize'）

或者，您可以使用 Astra DB 的 [服务器端嵌入计算](https://docs.datastax.com/en/astra-db-serverless/databases/embedding-generation.html) 功能（'vectorize'），在创建存储的服务器基础设施时指定嵌入模型。随后的读写操作中的嵌入计算将完全由数据库内部处理。（要使用此方法，您必须在文档中描述的 [在文档中](https://docs.datastax.com/en/astra-db-serverless/databases/embedding-generation.html) 启用所需的嵌入集成。）

#### 方法 3：从预存在的集合自动检测

您可能已经在 Astra DB 中有一个 [集合](https://docs.datastax.com/en/astra-db-serverless/api-reference/collections.html)，可能通过其他方式（例如通过 Astra UI 或第三方应用程序）预填充了数据，并且只想在 LangChain 中开始查询它。在这种情况下，正确的方法是在向量存储构造函数中启用 `autodetect_collection` 模式，并让类自行处理细节。（当然，如果您的集合没有 'vectorize'，您仍然需要提供一个 @\[`Embeddings`] 对象。）

#### 关于“混合搜索”的说明

Astra DB 向量存储支持在向量搜索中进行元数据搜索；此外，版本 0.6 引入了通过 [findAndRerank](https://docs.datastax.com/en/astra-db-serverless/api-reference/document-methods/find-and-rerank.html) 数据库原语对 *混合搜索* 的完全支持：文档从向量相似性 *和* 基于关键词（“词汇”）的搜索中检索，然后通过重新排序模型合并。这种完全由服务器端处理的搜索策略可以提高结果的准确性，从而提高您的 RAG 应用的质量。当可用时，向量存储会自动使用混合搜索（尽管如果您希望这样做，可以手动控制它）。

#### 其他信息

`AstraDBVectorStore` 可以以多种方式配置；请参阅 @\[API 参考]\[AstraDBVectorStore] 以获取完整指南，涵盖异步初始化；非 Astra-DB 数据库；自定义索引允许/拒绝列表；手动混合搜索控制；以及更多内容。

### 显式嵌入初始化（方法 1）

使用显式嵌入类实例化我们的向量存储：

```python theme={null}
# | output: false
# | echo: false
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(model="text-embedding-3-large")
```

```python theme={null}
from langchain_astradb import AstraDBVectorStore

vector_store_explicit_embeddings = AstraDBVectorStore(
    collection_name="astra_vector_langchain",
    embedding=embeddings,
    api_endpoint=ASTRA_DB_API_ENDPOINT,
    token=ASTRA_DB_APPLICATION_TOKEN,
    namespace=ASTRA_DB_KEYSPACE,
)
```

### 服务器端嵌入初始化（"vectorize"，方法 2）

在这个示例代码中，假设你已经

* 在你的 Astra DB 组织中启用了 OpenAI 集成，
* 向集成添加了一个名为 `"OPENAI_API_KEY"` 的 API 密钥，并将其范围限定为你正在使用的数据库。

更多详情，包括切换提供者/模型的说明，请参考 [文档](https://docs.datastax.com/en/astra-db-serverless/databases/embedding-generation.html)。

```python theme={null}
from astrapy.info import VectorServiceOptions

openai_vectorize_options = VectorServiceOptions(
    provider="openai",
    model_name="text-embedding-3-small",
    authentication={
        "providerKey": "OPENAI_API_KEY",
    },
)

vector_store_integrated_embeddings = AstraDBVectorStore(
    collection_name="astra_vectorize_langchain",
    api_endpoint=ASTRA_DB_API_ENDPOINT,
    token=ASTRA_DB_APPLICATION_TOKEN,
    namespace=ASTRA_DB_KEYSPACE,
    collection_vector_service_options=openai_vectorize_options,
)
```

### 自动检测初始化（方法 3）

如果你的 `AstraDBVectorStore` 已经存在于数据库上，并且需要使用它（用于读写），你可以使用这种模式。LangChain 组件将检查集合并推断出详细信息。

如果集合已经被创建，最重要的是——它是由 LangChain 以外的工具填充的，例如如果数据是通过 Astra DB 网页界面导入的，则推荐使用这种方法。

自动检测模式不能与 *集合* 设置（例如相似度度量等）共存；另一方面，如果没有使用服务器端嵌入，仍然需要向构造函数传递一个 @\[`Embeddings`] 对象。

在以下示例代码中，我们将“自动检测”上面通过方法 2 创建的集合（"vectorize"）。因此，不需要提供 @\[`Embeddings`] 对象。

```python theme={null}
vector_store_autodetected = AstraDBVectorStore(
    collection_name="astra_vectorize_langchain",
    api_endpoint=ASTRA_DB_API_ENDPOINT,
    token=ASTRA_DB_APPLICATION_TOKEN,
    namespace=ASTRA_DB_KEYSPACE,
    autodetect_collection=True,
)
```

## 管理向量存储

创建你的向量存储后，通过添加和删除不同的项目与之交互。

所有与向量存储的交互都与方法无关：如果你希望，请**调整以下单元格**，选择你创建并希望进行测试的向量存储。

```python theme={null}
# If desired, uncomment a different line here:

# vector_store = vector_store_explicit_embeddings
vector_store = vector_store_integrated_embeddings
# vector_store = vector_store_autodetected
```

### 向向量存储添加条目

通过使用 `add_documents` 方法将文档添加到向量存储中。

*“id”字段可以单独提供，在 `ids=[...]` 参数中与 `add_documents` 匹配，甚至可以完全省略以让存储生成 ID。*

```python theme={null}
from langchain_core.documents import Document

documents_to_insert = [
    Document(
        page_content="ZYX, just another tool in the world, is actually my agent-based superhero",
        metadata={"source": "tweet"},
        id="entry_00",
    ),
    Document(
        page_content="I had chocolate chip pancakes and scrambled eggs "
        "for breakfast this morning.",
        metadata={"source": "tweet"},
        id="entry_01",
    ),
    Document(
        page_content="The weather forecast for tomorrow is cloudy and "
        "overcast, with a high of 62 degrees.",
        metadata={"source": "news"},
        id="entry_02",
    ),
    Document(
        page_content="Building an exciting new project with LangChain "
        "- come check it out!",
        metadata={"source": "tweet"},
        id="entry_03",
    ),
    Document(
        page_content="Robbers broke into the city bank and stole $1 million in cash.",
        metadata={"source": "news"},
        id="entry_04",
    ),
    Document(
        page_content="Thanks to her sophisticated language skills, the agent "
        "managed to extract strategic information all right.",
        metadata={"source": "tweet"},
        id="entry_05",
    ),
    Document(
        page_content="Is the new iPhone worth the price? Read this review to find out.",
        metadata={"source": "website"},
        id="entry_06",
    ),
    Document(
        page_content="The top 10 soccer players in the world right now.",
        metadata={"source": "website"},
        id="entry_07",
    ),
    Document(
        page_content="LangGraph is the best framework for building stateful, "
        "agentic applications!",
        metadata={"source": "tweet"},
        id="entry_08",
    ),
    Document(
        page_content="The stock market is down 500 points today due to "
        "fears of a recession.",
        metadata={"source": "news"},
        id="entry_09",
    ),
    Document(
        page_content="I have a bad feeling I am going to get deleted :(",
        metadata={"source": "tweet"},
        id="entry_10",
    ),
]


vector_store.add_documents(documents=documents_to_insert)
```

```python theme={null}
['entry_00',
 'entry_01',
 'entry_02',
 'entry_03',
 'entry_04',
 'entry_05',
 'entry_06',
 'entry_07',
 'entry_08',
 'entry_09',
 'entry_10']
```

### 从向量存储删除条目

通过使用 `delete` 函数按 ID 删除条目。

```python theme={null}
vector_store.delete(ids=["entry_10", "entry_02"])
```

```text theme={null}
True
```

## 查询向量存储

一旦向量存储被创建并填充，您就可以查询它（例如作为您的链或智能体的一部分）。

### 直接查询

#### 相似度搜索

搜索与提供的文本相似的文档，如果需要，还可以添加额外的元数据过滤器：

```python theme={null}
results = vector_store.similarity_search(
    "LangChain provides abstractions to make working with LLMs easy",
    k=3,
    filter={"source": "tweet"},
)
for res in results:
    print(f'* "{res.page_content}", metadata={res.metadata}')
```

```text theme={null}
* "Building an exciting new project with LangChain - come check it out!", metadata={'source': 'tweet'}
* "LangGraph is the best framework for building stateful, agentic applications!", metadata={'source': 'tweet'}
* "Thanks to her sophisticated language skills, the agent managed to extract strategic information all right.", metadata={'source': 'tweet'}
```

#### 带分数的相似度搜索

您也可以返回相似度分数：

```python theme={null}
results = vector_store.similarity_search_with_score(
    "LangChain provides abstractions to make working with LLMs easy",
    k=3,
    filter={"source": "tweet"},
)
for res, score in results:
    print(f'* [SIM={score:.2f}] "{res.page_content}", metadata={res.metadata}')
```

```text theme={null}
* [SIM=0.71] "Building an exciting new project with LangChain - come check it out!", metadata={'source': 'tweet'}
* [SIM=0.70] "LangGraph is the best framework for building stateful, agentic applications!", metadata={'source': 'tweet'}
* [SIM=0.61] "Thanks to her sophisticated language skills, the agent managed to extract strategic information all right.", metadata={'source': 'tweet'}
```

#### 指定不同的关键字查询（需要混合搜索）

> 注意：此单元格仅当集合支持 [find-and-rerank](https://docs.datastax.com/en/astra-db-serverless/api-reference/document-methods/find-and-rerank.html) 命令且向量存储知晓此事实时才能运行。

如果向量存储正在使用支持混合搜索的集合，并且已检测到这一事实，则默认情况下在执行搜索时会使用该功能。

在这种情况下，find-and-rerank 过程中的向量相似性和基于词汇的检索步骤将使用相同的查询文本，除非您为后者显式提供不同的查询：

```python theme={null}
results = vector_store_autodetected.similarity_search(
    "LangChain provides abstractions to make working with LLMs easy",
    k=3,
    filter={"source": "tweet"},
    lexical_query="agent",
)
for res in results:
    print(f'* "{res.page_content}", metadata={res.metadata}')
```

```text theme={null}
* "Building an exciting new project with LangChain - come check it out!", metadata={'source': 'tweet'}
* "LangGraph is the best framework for building stateful, agentic applications!", metadata={'source': 'tweet'}
* "ZYX, just another tool in the world, is actually my agent-based superhero", metadata={'source': 'tweet'}
```

*上述示例硬编码了 "autodetected" 向量存储，该存储已检查集合并确定是否支持混合搜索。另一种选项是向构造函数显式提供混合搜索参数（参考 API 参考以获取更多详细信息/示例）。*

#### 其他搜索方法

还有多种其他搜索方法未在本笔记本中涵盖，例如 MMR 搜索和基于向量的搜索。

要查看 `AstraDBVectorStore` 中可用的完整搜索模式列表，请查阅 @\[API reference]\[AstraDBVectorStore]。

### 将向量存储转换为检索器

您还可以将向量存储转换为检索器，以便在您的链中更轻松地使用。

将向量存储转换为检索器，并使用简单的查询 + 元数据过滤器调用它：

```python theme={null}
retriever = vector_store.as_retriever(
    search_type="similarity_score_threshold",
    search_kwargs={"k": 1, "score_threshold": 0.5},
)
retriever.invoke("Stealing from the bank is a crime", filter={"source": "news"})
```

```text theme={null}
[Document(id='entry_04', metadata={'source': 'news'}, page_content='Robbers broke into the city bank and stole $1 million in cash.')]
```

## 检索增强生成（RAG）的用法

有关如何使用此向量存储进行检索增强生成（RAG）的指南，请参阅以下部分：

* [检索文档](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/retrieval.md)
* [使用 LangChain 构建 RAG 应用](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/rag.md)
* [智能体 RAG](https://langchain-docs-zh.mintlify.site/langchain/oss/langgraph/agentic-rag.md)

要了解更多信息，请查看 [使用 Astra DB 的完整 RAG 模板](https://github.com/langchain-ai/langchain/tree/v0.2/templates/rag-astradb)。

## 清理向量存储

如果您想从您的 Astra DB 实例中完全删除集合，请运行此命令。

*(您将丢失其中存储的数据。)*

```python theme={null}
vector_store.delete_collection()
```

***

## API 参考

有关所有 `AstraDBVectorStore` 功能和配置的详细文档，请参阅 @\[API reference]\[AstraDBVectorStore]。

***

> 官方原文：[src/oss/python/integrations/vectorstores/astradb.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/python/integrations/vectorstores/astradb.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.