下面介绍如何优化向 Chroma 中写入数据,让写入数据性能更好。
为了验证批量比单条写入更快,下面通过代码简单验证:
import time
import chromadb
import numpy as np
from chromadb.api import CreateCollectionConfiguration
from chromadb.api.collection_configuration import CreateHNSWConfiguration
client = chromadb.EphemeralClient()
# 上文用到的定义,直接搬过来,保证这段能独立跑
col = client.get_or_create_collection(
"bench", embedding_function=None,
configuration=CreateCollectionConfiguration(
hnsw=CreateHNSWConfiguration(
space="cosine",
ef_search=100,
)
)
)
# 指定向量维度和样本数量
D, N = 384,2000
# 固定随机种子,保证每次运行生成的向量完全一致
rng = np.random.default_rng(42)
# 模拟生成向量数据,L2归一化向量
X = (rng.normal(scale=0.6, size=(N, D))).astype(np.float32)
X /= np.linalg.norm(X, axis=1, keepdims=True)
# 模拟生成文档数据
docs = [f"文档内容 {i} " + "补充文字" * 20 for i in range(N)]
# 模拟生成文档ID
ids = [f"i{i}" for i in range(N)]
# 慢:一条一条写
t0 = time.perf_counter()
for i in range(len(ids)):
col.add(ids=[ids[i]], embeddings=[X[i]], documents=[docs[i]])
print(f"一条一条写:{time.perf_counter() - t0:.2f}s")
# 快:分批写
t0 = time.perf_counter()
for start in range(0, len(ids), 500):
end = start + 500
col.add(ids=ids[start:end], embeddings=X[start:end], documents=docs[start:end])
print(f"分批写:{time.perf_counter() - t0:.2f}s")运行代码,输出如下:
一条一条写:70.19s
分批写:0.44s注意,批次大小的经验值:
| 场景 | 建议批次 |
| 本地 PersistentClient | 500 ~ 2000 |
| HttpClient(同机房) | 200 ~ 1000 |
| HttpClient(跨公网) | 100 ~ 500 |
上限受 CHROMA_MAX_PAYLOAD_SIZE_BYTES(默认 40 MiB)约束。1536 维的话,1000 条就是 6 MB 左右,加上文档很快就到上限了。
前面章已经说过,这里再强调:自己算好传进去,速度能快一个数量级,还能并行和缓存。
from concurrent.futures import ThreadPoolExecutor
def embed_parallel(embedder, texts, batch_size=64, workers=4):
"""
多线程并行计算 embedding
适合网络IO型的Embedding服务(远程HTTP接口、OpenAI/BGE在线API);
CPU本地模型一般收益有限,容易被GIL限制
:param embedder: 向量化函数,签名要求:接收文本列表list[str],
返回向量列表list[list[float]]
:param texts: 全部待向量化的原始文本列表
:param batch_size: 每个子批次的文本数量,传给embedder的单批大小
:param workers: 线程池最大并发数,控制同时发起多少个请求
:return: 一维展开的向量列表,顺序和输入texts完全保持一致
"""
# 把全部文本切分成多个小批次,每一批最多batch_size条
batches = [texts[i:i + batch_size] for i in range(0, len(texts), batch_size)]
# 开启线程池,max_workers控制并发;with语句会自动等待全部任务完成、自动释放线程
with ThreadPoolExecutor(max_workers=workers) as ex:
# map:把每个batch交给embedder执行,返回结果顺序和batches顺序一一对应
results = list(ex.map(embedder, batches))
# 把每个批次的向量结果扁平化合并,还原成和输入文本一一对应的一维列表
return [v for r in results for v in r]sync_threshold 控制累计新增多少条向量之后,把内存里的 HNSW 图索引持久化刷到磁盘,调大减少磁盘刷写次数,大批量导入速度更快:
col.modify(configuration={"hnsw": {"sync_threshold": 100_000, "batch_size": 1000}})
# ... 灌数据 ...
col.modify(configuration={"hnsw": {"sync_threshold": 1000, "batch_size": 100}})不过我实测下来(20000 条),这个改动带来的差异不大(20.29s vs 20.79s,噪音范围内)。数据量更大、维度更高时差异才会显现。
实现一个简单的缓存,key 为文本 md5 摘要,value 为向量
import hashlib
from chromadb.utils.embedding_functions import OllamaEmbeddingFunction
class CachedEmbedder:
"""
包装原有 Embedding 函数,增加文本向量缓存
相同文本只计算一次向量,重复文本直接走缓存,减少 LLM/Embedding 服务调用、节省耗时与token
"""
def __init__(self, inner, max_size=100_000):
"""
:param inner: 原始的 embedding 函数,签名必须是
func(texts: list[str]) -> list[list[float]]
:param max_size: 缓存字典最大容量,避免无限膨胀撑爆内存
"""
self.inner = inner
# 缓存字典:key=文本md5摘要,value=对应的向量
self.cache: dict[str, list[float]] = {}
self.max_size = max_size
def __call__(self, texts: list[str]) -> list[list[float]]:
"""
支持批量文本向量化,自动命中缓存 / 计算缺失向量
:param texts: 一批待向量化的文本列表
:return: 和输入顺序一一对应的向量列表
"""
# 预分配结果容器,保证输出顺序和输入完全对齐
out = [None] * len(texts)
# 记录需要计算向量的文本、以及它在原始列表中的下标
missing, missing_idx = [], []
for i, t in enumerate(texts):
# 对文本做md5摘要,作为缓存key;相比直接存长文本做key更省内存
key = hashlib.md5(t.encode()).hexdigest()
if key in self.cache:
# 缓存命中,直接读取向量放入结果对应位置
out[i] = self.cache[key]
else:
# 缓存未命中,加入待计算队列
missing.append(t)
missing_idx.append(i)
# 如果存在需要新计算的文本,调用底层 embedding 函数批量计算
if missing:
vecs = self.inner(missing)
# 遍历:下标、原文、新向量,回填结果并写入缓存
for i, t, v in zip(missing_idx, missing, vecs):
key = hashlib.md5(t.encode()).hexdigest()
# 简单策略:缓存没到上限才写入;超过上限直接丢弃,不淘汰旧key
if len(self.cache) < self.max_size:
self.cache[key] = v
out[i] = v
return out
if __name__ == "__main__":
# 真实环境,用 Ollama 的 bge-m3 模型(先在 ollama 里 pull 并启动服务)
ef = OllamaEmbeddingFunction(
url="http://localhost:11434",
model_name="bge-m3",
timeout=60,
)
def fake_embed(texts):
print(f"fake_embed texts={texts}")
return ef(texts)
# 用 CachedEmbedder 包装原始 embedding 函数
embedder = CachedEmbedder(fake_embed)
# 第一次调用:5 条全新文本,全部走底层计算
docs = ["如何退款", "发票怎么开", "物流多久到", "会员权益", "修改收货地址"]
vecs1 = embedder(docs)
# 第二次调用:包含 3 条重复文本 + 1 条新文本
# 重复文本命中缓存,只有新文本会触发底层计算
docs2 = ["如何退款", "物流多久到", "发货时间", "发票怎么开"]
vecs2 = embedder(docs2)运行代码,测试效果:
fake_embed texts=['如何退款', '发票怎么开', '物流多久到', '会员权益', '修改收货地址']
fake_embed texts=['发货时间']可以看见,fake_embed() 被调用了两次,第一次计算了五个文本的向量,第二次仅计算了一个文本的向量,因为有三个是重复的。如果你的知识库里有大量重复内容(比如模板化的文档)时,这个缓存能省很多时间。