文章摘要

Qdrant近期公开了一套Branch-Aware Semantic Code Search方案，用于解决AI编程Agent在多Git分支环境中检索到错误版本代码的问题。普通向量索引往往只保存main分支或最后一次写入的Chunk，当发布分支、功能分支和主干代码同时存在时，Agent可能生成无法编译的调用方式。本文分析“错误版本问题”、代码Chunk身份、分支继承、增量索引和查询过滤的完整设计。

一、语义代码搜索的新问题：找对代码但版本错了

传统grep在当前工作区执行，因此天然对应当前分支。

语义代码搜索通常会：

解析代码 → 按函数或类切分 → 生成Embedding → 写入向量数据库

如果索引只基于main分支，开发者在release分支中提问：

如何调用optimizer_thresholds？

Agent可能检索到main中的新签名，而当前release分支仍使用旧签名。

结果是：

• 生成代码无法编译；
• 使用了尚未发布的API；
• 修改了错误版本文件；
• 发布分支被新功能污染；
• Code Review难以理解来源。

这就是Wrong-Version Problem。

二、为什么不能给每个分支完整复制一份索引

最直接方案：

main一份 release一份 feature-A一份 feature-B一份

问题是代码高度重复。

假设：

主干100万个Chunk 20个活跃分支 每个分支只修改1%

完整复制会产生接近20倍存储，而绝大多数内容相同。

还会增加：

• Embedding成本；
• 索引时间；
• 更新压力；
• 删除复杂度；
• 分支合并后的清理成本。

更合理的方案是保存：

共享祖先版本 ＋分支自己的差异

三、代码Chunk必须有稳定身份

普通文本RAG常用：

文档ID＋Chunk序号

代码搜索更适合按符号建立身份：

repository path language symbol_type qualified_name

例如：

{"repository":"qdrant","path":"src/config.rs","symbol_type":"function","qualified_name":"optimizer_thresholds"}

为什么不推荐滑动窗口？

第1—80行 第60—140行

代码增加一行后，后续窗口全部位移，难以判断两个Chunk是否代表同一个函数。

按函数、类、方法和声明切分，身份更稳定。

四、同一个符号可能存在多个版本

例如：

main：optimizer_thresholds(config, mode) release/v1.15：optimizer_thresholds(config) feature-x：optimizer_thresholds(config, profile)

向量数据库中不能简单使用：

path + symbol

作为唯一ID，否则后写入的分支会覆盖其他版本。

可以使用：

repository ＋ path ＋ symbol ＋ commit_hash

或版本内容哈希：

importhashlibdefchunk_version_id(repository:str,path:str,symbol:str,content:str)->str:raw="|".join([repository,path,symbol,content])returnhashlib.sha256(raw.encode("utf-8")).hexdigest()

五、分支感知的核心：可见性

查询某个分支时，需要返回：

该分支自己修改的版本 ＋ 从祖先分支继承且未被覆盖的版本 － 已被删除的版本

例如：

main ├── release/v1.15 └── feature-new-index

release分支能看到：

• 分支创建时从main继承的代码；
• release后续自己的补丁；
• 看不到main后续新增且未合并的代码。

因此，简单过滤：

branch = release/v1.15

还不够，因为继承的Chunk可能只标记在祖先提交上。

六、两种常见实现

方案一：保存分支可见列表

Payload：

{"symbol":"optimizer_thresholds","commit":"abc123","visible_branches":["main","release/v1.15"]}

优点：

• 查询简单；
• 过滤快速。

缺点：

• 分支创建、合并和删除时需要批量更新；
• 活跃分支很多时Payload膨胀。

方案二：保存提交和分支历史

向量点保存：

created_commit deleted_commit symbol_identity

查询时根据Git DAG判断该版本是否对目标分支可见。

优点：

• 数据模型更接近Git；
• 不需要给每个点写所有分支。

缺点：

• 查询逻辑复杂；
• 需要外部Git图服务或预计算。

七、如何处理覆盖

功能分支修改了父分支中的函数：

祖先版本A → 分支版本B

在该功能分支查询时：

B可见 A不可见

即使A的向量相似度更高，也不能返回。

需要记录：

symbol_identity version_order replaced_version

查询先确定可见版本，再做语义排序。

八、如何处理删除

代码删除不能只从索引中物理删除，因为其他分支可能仍需要旧版本。

应该记录墓碑：

{"symbol":"legacy_search","deleted_in_commit":"d91f02","deleted_in_branch":"main"}

main查询时排除，旧release分支仍可见。

只有确认所有活跃分支都不再引用该版本后，才进行物理清理。

九、增量索引链路

Git Push → 获取变更文件 → AST解析 → 提取新增、修改、删除符号 → 计算内容哈希 → 只为新版本生成Embedding → 更新分支可见性 → 写入向量库

不要每次Push重建整个仓库。

伪代码：

defprocess_commit(commit):changes=git.diff(commit.parent,commit)forfile_changeinchanges:old_symbols=parse_symbols(file_change.old_content)new_symbols=parse_symbols(file_change.new_content)update_symbol_versions(branch=commit.branch,commit_hash=commit.hash,old_symbols=old_symbols,new_symbols=new_symbols)

十、查询接口应该携带什么

{"repository":"enterprise-platform","branch":"release/4.2","query":"订单取消接口如何做幂等","language":"java","top_k":10}

过滤条件：

repository匹配 branch可见 language匹配 当前版本未删除 用户有仓库权限

再执行向量排序和可选Reranker。

十一、Chunk应该按什么粒度

推荐优先级：

类 方法 函数 接口 类型定义 配置块

同时附带：

• 文件路径；
• 类名；
• 方法签名；
• Docstring；
• Imports；
• 父类；
• 调用关系；
• 分支；
• Commit。

过细会缺少上下文，过大则检索不精确。

可以采用：

方法Chunk负责召回 类级父Chunk负责补充上下文

十二、与普通代码RAG的区别

普通方案只关注：

语义相似度

分支感知方案还必须关注：

版本正确性 分支可见性 符号身份 删除与覆盖 权限

正确的旧版本代码，比相似度更高的新版本代码更重要。

十三、适合哪些场景

• 多版本SDK；
• 长期维护release分支；
• 大型企业代码库；
• AI Code Review；
• 代码问答；
• 自动修复；
• 迁移助手；
• 多仓库Agent。

如果团队始终只在main开发、旧分支很快删除，普通索引可能已经足够。

十四、生产检查清单

□ Chunk具有稳定符号身份 □ 同一符号支持多个版本 □ 查询明确携带branch □ 继承关系正确 □ 覆盖后旧版本不可见 □ 删除使用墓碑 □ 只对变更内容生成Embedding □ 分支合并后更新可见性 □ 用户权限进入过滤条件 □ Trace记录实际返回commit

总结

AI编程Agent不仅要找“语义最相似”的代码，还要找：

当前仓库 当前分支 当前时间点 真正可用的代码版本

分支感知语义搜索的关键，不是增加一个branch字段，而是把Git的继承、覆盖和删除语义带入向量检索。