技术教程 on Kalend's Blog

ChromaDB + Python：5分钟搭建个人知识库

Wed, 24 Jun 2026 08:30:00 +0800

上一篇用 FAISS 搭语义搜索引擎，有人问我：有没有不用自己管索引文件的方案？有，ChromaDB 就是为这个场景生的。

先说结论

ChromaDB 是面向开发者的"零配置"向量数据库。pip install 就能用，不需要 Docker，不需要外部服务，自带持久化，支持元数据过滤，几行代码接入 embedding 模型。

一句话定位：向量数据库里的 SQLite。

如果你只是想快速搭一个知识库、文档搜索、RAG 原型，ChromaDB 是门槛最低的选择。等数据量到百万级、需要高并发了，再考虑 Qdrant 或 Milvus。

向量数据库 60 秒科普

上一篇 FAISS 文章讲过原理，这里用图书馆的类比快速过一遍。

你去图书馆找书，有两种方式：

索引卡方式（关键词搜索）：翻目录卡片，按书名精确匹配。搜"Python 入门"只能找到标题里有这几个字的书
问管理员方式（语义搜索）：跟管理员说"我想学编程"，他理解你的意思，给你推荐相关的书，不管书名叫什么

向量数据库干的就是"管理员"的活。它把每条文档编码成向量（一串数字），搜索时把你的查询也编码成向量，然后计算向量间的距离找最接近的。

ChromaDB 在此基础上多做了一件事：它把这些向量连同原始文本和元数据一起存好，不用你操心存储细节。FAISS 是搜索库，你得自己管存储；ChromaDB 是完整数据库，存储、索引、元数据一站式搞定。

5 分钟快速上手

第一步：安装

1

pip install chromadb

ChromaDB 自带一个内置 embedding 模型（all-MiniLM-L6-v2），英文场景开箱即用。但如果你处理中文，建议额外装一个中文模型：

1

pip install chromadb sentence-transformers

sentence-transformers 提供了丰富的中文 embedding 模型，下面的代码我会用它接入 BAAI/bge-small-zh-v1.5（约 100MB，首次自动下载）。

第二步：创建客户端和集合

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


import chromadb
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction

# 用中文 embedding 模型（默认模型偏英文，中文效果差）
ef = SentenceTransformerEmbeddingFunction(model_name="BAAI/bge-small-zh-v1.5")

# 创建持久化客户端，数据会保存到本地目录
client = chromadb.PersistentClient(path="./my_knowledge_base")

# 创建集合时指定 embedding 函数
collection = client.get_or_create_collection(
 name="my_docs",
 embedding_function=ef
)

PersistentClient 和 FAISS 的最大区别：数据自动落盘。程序关了再开，数据还在。不用手动 write_index / read_index，不用维护"索引 ID → 原始文本"的映射表。

底层存储用的是 SQLite 数据库（chroma.sqlite3），向量索引用二进制文件存储，全部放在你指定的 path 目录下。这意味着你甚至可以用 sqlite3 直接查看元数据，备份只需要拷贝整个目录。

如果你只想做内存测试，用 chromadb.Client() 即可，退出即丢。

第三步：添加文档

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# 添加文档，ChromaDB 自动帮你做 embedding
collection.add(
 documents=[
 "Python 是一门解释型编程语言，语法简洁易读",
 "Java 是面向对象的编程语言，跨平台运行",
 "今天天气真不错，适合出门散步",
 "如何申请退款？请在订单页面点击退款按钮",
 "我想把钱退回来，应该怎么操作",
 ],
 metadatas=[
 {"category": "编程", "source": "wiki"},
 {"category": "编程", "source": "wiki"},
 {"category": "生活", "source": "diary"},
 {"category": "客服", "source": "faq"},
 {"category": "客服", "source": "faq"},
 ],
 ids=["doc1", "doc2", "doc3", "doc4", "doc5"]
)

注意：这里指定了中文 embedding 模型，add() 的时候 ChromaDB 自动把文本转成向量存进去。ChromaDB 内置的默认模型（all-MiniLM-L6-v2）偏英文，对中文语义理解较差，所以处理中文数据时强烈建议换成中文模型。

第四步：查询

1
2
3
4
5
6
7
8


# 语义搜索
results = collection.query(
 query_texts=["编程语言有哪些"],
 n_results=3
)

for doc, dist in zip(results["documents"][0], results["distances"][0]):
 print(f"[距离: {dist:.4f}] {doc}")

输出：

1
2
3


[距离: 0.3133] Java 是面向对象的编程语言，跨平台运行
[距离: 0.3375] Python 是一门解释型编程语言，语法简洁易读
[距离: 0.7588] 今天天气真不错，适合出门散步

搜"编程语言有哪些"，前两条命中 Python 和 Java，第三条天气明显不相关。距离越小越相似。

补充一点：distances 返回的是向量距离，不是相似度分数。ChromaDB 默认用余弦距离，值域 [0, 2]，0 表示完全一致，2 表示完全相反。实际使用中，距离小于 1.0 的结果通常比较相关，大于 1.2 就可以当噪音忽略了。

第五步：元数据过滤

这是 ChromaDB 相比 FAISS 的杀手级功能——先筛选再搜索。

1
2
3
4
5
6
7
8


# 只在"客服"分类里搜索
results = collection.query(
 query_texts=["退款"],
 n_results=5,
 where={"category": "客服"}
)

print(results["documents"][0])

输出：

1

['如何申请退款？请在订单页面点击退款按钮', '我想把钱退回来，应该怎么操作']

where 条件支持 $eq（等于）、$ne（不等于）、$in（包含）等操作符：

1
2
3
4
5
6
7
8


# 多值过滤
where={"category": {"$in": ["编程", "客服"]}}

# 复合条件
where={"$and": [
 {"source": "faq"},
 {"category": "客服"}
]}

想象一个场景：你有 10000 篇文档，10 个分类。用户只想搜"技术"分类下的内容。FAISS 需要你自己实现过滤逻辑，ChromaDB 一个 where 参数搞定。

完整实战：搭建个人知识库

把上面的模块组合起来，做一个能增删查的迷你知识库：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68


import chromadb
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction
import time

class KnowledgeBase:
 def __init__(self, db_path="./my_kb"):
 self.client = chromadb.PersistentClient(path=db_path)
 ef = SentenceTransformerEmbeddingFunction(model_name="BAAI/bge-small-zh-v1.5")
 self.collection = self.client.get_or_create_collection(
 name="notes", embedding_function=ef
 )

 def add(self, text, category="未分类", doc_id=None):
 """添加一条笔记"""
 if doc_id is None:
 doc_id = f"note_{int(time.time()*1000)}"
 self.collection.add(
 documents=[text],
 metadatas=[{"category": category}],
 ids=[doc_id]
 )
 return doc_id

 def search(self, query, n=5, category=None):
 """语义搜索，可选按分类过滤"""
 where = {"category": category} if category else None
 results = self.collection.query(
 query_texts=[query],
 n_results=n,
 where=where
 )
 hits = []
 for doc, dist, meta in zip(
 results["documents"][0],
 results["distances"][0],
 results["metadatas"][0]
 ):
 hits.append({"text": doc, "distance": dist, "meta": meta})
 return hits

 def count(self):
 return self.collection.count()

# ========== 使用示例 ==========
kb = KnowledgeBase()

# 批量添加笔记
notes = [
 ("Python 列表推导式比 for 循环快，因为底层用 C 实现", "Python"),
 ("Git rebase 会重写提交历史，谨慎在公共分支使用", "Git"),
 ("Docker 容器隔离靠 namespace 和 cgroups", "Docker"),
 ("Python 装饰器本质是接受函数返回函数的高阶函数", "Python"),
 ("Git stash 暂存当前工作区改动，不提交到分支", "Git"),
]
for text, cat in notes:
 kb.add(text, category=cat)

print(f"知识库共 {kb.count()} 条笔记\n")

# 语义搜索：搜"循环优化"
print("=== 搜索: 循环优化 ===")
for hit in kb.search("循环优化", n=3):
 print(f" [{hit['meta']['category']}] {hit['text']}")

# 搜索：只在 Git 分类下搜
print("\n=== 搜索: 分支管理 (仅 Git) ===")
for hit in kb.search("分支管理", n=3, category="Git"):
 print(f" [{hit['meta']['category']}] {hit['text']}")

运行后重启程序，数据还在——因为 PersistentClient 自动落盘了。这就是 ChromaDB 和 FAISS 最大的体验差异：你不用管索引文件，数据自己活着。

补充两个实用技巧：

批量添加比逐条添加快得多。上面的示例为了清晰逐条 add()，实际使用时建议一次传入列表：

1
2
3
4
5
6


# 批量添加，比循环 add() 快 10 倍以上
collection.add(
 documents=["文档1", "文档2", "文档3"],
 metadatas=[{"cat": "a"}, {"cat": "b"}, {"cat": "c"}],
 ids=["d1", "d2", "d3"]
)

换更强的中文模型。如果你的数据量更大、精度要求更高，可以把 bge-small-zh-v1.5 换成 BAAI/bge-large-zh-v1.5（1024 维，约 1.3GB）。注意：同一个集合内不能混用不同模型，换模型必须新建集合。

选型对比：ChromaDB vs FAISS vs Qdrant

维度	ChromaDB	FAISS	Qdrant
部署方式	pip install，零配置	pip install，纯库	需 Docker 或独立服务
内置 embedding	有（all-MiniLM-L6-v2）	无，需自己编码	无
持久化	自动落盘	手动 save/load	自动
元数据过滤	where 条件，开箱即用	无，需自己实现	有，filter API
适用规模	<100万	任意（看索引类型）	千万级
典型场景	知识库、RAG 原型	高性能向量搜索	生产级语义搜索

我的选型建议：

个人知识库、文档搜索、RAG 原型 → ChromaDB。零配置，内置 embedding，5 分钟跑通
纯追求搜索速度、数据量可控 → FAISS。最轻最快，但要自己管存储和元数据
生产环境、高并发、需要精确过滤 → Qdrant。功能全性能好，代价是要部署一个服务

一句话总结：个人和原型用 ChromaDB，生产高并发用 Qdrant，纯速度用 FAISS。

结语

ChromaDB 的定位很清晰：向量数据库里的 SQLite。不需要服务端，不需要 Docker，pip install 之后几行代码就能跑，数据自动持久化，接入 embedding 模型就能开箱即用。

它不追求极限性能，不追求分布式高可用，但它把"存储 + 索引 + embedding + 元数据过滤"打包成一个极简的包。对于个人知识库、文档语义搜索、RAG 原型验证这些场景，ChromaDB 是目前最省心的选择。Python 开发者十分钟就能搭出一个能用的知识库，这个门槛在两年前是不可想象的。

上一篇 FAISS 文章解决了"怎么把向量搜得快"，这一篇解决了"怎么用得省心"。两者互补：FAISS 适合想完全掌控底层细节的极客，ChromaDB 适合想快速出结果的开发者。如果你刚接触向量检索，建议从 ChromaDB 开始——先跑通流程，理解语义搜索的价值，再根据实际需求决定是否需要换到 FAISS 或 Qdrant。

试试用自己的文档笔记跑一遍上面的代码，把日常积累的技术笔记、读书摘录、工作文档丢进去，你会发现语义搜索比关键词搜索好用太多。搜"性能优化"能找到"降低延迟"的笔记，搜"部署"能找到"Docker 配置"的记录——这在传统的搜索方式下几乎不可能。

关注 varkm，一起学习，一起成长

别再用 LIKE 搜数据库了：20 行代码搭一个语义搜索引擎

Sun, 21 Jun 2026 08:53:00 +0800

你在文档里搜"退款"，结果一个都没有。但文档里明明写着"我想退钱"。

先说结论

传统搜索靠关键词匹配，搜"退款"找不到"退钱"，因为机器只认字不认意思。

向量检索把文字变成数字（向量），按语义相似度搜索。搜"退款"能命中"我想退钱"，因为它俩意思一样。

Sentence-Transformers 负责编码，FAISS 负责搜索。

20 行 Python，搭一个比 MySQL LIKE 强 100 倍的语义搜索引擎。数据量从一千条到十亿条，都有对应的方案。

下面我从原理到代码，一步步带你跑通。

第一章：向量检索是什么（3 分钟搞懂原理）

文本变向量：让机器理解"意思"

embedding（嵌入）把一段文字编码成一串数字，比如 768 维的浮点数组。

这串数字就是文字的"语义指纹"。意思相近的文字，指纹也相近；意思无关的文字，指纹差很远。

“退款"和"退钱"的关键词不同，但编码出来的向量非常接近。“退款"和"天气预报"的向量则差了十万八千里。

相似度怎么算：余弦 vs L2

算两个向量有多接近，常用两种方式：

方式	原理	特点
余弦相似度	算向量夹角的余弦值	值域 [-1,1]，越大越相似
L2 距离	算欧氏距离	值域 [0,∞)，越小越相似

大多数语义搜索场景用余弦相似度。配合向量归一化（让每个向量的长度变成 1），余弦相似度等价于向量内积，计算更快。

为什么不用 MySQL LIKE

LIKE 做的是字面匹配。搜"退款”，数据库遍历每一条记录，看有没有"退"和"款"这两个字挨在一起。

“如何申请退款” → 命中 ✓
“我想把钱退回来” → 不命中 ✗
“退订服务” → 不命中 ✗

但这三条说的是同一件事。LIKE 的本质缺陷：它不理解语义，只匹配字符。

向量检索的思路完全不同：先把所有文本编码成向量，搜索时把查询也编码成向量，然后找最近的几个。它匹配的是"意思”，不是"字面"。

第二章：Sentence-Transformers — 让文本变成向量

安装和一行代码上手

1

pip install sentence-transformers faiss-cpu

加载模型、编码文本，三行搞定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


from sentence_transformers import SentenceTransformer

# 加载中文 embedding 模型
model = SentenceTransformer('BAAI/bge-small-zh-v1.5')

# 把文本编码成向量
texts = ["如何申请退款", "我想把钱退回来", "今天天气不错"]
embeddings = model.encode(texts)

print(embeddings.shape) # (3, 512) — 3条文本，每条512维

输出 (3, 512) 表示 3 条文本各编码成了 512 维的向量。

中文模型怎么选

这是新手最纠结的问题。我直接给你结论：

模型	维度	大小	适用场景
bge-small-zh-v1.5	512	~100MB	入门首选，速度快
m3e-base	768	~210MB	社区流行，中文适配好
bge-large-zh-v1.5	1024	~1.3GB	精度最高，生产推荐
BGE-m3	1024	~2.3GB	多语言+多功能，最强

我的建议：学习阶段用 bge-small-zh-v1.5，小快够用。上生产了换 bge-large-zh-v1.5 或 BGE-m3。

避坑：维度不一致不能混用

这是 90% 的新手会踩的坑。

bge-small 输出 512 维，m3e-base 输出 768 维。

如果你用 bge-small 建了索引，后来换成 m3e-base 编码查询，FAISS 直接报错——维度对不上。

规则：编码模型和建索引模型必须是同一个。换模型 = 重建索引，没有例外。

第三章：FAISS — 让向量搜起来飞快

安装

1
2


pip install faiss-cpu # CPU 版，够用
# pip install faiss-gpu # GPU 版，百万级以上考虑

3 分钟跑通第一个索引

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


import faiss
import numpy as np

# 假设你已经有 1000 条文本的向量（512维）
embeddings = np.random.rand(1000, 512).astype('float32')

# 建立索引
dim = 512
index = faiss.IndexFlatL2(dim)
index.add(embeddings)

print(f"索引中有 {index.ntotal} 条向量") # 1000

# 搜索：找最相似的 5 条
query = np.random.rand(1, 512).astype('float32')
distances, indices = index.search(query, k=5)

print("最相似的5条索引:", indices[0])
print("对应的L2距离:", distances[0])

四种索引类型决策树

这是这篇文章的核心价值。FAISS 有十几种索引，但 99% 的场景只需要搞懂这四种：

索引类型	数据量级	速度	精度	典型场景
IndexFlatL2	<10万	慢	100%精确	原型开发、小数据
IndexIVFFlat	百万级	快	近似（可调）	中等规模生产
IndexHNSWFlat	千万级	最快	高召回率	低延迟在线搜索
IndexIVFPQ	十亿级	快	有损压缩	超大规模+省内存

怎么选：别想太多，从 IndexFlatL2 开始。数据量到 10 万条以后再考虑换。

我把四种索引的适用场景画个决策路径：

1
2
3
4
5
6
7
8
9


你的数据有多少条？
│
├── < 10万 → IndexFlatL2（暴力搜索，100%精确，不用调参）
│
├── 10万~100万 → IndexIVFFlat（聚类分区，平衡速度和精度）
│
├── 100万~1000万 → IndexHNSWFlat（图索引，速度最快）
│
└── > 1000万 → IndexIVFPQ（乘积量化压缩，省内存）

索引的保存和加载

90% 的新手忘的一步。程序退出，内存里的索引就没了。

1
2
3
4
5


# 保存索引到磁盘
faiss.write_index(index, "my_index.faiss")

# 下次直接加载，不用重新编码
index = faiss.read_index("my_index.faiss")

注意：FAISS 只保存向量和索引结构，不保存原始文本。你需要自己维护一个"索引ID → 原始文本"的映射（比如存一个 JSON 或列表）。

第四章：实战 — 搭一个能用的中文语义搜索引擎

完整可运行代码

下面这段代码复制就能跑。我准备了 10 条模拟 FAQ 数据，展示语义搜索的效果。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


from sentence_transformers import SentenceTransformer
import faiss
import numpy as np
import time

# ========== 1. 准备数据 ==========
faqs = [
 "如何申请退款？请在订单页面点击申请退款按钮。",
 "我想把钱退回来，应该怎么操作？",
 "退款多久能到账？一般3-5个工作日。",
 "取消订单的步骤是什么？进入我的订单，选择取消。",
 "怎么取消已经付款的购买？联系客服处理。",
 "会员到期了怎么续费？在设置中点击续费。",
 "密码忘记了怎么找回？点击登录页的忘记密码。",
 "怎么修改绑定的手机号？在账户安全设置中修改。",
 "发票怎么开具？订单完成后在详情页申请。",
 "如何投诉服务质量？请联系客服热线反馈。",
]

# ========== 2. 编码 ==========
model = SentenceTransformer('BAAI/bge-small-zh-v1.5')
embeddings = model.encode(faqs, normalize_embeddings=True)
dim = embeddings.shape[1]

# ========== 3. 建索引（内积相似度 = 归一化后的余弦相似度）==========
index = faiss.IndexFlatIP(dim)
index.add(embeddings.astype('float32'))

# ========== 4. 搜索 ==========
def search(query, top_k=3):
 query_vec = model.encode([query], normalize_embeddings=True)
 scores, indices = index.search(query_vec.astype('float32'), top_k)
 
 print(f"\n搜索: '{query}'")
 print("-" * 50)
 for i, idx in enumerate(indices[0]):
 score = scores[0][i]
 print(f" [{score:.4f}] {faqs[idx]}")
 return indices[0]

# ========== 5. 效果展示 ==========
search("退款")
search("怎么把钱退回来")
search("取消购买")
search("续费会员")

# ========== 6. 性能测试 ==========
start = time.time()
for _ in range(1000):
 query_vec = model.encode(["测试查询"], normalize_embeddings=True)
 index.search(query_vec.astype('float32'), 5)
elapsed = time.time() - start
print(f"\n1000次搜索耗时: {elapsed:.2f}s (含编码时间)")
print(f"平均每次(含编码): 约 {elapsed/1000*1000:.2f}ms")

运行效果

搜"退款"命中"如何申请退款"和"我想把钱退回来"——关键词完全不同，但语义命中。

搜"取消购买"命中"怎么取消已经付款的购买"和"取消订单的步骤"——“取消"和"购买"拆开了照样匹配。

这就是语义搜索的威力：它理解意思，不依赖关键词重合。

性能数据

10 条数据的搜索时间几乎为 0（亚毫秒级）。扩展到 1000 条，纯索引搜索（不含编码）仍在 1ms 以内。

对比 MySQL LIKE 查询 1000 条记录，需要全表扫描 + 逐行字符匹配，通常在 5-50ms。向量检索在语义理解上有质的飞跃，速度也不逊色。

第五章：数据量增长后怎么办

索引迁移路径

数据量增长到一定程度，IndexFlatL2 的暴力搜索会变慢。这时候该换索引了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


IndexFlatL2 (暴力)
 │
 │ 数据量 > 10万，搜索开始变慢
 ▼
IndexIVFFlat (聚类分区)
 │
 │ 数据量 > 100万，需要更高吞吐
 ▼
IndexHNSWFlat (图索引)
 │
 │ 数据量 > 1000万，内存吃紧
 ▼
IndexIVFPQ (乘积量化)

切换时机：当你感觉搜索延迟不可接受（比如超过 100ms）的时候，就该考虑换索引了。不要过早优化。

FAISS vs 其他方案

FAISS 是一个搜索库，不是完整的数据库。它没有增删改查 API，没有持久化层，需要你自己管理。

如果不想自己管这些，可以考虑封装好的向量数据库：

方案	类型	适用规模	特点
FAISS	嵌入式库	任意	轻量无依赖，需自己管持久化
ChromaDB	轻量数据库	<100万	开箱即用，内置持久化
Qdrant	数据库	千万级	Rust 写的，高性能，API 友好
Milvus	分布式数据库	十亿级	生产级，支持分布式

我的建议：原型阶段用 FAISS，够轻够快。产品化了再按需升级。别一上来就上 Milvus，运维成本会吃掉你。

核心建议

别过早优化。从 IndexFlatL2 开始，能跑就先跑着。

等数据量真到了瓶颈再换索引，迁移成本远低于你从第一天就过度设计的成本。这句话适用于 99% 的项目。

结论

向量检索不是黑魔法。

Sentence-Transformers 把文本编码成向量，FAISS 把向量搜得飞快。两个库，20 行代码，你就拥有了一个能理解语义的搜索引擎。

搜"退款"能找到"退钱”，搜"取消购买"能命中"取消订单"。这就是语义搜索和关键词搜索的本质区别。

记住三个要点：从 IndexFlatL2 开始、编码模型和索引维度必须一致、别忘了保存索引到磁盘。

剩下的，动手跑一遍代码就懂了。

关注 varkm，一起学习，一起成长