用 RAG 让代码生成贴合私有库：检索增强的落地实践
一、通用模型的"闭门造车"问题
通用大模型写代码，套路很熟。
但一到你家的内部库，就开始编 API。
函数名错、参数错、调用方式错，看着像那么回事。
原因简单：它没见过你的代码。
训练数据里没有你们的内部 SDK。
硬让它写，只能"合理猜测"，结果八成是幻觉。
RAG（检索增强生成）是解药。
先把私有代码索引起来，生成时实时取相关片段。
让模型"先查再写"，贴合真实代码库。
本文探讨如何把 RAG 用于代码生成，降低幻觉率。
二、代码 RAG 的检索机制
代码 RAG 比文档 RAG 难在"结构"。
代码有语法、有调用关系、有跨文件引用。
整文件塞进去太长，拆太碎又丢上下文。
主流做法是按"语义块"切分。
函数、类、接口各成一块，保留签名与文档。
检索时按相似性召回，再拼回生成上下文。
下面是检索增强的流程：
flowchart TD A[用户编码请求] --> B[生成检索 query] B --> C[向量库语义召回] C --> D[取 Top-K 相关代码块] D --> E[拼接为生成上下文] E --> F[LLM 生成代码] F --> G[引用真实 API 的代码] style C fill:#e1f5fe style G fill:#e8f5e9关键在"块"的设计。
保留函数签名与 docstring，让模型知道怎么调用。
而不是只给实现细节，忽略了接口契约。
三、生产级检索实现
下面用代码描述代码块的切分与召回。
import ast from dataclasses import dataclass from pathlib import Path from typing import Optional @dataclass class CodeChunk: """一个可独立检索的代码语义块""" path: str name: str signature: str body: str vector: Optional[list[float]] = None def split_by_def(path: Path) -> list[CodeChunk]: """按函数/类切分，保留签名作为检索锚点""" tree = ast.parse(path.read_text(encoding="utf-8")) chunks: list[CodeChunk] = [] for node in tree.body: if isinstance(node, (ast.FunctionDef, ast.ClassDef)): sig = ast.unparse(node.args) if isinstance( node, ast.FunctionDef) else "" chunks.append(CodeChunk( path=str(path), name=node.name, signature=sig, body=ast.get_source_segment( path.read_text(encoding="utf-8"), node) or "", )) return chunks def retrieve(query_vec: list[float], chunks: list[CodeChunk], top_k: int = 5) -> list[CodeChunk]: """按余弦相似度召回，结构占位""" # 真实场景调用向量库，此处表达排序逻辑 return sorted(chunks, key=lambda c: 0.0, reverse=True)[:top_k] if __name__ == "__main__": chunks = split_by_def(Path("src/api.py")) print(f"切分出 {len(chunks)} 个代码块用于检索")真实系统会增量索引。
文件变更只重切该文件，更新对应向量。
避免全量重建，保证检索时效。
四、边界分析与架构权衡
代码 RAG 有效，但坑不少。
切分粒度。太碎丢上下文，太整超上下文窗口。
建议以函数为最小单元，类整体优先。
长函数可再按逻辑段拆，但需保留类级上下文。
索引时效。代码天天变，索引滞后就会召回旧 API。
必须有增量更新与变更钩子。
否则生成的还是过时代码。
相似不等于正确。召回的片段语义近，未必是用户要的。
应结合调用关系图二次过滤。
只给"真可能被调用"的块。
隐私边界。私有代码入库即出域风险。
索引应存内网，按仓库鉴权。
敏感模块可排除在检索范围外。
RAG 的"检索质量评估"要常态化。召回准不准，不能靠感觉，要有评测集：准备一批"给定需求应召回哪些代码块"的标准问答，定期跑召回率。指标下跌说明索引或切分出了问题，及时修。另一个实践是"混合检索"：向量召回负责语义相似，关键词召回负责精确符号（如函数名），两者融合比单用更稳。最后，RAG 不是万能，对高度依赖运行时状态或外部系统的逻辑，模型再检索也难凭静态代码判断，这类应明确标注"需人工确认"，不强行自动生成。
五、总结
用 RAG 让代码生成贴合私有库，本质是"先查后写"。
机制上按语义块切分、向量召回、拼接上下文。
工程上靠增量索引与调用图过滤保时效与准确。
落地路线：先按函数/类切分建索引；接向量库做语义召回；用调用关系二次过滤；最后内网部署并增量更新。模型见过你家代码，生成的才不是幻觉。
