花五篇量出了边界，现在需要一张更大的地图如果你从第 03 篇一路读到这里，那我们一起送走了一个缠了整整五篇的幽灵——Q8。回顾一下这场漫长的追捕。Q8 是process payment and create Stripe charge，它的 ground truth 里有个calculate_order_total（计算订单总价），我们用尽了文本检索的所有招式去抓它：向量基线抓不到，三种 chunking 抓不到，把called_by编进 embedding 只推到相似度 0.51 还是抓不到，最后连业界公认的"终极武器"BM25 + 向量混合检索都翻了车——不仅没修好 Q8，还把总分从 0.958 拖到了 0.931。五篇的结论，最后收束成一句话：calculate_order_total和"Stripe 支付"的关联，纯粹是结构性的。它藏在调用图的一条边上（被process_checkout调用），不写在任何函数的文本里。因此任何纯文本方案——向量、BM25、混合——都物理上够不着它。这句话，是我们花五篇实验换来的、有数字支撑的硬结论。它值钱，但它也只是一块拼图。因为在追 Q8 的过程中，我们其实顺手量出了三条检索路线各自的势力范围：向量擅长什么、够不着什么；图擅长什么、代价是什么；还有一类查询——“名为validate_jwt_token的函数在哪”——根本用不着语义，精确匹配一秒就返回。这三块势力范围拼在一起，才是代码库检索的完整版图。所以这一篇，我们换个高度。前五篇是拿着放大镜量单个检索算法的召回率，这一篇要退到卫星视角，画一张系统架构图：向量、图、符号这三路信号，到底该怎么组织成一个真正能用的生产系统。先给你打个预防针，读之前记在心里：这篇里凡是带具体 Recall 数字的，都是前五篇已经跑实验验证过的结论；凡是讲"该怎么设计系统"的部分，都是从这些结论推导出来的工程设计建议，还没有在完整生产系统上端到端验证过。我会在关键处反复标注，别把设计建议当成实验结论。先把三路信号的势力范围划清楚在动手设计之前，先把前五篇量出来的三块势力范围摆到台面上。这是整篇架构设计的地基，地基里的每一块砖都带着实验编号。第一路：向量检索——语义相似查询的主场。这是第 03 篇建立、后续四篇反复验证的基线：AST 函数级分割 + 原始代码 embedding，Recall@5 = 0.958，是所有文本方案里最强的向量基线（已实验验证）。它擅长处理"用自然语言描述功能、去找实现"这类查询——你说"找加密并安全存储密码的函数"，它能命中hash_password，哪怕你一个字都没提到函数名。它的边界也被量得很清楚：语义鸿沟填不平（第 06、07 篇）。calculate_order_total和"Stripe 支付"在真实世界就是两回事，任何 embedding 技巧都拉不近它俩。第二路：图检索——结构关系查询的主场。第 05 篇证明了调用图携带的结构信息是向量够不着的正交真相（已实验验证）：Q8 靠process_checkout → calculate_order_total这条调用边被两跳捞回。但第 05 篇也量出了它的代价——朴素 BFS 2 跳扩展会撑爆候选集，把 Q1 原本命中的verify_password挤出 top-5，一进一退总分归零。结论很微妙：方向对，方法糙。图信号值钱，但"检索后拿它做无脑 BFS 扩展"是错误用法。这个教训直接决定了后面架构里图检索的地位。第三路：符号检索——精确匹配查询的主场。这一路前五篇没专门做实验，但它的价值不言自明，也不需要实验证明：当你的查询本身就是一个精确的符号——“名为validate_jwt_token的函数定义在哪”、“哪些文件 import 了redis.Redis”——你要的不是"语义相近"，而是"字面精确命中"。这时候向量是杀鸡用牛刀，还容易被语义近似带偏；一个 grep 或一张函数名→文件→行号的符号表，10 毫秒内精确返回。把三块势力范围并排放，能看到一个漂亮的事实——它们几乎不重叠：查询类型 最擅长的路 举例 ──────────────────────────── ─────────── ───────────────────────── 自然语言描述功能，找实现 向量 "找验证 JWT 令牌的函数" 精确符号名 / import 符号 "validate_jwt_token 在哪" 结构关系 / 调用链 图 "谁调用了 createPayment" ──────────────────────────── ─────────── ─────────────────────────第 01 篇建立的"四个知识层次"框架，正好和这个版图对应：语法层（AST/符号）、语义层（向量）、架构层（图），再加上意图层（Git 历史）。生产系统的第一原则，就是承认这四层信号各自独立、缺一不可——不存在一个能通吃四层的"最好的检索方法"。架构原则一：多路召回，各司其职第一个原则，也是最反直觉的一个：别再找"那个最好的检索方法"了。前五篇我们干的就是这件事——不停地问"向量行不行？BM25 行不行？Hybrid 行不行？"，每一次都在赌某一路能 代码库知识库系列（08）：生产级架构设计——向量、图、符号索引如何组合
花五篇量出了边界，现在需要一张更大的地图如果你从第 03 篇一路读到这里，那我们一起送走了一个缠了整整五篇的幽灵——Q8。回顾一下这场漫长的追捕。Q8 是process payment and create Stripe charge，它的 ground truth 里有个calculate_order_total（计算订单总价），我们用尽了文本检索的所有招式去抓它：向量基线抓不到，三种 chunking 抓不到，把called_by编进 embedding 只推到相似度 0.51 还是抓不到，最后连业界公认的"终极武器"BM25 + 向量混合检索都翻了车——不仅没修好 Q8，还把总分从 0.958 拖到了 0.931。五篇的结论，最后收束成一句话：calculate_order_total和"Stripe 支付"的关联，纯粹是结构性的。它藏在调用图的一条边上（被process_checkout调用），不写在任何函数的文本里。因此任何纯文本方案——向量、BM25、混合——都物理上够不着它。这句话，是我们花五篇实验换来的、有数字支撑的硬结论。它值钱，但它也只是一块拼图。因为在追 Q8 的过程中，我们其实顺手量出了三条检索路线各自的势力范围：向量擅长什么、够不着什么；图擅长什么、代价是什么；还有一类查询——“名为validate_jwt_token的函数在哪”——根本用不着语义，精确匹配一秒就返回。这三块势力范围拼在一起，才是代码库检索的完整版图。所以这一篇，我们换个高度。前五篇是拿着放大镜量单个检索算法的召回率，这一篇要退到卫星视角，画一张系统架构图：向量、图、符号这三路信号，到底该怎么组织成一个真正能用的生产系统。先给你打个预防针，读之前记在心里：这篇里凡是带具体 Recall 数字的，都是前五篇已经跑实验验证过的结论；凡是讲"该怎么设计系统"的部分，都是从这些结论推导出来的工程设计建议，还没有在完整生产系统上端到端验证过。我会在关键处反复标注，别把设计建议当成实验结论。先把三路信号的势力范围划清楚在动手设计之前，先把前五篇量出来的三块势力范围摆到台面上。这是整篇架构设计的地基，地基里的每一块砖都带着实验编号。第一路：向量检索——语义相似查询的主场。这是第 03 篇建立、后续四篇反复验证的基线：AST 函数级分割 + 原始代码 embedding，Recall@5 = 0.958，是所有文本方案里最强的向量基线（已实验验证）。它擅长处理"用自然语言描述功能、去找实现"这类查询——你说"找加密并安全存储密码的函数"，它能命中hash_password，哪怕你一个字都没提到函数名。它的边界也被量得很清楚：语义鸿沟填不平（第 06、07 篇）。calculate_order_total和"Stripe 支付"在真实世界就是两回事，任何 embedding 技巧都拉不近它俩。第二路：图检索——结构关系查询的主场。第 05 篇证明了调用图携带的结构信息是向量够不着的正交真相（已实验验证）：Q8 靠process_checkout → calculate_order_total这条调用边被两跳捞回。但第 05 篇也量出了它的代价——朴素 BFS 2 跳扩展会撑爆候选集，把 Q1 原本命中的verify_password挤出 top-5，一进一退总分归零。结论很微妙：方向对，方法糙。图信号值钱，但"检索后拿它做无脑 BFS 扩展"是错误用法。这个教训直接决定了后面架构里图检索的地位。第三路：符号检索——精确匹配查询的主场。这一路前五篇没专门做实验，但它的价值不言自明，也不需要实验证明：当你的查询本身就是一个精确的符号——“名为validate_jwt_token的函数定义在哪”、“哪些文件 import 了redis.Redis”——你要的不是"语义相近"，而是"字面精确命中"。这时候向量是杀鸡用牛刀，还容易被语义近似带偏；一个 grep 或一张函数名→文件→行号的符号表，10 毫秒内精确返回。把三块势力范围并排放，能看到一个漂亮的事实——它们几乎不重叠：查询类型 最擅长的路 举例 ──────────────────────────── ─────────── ───────────────────────── 自然语言描述功能，找实现 向量 "找验证 JWT 令牌的函数" 精确符号名 / import 符号 "validate_jwt_token 在哪" 结构关系 / 调用链 图 "谁调用了 createPayment" ──────────────────────────── ─────────── ─────────────────────────第 01 篇建立的"四个知识层次"框架，正好和这个版图对应：语法层（AST/符号）、语义层（向量）、架构层（图），再加上意图层（Git 历史）。生产系统的第一原则，就是承认这四层信号各自独立、缺一不可——不存在一个能通吃四层的"最好的检索方法"。架构原则一：多路召回，各司其职第一个原则，也是最反直觉的一个：别再找"那个最好的检索方法"了。前五篇我们干的就是这件事——不停地问"向量行不行？BM25 行不行？Hybrid 行不行？"，每一次都在赌某一路能 RELATED READING
延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
