AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

顶点项目 02 —— 代码库之上的 RAG（跨仓库语义搜索） ​

2026 年，每个像样的工程组织内部都跑着一套理解含义、而不只是字符串的代码搜索。Sourcegraph Amp、Cursor 的代码库问答、Augment 的企业图谱、Aider 的 repomap、Pinterest 的内部 MCP——同一套形态。摄入很多个仓库，用 tree-sitter 解析，对函数级和类级的 chunk 做 embedding，混合搜索，重排，带引用作答。这个顶点项目要求你做一个能扛住跨 10 个仓库、200 万行代码，并且在每次 git push 时都能挺过增量重建索引的系统。

类型： Capstone 语言： Python（摄入）、TypeScript（API + UI） 前置要求： 第 5 阶段（NLP 基础）、第 7 阶段（transformer）、第 11 阶段（LLM 工程）、第 13 阶段（工具）、第 17 阶段（基础设施） 涉及阶段： P5 · P7 · P11 · P13 · P17 预计时间： 30 小时

问题背景 ​

到 2026 年，每个前沿编码 agent 都带着一层代码库检索，因为光靠上下文窗口解决不了跨仓库的问题。Claude 的 100 万 token 上下文有帮助，但它消除不了对排序检索的需求。在原始 chunk 上做朴素的余弦搜索，会在生成的代码、monorepo 的重复内容、以及很少被 import 的符号的长尾上把结果搞坏。生产上的答案是：在 AST 感知的 chunk 上做混合搜索（dense + BM25），加一个重排器，背后再有一张符号引用的图。

你通过给一支真实的仓库舰队建索引来学这件事——不是某个教程里的单仓库——并衡量 MRR@10、引用忠实度和增量新鲜度。失败模式都是基础设施层面的：一个 10 万文件的 monorepo、一次改动了半数文件的 push、一个要跨四个仓库才能正确作答的查询。

核心概念 ​

一条 AST 感知的摄入流水线用 tree-sitter 解析每个文件，抽出函数和类节点，按节点边界而不是固定的 token 窗口来切 chunk。每个 chunk 拿到三种表示：一个 dense embedding（Voyage-code-3 或 nomic-embed-code）、稀疏的 BM25 词项，以及一段简短的自然语言摘要。摘要加上了第三种可检索的模态——用户问“X 是怎么做鉴权的”，哪怕代码里只有 check_permission，摘要里也会提到 “authz”。

检索是混合式的。一个查询同时触发 dense 和 BM25 搜索，合并 top-k，把并集交给一个 cross-encoder 重排器（Cohere rerank-3 或 bge-reranker-v2-gemma-2b）。重排后的列表送给一个长上下文合成器（带 prompt caching 的 Claude Sonnet 4.7，或自托管的 Llama 3.3 70B），指示它每一条断言都要按文件和行号区间给出引用。没有引用的答案会被一个后置过滤器拒掉。

增量新鲜度是那个基础设施难题。Git push 触发一个 diff：哪些文件变了，哪些符号变了。只有受影响的 chunk 重新 embedding。受影响的跨文件符号边（import、方法调用）被重新计算。索引保持一致，不必每次提交都重新处理 200 万行。

架构 ​

git push --> webhook --> ingest worker (LlamaIndex Workflow)
                           |
                           v
             tree-sitter parse + AST chunk
                           |
            +--------------+----------------+
            v              v                v
          dense        BM25 index       summary (LLM)
        (Voyage / bge)  (Tantivy)        (Haiku 4.5)
            |              |                |
            +------> Qdrant / pgvector <----+
                            |
                            v
                      symbol graph (Neo4j / kuzu)
                            |
  query --> LangGraph agent (retrieve -> rerank -> synth)
                            |
                            v
                 Claude Sonnet 4.7 1M context
                            |
                            v
                 answer + file:line citations

技术栈 ​

  • 解析：带 17 种语言文法的 tree-sitter（Python、TS、Rust、Go、Java、C++ 等）
  • Dense embedding：Voyage-code-3（托管）或 nomic-embed-code-v1.5（自托管），bge-code-v1 作兜底
  • 稀疏索引：Tantivy（Rust）配 BM25F，对符号名和函数体做字段加权
  • 向量库：带混合搜索的 Qdrant 1.12，或给向量数低于 5000 万的团队用 pgvector + pgvectorscale
  • chunk 摘要模型：Claude Haiku 4.5 或 Gemini 2.5 Flash，做 prompt cache
  • 重排器：Cohere rerank-3 或自托管的 bge-reranker-v2-gemma-2b
  • 编排：摄入用 LlamaIndex Workflows，查询 agent 用 LangGraph
  • 合成器：带 prompt caching 的 Claude Sonnet 4.7（100 万上下文）
  • 符号图：Neo4j（托管）或 kuzu（嵌入式），存 import 和调用边
  • 可观测性：每个检索 + 合成步骤一个 Langfuse span
figure
ce-hybrid-retrieval

动手构建 ​

  1. 摄入遍历器。 在每个 push hook 上遍历 git 历史。收集变更的文件。对每个文件，用 tree-sitter 解析，连同完整源码区间抽出函数和类节点。产出 chunk 记录 \{repo, path, start_line, end_line, symbol, body\}。

  2. chunk 摘要器。 把 chunk 批量塞进 Haiku 4.5 调用，对 system 前导做 prompt caching。prompt：“用一句话总结这个函数，点出它的公开契约和副作用。”把摘要跟 chunk 一起存。

  3. embedding 池。 两条并行队列：dense（Voyage-code-3，批大小 128）和 summary（同一个模型，但跑在摘要字符串上）。把向量写进 Qdrant，payload 为 \{repo, path, start_line, end_line, symbol, kind\}。

  4. BM25 索引。 字段加权的 Tantivy 索引：符号名权重 4、函数体权重 1、摘要权重 2。让“找到名叫 X 的函数”这类查询能跟“找到做 X 的那个函数”并存。

  5. 符号图。 对每个 chunk，记录边：import（这个文件用了仓库 Z 里的符号 Y）、调用（这个函数调用了类 C 上的方法 M）、继承。存进 kuzu。查询时用来跨仓库边界扩展检索。

  6. 查询 agent。 带三个节点的 LangGraph。retrieve 并行触发 dense + BM25，按 (repo, path, symbol) 去重。rerank 在 top-50 上跑 cross-encoder，保留 top-10。synth 把重排后的 chunk 放进上下文调用 Claude Sonnet 4.7，缓存 system prompt，要求 file:line 引用。

  7. 引用强制。 解析模型输出；任何没有 (repo/path:start-end) 锚点的断言都被标记，要么重问要么丢弃。把只含已引用内容的答案返回给用户。

  8. 增量重建索引。 每个 webhook 上，计算符号级 diff。只对文本变了的 chunk 重新 embedding。对 import 变了的 chunk 重新计算符号边。指标：在一支 200 万行的舰队上，一次 50 文件的 push 在 60 秒内完成重建索引。

  9. 评测。 给 100 个跨仓库问题标注金标准 file:line 答案。衡量 MRR@10、nDCG@10、引用忠实度（断言中带可验证锚点的占比），以及 p50/p99 延迟。

实际使用 ​

$ code-rag ask "how is S3 multipart abort wired into our retry budget?"
[retrieve]  12 chunks dense + 7 chunks bm25, 16 unique after dedup
[rerank]    top-5 kept (cohere rerank-3)
[synth]     claude-sonnet-4.7, cache hit rate 68%, 2.1s
answer:
  Multipart aborts are triggered by `AbortMultipartOnFail` in
  services/uploader/retry.go:122-148, which decrements the per-bucket
  retry budget defined in config/budgets.yaml:34-51 ...
  citations: [services/uploader/retry.go:122-148, config/budgets.yaml:34-51,
              libs/s3client/multipart.ts:44-61]

拿去用 ​

可交付 skill outputs/skill-codebase-rag.md。给定一组仓库语料，它会立起摄入流水线、混合索引和查询 agent，对任何跨仓库问题返回一个带引用的答案。评分标准：

权重标准怎么衡量
25检索质量在 100 个问题的留出集上的 MRR@10 和 nDCG@10
20引用忠实度答案断言中带可验证 file:line 锚点的占比
20延迟与规模在所建索引的语料规模上、10k QPS 下的 p95 查询延迟
20增量索引正确性一次 50 文件提交从 git push 到可搜索的耗时
15体验与答案排版引用可点击、片段预览、追问的可操作性
100

练习 ​

  1. 把 Voyage-code-3 换成自托管的 nomic-embed-code。衡量 MRR@10 的差值。报告在开启重排后这个差距会不会缩小。

  2. 往语料里注入 20% 的生成代码（LLM 产出的样板代码）并重新评测。观察检索被污染的现象。给 payload 加一个 “generated” 标记，并给这些命中降权。

  3. 在你的语料规模上，给 Qdrant 混合搜索 vs pgvector + pgvectorscale 跑基准。报告批大小为 1 时的 p99。

  4. 加一个基于采样的漂移检查：每周重跑那 100 个问题的评测。MRR@10 跌幅 > 5% 时告警。

  5. 扩展到跨语言符号解析：一个 Python 函数通过 gRPC 调用一个 Go 服务。用符号图把它们连起来。

关键术语 ​

术语大家嘴上怎么说它实际是什么
AST-aware chunking（AST 感知切块）“函数级切分”在 tree-sitter 节点边界处切代码，而不是用固定的 token 窗口
Hybrid search（混合搜索）“dense + 稀疏”并行跑 BM25 和向量搜索，合并 top-k，再重排
Cross-encoder rerank（cross-encoder 重排）“第二阶段排序”把 (query, candidate) 一对一起打分的模型，比余弦更准
Prompt caching“缓存的 system prompt”2026 年 Claude / OpenAI 的特性，对重复的前缀 token 最多打到一折
Symbol graph（符号图）“代码图”跨文件、跨仓库的 import、调用、继承边
Citation faithfulness（引用忠实度）“有据可循的答案率”用户点开锚点、读引用的区间就能核实的断言占比
Incremental re-index（增量重建索引）“push 到可搜索的时间”从 git push 到变更符号变得可查询的墙钟时间

延伸阅读 ​