WeClaw_73｜向量库重建实战：维度变更、10000 字符截断陷阱与文件锁

第五季系列文章第 4 篇（总第 73 篇） - 向量库全量重建 · content_text 截断陷阱 · ChromaDB 文件锁 · git stash 对照归因 · 备份回滚设计

📚 专栏信息

《从零到一构建跨平台 AI 助手：WeClaw 实战指南》专栏 · 第五季

专栏定位：面向开发者和技术决策者的实战专栏，用真实案例和完整代码带你理解如何构建生产级 AI 应用

本文是嵌入模型替换三部曲的收官篇：模型选好了（第 71 篇）、召回缺陷修了（第 72 篇），还剩最脏最累的活——把两个生产向量库从 384 维全量重建到 768 维。这一路踩到的坑比预想的多：入库时被悄悄截断的 content_text、被主程序锁死的 ChromaDB 文件、凭想象写出来的错误接口、以及 pytest 里 12 个"疑似被我搞坏"的用例。但也有意外之喜：重建后知识库的 chunk 数从 381 暴涨到 1311——丢失已久的内容被找了回来。

👨‍💻 作者与项目

作者简介：翁勇刚 WENG YONGGANG 新概念龙虾-WeClaw 开发团队负责人，一群专注于跨平台 AI 应用的实践者理念："再复杂的技术，也能用代码讲清楚"

💻 项目地址：https://github.com/wyg5208/weclaw.git
🌐 官网地址：https://weclaw.link
📝 作者 CSDN：https://blog.csdn.net/yweng18
⭐ 欢迎 Star⭐、Fork🍴、贡献代码🤝

📝 摘要

本文结构概览：维度变更为什么没有增量迁移的余地 → 重建脚本的设计（备份、口径对齐、自检）→ 三个实战坑（内容截断、文件锁、接口想当然）→ 重建结果与意外收获 → 用 git stash 对照法给 12 个 pytest 失败用例定责。

核心问题：嵌入模型从 384 维换到 768 维，旧向量全部作废；重建不是"把库删了重跑"一句话——数据源哪里来、口径怎么对齐、失败怎么回滚、结果怎么验证，每一步都有暗礁。

关键成果：

一个可复用的重建脚本设计：--experience/--knowledge/--all + 自动 .bak 备份 + 抽样自检
发现并绕开 content_text 入库 10000 字符截断陷阱：从原始文件重新解析，chunk 数 381 → 1311
ChromaDB 文件锁排障：重建必须在主程序关闭状态下执行
git stash 对照归因法：3 failed + 9 errors 实证为既存问题，与本次改动无关

适合读者：维护生产向量库 / RAG 系统的工程师；需要做"数据重建 + 回归定责"的所有人

阅读时长：约 13 分钟

关键词：ChromaDB、向量库重建、维度变更、数据截断、文件锁、git stash、回归测试

一、为什么必须全量重建？

嵌入模型从 all-MiniLM-L6-v2（384 维）切到 bge-base-zh-v1.5（768 维），旧向量库的处境很简单：一个字节都不能留。

维度对不上：ChromaDB collection 的维度在首次写入时固化，768 维查询向量打 384 维索引直接报错；
语义空间对不上：就算维度侥幸相同，两个模型的向量空间也毫无对应关系，新 query 向量在旧空间里检索出来的是纯噪声。

所以没有"增量迁移"这个选项，只有全量重建。WeClaw 有两个库要重建：

库	向量目录	数据源（真相所在）	规模
经验库	`~/.weclaw/experience_vectors`	SQLite `experiences.db`	169 条
知识库	`~/.weclaw/chroma_db`	SQLite `weclaw_rag.db` + 原始文件	32 篇文档

好消息是：SQLite 元数据库全程不动。向量库在这套架构里是纯派生数据（derived data），真相永远在 SQLite 和原始文件里——这是当初混合存储设计留下的最大红利：派生数据可以随时炸掉重建，不心疼。

二、重建脚本的三个设计要点

新建 scripts/rebuild_vector_stores.py，257 行，三个设计要点。

2.1 先备份，再动手

def _backup_dir(target: Path) -> Path | None:
    """重建前把旧向量目录整体改名为 .bak，失败可秒级还原。"""
    if not target.exists():
        return None
    bak = target.with_name(target.name + ".bak")
    if bak.exists():
        shutil.rmtree(bak)   # 只保留最近一份备份
    target.rename(bak)
    return bak

回滚路径因此极短：改回 DEFAULT_MODEL 一行 + 把 .bak 目录改回原名，两分钟内可退回改动前状态。重建类操作的第一原则：先给自己留好退路，再删东西。

2.2 口径与生产代码逐字对齐

重建最隐蔽的失败模式不是报错，而是悄悄用了和生产不一致的口径——文本拼接顺序不同、metadata 少个字段、id 规则不同，重建"成功"了，线上召回却对不上号。

经验库的入库口径直接从 ExperienceStore.record 抄写：

# 与 ExperienceStore.record 完全一致的口径
text = f"{r[1]} {r[2]} {r[3]} {r[4]}"      # trigger diagnosis fix_summary abstract_pattern
chroma_id = f"exp_{r[0]}"                   # exp_{id}
metadata = {
    "experience_id": r[0],
    "outcome": r[5],
    "source_type": r[6],
    "created_at": r[7],
}

知识库同理：分块器用生产同款 TextSplitter(chunk_size=1000, chunk_overlap=100)，metadata 按 knowledge_rag._add_document 现行字段（doc_id/filename/file_type/chunk_index），并同步回写 chunk_count。

2.3 重建完自己考自己

脚本末尾内置 self_check()：随机抽 3 条真实 query 打刚建好的库，检索非空才算通过。这一步成本 5 秒，能当场拦住"建完了但根本查不到东西"级别的低级灾难。

三、三个实战坑

3.1 坑一：content_text 的 10000 字符暗桩

知识库重建最初的思路很自然：rag_documents 表里有 content_text 字段，直接读出来重新分块编码就行。

动手前核对入库代码时，一行代码让计划急转弯：

# knowledge_rag._add_document 入库时——
content_text=parse_result.content[:10000],   # ← 只存了前 10000 字符！

content_text 在入库时被截断到 10000 字符。一篇 40KB 的英文论文，SQLite 里只躺着前四分之一。如果照原计划用它重建，等于把截断固化成永久损失——而且不会有任何报错。

正确姿势：优先从 stored_path 指向的原始文件重新解析，文件缺失才降级回 content_text 并告警：

def _load_doc_text(row) -> tuple[str, str]:
    stored = Path(row["stored_path"] or "")
    if stored.exists():
        result = DocumentParser().parse(str(stored))   # 生产同款解析器（含 OCR）
        if result and result.content:
            return result.content, "reparsed"
    logger.warning("原始文件缺失，回退截断的 content_text: %s", row["filename"])
    return row["content_text"] or "", "fallback"

重建结果验证了这个决策的价值：旧库 381 chunk → 新库 1311 chunk。多出来的 900+ chunk 就是历年被 [:10000] 吃掉的内容——这次重建顺手把它们全部找了回来。32 篇文档中 17 篇成功重解析，15 篇原始文件已缺失（按预案回退 + 告警）。

教训一句话：重建的数据源永远选"最上游的真相"。派生字段（尤其是入库时做过截断/清洗/摘要的）只能当降级备胎。

3.2 坑二：ChromaDB 的文件锁

脚本第一次运行，当头一个：

PermissionError: [WinError 32] 另一个程序正在使用此文件，进程无法访问。
  ...\experience_vectors\...\data_level0.bin

排查发现 WeClaw 主程序正在运行——它启动时初始化了 ExperienceStore，ChromaDB 的 PersistentClient 持有着 data_level0.bin 的文件句柄。Windows 下这类句柄是硬锁，备份时的 rename 直接被拒。

处理方式没有花活：请用户退出主程序，重跑成功。但这条要写进重建脚本的使用说明和文档里：

向量库重建必须在主程序关闭状态下执行。 任何持有 PersistentClient 的进程都会锁住向量文件。

更通用的教训：设计离线维护脚本时，第一个要问的问题是"谁在运行时持有这份数据"。数据库如此，向量库如此，甚至一个被 mmap 的模型文件也如此。

3.3 坑三：接口是核对出来的，不是想象出来的

脚本初稿里有两处凭"合理想象"写的调用：

dim = embedder.dimension          # ❌ 实际接口是 get_dimension()
hits = vs.search(text, top_k=3)   # ❌ 实际接口是 query(text, n_results=3)

两处都"看起来很像真的"——很多库确实叫 dimension 和 search。但这个项目里就是 get_dimension() 和 query()。写工具脚本时对项目内部接口的每一次"我记得是这样"，都值得花 30 秒 grep 确认，比跑起来报 AttributeError 再回头改快得多。

四、重建结果

库	结果	耗时
经验库	169 条向量（= SQLite 记录数 ✓）	3.0s（GPU）
知识库	32 篇 → 1311 条向量（旧库 381）	531.5s（含 OCR 重解析）

知识库的 8 分多钟里大头是 PDF 重解析和 OCR，真正的编码时间与第 71 篇的 CPU 实测预估（2~3 分钟量级）一致。抽样自检通过，端到端召回验证 15/15 = 100%（详见第 72 篇）。

五、最后一关：pytest 里的 12 个"疑犯"

改动收尾跑回归：test_experience_store / test_experience_e2e / test_knowledge_rag 三个文件，结果 35 passed，3 failed + 9 errors。

12 个红名单，是我改坏的吗？逐个读报错可以分析个大概（tool fixture 缺失、gui_app_v2.py 引用不存在……），但"看起来像既存问题"和"证明是既存问题"之间隔着一道举证责任。我们用了成本最低、说服力最高的办法——git stash 对照实验：

# 1. 把本次全部改动暂存，回到改动前的代码
git stash push -- src/core/experience_store.py src/core/rag/embedder.py src/core/rag/download_embedding_model.py

# 2. 在"未改动"的代码上跑同一组测试
pytest tests/test_experience_store.py tests/test_experience_e2e.py tests/test_knowledge_rag.py -s

# 3. 恢复改动
git stash pop

结果：改动前的代码上跑出完全相同的 failed/errors 清单。结论落地：三类失败全部是既存问题——test_knowledge_rag 缺 tool fixture、gui_app_v2.py 早已被重构移除、_ensure_store 增加懒加载兜底后旧测试的预期已过时。已记入遗留事项，另开任务修复，不与本次改动混淆。

这个方法值得固化成习惯：回归测试出现失败时，先在基线代码上复跑一遍再定责。它把"我认为不是我改坏的"变成"实证不是我改坏的"，无论对同事还是对三个月后的自己，都是完全不同等级的交代。

六、总结：重建类任务的操作框架

5 步框架：

1. 留退路   —— 自动备份，回滚路径 < 5 分钟
2. 找真相   —— 数据源选最上游（原始文件 > 派生字段）
3. 对口径   —— 文本构造 / id / metadata 与生产代码逐字对齐
4. 自验证   —— 脚本内置抽样自检 + 端到端召回验证
5. 严定责   —— 回归失败先跑基线对照，再下结论

3 个关键点：

派生数据可炸毁重建是架构红利，但前提是入库口径可复现、真相源头还在
入库时的截断/清洗是时间胶囊里的暗桩——重建时刻就是它们引爆的时刻，提前审计入库代码
文件锁、接口签名、测试基线，三样都不能靠想象，只能靠核对

互动环节

思考题：

如果 32 篇文档的原始文件全部缺失，只剩截断的 content_text，你会照常重建还是先做一轮"文档找回"？决策依据是什么？
你的系统里有哪些字段在入库时做过截断或有损清洗？如果明天要重建，它们会成为暗桩吗？

讨论话题：

"向量库是派生数据，随时可以重建"——你的项目敢这么说吗？如果不敢，缺的是哪一环？

系列回顾：嵌入模型替换三部曲

📖 第 71 篇：《嵌入模型不是玄学：四轮实证把 Hit@1 从 33% 拉到 93% 的完整决策过程》
📖 第 72 篇：《时间衰减的隐形杀手：离线评估 93%，上线为什么只有 80%？》
📖 第 73 篇（本文）：《向量库重建实战：维度变更、10000 字符截断陷阱与文件锁》