RAG 知识库更新实战:增量索引、版本控制与可验证删除

很多 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
);

它有三个作用:

  1. 内容未变化时快速跳过;
  2. 记录一次成功同步包含哪些切片;
  3. 为排错和审计提供时间与版本信息。

但不能只相信清单。进程可能在写完 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 个行为:

  1. 首次同步正确创建切片;
  2. 相同文档重复同步不会增加记录;
  3. 文档缩短后,多余尾部切片被删除;
  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
定期全量对账发现漂移

做到这些之后,"重新跑一遍索引脚本"才不再是一场赌博,而是一次可以解释、验证和恢复的同步操作。

参考资料

相关推荐
钱栈up36 分钟前
IDEA 一天冻死两次:顺着线程 dump 揪出 JRebel,再用 DCEVM 把它替掉
jvm·agent·intellij idea
文谦南宁AI普工42 分钟前
把 eval 做成发布门禁:配对检验 + 三档判定,一个不到 200 行的纯标准库实现
agent·ai编程·产品
fishfinal1 小时前
VitePress 架构重构实录:拒绝扁平与耦合,重构你的独立文档项目
后端
Java内核笔记1 小时前
方法级 trace 看不出第几轮:给 Agent 补一层轮次维度
人工智能·spring boot·后端
数据库小学妹1 小时前
数据库容量规划:四个数与扩容触发线
运维·数据库·后端
AAA修煤气灶刘哥1 小时前
DSH Super-agent 双层架构:如何兼顾后台执行与持续响应
人工智能·后端·设计模式
泡海椒1 小时前
jquick-pdf 资源使用率报表模板:政务云集群水位的图表版与表格版怎么选
后端
用户5080070546281 小时前
1元机器到手后,我拿它跑了一套微服务测试环境
后端
郭生1 小时前
dedecms等php类cms静态生成速度慢或超时原因及解决方法
后端