第 4 章:入库:幂等、增量与版本
全量重灌是最省事的做法,但文档库一大,它就从"省事"变成"每天跑四十分钟"。
学习目标
- 写出幂等的片段 id,重复灌库不会产生两份
- 用文件指纹做增量更新,只处理变化的文档
- 会按
doc_id精确删除一份文档的全部片段 - 换 embedding 模型时能不停机地重建
4.1 建集合的三件事没变
向量库课的第 2、3 章已经讲过:维度对齐、距离度量、集合名带模型版本。这里只重复一句最要紧的——
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 决定了"重复灌库"是幂等还是翻倍。
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 增量更新:先比指纹
思路很简单:内容没变的文档,不重新切、不重新算向量。
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 | 读一遍文件 | 要求严格、文件不多 |
把指纹存到一个小状态文件里:
{ "manual_a100.pdf": "9f3c1a2b7d4e5f60", "faq.md": "1a2b3c4d5e6f7081" }state = load_state("./ingest_state.json")
changed = [p for p in all_files if state.get(p) != fingerprint(p)]只对 changed 跑"解析 → 切分 → embedding → upsert"。
4.4 删除:按 doc_id 过滤删
文档被删或改名时,旧片段必须清掉,否则会和新内容一起被召回——这是"答非所问"的常见来源。
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 项目里要额外做一件事:把"当前集合名"放进配置,而不是到处写死。
# config.py
QDRANT_COLLECTION = "docs__bge_small_zh_v15"
EMBED_MODEL = "BAAI/bge-small-zh-v1.5"这样重建时改两行配置,重启服务即可切换。
4.6 批量写入的姿势
| 做法 | 结果 |
|---|---|
| 一条一条 upsert | 慢到不可用 |
一次 100–500 条,wait=False | 吞吐最高 |
| 一次几万条 | 请求体过大、超时 |
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 入库后的对账
灌完一定要核一下数:
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。
本章小结
| 要点 | 说明 |
|---|---|
| 幂等 id | uuid5(doc_id:idx),重复灌不翻倍 |
| 增量 | 文件指纹对比,只处理变化的 |
| 指纹时机 | 写库成功后再更新状态 |
| 删除 | 按 doc_id 过滤删,前提是建了索引 |
| 版本 | 新集合 + 配置化集合名 |
| 批量 | 100–500 条一批,末尾 wait=True |
| 对账 | 点数与本地切分数量对比 |
下一章
库里有东西了,下一章讲怎么把它"准确地找出来":稠密、关键词、过滤三路怎么配,以及怎么量召回率。