概述
做 AI 应用，向量数据库是绕不开的环节。Qdrant、Milvus 功能强大，但部署重、运维复杂。如果你只需要在本地或小型项目里存 embedding、做相似度检索，ChromaDB 是最省心的选择。
它不用 Docker，不用写配置文件，Python 一行代码就能跑起来。支持持久化存储、SQL 过滤、多集合管理，还能嵌入到任何 Python 项目里。
这篇教程教你在 Linux 服务器或本地电脑上搭好 ChromaDB 环境，附带 Python 完整使用示例。
准备工作
你需要以下条件：
- 一台 Linux 机器（Ubuntu 22.04 / Debian 12 最佳，也支持 Mac 和 Windows）
- Python 3.8+（推荐 3.10+，支持类型提示更完整）
- pip 或 uv 包管理器
- 约 200MB 磁盘空间（ChromaDB 本身很小，但首次下载 embedding 模型会多花点空间）
先检查 Python 环境：
python3 --version
pip3 --version
输出类似 Python 3.10.12 和 pip 22.0.6 就说明环境正常。
如果还没装 Python，用 apt 安装：
sudo apt update
sudo apt install -y python3 python3-pip python3-venv
第一步：创建项目目录和虚拟环境
mkdir -p ~/chromadb-demo && cd ~/chromadb-demo
python3 -m venv venv
source venv/bin/activate
虚拟环境很重要。ChromaDB 的依赖比较多，装在系统 Python 里容易冲突。激活后你的命令行提示符前面会出现 (venv)，说明生效了。
第二步：安装 ChromaDB
pip install chromadb
安装完成后验证版本：
python3 -c "import chromadb; print(chromadb.__version__)"
输出版本号（如 0.4.24）说明安装成功。
第三步：启动 ChromaDB 服务
ChromaDB 有两种运行模式：嵌入式（内存）和服务器模式。
嵌入式模式不需要额外启动，代码里直接用就行。但如果你想让多个进程共享数据，或者想通过 HTTP API 访问，需要启动服务：
chroma run --path ~/chromadb-data --host 0.0.0.0 --port 8000
参数说明：
--path指定数据持久化目录，服务重启后数据不丢失--host 0.0.0.0允许局域网内其他机器访问，本地开发用127.0.0.1即可--port默认 8000，改端口避免冲突
启动后看到类似输出就说明跑起来了：
INFO: Uvicorn running on http://0.0.0.0:8000
INFO: Application startup complete.
另一个终端测试 API：
curl http://localhost:8000/api/v1/heartbeat
返回 {"status": {}} 就说明服务正常。
第四步：Python 使用示例
写一个完整的示例，覆盖创建集合、插入数据、搜索、过滤、删除等核心操作：
import chromadb
# 连接本地服务（嵌入式模式）
client = chromadb.Client()
# 创建或获取集合
collection = client.get_or_create_collection(
name="my_notes",
metadata={"hnsw:space": "cosine"} # 余弦相似度
)
# 插入数据
collection.add(
documents=[
"怎么在 Linux 上安装 Docker",
"Python 异步编程的最佳实践",
"Rust 所有权模型详解",
"向量数据库选型指南",
],
ids=["doc1", "doc2", "doc3", "doc4"],
metadatas=[
{"category": "devops", "difficulty": "beginner"},
{"category": "python", "difficulty": "advanced"},
{"category": "rust", "difficulty": "intermediate"},
{"category": "database", "difficulty": "intermediate"},
]
)
# 向量搜索
results = collection.query(
query_texts=["数据库"],
n_results=2,
where={"category": "database"} # SQL 过滤
)
print(results["documents"])
# ['向量数据库选型指南']
# 全部数据
all_docs = collection.get()
print(all_docs["documents"])
# 更新数据
collection.update(
ids=["doc1"],
documents=["Docker 安装完全指南 2024"],
metadatas=[{"category": "devops", "difficulty": "beginner"}]
)
# 删除数据
collection.delete(ids=["doc4"])
把这些代码保存为 demo.py，运行：
python3 demo.py
第五步：持久化配置（重要）
默认的嵌入式模式数据存在内存里，进程退出就没了。生产环境需要持久化：
# 持久化到本地目录
client = chromadb.PersistentClient(path="./chroma_data")
collection = client.get_or_create_collection("my_notes")
collection.add(
documents=["这是一条持久化的数据"],
ids=["persistent_doc"]
)
运行后会在当前目录生成 chroma_data 文件夹，里面是 SQLite 文件，直接备份整个目录就是备份全部数据。
如果用服务器模式，数据已经在 --path 指定的目录里持久化了，不用额外配置。
验证
启动服务后，用以下命令确认一切正常：
# 1. 检查服务心跳
curl http://localhost:8000/api/v1/heartbeat
# 2. 创建集合
curl -X POST http://localhost:8000/api/v1/collections \
-H "Content-Type: application/json" \
-d '{"name": "test_collection"}'
# 3. 插入数据
curl -X POST http://localhost:8000/api/v1/collections/test_collection/add \
-H "Content-Type: application/json" \
-d '{"ids": ["t1"], "documents": ["hello world"]}'
# 4. 查询
curl -X POST http://localhost:8000/api/v1/collections/test_collection/query \
-H "Content-Type: application/json" \
-d '{"query_texts": ["hello"], "n_results": 1}'
四个命令都返回正确结果，说明环境搭建成功。
常见问题
问题 1：安装时报 ModuleNotFoundError: No module named 'pydantic'
ChromaDB 依赖 Pydantic，但有时 pip 解析依赖会漏掉。解决方法：
pip install pydantic>=2.0.0
pip install chromadb --no-deps
先装依赖，再装 ChromaDB 本体。
问题 2：服务启动后端口被占用
# 查占用端口的进程
lsof -i :8000
# 杀掉进程
kill -9 <PID>
# 或者换一个端口启动
chroma run --path ~/chromadb-data --port 8001
问题 3：数据太大内存不够
ChromaDB 默认在内存里做向量搜索，数据量大时会 OOM。解决方法是用 PersistentClient 模式，数据存磁盘，内存占用大幅降低：
import chromadb
client = chromadb.PersistentClient(path="/data/chromadb")
问题 4：Python 里怎么指定 Embedding 模型
ChromaDB 默认用 AllMiniLmL6V2 模型，从 HuggingFace 下载。国内网络可能慢，可以指定本地模型或换源：
# 设置 HuggingFace 镜像
export HF_ENDPOINT=https://hf-mirror.com
pip install chromadb
然后在代码里指定模型：
from chromadb.utils import embedding_functions
ef = embedding_functions.SentenceTransformerEmbeddingFunction(
model_name="sentence-transformers/all-MiniLM-L6-v2"
)
collection = client.get_or_create_collection(
"my_collection",
embedding_function=ef
)
问题 5：怎么备份数据
直接复制数据目录就行：
# 备份
cp -r ~/chromadb-data ~/chromadb-data-backup-$(date +%Y%m%d)
# 恢复
rm -rf ~/chromadb-data
cp -r ~/chromadb-data-backup-20260827 ~/chromadb-data
总结
ChromaDB 是目前最简单的向量数据库方案。一行 pip install 装好，一行 chroma run 启动服务，Python 里 get_or_create_collection 就能用。适合个人项目、原型开发、小型 RAG 应用。数据量超过百万条时，建议迁移到 Qdrant 或 PGVector。
你的项目里需要向量搜索吗？用 ChromaDB 试一下，五分钟就能跑起来。