Skip to main content
本笔记本介绍如何开始使用 Chroma 向量存储。
Chroma 是一个专注于开发者生产力和幸福感的 AI 原生开源向量数据库。Chroma 采用 Apache 2.0 许可证。在 此页面 查看 Chroma 的完整文档，并在 此页面 查找 LangChain 集成的 API 参考。
Chroma CloudChroma Cloud 提供无服务器向量和全文搜索功能。它速度极快、具有成本效益、可扩展且省心。只需 30 秒即可创建数据库并使用 5 美元的免费额度试用。开始使用 Chroma Cloud

​
设置

要访问 Chroma 向量存储，您需要安装 langchain-chroma 集成包。 
pip install -qU "langchain-chroma>=0.1.2"

​
凭据

您可以无需任何凭据即可使用 Chroma 向量存储，只需安装上述包即可！ 如果您是 Chroma Cloud 用户，请设置您的 CHROMA_TENANT、CHROMA_DATABASE 和 CHROMA_API_KEY 环境变量。 安装 chromadb 包后，您还可以访问 Chroma CLI，它可以为您设置这些变量。首先，通过 CLI 登录，然后使用 connect 命令： 
chroma db connect [db_name] --env-file
如果您希望获得业界最佳的模型调用自动追踪，也可以通过取消注释以下内容来设置您的 LangSmith API 密钥： 
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"

​
初始化

​
基本初始化

以下是基本初始化，包括使用目录将数据保存到本地。 
# | output: false
# | echo: false
from langchain_openai import OpenAIEmbeddings

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

​
本地运行（内存中）

您可以通过实例化带有集合名称和嵌入提供程序的 Chroma 实例，使 Chroma 服务器在内存中运行： 
from langchain_chroma import Chroma

vector_store = Chroma(
    collection_name="example_collection",
    embedding_function=embeddings,
)
如果您不需要数据持久性，这是在构建 LangChain AI 应用程序时进行实验的好选择。

​
本地运行（带数据持久性）

您可以提供 persist_directory 参数以在程序多次运行时保存您的数据： 
from langchain_chroma import Chroma

vector_store = Chroma(
    collection_name="example_collection",
    embedding_function=embeddings,
    persist_directory="./chroma_langchain_db",
)

​
连接到 Chroma 服务器

如果您有一个在本地运行的 Chroma 服务器，或者您自己 部署 了一个，您可以通过提供 host 参数连接到它。 例如，您可以使用 chroma run 启动本地运行的 Chroma 服务器，然后通过 host='localhost' 连接它： 
from langchain_chroma import Chroma

vector_store = Chroma(
    collection_name="example_collection",
    embedding_function=embeddings,
    host="localhost",
)
对于其他部署，您可以使用 port、ssl 和 headers 参数自定义您的连接。

​
Chroma Cloud

Chroma Cloud 用户也可以使用 LangChain 构建。为您的 Chroma 实例提供 Chroma Cloud API 密钥、租户和数据库名称： 
from langchain_chroma import Chroma

vector_store = Chroma(
    collection_name="example_collection",
    embedding_function=embeddings,
    chroma_cloud_api_key=os.getenv("CHROMA_API_KEY"),
    tenant=os.getenv("CHROMA_TENANT"),
    database=os.getenv("CHROMA_DATABASE"),
)

​
从客户端初始化

您也可以从 Chroma 客户端初始化，如果您想要更容易访问底层数据库，这特别有用。

​
本地运行（内存中）

import chromadb

client = chromadb.Client()

​
本地运行（带数据持久性）

import chromadb

client = chromadb.PersistentClient(path="./chroma_langchain_db")

​
连接到 Chroma 服务器

例如，如果您在本地运行 Chroma 服务器（使用 chroma run）： 
import chromadb

client = chromadb.HttpClient(host="localhost", port=8000, ssl=False)

​
Chroma Cloud

设置好 CHROMA_API_KEY、CHROMA_TENANT 和 CHROMA_DATABASE 后，您可以直接实例化： 
import chromadb

client = chromadb.CloudClient()

​
访问您的 Chroma 数据库

collection = client.get_or_create_collection("collection_name")
collection.add(ids=["1", "2", "3"], documents=["a", "b", "c"])

​
创建 Chroma 向量存储

vector_store_from_client = Chroma(
    client=client,
    collection_name="collection_name",
    embedding_function=embeddings,
)

​
管理向量存储

创建向量存储后，我们可以通过添加和删除不同项目与其交互。

​
向向量存储添加项目

我们可以使用 add_documents 函数将项目添加到我们的向量存储中。 
from uuid import uuid4

from langchain_core.documents import Document

document_1 = Document(
    page_content="I had chocolate chip pancakes and scrambled eggs for breakfast this morning.",
    metadata={"source": "tweet"},
    id=1,
)

document_2 = Document(
    page_content="The weather forecast for tomorrow is cloudy and overcast, with a high of 62 degrees.",
    metadata={"source": "news"},
    id=2,
)

document_3 = Document(
    page_content="Building an exciting new project with LangChain - come check it out!",
    metadata={"source": "tweet"},
    id=3,
)

document_4 = Document(
    page_content="Robbers broke into the city bank and stole $1 million in cash.",
    metadata={"source": "news"},
    id=4,
)

document_5 = Document(
    page_content="Wow! That was an amazing movie. I can't wait to see it again.",
    metadata={"source": "tweet"},
    id=5,
)

document_6 = Document(
    page_content="Is the new iPhone worth the price? Read this review to find out.",
    metadata={"source": "website"},
    id=6,
)

document_7 = Document(
    page_content="The top 10 soccer players in the world right now.",
    metadata={"source": "website"},
    id=7,
)

document_8 = Document(
    page_content="LangGraph is the best framework for building stateful, agentic applications!",
    metadata={"source": "tweet"},
    id=8,
)

document_9 = Document(
    page_content="The stock market is down 500 points today due to fears of a recession.",
    metadata={"source": "news"},
    id=9,
)

document_10 = Document(
    page_content="I have a bad feeling I am going to get deleted :(",
    metadata={"source": "tweet"},
    id=10,
)

documents = [
    document_1,
    document_2,
    document_3,
    document_4,
    document_5,
    document_6,
    document_7,
    document_8,
    document_9,
    document_10,
]
uuids = [str(uuid4()) for _ in range(len(documents))]

vector_store.add_documents(documents=documents, ids=uuids)

​
更新向量存储中的项目

既然我们已经将文档添加到向量存储中，我们可以使用 update_documents 函数更新现有文档。 
updated_document_1 = Document(
    page_content="I had chocolate chip pancakes and fried eggs for breakfast this morning.",
    metadata={"source": "tweet"},
    id=1,
)

updated_document_2 = Document(
    page_content="The weather forecast for tomorrow is sunny and warm, with a high of 82 degrees.",
    metadata={"source": "news"},
    id=2,
)

vector_store.update_document(document_id=uuids[0], document=updated_document_1)
# You can also update multiple documents at once
vector_store.update_documents(
    ids=uuids[:2], documents=[updated_document_1, updated_document_2]
)

​
从向量存储删除项目

我们也可以按以下方式从向量存储中删除项目： 
vector_store.delete(ids=uuids[-1])

​
查询向量存储

一旦创建了向量存储并添加了相关文档，您很可能希望在运行链或智能体期间查询它。

​
直接查询

​
相似度搜索

执行简单的相似度搜索可以如下所示： 
results = vector_store.similarity_search(
    "LangChain provides abstractions to make working with LLMs easy",
    k=2,
    filter={"source": "tweet"},
)
for res in results:
    print(f"* {res.page_content} [{res.metadata}]")

​
带分数的相似度搜索

如果您想执行相似度搜索并接收相应的分数，可以运行： 
results = vector_store.similarity_search_with_score(
    "Will it be hot tomorrow?", k=1, filter={"source": "news"}
)
for res, score in results:
    print(f"* [SIM={score:3f}] {res.page_content} [{res.metadata}]")

​
按向量搜索

您也可以按向量搜索： 
results = vector_store.similarity_search_by_vector(
    embedding=embeddings.embed_query("I love green eggs and ham!"), k=1
)
for doc in results:
    print(f"* {doc.page_content} [{doc.metadata}]")

​
其他搜索方法

本笔记本未涵盖各种其他搜索方法，例如 MMR 搜索。有关 Chroma 可用的搜索能力的完整列表，请查看 API 参考。

​
转换为检索器进行查询

您还可以将向量存储转换为检索器，以便在链中更轻松地使用。有关您可以传递的不同搜索类型和 kwargs 的更多信息，请访问 Chroma API 参考。 
retriever = vector_store.as_retriever(
    search_type="mmr", search_kwargs={"k": 1, "fetch_k": 5}
)
retriever.invoke("Stealing from the bank is a crime", filter={"source": "news"})

​
用于检索增强生成的用法

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

​
API 参考

有关所有 Chroma 向量存储功能和配置的详细文档，请前往 API 参考
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.