玩转Chroma：用Python搭建智能知识库

在AI大模型时代，向量数据库成了构建知识库的核心工具。

Chroma作为轻量、易用的开源向量数据库，无需复杂配置就能快速搭建专属知识库。

今天就带大家从部署到代码实操，一步步掌握用Chroma搭建、操作知识库的全流程。

目录├── 1. 部署Chroma服务│ ├── 1.1 准备Docker环境│ ├── 1.2 启动Chroma服务│ └── 1.3 验证部署是否成功├── 2. 用Python操作知识库│ ├── 2.1 连接Chroma服务│ ├── 2.2 创建知识库集合│ ├── 2.3 向知识库添加文档│ ├── 2.4 智能语义检索│ └── 2.5 更新和删除│ ├── 2.5.1 更新文档│ ├── 2.5.2 删除文档│ └── 2.5.3 删除整个集合├── 3. 让检索结果更精准└── 4. 总结

1. 部署Chroma服务

本章介绍通过Docker部署Chroma。

1.1. 准备Docker环境

先把Docker和Docker Compose装好（以Ubuntu 22.04为例）：

# 卸载旧版Docker相关包for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do  sudo apt-get remove -y $pkg 2>/dev/nulldone# 安装依赖并添加官方GPG密钥sudo apt-get install -y ca-certificates curlsudo install -m 0755 -d /etc/apt/keyringssudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.ascsudo chmod a+r /etc/apt/keyrings/docker.asc# 添加Docker官方仓库并安装echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/nullsudo apt-get updatesudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin# 启动并开机自启Dockersudo systemctl enable --now docker

1.2. 启动Chroma服务

创建部署目录和配置文件，一键启动服务：

# 创建目录mkdir -p chroma-deployment && cd chroma-deployment# 编写docker-compose.ymlcat > docker-compose.yml << EOFversion: '3.9'services:  chroma-server:    image: chromadb/chroma:latest    container_name: chroma-server    restart: unless-stopped    ports:      - "18000:8000"                 # 前面是映射到宿主机的端口，可自定义    volumes:      - chroma-data:/data    environment:      - IS_PERSISTENT=TRUE           # 开启持久化      - ANONYMIZED_TELEMETRY=FALSE   # 禁用匿名数据收集      - CHROMA_SERVER_HOST=0.0.0.0   # 允许外部访问      - CHROMA_SERVER_CORS_ALLOWED_ORIGINS=* # 允许跨域    healthcheck:      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v2/heartbeat"]      interval: 30s      timeout: 10s      retries: 3volumes:  chroma-data:    driver: localEOF# 启动服务sudo docker compose up -d

如果拉取镜像慢，可以配置为国内镜像源：

sudo tee /etc/docker/daemon.json <<-'EOF'{  "registry-mirrors": [    "https://docker.m.daocloud.io",    "https://hub-mirror.c.163.com",    "https://docker.mirrors.ustc.edu.cn"  ]}EOF# 重启Docker生效sudo systemctl daemon-reload && sudo systemctl restart dockersudo docker compose up -d

1.3. 验证部署是否成功

# 心跳检测（返回{"nanoseconds":xxx}即正常）curl http://localhost:18000/api/v2/heartbeat# 查看版本curl http://localhost:18000/api/v2/version

2. 用Python操作知识库

部署好Chroma服务后，用Python客户端连接，完成知识库文档的增删改查全流程。

2.1. 连接Chroma服务

先安装依赖：

pip install chromadb sentence-transformers

编写Python程序：

import chromadb# 连接远程/本地ChromaDB服务（替换为你的服务端IP）client = chromadb.HttpClient(host="127.0.0.1", port=18000)# 查看服务状态print("Chroma版本:", client.get_version())print("已有知识库集合:", client.list_collections())

2.2. 创建知识库集合

“集合（Collection）”相当于关系数据库的“表”，用来管理向量数据。需要配置嵌入模型（Embedding），用于把文本转成向量：

from chromadb.utils import embedding_functions# 配置嵌入模型（可选Ollama或本地模型）# 方式1：用Ollama的嵌入模型（需本地启动Ollama）ef = embedding_functions.OllamaEmbeddingFunction(    url="http://localhost:11434/api/embeddings",    model_name="nomic-embed-text:latest")# 方式2：用本地下载的开源嵌入模型（无需Ollama）# ef = embedding_functions.SentenceTransformerEmbeddingFunction(#     model_name="bge-large-zh-v1.5"  # 中文优选# )# 创建/获取知识库集合collection = client.get_or_create_collection(    name="my_knowledge_base",  # 集合名    metadata={"description": "个人智能知识库", "version": "1.0"},    embedding_function=ef  # 绑定嵌入模型)print("知识库集合创建成功！")

2.3. 向知识库添加文档

往集合里添加文本数据，ChromaDB会自动把文本转成向量存储：

# 准备待添加的文档、元数据、唯一ID（以下仅为示例）docs = [    "ChromaDB 是一个专为 AI 设计的开源向量数据库，轻量且易用。",    "Python 是一种广泛使用的高级编程语言，适合快速开发。",    "本地部署大语言模型可以有效保护企业数据隐私，避免数据外泄。",    "Ollama 是一个在本地运行大模型的便捷工具，支持一键部署LLM。",    "向量检索的核心是计算文本向量的距离，距离越小语义越相似。"]# 元数据：给文档加标签，方便后续过滤metadatas = [    {"source": "技术文档", "author": "自己"},    {"source": "维基百科", "author": "AI"},    {"source": "技术文档", "author": "自己"},    {"source": "维基百科", "author": "AI"},    {"source": "技术文档", "author": "自己"}]# 每个文档的唯一IDids = ["doc_1", "doc_2", "doc_3", "doc_4", "doc_5"]# 添加数据到知识库collection.add(    documents=docs,    metadatas=metadatas,    ids=ids)# 查看知识库数据量print("知识库文档总数:", collection.count())print("已添加的文档详情:", collection.get())

2.4. 智能语义检索

输入自然语言问题，从知识库中找出最相关的内容，这也是智能问答的核心逻辑：

# 输入查询问题query = "什么是Ollama？"# 语义检索（自动把问题转向量，匹配相似文档）results = collection.query(    query_texts=[query],  # 查询文本    n_results=5,          # 返回Top5相似结果    # where={"source": "维基百科"}  # 可选：按元数据过滤)# 解析并输出结果print("=== 知识库检索结果 ===")for i, (doc, dist, meta) in enumerate(    zip(results["documents"][0], results["distances"][0], results["metadatas"][0])):    # 距离越小，语义越相似（0=完全匹配，1=完全不相关）    print(f"{i+1}. {doc}")    print(f"    相似度距离: {dist:.4f} | 文档来源: {meta['source']}")

ChromaDB 返回的是“距离” (Distance)：数值越小，代表向量在空间中的间隔越近，语义越相似。

• • 距离 = 0：表示完全相同（完美匹配）。
• • 距离 = 1：表示完全不相关。

2.5. 更新和删除

（1）更新文档

如果文档内容有变化，按ID更新：

# 更新doc_4的内容和元数据collection.update(    documents=["Ollama 是本地运行大模型的轻量工具，开源免费，支持Llama、Qwen等多款模型。"],    metadatas=[{"source": "维基百科", "author": "AI"}],    ids=["doc_4"])print("文档更新成功！")

（2）删除文档

按ID或元数据条件删除：

# 方式1：按ID删除collection.delete(ids=["doc_3"])# 方式2：按元数据过滤删除（例：删除来源为"临时文档"的内容）# collection.delete(where={"source": "临时文档"})print("删除后文档总数:", collection.count())

（3）删除整个集合

try:    client.delete_collection("my_knowledge_base")    print("知识库集合已删除")except:    print("集合不存在")

3. 让检索结果更精准

在以上示例中，检索的结果如下所示。

很明显，与问题“什么是Ollama？”最相关的应该是3，但是结果却把其它文档排到了前面。

当遇到这种检索结果不够准确的情况时，我们可以通过 Rerank（重排序）方法，提升检索精度：

from sentence_transformers import CrossEncoder# 步骤1：ChromaDB粗检索（快速获取候选结果）query = "什么是Ollama？"raw_results = collection.query(    query_texts=[query],    n_results=10  # 先取Top10候选)# 步骤2：用重排模型精排（提升准确率）rerank_model = CrossEncoder("bge-reranker-base")  # 中文重排优选模型# 构造（查询问题，候选文档）对pairs = [[query, doc] for doc in raw_results["documents"][0]]# 计算相关性分数（分数越高越相关）scores = rerank_model.predict(pairs)# 按分数排序，取Top5doc_score_pairs = list(zip(raw_results["documents"][0], scores))doc_score_pairs.sort(key=lambda x: x[1], reverse=True)final_results = doc_score_pairs[:5]# 输出精排结果print("===== 精准检索结果 =====")for i, (doc, score) in enumerate(final_results):    print(f"{i+1}. {doc} | 相关性分数: {score:.4f}")

4. 总结

Chroma的优势在于轻量化、易上手，通过几行Python代码就能完成知识库的创建、数据管理和语义检索。无论是搭建个人知识库，还是做AI问答的底层数据支撑，Chroma都是绝佳选择。

你可以基于这个基础，扩展更多功能，比如对接大模型做知识问答系统。

赶紧动手试试，把零散的知识变成可检索的智能知识库吧！

Tips

1. 1. 有的嵌入模型对中文材料支持更好，可根据公开评测对比选用；
2. 2. 重排模型（Rerank）能显著提升检索精度，适合对结果要求较高的场景；
3. 3. 记得开启ChromaDB的持久化，避免服务重启后数据丢失。

1. 欢迎点赞、收藏、关注