用 Chroma 跑通文本向量检索的最小流程

向量数据库用于存储向量并执行相似度检索。文本、图片、音频等数据可以先通过 embedding 模型转换成向量，再写入向量数据库。

Chroma 是一个开源向量数据库。本文只演示最小使用流程：

  1. 创建 Chroma client
  2. 创建 collection
  3. 写入文档
  4. 使用自然语言查询相似文档
  5. 查看返回结果

Chroma 是什么

Chroma 可以保存以下数据：

在最小 Demo 中，可以不手动传入 embeddings。Chroma 会使用默认 embedding 模型，把 documents 和 query_texts 自动转换成向量。

例如查询：

Chroma 怎么把数据保存到本地？

可以匹配到：

PersistentClient 可以把 Chroma 数据保存到本地目录。

这类查询不是精确字符串匹配，而是相似度检索。

环境

使用 uv 创建虚拟环境：

uv venv
.\.venv\Scripts\Activate.ps1
uv pip install -r requirements.txt

requirements.txt 里只需要：

chromadb>=1.0.0

运行 Demo：

uv run python demo.py

第一次运行时，Chroma 会下载默认 embedding 模型。下载完成后会使用本地缓存。

最小 Demo

import chromadb


def main() -> None:
    # 1. 创建 Chroma 客户端。
    # Client() 是内存模式：适合 demo 和快速测试，程序结束后数据会消失。
    # 如果你想保存到本地磁盘，可以改成：
    # client = chromadb.PersistentClient(path="chroma_data")
    client = chromadb.Client()

    # 2. 创建或获取一个 collection。
    # collection 可以理解成一组文档的集合，类似数据库里的“表”。
    collection = client.get_or_create_collection(name="simple_chroma_demo")

    # 3. 准备几条示例文档。
    ids = ["doc1", "doc2", "doc3"]
    documents = [
        "Chroma 是一个向量数据库，可以用来做相似度搜索。",
        "PersistentClient 可以把 Chroma 数据保存到本地目录。",
        "RAG 会先从知识库检索相关内容，再交给大语言模型回答。",
    ]
    metadatas = [
        {"topic": "chroma"},
        {"topic": "persistence"},
        {"topic": "rag"},
    ]

    # 4. 写入文档。
    # 这里没有手动传 embeddings，所以 Chroma 会使用默认 embedding 模型
    # 自动把 documents 转成向量，然后保存起来。
    collection.upsert(
        ids=ids,
        documents=documents,
        metadatas=metadatas,
    )

    # 5. 用自然语言查询。
    query = "Chroma 怎么把数据保存到本地？"
    results = collection.query(
        query_texts=[query],
        n_results=2,
    )

    print(f"问题：{query}")
    print(f"当前 collection 文档数量：{collection.count()}")

    for index, document in enumerate(results["documents"][0], start=1):
        doc_id = results["ids"][0][index - 1]
        metadata = results["metadatas"][0][index - 1]
        distance = results["distances"][0][index - 1]

        print(f"\n结果 {index}")
        print(f"id: {doc_id}")
        print(f"metadata: {metadata}")
        print(f"distance: {distance:.4f}")
        print(f"document: {document}")


if __name__ == "__main__":
    main()

运行结果

问题：Chroma 怎么把数据保存到本地？
当前 collection 文档数量：3

结果 1
id: doc2
metadata: {'topic': 'persistence'}
distance: 0.3286
document: PersistentClient 可以把 Chroma 数据保存到本地目录。

结果 2
id: doc1
metadata: {'topic': 'chroma'}
distance: 0.4719
document: Chroma 是一个向量数据库，可以用来做相似度搜索。

第一个结果匹配到 PersistentClient 相关文档，说明查询文本和目标文档在向量空间中距离更近。

API 说明

chromadb.Client()：创建一个内存模式的 Chroma 客户端，适合快速测试。

get_or_create_collection()：创建或获取一个 collection。collection 可以理解成一组文档集合。

upsert()：写入或更新文档。这里传入了 ids、documents 和 metadatas。

query()：查询相似内容。这里使用 query_texts，Chroma 会自动把查询文本转换成向量。

distance：距离越小，通常表示越相似。不同距离算法下数值含义会有差异，但在这个 Demo 里可以先理解为“越小越接近”。

内存模式

Demo 里使用的是：

client = chromadb.Client()

这是内存模式，适合临时测试。程序结束后，数据不会长期保存。

持久化模式

需要把数据保存到本地目录时，改用 PersistentClient：

client = chromadb.PersistentClient(path="chroma_data")

数据会写入 chroma_data 目录。下次程序启动后可以继续读取。

总结