Skip to content

第 4 章:入库:幂等、增量与版本 ​

全量重灌是最省事的做法,但文档库一大,它就从"省事"变成"每天跑四十分钟"。


学习目标 ​

  • 写出幂等的片段 id,重复灌库不会产生两份
  • 用文件指纹做增量更新,只处理变化的文档
  • 会按 doc_id 精确删除一份文档的全部片段
  • 换 embedding 模型时能不停机地重建

4.1 建集合的三件事没变 ​

向量库课的第 2、3 章已经讲过:维度对齐、距离度量、集合名带模型版本。这里只重复一句最要紧的——

python
client.create_collection(
    collection_name="docs__bge_small_zh_v15",
    vectors_config=VectorParams(size=512, distance=Distance.COSINE),
)

RAG 场景多一个要求:给 doc_id 建 payload 索引。后面按文档删除时要靠它,不建索引删除会退化成扫描。


4.2 片段 id 必须可推导 ​

id 决定了"重复灌库"是幂等还是翻倍。

python
from uuid import uuid5, NAMESPACE_URL

def point_id(doc_id: str, idx: int) -> str:
    return str(uuid5(NAMESPACE_URL, f"{doc_id}:{idx}"))

同一份文档、同一个片段序号,永远得到同一个 id。Qdrant 的 upsert 遇到相同 id 是覆盖,不是追加。

不要用 uuid4() 随机 id——那是"每次灌库都多一份"的根源,而且很难发现,直到你看到点数翻倍。


4.3 增量更新:先比指纹 ​

思路很简单:内容没变的文档,不重新切、不重新算向量。

python
import hashlib, json, os

def fingerprint(path: str) -> str:
    h = hashlib.sha256()
    h.update(str(os.path.getsize(path)).encode())
    h.update(str(int(os.path.getmtime(path))).encode())
    return h.hexdigest()[:16]     # 便宜版:大小 + 修改时间

更严谨的是对文件内容做 hash(大文件会慢,但更准)。二选一:

方式成本适合
大小 + mtime极低日常增量,误判概率可接受
内容 sha256读一遍文件要求严格、文件不多

把指纹存到一个小状态文件里:

json
{ "manual_a100.pdf": "9f3c1a2b7d4e5f60", "faq.md": "1a2b3c4d5e6f7081" }
python
state = load_state("./ingest_state.json")
changed = [p for p in all_files if state.get(p) != fingerprint(p)]

只对 changed 跑"解析 → 切分 → embedding → upsert"。

每次跑,只处理"变过"的那几份扫描文档目录12 份 PDF + 30 份 md算指纹并对比状态sha256 / size+mtime变了吗?没变就跳过是先删旧片段再解析重切重算upsert(幂等 id)状态文件:{"a100.pdf": "9f3c…", "faq.md": "1a2b…"} ← 只记录"最后一次成功入库"的指纹关键细节:指纹要在写库成功之后再更新。先更新指纹、后写库,中途失败就永远补不上了。删除文档时也要同步删状态,否则下次运行会以为"它还是最新的"。

4.4 删除:按 doc_id 过滤删 ​

文档被删或改名时,旧片段必须清掉,否则会和新内容一起被召回——这是"答非所问"的常见来源。

python
from qdrant_client.models import FilterSelector, Filter, FieldCondition, MatchValue

def delete_doc(doc_id: str):
    client.delete(
        collection_name=COL,
        points_selector=FilterSelector(
            filter=Filter(must=[FieldCondition(key="doc_id", match=MatchValue(value=doc_id))]
        ),
        wait=True,
    )

前提是 doc_id 建了 payload 索引,且每个片段都写了 doc_id。

改文档时的顺序:先删旧片段 → 再解析入库。反过来的话,如果新版解析失败,库里的旧版也没了——但总比"新版旧版混着召回"好。


4.5 版本:换模型要重建 ​

换 embedding 模型的规则在向量库课讲过:新集合 + 别名切换。

RAG 项目里要额外做一件事:把"当前集合名"放进配置,而不是到处写死。

python
# config.py
QDRANT_COLLECTION = "docs__bge_small_zh_v15"
EMBED_MODEL = "BAAI/bge-small-zh-v1.5"

这样重建时改两行配置,重启服务即可切换。


4.6 批量写入的姿势 ​

做法结果
一条一条 upsert慢到不可用
一次 100–500 条,wait=False吞吐最高
一次几万条请求体过大、超时
python
def upsert_batched(points, batch=256):
    for i in range(0, len(points), batch):
        client.upsert(collection_name=COL, points=points[i:i+batch], wait=False)
    client.upsert(collection_name=COL, points=[], wait=True)   # 触发等待,确保落盘

最后那句空 upsert 是否可靠,取决于客户端版本,别照抄——稳妥做法是最后一批用 wait=True。


4.7 一个完整的 ingest ​


4.8 入库后的对账 ​

灌完一定要核一下数:

python
info = client.get_collection(COL)
print("总片段", info.points_count)

# 按 doc_id 抽样核对:每份文档的片段数是否与本地切分结果一致
for doc_id, expected in local_counts.items():
    got = client.count(COL, count_filter=Filter(
        must=[FieldCondition(key="doc_id", match=MatchValue(value=doc_id))]
    )).count
    if got != expected:
        print("不一致", doc_id, expected, got)

最常见的两个异常:

  • 数量翻倍 → id 不是幂等的;
  • 数量偏少 → 批量写入有批次失败,或 payload 里没写 doc_id。

本章小结 ​

要点说明
幂等 iduuid5(doc_id:idx),重复灌不翻倍
增量文件指纹对比,只处理变化的
指纹时机写库成功后再更新状态
删除按 doc_id 过滤删,前提是建了索引
版本新集合 + 配置化集合名
批量100–500 条一批,末尾 wait=True
对账点数与本地切分数量对比

下一章 ​

库里有东西了,下一章讲怎么把它"准确地找出来":稠密、关键词、过滤三路怎么配,以及怎么量召回率。

本文阅读--次|全站访问--次|访客--人