很多 RAG 教程讲到"加载文档---切分---向量化---写入向量库"就结束了。这个流程适合第一次建库,却没有回答知识库上线后更常见的问题:
- 同一个目录每天同步一次,会不会重复入库?
- 文件修改后,旧切片是否还留在向量库?
- 文档从 20 个切片缩短到 12 个,后 8 个怎样清理?
- 源文件被删除后,怎样证明向量和元数据都已删除?
- 同步中途崩溃,下次运行能否自动恢复?
如果这些问题没有明确答案,检索结果中就可能同时出现新旧版本。模型最终引用了旧条款、旧产品说明或过期非遗资料时,单纯调整 Prompt 并不能解决根因。
本文实现一个小型但完整的同步器:Python 负责计算内容指纹和同步计划,SQLite 保存同步清单,ChromaDB 保存切片。重点不是某个向量库 API,而是一套可以迁移到其他存储的对账协议。
1. add 不是知识库同步
最直接的入库代码通常是:
python
collection.add(
ids=chunk_ids,
documents=chunks,
metadatas=metadatas,
)
它表达的是一次写入动作,不是"让向量库最终与源文件一致"。
同步需要先定义期望状态:对于文档 docs/a.md,当前应该有哪些切片 ID、每个切片属于哪个版本,以及旧版本中哪些 ID 已经不应存在。然后把向量库的实际状态调整到这个期望状态。
可以把它理解成:
text
源文件当前状态
↓
计算期望的切片集合
↓
读取向量库实际集合
↓
upsert 期望记录 + delete 多余记录
↓
重新读取并核对
↓
最后提交同步清单
这与"再执行一次入库脚本"有本质区别。
2. 先区分三个容易混淆的标识
一个可维护的索引至少需要三类标识。
2.1 doc_id:文档是谁
doc_id 表示业务身份,而不是某次上传生成的随机 UUID。例如:
text
laws/civil-code.md
heritage/suzhou-embroidery.md
course/python/week-03.md
同一份文档内容改变后,doc_id 仍然不变。路径可能移动的系统,可以改用数据库主键或对象存储中的稳定键。
需要注意:craft_name、文件显示名和数据库主键不一定是同一个概念。项目中已有稳定主键时,应直接沿用,不要临时拿名称代替身份。
2.2 content_hash:文档现在是什么版本
对规范化后的文本计算 SHA-256:
python
import hashlib
def sha256_text(text: str) -> str:
return hashlib.sha256(text.encode("utf-8")).hexdigest()
哈希相同,可以进入快速跳过路径;哈希不同,说明至少需要重新对账。它不是法律意义上的版本号,但很适合判断内容是否变化。
2.3 chunk_id:向量库中的记录是谁
本文使用"文档身份哈希 + 切片序号"生成稳定 ID:
python
def chunk_id(doc_id: str, index: int) -> str:
prefix = hashlib.sha256(doc_id.encode("utf-8")).hexdigest()
return f"{prefix}:{index:06d}"
文档第二次同步时,相同位置的切片仍使用同一个 ID,upsert 会覆盖其文本、向量和元数据;如果切片数量减少,多出来的旧 ID 会被显式删除。
这种策略简单、可解释,但也有代价:文档开头插入内容后,后续切片位置可能整体变化,需要重新向量化。大规模系统可以进一步做内容感知切分和切片级哈希复用,第一版不必同时解决所有优化问题。
Chroma 的数据模型中,每条记录本身就包含唯一 ID、向量、可选元数据和文档;文档 ID 的具体语义由应用决定。官方文档也提醒,Chroma 不能通过复合 ID 的一部分进行查询,所以本文另外把 doc_id 放进 metadata,用它查询一份文档的全部记录。Chroma 数据模型|Document IDs
3. SQLite 清单不是第二个向量库
同步清单只保存每份文档最后一次成功提交的状态:
sql
CREATE TABLE documents (
doc_id TEXT PRIMARY KEY,
content_hash TEXT NOT NULL,
chunk_ids_json TEXT NOT NULL,
synced_at TEXT NOT NULL
);
它有三个作用:
- 内容未变化时快速跳过;
- 记录一次成功同步包含哪些切片;
- 为排错和审计提供时间与版本信息。
但不能只相信清单。进程可能在写完 Chroma、提交 SQLite 之前崩溃,也可能有人绕过同步器直接改动向量库。因此每次更新和删除的最终判断,都要重新读取 Chroma 中该 doc_id 的实际 ID 集合。
换句话说:
text
Manifest = 加速与审计
Chroma 实际记录 = 必须对账的外部状态
源文件 = 期望状态的来源
4. 把 Chroma 接到同步器
安装并创建本地持久化集合:
powershell
python -m pip install chromadb
python
import chromadb
client = chromadb.PersistentClient(path="./chroma_data")
collection = client.get_or_create_collection("knowledge_base")
Chroma 官方文档将 PersistentClient 定位为本地开发与测试方式;生产环境更适合服务端部署并使用 HttpClient 或 AsyncHttpClient。不要因为示例能在本机持久化,就直接把同一进程架构当作生产方案。Chroma Python Client
下面定义同步器所需的最小接口:
python
from typing import Any, Protocol
class CollectionLike(Protocol):
def upsert(
self,
*,
ids: list[str],
documents: list[str],
metadatas: list[dict[str, Any]],
) -> Any: ...
def get(
self,
*,
where: dict[str, Any],
include: list[str],
) -> dict[str, Any]: ...
def delete(self, *, ids: list[str]) -> Any: ...
使用协议而不是在业务逻辑里到处直接调用 Chroma,有两个好处:同步算法可以单元测试,以后切换为其他向量库时也更容易替换适配层。
5. 核心同步算法:先写新状态,再清旧状态
为了突出同步流程,示例使用固定字符数切片:
python
def split_text(text: str, chunk_size: int = 500) -> list[str]:
if chunk_size <= 0:
raise ValueError("chunk_size must be positive")
normalized = text.replace("\r\n", "\n").strip()
if not normalized:
return []
return [
normalized[i:i + chunk_size]
for i in range(0, len(normalized), chunk_size)
]
生产项目应替换成现有的标题、段落或语义切分器。切分算法本身也应带版本,例如 splitter_version=v2;算法改变时,即使原文没变,也应触发重建。
同步的关键代码如下:
python
from dataclasses import dataclass
@dataclass(frozen=True)
class SourceDocument:
doc_id: str
text: str
class DocumentSynchronizer:
def __init__(self, collection, manifest):
self.collection = collection
self.manifest = manifest
def _ids_in_store(self, doc_id: str) -> set[str]:
result = self.collection.get(
where={"doc_id": doc_id},
include=[],
)
return set(result.get("ids", []))
def sync(self, document: SourceDocument, chunk_size: int = 500):
content_hash = sha256_text(document.text)
previous = self.manifest.get(document.doc_id)
# 快速路径也检查一次实际 ID,避免清单与向量库已经漂移
if previous and previous["content_hash"] == content_hash:
expected = set(previous["chunk_ids"])
if self._ids_in_store(document.doc_id) == expected:
return {"action": "unchanged"}
chunks = split_text(document.text, chunk_size)
desired_ids = [
chunk_id(document.doc_id, i)
for i in range(len(chunks))
]
desired_set = set(desired_ids)
old_ids = self._ids_in_store(document.doc_id)
if desired_ids:
self.collection.upsert(
ids=desired_ids,
documents=chunks,
metadatas=[
{
"doc_id": document.doc_id,
"content_hash": content_hash,
"chunk_index": i,
}
for i in range(len(chunks))
],
)
stale_ids = sorted(old_ids - desired_set)
if stale_ids:
self.collection.delete(ids=stale_ids)
actual_ids = self._ids_in_store(document.doc_id)
if actual_ids != desired_set:
raise RuntimeError(
"vector-store verification failed: "
f"expected={desired_set}, actual={actual_ids}"
)
# 只有外部状态验证通过,才提交清单
self.manifest.commit_document(
document.doc_id,
content_hash,
desired_ids,
)
return {
"action": "updated" if previous else "created",
"upserted": len(desired_ids),
"deleted": len(stale_ids),
}
Chroma 官方 API 将 upsert、get、delete 都作为 collection 级操作;where 可以按 metadata 过滤记录。Chroma Core API|Metadata Filters
这个算法有四个重要细节。
5.1 使用 upsert,让重复执行收敛到同一状态
同一批稳定 ID 重复写入不会生成第二套记录,而是覆盖对应 ID。幂等性不是"脚本保证只运行一次",而是"即使重复运行,结果仍然一致"。
5.2 先写期望记录,再删除多余记录
更新文档时先写入当前版本,再清理旧尾部,可以缩短"文档完全不可检索"的时间。但 Chroma 与 SQLite 之间没有跨系统事务,因此这仍不是严格原子更新。
5.3 删除集合差,而不是猜测旧切片数量
python
stale_ids = old_ids - desired_ids
文档从 20 个切片缩短到 12 个时,集合差精确给出需要删除的 8 个 ID。不要使用"覆盖前 12 个就算更新完成"的做法。
5.4 清单最后提交
只有 actual_ids == desired_ids,SQLite 才记录新版本。下次运行看到的"已同步",至少对应上一次经过集合校验的状态。
6. 为什么中途崩溃后还能重试
假设更新过程在不同位置中断:
| 中断位置 | 可能状态 | 下次同步怎样处理 |
|---|---|---|
upsert 前 |
仍是旧版本 | 重新执行全部步骤 |
upsert 后、删除前 |
新记录已写,旧尾部仍在 | 相同 ID 再次 upsert,并重新计算集合差 |
| 删除后、清单提交前 | 向量库已是新状态,清单仍是旧状态 | 重新对账,覆盖相同 ID,再提交清单 |
| 清单提交后 | 三方一致 | 快速校验后跳过 |
恢复能力来自三个条件:
- ID 是确定性的;
- 写入使用幂等
upsert; - 每次都从实际记录重新计算差异。
这不是完整的分布式事务。如果两个同步进程同时修改同一个 doc_id,仍可能互相覆盖。生产环境应为文档或知识库增加互斥锁、任务租约或单写队列。
7. 删除也必须是一个可验证操作
源文件消失时,不应只从 SQLite 清单删除一行:
python
def delete_document(self, doc_id: str):
old_ids = self._ids_in_store(doc_id)
if old_ids:
self.collection.delete(ids=sorted(old_ids))
remaining = self._ids_in_store(doc_id)
if remaining:
raise RuntimeError(f"delete verification failed: {remaining}")
self.manifest.remove(doc_id)
return {
"action": "deleted",
"deleted": len(old_ids),
}
顺序仍然是:删除向量记录、读取验证、最后删除清单。Chroma 文档说明,collection 的 delete 会永久移除对应记录的向量、文档和元数据,因此执行前必须把目标范围限制到精确 ID,并保留源数据或备份。Chroma Collections
如果系统需要软删除,可以先把业务数据库中的状态改为 inactive,检索时使用 metadata 过滤;后台确认后再物理删除。这样更容易撤销,但要确保每条查询都带上状态过滤条件。
8. 用四个测试守住同步不变量
我没有在测试中加载真实嵌入模型,而是实现了一个内存版 collection。它遵循相同的 upsert/get/delete 接口,用来验证同步状态机:
python
class InMemoryCollection:
def __init__(self):
self.rows = {}
def upsert(self, *, ids, documents, metadatas):
for row_id, document, metadata in zip(
ids, documents, metadatas
):
self.rows[row_id] = {
"document": document,
"metadata": metadata,
}
def get(self, *, where, include):
ids = [
row_id
for row_id, row in self.rows.items()
if all(
row["metadata"].get(key) == value
for key, value in where.items()
)
]
return {"ids": sorted(ids)}
def delete(self, *, ids):
for row_id in ids:
self.rows.pop(row_id, None)
4 个核心单元测试方法覆盖 5 个行为:
- 首次同步正确创建切片;
- 相同文档重复同步不会增加记录;
- 文档缩短后,多余尾部切片被删除;
- 人为删掉一条向量记录后,再次同步能修复缺失项;
- 删除文档后,内存向量库和清单都没有残留。
此外,我在 Python 3.13.7、ChromaDB 1.5.1 下增加了 1 个持久化集成测试,使用确定性的三维测试嵌入依次执行首次创建、内容缩短、关闭后重新连接和精确删除。4 个单元测试与 1 个集成测试全部通过;合并运行耗时约 1 秒。
测试嵌入只为避免下载模型并稳定复现,不代表 BGE-M3 的向量质量。上述结果也不代表服务端部署、并发写入或大规模数据性能已经通过验证。
真实项目还应增加两类集成测试:
- 使用项目锁定版本的 Chroma,检查 API 和持久化重启;
- 使用实际嵌入模型,更新文档后查询旧关键词,确认旧内容不再被召回。
第二类测试尤其重要。ID 集合正确只能证明记录数量和归属正确,不能证明检索质量正确。
9. 批量同步目录时怎样发现删除
单文档同步完成后,目录同步可以按下面的方式组织:
text
扫描源目录得到 current_doc_ids
读取 manifest 得到 known_doc_ids
for doc in 当前源文件:
sync(doc)
for doc_id in known_doc_ids - current_doc_ids:
delete_document(doc_id)
扫描时应明确:
- 哪些扩展名进入知识库;
- 是否忽略临时文件和隐藏目录;
- 路径大小写怎样规范化;
- 文件读取失败时,是终止整批任务还是保留上次版本;
- 空文件表示"删除所有切片",还是数据异常。
我更倾向于:读取失败时保留旧版本并报警,不把"本次没有成功读到"误判成"用户要求删除"。只有明确确认源对象不存在,才进入删除流程。
10. 上生产前还要补哪些边界
本文代码刻意只实现核心协议。接入真实系统时,至少还要补齐以下内容。
10.1 把处理配置纳入版本
文档内容没变,但切分器、清洗器、嵌入模型发生变化时,旧索引也需要更新。可以计算:
text
index_version = hash(
content_hash,
parser_version,
splitter_version,
embedding_model,
embedding_dimension
)
BGE-M3 的模型路径相同也不一定代表处理配置相同;归一化、最大长度和 pooling 方式都应写进可审计配置。
10.2 分批写入并记录进度
大文档不要一次提交所有切片。应读取向量库允许的最大批次,分批 upsert,每批失败可重试。Chroma Python Client 暴露了获取最大批次大小的方法,生产代码不应把批量值永久写死。Chroma Python Client
10.3 同步和查询之间确定一致性策略
更新过程中,查询可能看到部分新状态。严格场景可以采用"双版本 + active_version"切换:先完整写入新版本,验证后原子地把业务侧活动版本从 v1 指向 v2,再异步清理 v1。
代价是临时占用双份存储,而且所有查询必须带版本过滤。对于法律条文或需要审计的知识库,这个代价往往值得;普通个人知识库可以先使用本文的单版本对账。
10.4 不要只记录成功日志
每轮同步至少记录:
text
run_id
doc_id
old_hash / new_hash
expected_chunks / actual_chunks
upserted / deleted
started_at / finished_at
error
有了结构化日志,才能回答"这条旧内容什么时候进入向量库、哪次任务应该删除它、删除是否验证通过"。
10.5 定期做全量对账
增量同步保证每次操作尽量正确,全量对账负责发现长期漂移。可以定期检查:
- manifest 中存在、源目录不存在的文档;
- Chroma 中存在、manifest 不存在的
doc_id; - 实际切片 ID 与清单不一致的文档;
- metadata 中的模型版本与当前配置不一致的记录。
发现异常后先输出报告,再决定自动修复。不要让"对账脚本"默认拥有无范围限制的删除权限。
11. 放到 RAG 项目里,职责应该怎样拆
建议把索引流程拆为五层:
text
SourceLoader 读取文件、数据库或对象存储
Parser 提取并规范化正文
Chunker 生成确定性的切片序列
VectorStoreAdapter 封装 Chroma 的读写删
IndexSynchronizer 计算差异、验证并提交清单
这样排查问题时可以先定位层次:
- 原文没有读到:Loader 问题;
- 标题或条款结构丢失:Parser 问题;
- 召回片段语义破碎:Chunker 问题;
- 记录数量不一致:Adapter 或同步协议问题;
- 旧记录未清理:Synchronizer 问题。
对 HeritageMind,可以用稳定的非遗项目主键作为 doc_id,不要混用技艺名称;对 LexRAG,可以把法规、编章条和数据版本放入 metadata;对 EduTutor,可以把课程资料的拥有者与访问范围一并写入过滤字段。这里只是迁移建议,并不表示这些项目已经完成上述改造。
结语
RAG 知识库真正难维护的部分,不是第一次把文本变成向量,而是让源数据、向量记录和版本清单长期保持一致。
一套最小可靠方案可以概括为:
text
稳定 doc_id 确认身份
内容哈希判断版本
确定性 chunk_id 支持幂等写入
集合差清理残留
读后校验确认结果
最后提交 manifest
定期全量对账发现漂移
做到这些之后,"重新跑一遍索引脚本"才不再是一场赌博,而是一次可以解释、验证和恢复的同步操作。