企业官网建设流程全解析

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 Karpathy's LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidian

claude-obsidian是一个开源的 AI 第二大脑工具，专为 Obsidian + Claude Code 打造：把任意资料丢进去，它会自动阅读、建立链接并归档成一张由纯 Markdown 构成的知识图谱。而在 v2 版本中，真正让这套知识库"越用越聪明"的，是隐藏在 scripts/ 目录下的检索四件套——contextual-prefix.py、bm25-index.py、rerank.py与retrieve.py。它们协同完成"切块 → 索引 → 重排 → 检索"的完整混合检索流水线，让你的笔记库拥有接近搜索引擎的召回能力。本文面向新手，讲清每个脚本的作用、彼此关系与上手步骤。

检索四件套是什么？一张表看懂分工 🔍

四个脚本各司其职，数据流方向是单向的：前两个脚本负责建索引（写入.vault-meta/派生缓存，绝不改动你的笔记），后两个负责查索引。

这套设计借鉴了 Anthropic 2024 年提出的上下文检索（Contextual Retrieval）模式：孤立的段落往往缺少主语和背景，给它补一句前缀，关键词检索的命中率就显著上升。而 BM25 保证确定性与离线可用，语义重排提供同义词与跨语言的补充——两者互补，缺一不可。

第一步：contextual-prefix.py 给每段笔记补上"上下文"

这一步是整条流水线的地基。它对wiki/下的每页笔记做两件事：

• 智能切块：优先沿段落边界切分，目标每块约 2000 字符，超过 4000 字符才硬切，块间保留 200 字符重叠，避免句子被拦腰截断。
• 生成前缀：为每块生成 1~2 句"定位前缀"，说明这段文字来自哪页、讲什么主题。

前缀生成有三档，脚本会按环境自动选择：

1. 配置了 Anthropic API Key → 调用 Haiku 4.5 生成（需显式加--allow-egress同意数据出网）；
2. 系统装有claude命令 → 走 Claude Code 订阅（同样需--allow-egress）；
3. 默认档：只用本地 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）拿到路径直接读原文、综合作答，而检索结果本身不算证据，答案必须回到笔记原文里找出处。

几个实用开关：

当索引不存在或损坏时，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 Karpathy's LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidian