上下文工程进阶仓库级语义检索与代码分块策略一、文件级检索的天花板上一阶段我们把代码按函数切分、向量召回。在单仓库小规模下效果不错。但仓库一大函数成千上万召回开始不准。问题出在块的粒度与关联丢失。只召回几个孤立函数模型看不到它们之间的调用关系。生成的代码可能用错依赖或重复已有实现。仓库级语义检索要解决的是把结构关系也编码进检索。让召回的不是碎片而是带上下文的代码群。本文探讨仓库级的检索与分块策略。二、仓库级检索的机制核心思想是检索单元 语义块 关系。分块时不仅存代码还存它的调用者与被调用者。召回时按相似度取块再沿关系图扩展一圈。这样模型拿到的不是孤岛而是一个子树。既有目标函数也有它依赖和依赖它的邻居。生成时上下文更完整幻觉更少。下面是扩展检索的流程flowchart TD A[查询] -- B[向量召回 Top-K 块] B -- C[沿调用图扩展邻居] C -- D[去重合并子树] D -- E[按预算截断] E -- F[拼为生成上下文] style B fill:#e1f5fe style F fill:#e8f5e9关键在扩展深度的权衡。扩一层够用扩两层可能引入噪声。应基于查询类型动态调整实现类扩深用法类扩浅。三、生产级实现下面用代码描述调用图扩展召回。from dataclasses import dataclass, field from typing import Optional dataclass class CodeBlock: id: str text: str calls: set[str] field(default_factoryset) called_by: set[str] field(default_factoryset) score: float 0.0 def expand(graph: dict[str, CodeBlock], seeds: list[str], depth: int 1) - list[str]: 从召回种子沿调用图扩展召回关联子树 visited: set[str] set() frontier list(seeds) for _ in range(depth): nxt: list[str] [] for sid in frontier: if sid in visited: continue visited.add(sid) block graph.get(sid) if not block: continue nxt.extend(block.calls | block.called_by) frontier nxt return list(visited) def retrieve(graph: dict[str, CodeBlock], query: str, top_k: int 5, depth: int 1) - list[str]: # 结构占位真实场景用向量相似度给 seed 打 score seeds sorted(graph.keys(), keylambda k: graph[k].score, reverseTrue)[:top_k] return expand(graph, seeds, depth) if __name__ __main__: g: dict[str, CodeBlock] { a: CodeBlock(a, def a, calls{b}), b: CodeBlock(b, def b, called_by{a}), } print(retrieve(g, 如何使用 a, depth1))真实系统会预建调用图并持久化。代码变更时增量更新边而非全量重算。检索时图查询是 O(度数)极快。四、上下文工程进阶的代价与边界仓库级检索更强但更复杂。图构建成本。大规模仓库建调用图耗资源。应增量更新且只在变更文件重算影响子图。全量重建放在夜间低频执行。扩展噪声。关系多的块扩展会带入无关邻居。需用相似度对扩展项再过滤而非无脑全收。深度建议默认 1按需上调。分块边界。跨文件的继承、装饰器关系难被切分捕获。这类语义要在分块时特殊标注否则召回断裂。规则要随语言特性补充。存储膨胀。每块存关系索引体积更大。应按仓库规模选存储超大仓库用图数据库而非内存。仓库级检索的查询理解是效果上限。检索准不准一半在分块与图一半在查询本身质量。原始自然语言查询往往模糊直接向量化召回噪声大。建议在检索前先让模型把查询改写成代码语义查询如提取目标函数名、意图关键词再去做向量召回命中率明显提升。另一个实践是反馈闭环用户对召回结果的点踩要点沉淀为查询改写的正负例逐步纠偏。最后超大仓库的检索要分层先按目录/包粗筛范围再在范围内精细召回避免全仓暴力扫描既快又省。五、总结仓库级语义检索本质是把结构关系编进上下文。机制上以种子召回 调用图扩展召回子树而非碎片。工程上靠增量建图与相似度再过滤控噪声。落地路线先建持久化调用图向量召回种子块沿图扩展一圈去重按预算截断拼上下文。模型看到的不再是孤岛而是能跑通的关系网。