Chroma向量数据库零安装入门指南：快速搭建本地语义搜索系统

1次阅读

没有评论

共计 2216 个字符，预计需要花费 6 分钟才能阅读完成。

刚开始接触语义搜索项目时，我像大多数 ML 新手一样被 Milvus、Weaviate 这些数据库的依赖项折磨得够呛：

需要提前安装 Docker 和 Kubernetes
至少 3GB 内存才能跑起来基础服务
官方文档里复杂的集群配置说明让人望而生畏

直到发现 Chroma 的 嵌入式模式——这个只有 2.7MB 的轻量级解决方案，我才意识到原来搭建向量数据库可以像导入普通 Python 包一样简单。

Chroma 提供两种使用方式，对初学者特别友好：

嵌入式模式（推荐新手）
直接 pip install chromadb 即可使用
数据完全运行在本地进程内存中
适合快速验证和开发阶段
服务端模式
需要启动单独的服务器进程
支持多客户端连接
适合生产环境部署

# 最简启动示例 - 嵌入式模式
import chromadb
client = chromadb.Client()  # 一行代码完成数据库初始化

下面通过完整示例演示基本工作流，包含异常处理等生产级代码规范：

import chromadb
from chromadb.utils import embedding_functions

# 1. 初始化客户端（自动创建内存数据库）try:
    client = chromadb.Client()
except Exception as e:
    print(f"初始化失败: {e}")
    raise

# 2. 创建集合（相当于 SQL 的表）default_ef = embedding_functions.DefaultEmbeddingFunction()
collection = client.create_collection(
    name="my_docs",
    embedding_function=default_ef  # 使用默认的 sentence-transformers 模型
)

# 3. 批量插入文档（建议每次至少插入 100 条）documents = ["机器学习很有趣", "Chroma 不需要安装", "Python 是最好的语言"]
metadatas = [{"source": "doc1"}, {"source": "doc2"}, {"source": "doc3"}]
ids = ["id1", "id2", "id3"]

collection.add(
    documents=documents,
    metadatas=metadatas,
    ids=ids
)

# 4. 执行相似度查询
results = collection.query(query_texts=["推荐一个数据库"],
    n_results=2
)
print(results)

关键点说明：
– 默认使用 all-MiniLM-L6-v2 模型生成 384 维向量
– 批量插入比单条插入快 10 倍以上
– 内存模式下查询延迟通常在 10ms 以内

当需要保存数据到磁盘时，注意处理文件权限：

# 持久化客户端示例
client = chromadb.PersistentClient(path="./chroma_db")

# 常见错误：# - Windows 系统需要管理员权限
# Linux/Mac 建议先创建目录并设置权限：# mkdir -p ./chroma_db && chmod 755 ./chroma_db

Chroma 默认使用余弦相似度，当向量范数很小时会出现数值不稳定：

# 解决方案：插入时做归一化
from sklearn.preprocessing import normalize

embeddings = default_ef(documents)
normalized_embeddings = normalize(embeddings)
collection.add(embeddings=normalized_embeddings, ...)

对于超过 1 万条记录的数据集，建议启用近似搜索：

collection = client.create_collection(
    name="large_collection",
    metadata={"hnsw:space": "cosine"}  # 启用 HNSW 索引
)

可以无缝接入 AI 应用开发生态：

from langchain.vectorstores import Chroma
from langchain.embeddings import HuggingFaceEmbeddings

embedding_func = HuggingFaceEmbeddings()
vectorstore = Chroma.from_documents(
    documents=split_docs,
    embedding=embedding_func,
    persist_directory="./chroma_db"
)

在我的 MacBook Pro(M1 芯片)上测试不同规模数据集的表现：