最近在调一个跨模块调用的问题光标停在一个从隔壁模块导入的函数参数上IDE补全只给了函数名参数列表和返回类型全靠我脑子里的记忆。这不是某个工具不行而是单文件层面的补全模型根本看不到仓库里其他文件的定义。要让补全在写代码的当下拿到真正相关的跨文件上下文就得给模型配一个能按需取数的“外挂”——这正是仓库级代码补全和选择性检索这套组合要解决的核心问题。我在这套方案上折腾了几个月从最朴素的把所有仓库分块塞进向量库检索到最后做成一条带触发选择、符号级召回和调用图过滤的完整管线踩的坑比想象中多。这篇文章不打算列公式我把整个思路、模块拆解、索引设计、实测噪声和评估陷阱都写出来给那些准备在内部项目里做仓库级补全的人当参考。1. 仓库级代码补全为什么离不开“检索”——从IDE失灵说起1.1 单文件补全的边界先聊一个每天都在发生的场景你在工程里新写一个模块需要调用工具层早就封装好的一个函数。编辑器只能告诉你函数名叫什么参数有几个、每个参数什么含义、返回什么类型一概不知。调用点的类型约束、数据流这些基础信息也经常跨文件断掉。这类问题我习惯叫“跨文件符号缺失”它恰恰是仓库级补全要解决的第一类问题。传统补全管线依赖编辑器内的语法树和类型推断但类型推断本身需要解析整个项目依赖很多构建配置下根本跑不完整。大模型补全如果只给当前文件的上下文那它能写出函数名是因为训练语料里见过但具体签名、当前仓库里的自定义类型、调用链上的约定它只能靠猜。猜错的概率不高但猜错一次就足够让人头疼。1.2 全量上下文的性价比困局有人会说既然缺信息那把整个仓库都喂给模型不就完了。这个想法在小型项目里勉强可行但很快会遇到三个问题。第一是上下文窗口的容量虽然主流模型把窗口做得越来越大但窗口大不等于中间信息不丢。写代码时真正关键的定义经常被淹没在大段无关代码里模型在处理长输入时对中后部内容的关注度会明显下降。第二是成本仓库里几十上百个文件全部走一遍输入在线场景下的token开销成倍增长延迟和成本都兜不住。第三是噪声无关文件的插入不是无害的模型会被干扰生成出结构正确但语义完全错误的内容这种错误比我上面说的“猜错签名”还要隐蔽。所以基本结论是仓库信息必须做选择而不是全量搬运。选择的方式有很多种最常见的框架是先把仓库切成可检索的单元建立索引在补全发生时根据当前上下文召回最相关的片段再拼进上下文让模型生成。这就是仓库级代码补全里检索增强的出发点。1.3 稀疏性假设检索能work的第一性原理做检索方案前我非常确信一个前提单个补全点真正需要的仓库知识是稀疏的。你可能只需要三四个跨文件符号的定义、一个数据结构的字段清单、一个API的返回类型。检索的任务不是把“所有可能相关的”都拿进来而是根据当前代码意图定位到这有限的几个定义。这个稀疏性假设是整个设计的基石。一旦接受它很多决策就顺理成章了不需要召回几十个文件不需要把检索做得很重反而需要的是克制——选最少的、最准的上下文进模型。2. 选择性检索和朴素RAG的关键分野先决定“要不要查”再决定“查谁”2.1 朴素RAG的翻车现场把检索增强套到代码补全上第一个跑通的版本往往长这样每次补全都拿光标前的上下文去向量化仓库分块召回top-k块拼进prompt。听起来没什么问题但实际一测就开始翻车。翻车点主要有三个。一是很多补全点根本不需要外部信息比如继续写局部变量初始化、补一个循环体模型只看当前函数就够。这种情况硬塞进5个chunk文本里经常带出一堆无关符号名模型会顺着这些名字编造根本不存在的方法。二是即使需要外部信息检索回来的chunk也经常不对路代码文件里结构相似的内容反复出现向量相似度会把“双胞胎文件”带回来但它根本不是被调用的那个。三是chunk内部信息太杂一个文件里的公共方法、私有函数挤在一起真正需要的只有其中一个函数定义却要捎带几百token无关内容。2.2 “选择性”选的是什么把selective拆开我理解成三个层面触发选择当前补全点需不需要检索。这是第一层漏斗能砍掉大量无效召回。模型仅凭局部上下文就能给出高置信预测时完全不需要打扰检索。内容选择检索对象是谁。不做整文件捞取而是把符号定义当作最小召回单元需要哪个函数就回哪个函数而不是连带整段无关代码。数量选择召回多少个符号。不是固定k而是根据当前上下文中“未解析的跨文件引用数量”和“模型置信度”动态调整。少的补全点可能一个符号就够复杂的补全点才多一点。三个层面合起来的效果是能用局部知识解决的不打扰检索必须跨文件的只带必要符号相关度不够宁可放弃也不强塞。下面这个表能说清楚朴素RAG和选择性检索的差别维度朴素RAG选择性检索触发方式每次补全都检索按置信度/跨文件引用判定触发召回单元文本chunk通常1个文件多行符号级函数、类、常量召回数量固定top-k动态数量上限受控噪声处理基本不管用路径过滤、调用图过滤、相关性阈值信息缺失时硬塞低相关结果放弃检索退回局部生成2.3 一个可落地的决策流程我不会给你一套现成的阈值但可以提供一个决策逻辑的模板。我们内测时用的规则演进版大概是下面这样def need_retrieval(cursor_context, model_outputs): top_prob softmax_probs[0] if top_prob 0.7 and no_unknown_refs(cursor_context): return False # 局部模型足够自信不检索 elif has_cross_file_ref(cursor_context): return True # 存在明确的跨文件引用目标 else: return entropy(cursor_context) threshold这段逻辑的核心是“不要用同一套策略对待所有补全请求”。一个简单可靠的触发选择器可以把检索调用频率降到请求量的30%-40%。检索调少了整体延迟降下来生成质量反而更高因为模型不再被无关上下文带偏。3. 三个核心模块的工程实现查询构造、触发判定和召回策略3.1 查询构造光标上下文的清洗与截断检索的第一步不是直接拿完整光标上下文做向量化。光标前的代码往往有大量干扰无意义的空白、未闭合的字符串、刚写的半截表达式。我试下来的几条经验截取窗口拿光标前256 token够了太长会让向量被前面的无关代码带偏。语法裁剪用解析器把半截token切掉保持最后一个完整语句。把一段“if user.”这种半截代码直接向量化效果很差因为解析不了含义。目标优先如果前面刚出现from xxx import或import这类语句说明开发者正在做跨文件引用把导入目标作为query的高权重部分。还有一个trickquery不要只用一个文本块。我把query拆成“语法前缀最近标识符调用目标”三部分分别向量化再和检索结果做分数融合。这样能降低长前缀噪声对短符号名的淹没特别是当函数名只有30个字符而光标前已经有300个字符的上下文时。3.2 触发判定用“犹豫程度”和显式信号做或运算触发判定可以走两条路。一条是显式信号解析当前语法树看是否存在跨文件引用、是否在写import语句、函数调用参数是否未闭合且函数名不在当前作用域内。另一条是模型内在信号用解码器输出概率分布判断模型“犹豫”程度。我用熵和top1概率的组合一个判断标准可以定为top1概率低于0.7或者前三个候选概率接近说明模型拿不准值得检索一把。一开始我只用了显式信号机械但可控后来发现很多需要检索的场景并不伴随import语句——比如一个调用来自“utils”这种已导入模块但要用到其中某个子函数时模型其实并不知道它存在。所以后来我把显式信号和模型信号做了“或”而不是“与”。用“或”的代价是多了一些无效检索但漏检率显著下降。在补全场景里漏检比误检更让人难受因为用户会直接看到补全出来的跨文件符号是编的。3.3 召回策略文件级、符号级、调用图级三种召回粒度我分别说一下。文件级召回最糙但覆盖率高。缺点是上下文噪声大模型容易在文件里乱找。我一般限制在200行以内的小文件才用文件级召回大型文件一定得切碎。符号级召回是主力。我把解析后的函数、类、常量定义作为基本单元向量索引的是“符号签名注释函数体摘要”检索时只返回符号本身。这种做法的精度很高缺点是依赖解析器质量。语言一多维护成本跟着上来了但为了精度这钱花得值。调用图驱动不依赖embedding。它从当前函数出发沿着调用边往外走两跳把被调用函数的定义直接作为候选再配合过滤规则。它能抓住代码里的真实调用关系但要求仓库能解析出相对完整的调用图。很多大型仓库的反射、动态调用会让图不完整所以不能单独靠它。我线上的最终方案是符号级为主、调用图为辅向量召回Top50符号调用图候选取Top20一起送进一个轻量reranker——按与query的token重叠率、图距离、路径相似度打分——最后只保留Top5。这套流程把无关召回率压到了可接受的范围。注意Top5不是每个场景都需要的最终送入模型的上下文量由前面提的“动态数量选择”进一步压缩。4. 仓库侧索引与切分怎么设计AST感知比“全部embedding”更靠谱4.1 代码文本不适合直接embedding如果直接把仓库每行文本塞进通用文本向量模型容易遇到两类问题一是把两个结构一模一样但业务完全无关的文件召回混了二是相同语义但命名风格不同的两个函数在向量空间里距离可能非常远。代码的语义不是纯文本语义函数名、类型签名、调用关系这些结构性信息在通用文本向量里表达得很弱。所以仓库级索引一定要以语法树为基底而不是把整仓文本当作文档库来embedding。这不是说向量模型没用而是说它应该作用在“已经理解结构”的符号上而不是作用在原始文本上。4.2 AST感知的切分策略每个语言的文件先经过解析器转成语法树然后按顶层定义切分function/method函数名、参数签名、返回类型、函数体摘要前N行、装饰器/注解、文档字符串。class类名、继承目标、公开方法签名列表。constant/macro变量名和值。import块按模块分组方便把“导入目标”解析到具体符号。存储层面每条符号记录同时带三份内容纯文本摘要供向量模型输入、符号签名供精确匹配检索、位置信息文件路径、起止行。符号到文件的映射要双向维护既能从符号查文件也能从文件查包含哪些符号。这个双向索引在过滤阶段很有用——我可以快速判断一个候选是否和当前文件处于同一模块依赖关系里。4.3 稀疏与稠密双路索引我用BM25和稠密向量双通道并行。稠密向量负责语义相似召回BM25负责精确符号名命中。很多时候开发者要调用的就是“foo”这个名字向量相似度把很多相关但不叫foo的东西召回来BM25直接按名字锁定目标。双通道召回后用一个reranker融合分数。融合时要注意归一化BM25的分数和余弦相似度根本不在一个量级上直接相加会把稀疏成分压没。我是各自做min-max归一化再按0.4/0.6加权。这个比例不是拍脑袋拍的是在一次内部压测上扫出来的不同仓库最好的比例会略有漂移但0.4/0.6在多数场景下都是不错的起点。4.4 增量更新与版本一致性索引如果只在最开始建一次很快会废。常见做法是监听保存事件或版本管理动作对变更文件做增量解析更新对应符号并把失效符号从索引里摘掉。这里有个非常容易忽略的点检索返回的代码块必须与当前提交版本一致。开发分支上经常出现“另一个分支改了方法签名但当前分支还没合并”的情况。索引如果不带版本信息补全就会用旧签名误导模型。我的做法是索引条目记commit标识和分支可见性检索阶段过滤掉当前分支不可见的代码。这个过滤逻辑不复杂但少了它整个检索系统在三五个人协作的仓库里就会时不时给出过时信息。5. 实测中的四类典型噪声与修正方案5.1 相似文件造成的假召回这个坑在第一版就撞上了。同一个仓库里常见一批结构几乎相同的工具文件比如不同模块的“封装管理器”都有构造函数、初始化方法、注册方法。它们在向量空间里的距离非常近检索“某个注册方法的具体实现”时经常召回到隔壁模块的相似文件补全出来的方法体语义完全不对而且很隐蔽——源码结构看着挺正常所有符号名都对得上就是业务逻辑错了。修正思路不是调向量模型而是加结构约束候选必须和当前文件在同一个模块依赖子图里或者至少路径层级相近。我同时把当前文件路径作为query的过滤条件。路径过滤极其简单效果却立竿见影无关召回率明显下降。你要是有类似问题可以先从路径过滤入手别急着换向量模型。5.2 测试代码和测试夹具的污染仓库里测试目录经常占很大比例。测试代码里大量重复的mock、断言模板、测试数据构造恰恰和业务代码在向量空间里极其接近。检索经常把测试文件里的片段带回来不但没用还会把模型带偏——它开始生成assert、mock之类的测试风格内容甚至把测试断言写进生产函数里。我把所有测试目录排除在召回范围外除非查询本身来自测试文件。这是一个更一般的“环境感知过滤”根据当前光标所在目录动态限制检索空间。生产代码检索生产代码测试代码检索测试代码。这样既能避免交叉污染又能让模型在对应目录下生成风格匹配的结果。5.3 延迟不稳定检索链路一旦加进在线流程延迟就是体验的死穴。我压测过一个较大规模仓库的项目单次检索平均120ms但P95能飙升到500ms以上用户直接反馈“补全像卡住了”。问题出在向量检索的候选集太大reranker要处理几百个候选的长文本。优化做了三件事第一召回候选上限从200降到50第二reranker批次推理设超时上限超了直接退回到只保留双路检索中最高分的那一条结果第三检索和生成并行——让模型先生成前几十个token检索结果准备好后再注入继续生成。第三个方案改动最大但效果最好体感上几乎没有额外延迟。如果你们已经有一段基于局部上下文的生成流程强烈建议用并行方案而不是先检索再生成串行等待。5.4 版本漂移与过期索引这个在上面提过但实测里它不止一次被低估。有团队成员在功能分支上大改了一个核心接口索引没来得及更新补全还在用旧版本的方法签名生成的调用代码跟着错。这类问题频率不高但一错就是一大片而且很难靠终端用户自己发现根因。现在的做法是索引更新不追求秒级实时但至少做到分钟级每个索引条目记commit信息和分支可见性检索阶段做一次“所见即当前分支版本”的过滤。如果过滤后候选太少宁可返回不检索也不用过期信息。这是个保守策略但在工程里保守往往意味着稳定。6. 评估补全质量时最容易掉进去的坑6.1 只看自动匹配指标的误区仓库级补全的评估比普通补全更难。常用指标是精确匹配率、编辑距离相似度、Sari一类。但代码补全里精确匹配率对“函数少写一个参数注释”这种微小差异过于严苛对“结构完全错误但碰巧函数名一致”这种重大问题却毫无反应。编辑相似度只盯着字符串层面一段clone过来的代码只要换了个变量名就算低分但实际上完全正确。我一度被自动化指标误导过调整了一版检索策略精确匹配率和编辑相似度都涨了几个点上线前人工一测发现补全内容经常带着莫名其妙的断言和测试片段只是没用测试代码执行所以指标没崩。后来我把评估拆成两层离线用一批标注场景做自动指标再配一小部分人工判定“是否可直接接受”。两层都要做缺一不可。6.2 面向人的判定维度人工判定我用了四个维度目标符号是否正确需要召回的符号是不是被调用的那个还是召回了同名的其他东西。类型契约是否一致参数类型、返回类型与调用点是否吻合。这个维度最关键类型契约错整段代码即使能写出来也是废的。风格是否跟随当前文件命名风格、注释习惯是否贴近当前文件。模型一旦被测试代码污染风格会立刻暴露。有没有多余信息比如塞进了无关的import或错误的mock片段。这个维度直接反映检索噪声。四个维度里你们可能觉得第一个最重要我实际用的体会是第二个更关键。类型契约出错很难由后续工具发现而它恰恰是仓库级补全最容易犯的错——因为检索回来的符号定义和调用点本来就不在同一个类型系统里。6.3 一次调优路径的复盘完整复盘我最近一次调优。起始版本触发阈值偏低大约40%的补全请求都走了检索召回精度不高。我先提高阈值触发率降到20%精度明显上升但能感知到部分复杂跨文件场景开始不检索了用户的补全体验反而退步。接着我把触发逻辑从单一阈值改成“分值类型”的组合import语句和明确跨文件引用的query强制检索普通赋值语句只在高熵时检索。最后一步控制召回数量Top5降到Top3自动指标几乎没变但人工判定“多余信息”项从15%降到6%。这些数字来自我们内部标注集不具普遍性但趋势很明确少而准的方向是对的。每多塞一个没用的符号进上下文模型就多一分被带跑的风险。6.4 线上信号比离线指标更值得关注再高级的离线指标也不如线上真实反馈。内测时我加了一个小信号用户接受补全后短时间内没有回退操作的比例。这个“不回退率”和检索精度强相关。把它作为长期观察指标比任何离线指标都更能反映真实体验。做这类系统的人我建议尽早想清楚线上怎么埋点而不是等离线指标满意了再补。埋点越早积累的信号越厚后面调优才有依据。写在最后一条关于“克制”的体会整个项目做下来我最大的变化是心态。最开始我想的是怎么让检索更强大、更全、更快后来发现真正让补全变好用的是克制。每一个被带进上下文却没有实际价值的符号都在偷偷告诉模型“你该学着编造类似的东西了”。如果再做一版我会把更多精力放在触发选择上让大部分请求根本不进入检索通道。对正在做类似系统的人我建议先把触发选择想清楚再谈召回多准、索引多快——一道正确关闭的闸门远比一条加宽的水管更有价值。