代码检索与普通文本检索的本质区别
将代码当作普通的自然语言文章切块（Chunking）存在严重缺陷：
- 语义断裂：如果一个长函数被机械地在第 50 行切成两半，下半部分就会丢失所有变量定义与作用域上下文；
- 精确符号要求：在排查 Bug 时，变量名
user_id与order_id差一个字母就完全不同，向量的模糊相似度在此往往会导致误判。
三维混合定位引擎方案
- AST 语义感知切块：利用 Tree-sitter 解析语言 AST，严格以 Class、Function 或 Interface 为单位切块，并自动将父级类名、导入依赖作为元数据头注入 Chunk；
- 倒排稀疏索引（BM25）：保证对函数名、错误常量与专有名词的 100% 精确召回；
- 稠密向量索引（Dense Embeddings）：负责捕获“实现用户身份验证并生成 JWT 令牌的逻辑”这类概念级模糊搜索；
- 互惠排序融合（RRF）：将两种分数加权归一化，输出高精度的候选代码段。
落地示例：索引流水线的构建顺序
先建 AST 索引，再建向量索引。前者决定"块边界"，后者只是给已有块补语义入口；顺序颠倒会导致切块口径反复变更、嵌入全部重算。
增量更新是决定可用性的关键。以文件为单位记录内容哈希，只重算变化文件涉及的块；对重命名与移动做单独处理，否则一次大规模格式化提交就能让索引整体失效。建议把索引目录与仓库提交号绑定，查询结果里回带提交号，避免出现"检索到已被删除的实现"这类困惑。
查询侧的最小可用形态是：先做符号抽取（识别出查询里的函数名、文件名、错误码），命中符号走 BM25，未命中部分走向量检索，最后统一进 RRF 融合。
两路召回的分工对比
| 查询类型 | 稀疏索引 BM25 | 稠密向量索引 | 建议做法 |
|---|---|---|---|
| 精确符号与错误码 | 强 | 弱 | 以稀疏为主 |
| 概念描述类需求 | 弱 | 强 | 以向量为主 |
| 同义命名与缩写 | 不稳定 | 中 | 两路并跑再融合 |
| 跨语言调用链 | 弱 | 弱 | 交给图谱或调用图 |
| 超高频常见词 | 噪声大 | 中 | 停用词与路径降权 |
RRF 的价值在于不需要为两路分数做量纲对齐，只用排名即可，因此实践中通常比加权分数求和更稳。
验证方法
准备一批"金标准查询"，每条人工标注应命中的文件与函数，覆盖三类：精确符号、自然语言描述、报错信息片段。每次改动切块策略或嵌入模型后跑一遍，看前五条结果的命中率与前一条的命中率，两者同时不降才允许上线。另加一条时延预算：万级文件仓库的冷启动索引与单次查询耗时各设上限，超出就要考虑分层索引或增量重建。
常见故障速查
| 现象 | 原因 | 处理 |
|---|---|---|
| 结果总是同一个超大类 | 切块粒度未限制上限 | 超长函数按内部块二次切并保留头部 |
| 搜函数名却召回注释 | 稀疏索引未区分符号权重 | 对声明与标识符单独建字段加权 |
| 改动后召回旧代码 | 增量更新漏删失效块 | 按文件哈希全量比对并清理 |
| 语义查询返回无关文件 | 嵌入模型不适配代码 | 换代码向量化方案或缩小候选域 |
| 融合后精度反而下降 | 两路候选比例失衡 | 调整每路取回条数与融合常数 |
小结
混合检索是否值得投入，用两个问题判定：把查询按"含明确符号"与"纯概念描述"分两类，分别统计前五条命中率；若两类都低于可接受水平，先修切块边界与元数据，不要急着换嵌入模型。索引一致性则看删除一个文件后，检索结果里是否还能召回到它——能，就说明失效机制有漏洞。