语义搜索（向量索引）工具说明

给 wiki 的 8,000+ 原始语料建本地语义索引，支持"结合知识库"式查询。
构建于 2026-08-10，纯本地，无外部 API。

是什么

对 wiki/raw/articles/ 下全部 6,369 个可读 markdown 文件做分块 + 中文嵌入（BAAI/bge-small-zh-v1.5），存成 faiss 向量索引。查询时把问题嵌入后检索 top-k 相关文本块，返回文件路径 + 相似度 + 片段。

解决什么问题：Obsidian 全文搜索是关键词匹配；这套索引能按语义找到相关文件——比如搜"稳定币监管新进展"能命中没有出现"监管"字样的相关段落。

文件位置

文件	作用
`wiki/tools/build_vector_index.py`	构建主索引（含断点续跑，可重跑增量）
`wiki/tools/build_extract_index.py`	构建 extract 转换语料的独立索引（非 md 转出的 md，P0 起）
`wiki/tools/wiki_search.py`	查询工具（CLI，双索引自动合并）
`~/文档/区块链wiki-vectordb/`	向量库本体（vault 外，避免 Obsidian 索引臃肿）

双索引结构（2026-08-11 起）

主索引只编 raw/articles/ 下 md；非 md 语料转换出的 md（~/文档/区块链wiki-extract/，见 convert_nonmd.py）独立建 extract_flat.index，wiki_search.py 查询时双索引各自 top-k 再合并排序。extract 结果标记 extract，articles 结果标记 ●。新增转换文件后重跑 build_extract_index.py 重建小索引即可（几分钟），不碰主索引。

离线强制：三个脚本都设了 HF_HUB_OFFLINE=1——本机有模型缓存，若不设会联网检查 huggingface，在 Clash 代理环境下挂起（实测卡死 0% CPU）。模型只在缓存存在时可用。

使用

# 查询（top 8 结果，含相似度与片段）
python3 ~/文档/我的区块链wiki/wiki/tools/wiki_search.py "L2 扩容方案对比" --top 8

# 显示片段
python3 ~/文档/我的区块链wiki/wiki/tools/wiki_search.py "Celestia 数据可用性" --show-text

结果示例：

 1. [0.72]● blockchain/区块链研究/.../每日国外区块链发展动态回顾-2026年6月16至22日.md  (第12块)

● 标记该文件首次出现的命中；同文件后续命中用空格，便于看出"这个文件最相关"。

重建索引

# 全量重建（约 3-4 小时，CPU；支持中断后续跑）
python3 ~/文档/我的区块链wiki/wiki/tools/build_vector_index.py

# 参数
--chunk 600   # 分块字符数
--overlap 80  # 块间重叠
--out DIR     # 输出目录（默认 ~/文档/区块链wiki-vectordb）

断点续跑：中断后重跑同一条命令，自动检测已有 checkpoint，只处理未完成文件。建议新语料进库后每月重跑一次（增量）。

与工作流的关系

用户说 "结合知识库" 时，先跑 wiki_search.py 召回候选文件，再读文件精读，最后综合回答（符合 vault CLAUDE.md 的查询权限规则）。
向量召回是候选生成，不是结论——命中片段仍需回到原文核对（诚实声明：分块截断、个别片段可能脱离上下文）。

参数与限制（诚实声明）

模型 BAAI/bge-small-zh-v1.5（512 维，中文优化，本机缓存）。
分块 600 字符 + 80 重叠；约 6,369 文件 → 约 15-18 万块 → 索引约 550MB。
纯 CPU（本机无 GPU）：构建约 3-4 小时，查询 < 1 秒。
只索引 articles/ 下 .md；原始 PDF/docx 未索引——原 1,300+ 加密深度语料(白皮书/思想家/文章)已被用户删除(2026-08-11,整文件夹"区块链研究资料")，非 md 现存仅 512(书籍/融资项目 docx,已转 54 个)。现存加密 178 个"已转音频"残留无需转换。
失效路径过滤：主索引仍含已删研究资料的 2,154 个死块,wiki_search.py 按 blockchain/区块链研究资料 前缀跳过,不命中。
只读原始文件：构建脚本绝不写 raw/articles/，产出全在向量库目录。

后续可选

把 wiki/concepts/、wiki/entities/、wiki/reports/ 页面也编入（"知识库内的语义导航"）。