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

# Apache Cassandra 集成

> 使用 LangChain Python 与 Apache Cassandra 向量存储进行集成。

本页面提供了将 [Apache Cassandra®](https://cassandra.apache.org/) 用作向量存储的快速入门指南。

> [Cassandra](https://cassandra.apache.org/) 是一个 NoSQL、面向行、高度可扩展且高可用的数据库。从 5.0 版本开始，该数据库附带了 [向量搜索功能](https://cassandra.apache.org/doc/trunk/cassandra/vector-search/overview.html)。

*Note: 除了访问数据库外，运行完整示例还需要一个 OpenAI API 密钥。*

### 设置和通用依赖项

使用该集成需要以下 Python 包。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install -qU langchain-community "cassio>=0.1.4"
```

*Note: 根据您的 LangChain 设置，您可能需要安装/升级此演示所需的其他依赖项*
*(specifically, recent versions of `datasets`, `openai`, `pypdf` and `tiktoken` are required, along with `langchain-community`).*

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import os
from getpass import getpass

from datasets import (
    load_dataset,
)
from langchain_community.document_loaders import PyPDFLoader
from langchain_core.documents import Document
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain_text_splitters import RecursiveCharacterTextSplitter
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
if "OPENAI_API_KEY" not in os.environ:
    os.environ["OPENAI_API_KEY"] = getpass("OPENAI_API_KEY = ")
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
embe = OpenAIEmbeddings()
```

## 导入向量存储

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_community.vectorstores import Cassandra
```

## 连接参数

本页面显示的向量存储集成可用于 Cassandra 以及其他衍生数据库（如 Astra DB），这些数据库使用 CQL（Cassandra 查询语言）协议。

> DataStax [Astra DB](https://docs.datastax.com/en/astra-serverless/docs/vector-search/quickstart.html) 是构建在 Cassandra 之上的托管无服务器数据库，提供相同的接口和优势。

根据您是连接到 Cassandra 集群还是通过 CQL 连接到 Astra DB，在创建向量存储对象时将提供不同的参数。

### 连接到 Cassandra 集群

您首先需要创建一个 `cassandra.cluster.Session` 对象，如 [Cassandra 驱动程序文档](https://docs.datastax.com/en/developer/python-driver/latest/api/cassandra/cluster/#module-cassandra.cluster) 中所述。详细信息各不相同（例如网络设置和身份验证），但这可能类似于：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from cassandra.cluster import Cluster

cluster = Cluster(["127.0.0.1"])
session = cluster.connect()
```

现在，您可以将 session 和您想要的 keyspace 名称设置为全局 CassIO 参数：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import cassio

CASSANDRA_KEYSPACE = input("CASSANDRA_KEYSPACE = ")

cassio.init(session=session, keyspace=CASSANDRA_KEYSPACE)
```

现在您可以创建向量存储：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
vstore = Cassandra(
    embedding=embe,
    table_name="cassandra_vector_demo",
    # session=None, keyspace=None  # Uncomment on older versions of LangChain
)
```

*Note: 在创建向量存储时，您也可以直接将 session 和 keyspace 作为参数传递。然而，如果您的应用程序以多种方式（例如用于向量存储、聊天内存和 LLM 响应缓存）使用 Cassandra，则使用全局 `cassio.init` 设置会更方便，因为它允许在一个地方集中管理凭据和数据库连接。*

### 通过 CQL 连接到 Astra DB

在这种情况下，您使用以下连接参数初始化 CassIO：

* 数据库 ID，例如 `01234567-89ab-cdef-0123-456789abcdef`
* 令牌，例如 `AstraCS:6gBhNmsk135....`（必须是“数据库管理员”令牌）
* 可选的 Keyspace 名称（如果省略，将使用数据库的默认名称）

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
ASTRA_DB_ID = input("ASTRA_DB_ID = ")
ASTRA_DB_APPLICATION_TOKEN = getpass("ASTRA_DB_APPLICATION_TOKEN = ")

desired_keyspace = input("ASTRA_DB_KEYSPACE (optional, can be left empty) = ")
if desired_keyspace:
    ASTRA_DB_KEYSPACE = desired_keyspace
else:
    ASTRA_DB_KEYSPACE = None
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import cassio

cassio.init(
    database_id=ASTRA_DB_ID,
    token=ASTRA_DB_APPLICATION_TOKEN,
    keyspace=ASTRA_DB_KEYSPACE,
)
```

现在您可以创建向量存储：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
vstore = Cassandra(
    embedding=embe,
    table_name="cassandra_vector_demo",
    # session=None, keyspace=None  # Uncomment on older versions of LangChain
)
```

## 加载数据集

将源数据集中的每个条目转换为 `Document`，然后将它们写入向量存储：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
philo_dataset = load_dataset("datastax/philosopher-quotes")["train"]

docs = []
for entry in philo_dataset:
    metadata = {"author": entry["author"]}
    doc = Document(page_content=entry["quote"], metadata=metadata)
    docs.append(doc)

inserted_ids = vstore.add_documents(docs)
print(f"\nInserted {len(inserted_ids)} documents.")
```

在上面，`metadata` 字典是从源数据创建的，并且是 `Document` 的一部分。

添加更多条目，这次使用 `add_texts`：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
texts = ["I think, therefore I am.", "To the things themselves!"]
metadatas = [{"author": "descartes"}, {"author": "husserl"}]
ids = ["desc_01", "huss_xy"]

inserted_ids_2 = vstore.add_texts(texts=texts, metadatas=metadatas, ids=ids)
print(f"\nInserted {len(inserted_ids_2)} documents.")
```

*Note: 您可能希望通过增加并发级别来加快 `add_texts` 和 `add_documents` 的执行速度*
*对于这些批量操作 - 查看方法的 `batch_size` 参数*
*了解更多详情。根据网络和客户端机器规格，您的最佳参数选择可能会有所不同。*

## 运行搜索

本节演示元数据过滤和获取相似度分数：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
results = vstore.similarity_search("Our life is what we make of it", k=3)
for res in results:
    print(f"* {res.page_content} [{res.metadata}]")
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
results_filtered = vstore.similarity_search(
    "Our life is what we make of it",
    k=3,
    filter={"author": "plato"},
)
for res in results_filtered:
    print(f"* {res.page_content} [{res.metadata}]")
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
results = vstore.similarity_search_with_score("Our life is what we make of it", k=3)
for res, score in results:
    print(f"* [SIM={score:3f}] {res.page_content} [{res.metadata}]")
```

### MMR（最大边际相关性）搜索

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
results = vstore.max_marginal_relevance_search(
    "Our life is what we make of it",
    k=3,
    filter={"author": "aristotle"},
)
for res in results:
    print(f"* {res.page_content} [{res.metadata}]")
```

## 删除存储的文档

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
delete_1 = vstore.delete(inserted_ids[:3])
print(f"all_succeed={delete_1}")  # True, all documents deleted
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
delete_2 = vstore.delete(inserted_ids[2:5])
print(f"some_succeeds={delete_2}")  # True, though some IDs were gone already
```

## 最小化 RAG 链

接下来的单元格将实现一个简单的 RAG 管道：

* 下载示例 PDF 文件并将其加载到存储中；
* 使用 LCEL（LangChain 表达式语言）创建 RAG 链，以向量存储为核心；
* 运行问答链。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
!curl -L \
    "https://github.com/awesome-astra/datasets/blob/main/demo-resources/what-is-philosophy/what-is-philosophy.pdf?raw=true" \
    -o "what-is-philosophy.pdf"
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pdf_loader = PyPDFLoader("what-is-philosophy.pdf")
splitter = RecursiveCharacterTextSplitter(chunk_size=512, chunk_overlap=64)
docs_from_pdf = pdf_loader.load_and_split(text_splitter=splitter)

print(f"Documents from PDF: {len(docs_from_pdf)}.")
inserted_ids_from_pdf = vstore.add_documents(docs_from_pdf)
print(f"Inserted {len(inserted_ids_from_pdf)} documents.")
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
retriever = vstore.as_retriever(search_kwargs={"k": 3})

philo_template = """
You are a philosopher that draws inspiration from great thinkers of the past
to craft well-thought answers to user questions. Use the provided context as the basis
for your answers and do not make up new reasoning paths - just mix-and-match what you are given.
Your answers must be concise and to the point, and refrain from answering about other topics than philosophy.

CONTEXT:
{context}

QUESTION: {question}

YOUR ANSWER:"""

philo_prompt = ChatPromptTemplate.from_template(philo_template)

llm = ChatOpenAI()

chain = (
    {"context": retriever, "question": RunnablePassthrough()}
    | philo_prompt
    | llm
    | StrOutputParser()
)
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
chain.invoke("How does Russel elaborate on Peirce's idea of the security blanket?")
```

更多信息，请查看 [使用 Astra DB 通过 CQL 的完整 RAG 模板](https://github.com/langchain-ai/langchain/tree/master/templates/cassandra-entomology-rag)。

## 清理

以下内容本质上是从 CassIO 检索 `Session` 对象并使用它运行 CQL `DROP TABLE` 语句：

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
cassio.config.resolve_session().execute(
    f"DROP TABLE {cassio.config.resolve_keyspace()}.cassandra_vector_demo;"
)
```

### 了解更多

有关更多信息、扩展快速入门和额外使用示例，请访问 [CassIO 文档](https://cassio.org/frameworks/langchain/about/) 以了解有关使用 LangChain `Cassandra` 向量存储的更多信息。

#### 归属声明

> Apache Cassandra、Cassandra 和 Apache 是美国和/或其他国家的 [Apache 软件基金会](http://www.apache.org/) 的注册商标或商标。

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\oss\python\integrations\vectorstores\cassandra.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>