claude-obsidian检索四件套脚本详解：contextual-prefix、bm25-index、retrieve与rerank

claude-obsidian检索四件套脚本详解contextual-prefix、bm25-index、retrieve与rerank【免费下载链接】claude-obsidianSelf-organizing AI second brain for Obsidian Claude Code. Drop any source and Claude reads, links, and files it into one connected knowledge graph of plain Markdown you own. AI note-taking, personal knowledge management (PKM), and an open-source Notion alternative. Based on Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidianclaude-obsidian是一个开源的 AI 第二大脑工具专为 Obsidian Claude Code 打造把任意资料丢进去它会自动阅读、建立链接并归档成一张由纯 Markdown 构成的知识图谱。而在 v2 版本中真正让这套知识库越用越聪明的是隐藏在 scripts/ 目录下的检索四件套——contextual-prefix.py、bm25-index.py、rerank.py与retrieve.py。它们协同完成切块 → 索引 → 重排 → 检索的完整混合检索流水线让你的笔记库拥有接近搜索引擎的召回能力。本文面向新手讲清每个脚本的作用、彼此关系与上手步骤。检索四件套是什么一张表看懂分工 四个脚本各司其职数据流方向是单向的前两个脚本负责建索引写入.vault-meta/派生缓存绝不改动你的笔记后两个负责查索引。脚本角色一句话职责产物位置contextual-prefix.py切块 上下文前缀把 Wiki 笔记按段落切成小块并为每块补一句这是哪页笔记的什么内容.vault-meta/chunks/bm25-index.py关键词索引用纯标准库构建标准 Okapi BM25 倒排索引k11.5, b0.75.vault-meta/bm25/index.jsonrerank.py语义重排可选用本地 Ollama 嵌入模型对候选块做余弦相似度重排.vault-meta/embed-cache.jsonretrieve.py检索总指挥BM25 先召回 top-20再重排到 top-5输出带路径和摘要的 JSON 结果stdoutJSON这套设计借鉴了 Anthropic 2024 年提出的上下文检索Contextual Retrieval模式孤立的段落往往缺少主语和背景给它补一句前缀关键词检索的命中率就显著上升。而 BM25 保证确定性与离线可用语义重排提供同义词与跨语言的补充——两者互补缺一不可。第一步contextual-prefix.py 给每段笔记补上上下文这一步是整条流水线的地基。它对wiki/下的每页笔记做两件事智能切块优先沿段落边界切分目标每块约 2000 字符超过 4000 字符才硬切块间保留 200 字符重叠避免句子被拦腰截断。生成前缀为每块生成 1~2 句定位前缀说明这段文字来自哪页、讲什么主题。前缀生成有三档脚本会按环境自动选择配置了 Anthropic API Key → 调用 Haiku 4.5 生成需显式加--allow-egress同意数据出网系统装有claude命令 → 走 Claude Code 订阅同样需--allow-egress默认档只用本地 frontmatter 首段合成前缀零成本、零出网。对新手来说默认档就是安全起点不联网、不花钱BM25 与向量通道依然完整可用。每个切块会写成带内容哈希的 JSON 记录笔记没变化时重复运行会自动跳过页面变了才会增量重建。第二步bm25-index.py 构建本地 BM25 关键词索引有了带上下文的切块第二步是建索引。bm25-index.py全程只用 Python 标准库无需安装任何第三方包把一个index.json写到.vault-meta/bm25/。它有几个对新手很友好的细节中文友好中日韩文字会自动切出 1/2/3 字 n-gram不做分词也能匹配到长文档纯本地索引构建与查询完全离线你的笔记不出机器三个子命令build全量建索引、stats查看索引规模、query直接按词查询方便排查。索引文件记录词频、文档频率和倒排表。由于前缀文本已被编入索引搜LLM Wiki 模式能命中的不再是碰巧含这四个字的段落而是被前缀点明主题的段落——这就是上下文检索的增益所在。第三步rerank.py 可选的语义重排关键词检索有个天然短板同义词搜不到。你写知识复利笔记里是复利式学习BM25 就哑火了。rerank.py解决的就是这个问题调用本机Ollama 的嵌入模型默认多语言nomic-embed-text-v2-moe给查询和候选块分别打search_query:/search_document:前缀后向量化按余弦相似度重排嵌入结果按模型 方案 输入哈希缓存在.vault-meta/embed-cache.json同一候选不重复计算故障即降级Ollama 没启动、模型没拉取、嵌入失败……任何一步出问题重排自动变为原样返回直接沿用 BM25 的顺序检索永远不会因为重排环节而失败隐私边界默认只连本机127.0.0.1连远程 Ollama 必须显式加--allow-remote-ollama。需要提醒约 958 MB 的模型永远不会被自动下载是否安装由你自己决定——不用重排纯 BM25 通道依然完整可用。第四步retrieve.py 一条命令完成混合检索前三个脚本可以单独调用但日常使用你只需要retrieve.py。它把整条流水线串起来python3 scripts/retrieve.py 我的笔记库里关于复利的内容 --top 5 --explain执行路径是BM25 召回 top-20 → 可选语义重排 → 按页面去重 → 返回 top-5。输出是结构化 JSON每条结果包含切块编号、笔记的绝对路径、BM25 分数、重排分数和 200 字符摘要——调用方通常是 Claude拿到路径直接读原文、综合作答而检索结果本身不算证据答案必须回到笔记原文里找出处。几个实用开关参数作用--top 10调整返回条数1~1000--no-rerank跳过重排只走确定性的 BM25纯离线--model nomic-embed-text显式选用更小的英文 v1.5 模型--explain附各阶段诊断信息排查为什么没搜到当索引不存在或损坏时retrieve.py会以退出码 10 明确告知并给出重建命令调用方会回退到常规的 vault 查询路径——宁可诚实报告没有结果也不伪造匹配。快速上手三条命令启用本地检索 首次使用建议先预览再执行项目所有写操作都遵循这一约定。拿到仓库后git clone https://gitcode.com/GitHub_Trending/cl/claude-obsidian bash bin/setup-retrieve.sh --vault /path/to/你的vault --no-llm # 预览计划 bash bin/setup-retrieve.sh --vault /path/to/你的vault --no-llm --apply # 确认无误后执行随后随时可以体检python3 scripts/bm25-index.py --vault ... stats看索引规模--peek类选项预览任何操作而不写入。更完整的约定见 skills/wiki-retrieve/SKILL.md 与 docs/compound-vault-guide.md。小结为什么这套检索设计值得借鉴claude-obsidian 的检索四件套给个人知识库检索提供了一个务实范本离线优先核心链路切块 BM25纯标准库、零依赖、不出网可选增强语义重排是可插拔的锦上添花且失败时确定性降级隐私可控一切出网操作API 前缀生成、远程 Ollama都需要用户显式加旗标同意诚实可靠内容哈希校验拒绝过期缓存空索引如实报告而非编造结果。对新手而言最值得带走的心法只有一条先用确定性检索打好地基再按需叠加模型能力。理解了这条流水线你也可以在自己的笔记系统里复刻它。【免费下载链接】claude-obsidianSelf-organizing AI second brain for Obsidian Claude Code. Drop any source and Claude reads, links, and files it into one connected knowledge graph of plain Markdown you own. AI note-taking, personal knowledge management (PKM), and an open-source Notion alternative. Based on Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidian创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考