做代码库问答和文档问答有一个很明显的差别：一份技术文档可以按段落切块后直接放进向量库，效果往往已经够用；但一套源码里，一个函数只有几十行，却可能被几十个地方调用，它的“含义”是由调用方、被调用方、继承关系共同决定的。code-graph-rag这种项目要解决的正是这个问题：把源码解析成一张可以查询的代码知识图，然后基于图结构做检索增强生成。这篇文章会围绕code-graph-rag的思路，把从源码解析、建图、向量索引到本地问答的完整链路展开，读者可以拿一个自己的小仓库按步骤跑通。
这类项目放到 RAG 技术脉络里，属于 GraphRAG 在代码场景的落地实践。传统 RAG 解决的是“在非结构化文本里找答案”，而代码既是文本，又是带有强依赖关系的结构化对象。只做向量检索会丢掉调用链和继承关系，只做图查询又缺少语义召回，所以code-graph-rag的核心技术主线是：解析代码生成图谱，再用图结构修正 RAG 的召回和生成。下面从原理开始拆解。
1. 为什么代码问答需要图结构，而不是纯向量检索
1.1 普通 RAG 的切块策略在代码场景下为什么失效
普通 RAG 的处理流程一般是：把文档切块、做 embedding、存向量库、查询时用向量相似度召回 TopK 文本块。这个流程对自然语言文档有效，因为文档段落之间的依赖关系比较弱，读者靠上下文就能理解。
代码则完全不同。比如一个登录接口login调用同项目另一个文件里的validate_token，如果按固定长度切块，很容易出现两种情况：
login函数被切到两个块里，函数头在一个块，函数体在另一个块；login和validate_token的语义并不相似，但它们之间存在调用关系。
第二种情况是普通向量检索最容易漏掉的。用户问“修改validate_token会影响哪些地方”，向量检索只能召回与问题文本相似的内容，它并不知道login调用了validate_token，更不知道还有多少地方间接依赖这条调用链。
还有一个问题是代码里到处都是重复的框架样板。把from xxx import yyy、if __name__ == "__main__"这类内容作为向量切块后，它们会制造大量低价值文本块，既浪费存储，又会污染相似度排序结果。代码问答需要的不是“相似的文本片段”，而是“结构上相关的代码实体”。
1.2 图的本质：让检索从“找相似文本”变成“找相关结构”
code-graph-rag的基本假设是：代码库可以表示为一张有向图，节点是代码实体，边是实体之间的关系。GraphRAG 在通用文档场景里把文档处理成“实体-关系”三元组，这里则把代码解析成“符号-关系”图。
一张代码知识图至少包含这些元素：
- 文件节点，保存文件路径、语言类型、整体职责描述；
- 类节点，保存类名、父类、注解或装饰器；
- 函数节点，保存函数名、参数、返回值、函数体摘要；
- 模块导入关系，例如
A import B； - 调用关系，例如
A.func calls B.func； - 继承关系，例如
A extends B； - 引用关系，例如
A 引用了 B 的常量或工具函数。
建图之后，RAG 的检索不再只是“把问题向量化后找相似块”，而是先找到种子节点，再沿着边扩展出邻居、两跳关系，甚至整条调用链。这一步把代码问答从“语义匹配”提升到了“结构推理”。
1.3 节点和关系设计直接决定问答效果
图建得太粗，问答就退化成了文件级检索；建得太细，图会爆炸，且大量低价值节点会干扰检索。实际项目里建议先按“文件、类、函数”三个粒度建节点，再按需要补充变量、常量、接口、测试用例等节点。
| 节点粒度 | 适合回答的问题 | 不建议回答的问题 |
|---|---|---|
| 文件 | 这个模块是干什么的 | 某个函数被谁调用 |
| 类 | 这个类的职责和使用方式 | validate_token在哪定义 |
| 函数 | 某个函数的入参、返回值和调用方 | 整个系统的模块划分 |
| 变量/常量 | 某个配置项出现在哪些地方 | 架构层面的影响分析 |
节点的属性也不只包括名称。建议在解析阶段同时生成每个节点的“签名摘要”，比如函数参数、返回类型、一行代码职责描述。这些短摘要可以作为 embedding 的输入文本，让语义检索和结构检索共用一个节点索引。关系边的类型需要用枚举管理，不要用自由字符串，否则后续写图查询时会很难维护。
2. 构建代码知识图的完整流程
2.1 从源码到 AST 再到符号表
建图的第一步是把源码转换成结构化数据。推荐用 tree-sitter 这类增量解析器做第一步，因为它能准确识别函数、类、方法、导入语句的边界，错误容忍度也比正则表达式高很多。
解析流程通常是：
- 按扩展名识别语言，选择对应的 tree-sitter grammar；
- 对整个文件生成 AST；
- 遍历 AST，提取类、函数、导入、赋值等节点；
- 为每个节点生成全局唯一的符号 ID，例如
module/file.py::ClassName::method_name； - 记录节点所在文件、起止行号、源码片段和生成摘要。
这里的符号表是后续所有索引的基础。符号 ID 必须稳定，因为后面做增量更新时，要判断一个函数是新增、修改还是删除。
2.2 建立调用、继承和引用关系
AST 只能给出单个文件内部的语法结构，跨文件关系需要再做一层分析。常见做法是：
- 通过 import 语句建立文件或模块之间的依赖；
- 在函数调用点解析被调用方的限定名；
- 对类定义解析父类引用；
- 识别装饰器、注解和配置映射关系。
静态解析做不到 100% 准确。比如 Python 里的getattr(obj, method_name)、Java 的反射调用、JavaScript 的动态属性访问，都无法在静态分析阶段确定目标。实际项目的做法是：能解析的关系先解析，解析不了的关系通过文本相似度做候选召回，或在生成阶段明确提示模型“以下调用链可能不完整”。
2.3 存储：图数据库与向量索引配合
建好图之后，需要同时保存两份数据：图结构和节点语义向量。
图结构可以放在 Neo4j 这类专业图数据库，也可以放在 NetworkX 这类内存图结构里。两者差别很明显：
| 存储方案 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| Neo4j | 支持 Cypher 查询、事务、增量更新、权限控制 | 部署复杂度高，License 和运维成本需要评估 | 上百个服务、多人协作的长期系统 |
| NetworkX | 无额外服务，示例代码简单，适合学习和实验 | 数据量大后内存压力大，无持久化能力 | 演示项目、小仓库、本地原型 |
| 自定义关系表（SQL） | 与现有业务系统容易集成 | 多跳递归查询要手写 SQL 或多次查询 | 已有业务数据库，不想再维护图数据库 |
向量索引可以用独立的向量数据库，也可以用支持向量索引的图数据库插件。关键点在于：向量索引里的每一条记录都必须保存节点 ID，这样语义检索命中的结果才能回溯到图中的节点，继续做邻居扩展。
2.4 检索时如何把文本相关性和图上下文结合
code-graph-rag的检索阶段通常采用两阶段策略。
第一阶段做混合召回：把问题向量化，在节点向量索引中召回 TopK 个候选节点；同时把问题里的关键词、标识符、类名、函数名提取出来，在图里做模糊匹配。
第二阶段做图扩展：从第一阶段的候选节点出发，查询一到两跳邻居，得到调用方、被调用方、相关类和相关文件。然后把「问题 + 种子节点 + 图上下文」组装成提示词，交给大模型生成回答。
这种两阶段策略能同时兼顾语义相关性和结构完整性。比如用户问“我想加一个记住登录状态的功能，应该改哪些文件”，语义召回可能命中某个包含“remember”注释的函数，图扩展则能顺藤摸瓜找出所有涉及登录鉴权链路的函数。
3. 本地运行 code-graph-rag 的最小环境与准备
3.1 依赖组件清单
由于code-graph-rag这类仓库的依赖版本变化较快，下面给出的组件清单用于说明一套最小可运行环境需要哪些部分。落地前，要结合仓库 README 和本机环境确认版本。
| 组件 | 作用 | 建议 |
|---|---|---|
| Python | 运行解析、建图、API 服务 | 3.10 或以上 |
| tree-sitter | 解析多语言源码 | 按目标语言安装对应 grammar |
| NetworkX 或 Neo4j | 保存代码知识图 | 学习环境先用 NetworkX，生产再用 Neo4j |
| embedding 模型 | 生成节点和问题的向量 | 可用本地模型，也可用已有向量服务 |
| 大模型推理服务 | 生成问答结果 | 本地建议用 llama.cpp 加载 Qwen2-7B 指令版量化模型 |
| FastAPI | 提供问答 HTTP 接口 | 3.x 版本即可 |
如果希望完全本地运行，推荐组合是llama.cpp + Qwen2-7B-Instruct 量化版 + FastAPI。这个组合不需要申请外部接口，只要机器内存和显存足够，就能把数据留在本地处理。
3.2 最小项目结构
一个最小实现可以按下面目录组织：
code-graph-rag/ ├── extractor/ │ ├── parser.py # tree-sitter 解析源码 │ ├── symbols.py # 符号定义和 ID 生成 │ └── relations.py # 调用、导入、继承关系抽取 ├── graph/ │ ├── builder.py # 把解析结果写入图结构 │ └── query.py # 图查询和邻居扩展 ├── index/ │ ├── embedder.py # 节点摘要向量化 │ └── vector_store.py # 向量索引读写 ├── server/ │ ├── app.py # FastAPI 入口 │ └── prompt.py # 提示词模板 ├── data/ # 测试代码仓库 ├── test_queries.md └── README.md这只是示例结构。实际项目要根据自己的包名和代码习惯调整，但“解析层、图存储层、向量索引层、服务层”这四层边界尽量保留，因为后面排查问题会非常依赖分层。
3.3 准备一份测试代码仓库
学习阶段不要直接拿复杂微服务工程试。先用一个十几文件的小工具仓库，最好包含跨文件调用、类继承和少量公共工具函数。
下面给一个最简单的 Python 示例，方便验证图关系：
# auth/service.py from common.utils import validate_token class AuthService: def login(self, username: str, password: str) -> str: token = self.create_token(username) return token def create_token(self, username: str) -> str: return f"token-{username}"# common/utils.py def validate_token(token: str) -> bool: return token.startswith("token-")这个例子虽然简单，但已经包含两条关键关系：auth/service.py导入了common/utils.py，AuthService.login调用了create_token，同时文件之间通过 import 建立依赖。跑通这个例子后，再换更大的仓库就能检查图扩展逻辑是否正确。
4. 核心实现思路与关键配置
4.1 解析代码生成图数据
下面用 tree-sitter 解析 Python 函数定义，代码用于说明思路，实际 API 版本可能不同：
from tree_sitter import Language, Parser import tree_sitter_python PARSE_LANGUAGE = Language(tree_sitter_python.language()) parser = Parser(PARSE_LANGUAGE) def extract_functions(source: str): tree = parser.parse(source.encode("utf-8")) root = tree.root_node functions = [] def walk(node, parent_class=None): if node.type == "function_definition": name_node = node.child_by_field_name("name") if name_node: functions.append( { "name": name_node.text.decode(), "class": parent_class, "start": node.start_point[0] + 1, "end": node.end_point[0] + 1, "source": source[node.start_byte:node.end_byte], } ) if node.type == "class_definition": class_node = node for child in node.children: walk(child, parent_class=class_node.child_by_field_name("name").text.decode()) else: for child in node.children: walk(child, parent_class=parent_class) walk(root) return functions这里要区分“类方法”和“普通函数”，因为同名的类方法在不同类里是完全不同的符号。符号 ID 可以定义为文件路径::类名::函数名，没有类的函数就退化为文件路径::函数名。这个 ID 决定后面去重、更新和查询是否能对准节点。
4.2 图数据写入内存图或 Neo4j
学习阶段用 NetworkX 最省事：
import networkx as nx graph = nx.MultiDiGraph() def add_function_node(symbol_id, file_path, summary): graph.add_node( symbol_id, kind="function", file=file_path, summary=summary, ) def add_call_relation(caller_symbol, callee_symbol): graph.add_edge(caller_symbol, callee_symbol, relation="CALLS")MultiDiGraph允许两个节点之间存在多条不同类型的边，方便后续加IMPORTS、INHERITS、REFERENCES。如果生产环境要用 Neo4j，可以导入同样的边数据：
CREATE (f:Function {id: $id, name: $name, file: $file, summary: $summary}) CREATE (f)-[:CALLS]->(t)Cypher 查询两跳调用链非常直观：
MATCH (f:Function {name: 'login'})-[:CALLS*1..2]->(target:Function) RETURN DISTINCT target.name, target.file4.3 对代码块做向量化并与图节点绑定
图节点建立后，还需要一个字段用于语义检索：节点摘要。摘要可以是“函数签名 + 一句话注释 + 源码片段”，长度控制在 200 到 500 个字符。
切块参数可以参考下面这张表，它不是绝对的，要根据 embedding 模型的上下文长度调整：
| 参数 | 含义 | 常见值 | 调大影响 | 调小影响 |
|---|---|---|---|---|
| chunk_size | 单段文本长度 | 400-800 字符 | 语义更完整，检索粒度变粗 | 定位精确，但上下文易被截断 |
| chunk_overlap | 相邻块重叠长度 | 50-100 字符 | 减少信息丢失，索引体积变大 | 边界信息容易丢 |
| top_k | 语义召回节点数 | 5-20 | 召回全，噪声多 | 响应快，容易漏关键节点 |
| graph_depth | 图邻居扩展层数 | 1-2 | 影响分析更全面，查询变慢 | 只能覆盖直接依赖 |
向量存储里每条记录保存symbol_id，而不是只保存文本。查询命中向量后，用symbol_id回到图里查邻居，这样才能把语义相关变成结构相关。
4.4 问答阶段的检索与提示词组织
本地问答服务可以用 FastAPI 写一个最简接口：
from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class AskRequest(BaseModel): query: str class AskResponse(BaseModel): answer: str context_nodes: list[str] @app.post("/ask", response_model=AskResponse) def ask(req: AskRequest): seed_nodes = vector_store.search(req.query, top_k=10) context_nodes = graph_query.expand(seed_nodes, depth=2) answer = llm_chain.run( question=req.query, context=format_context(context_nodes), ) return AskResponse(answer=answer, context_nodes=context_nodes)提示词模板建议明确告诉模型两类信息：一是代码节点清单，二是节点之间的关系。不要只给源码片段，否则又退化成普通 RAG。一个简单的组织方式：
基于以下代码图谱节点回答问题。 节点之间可能存在 CALLS、IMPORTS、INHERITS 关系。 如果调用链不完整，请明确说明。 节点： {context} 问题： {query}本地大模型服务可以用 llama.cpp 启动：
llama-server \ -m qwen2-7b-instruct-q4_k_m.gguf \ --host 127.0.0.1 \ --port 8080 \ -c 8192如果当前版本的 llama.cpp 仍在build/bin下提供旧的可执行文件server，把llama-server换成对应路径即可。模型加载后，问答服务通过 HTTP 调用这个端口，就能做到请求代码、检索图谱、生成回答全链路本地运行。
5. 运行验证与结果分析
5.1 启动服务并建立索引
按顺序执行下面几步：
# 1. 解析测试代码仓库，生成图数据 python -m extractor.parser --repo data/my_demo # 2. 建立向量索引 python -m index.build --node-store graph_nodes.json # 3. 启动本地模型服务 llama-server -m qwen2-7b-instruct-q4_k_m.gguf --host 127.0.0.1 --port 8080 -c 8192 # 4. 启动问答 API uvicorn server.app:app --host 127.0.0.1 --port 8000每一步都要有检查点。第 1 步结束后，检查输出的 JSON 里是否包含预期函数、类、导入边；第 2 步结束后，检查向量库条数是否与节点数量一致；第 4 步启动成功后，先访问http://127.0.0.1:8000/docs确认 FastAPI 服务正常。
5.2 提问测试
使用 curl 测试一个典型问题：
curl -X POST http://127.0.0.1:8000/ask \ -H "Content-Type: application/json" \ -d '{"query": "修改 validate_token 会影响哪些函数？"}'对前面极小的示例仓库来说，正常回答应该包含：AuthService.login和create_token，并且回答会说明影响路径是validate_token <- login。如果回答只给出validate_token自己的定义，说明图扩展阶段没有生效，要去查调用边是否建立成功。
5.3 对比纯向量 RAG 的效果差异
把同样的测试数据跑一组对照实验：一组只做向量切块检索，一组使用code-graph-rag的图扩展。对比项至少包括：
| 测试问题 | 纯向量 RAG | code-graph-rag |
|---|---|---|
| 某个函数定义在哪个文件 | 能回答 | 能回答 |
| 某个函数被哪些地方调用 | 依赖代码注释，容易漏 | 图查询直接列出调用方 |
| 修改 A 影响哪些模块 | 难以回答 | 调用链和导入链可推导 |
| 两个函数的调用层级 | 靠运气命中 | 多跳查询可复现 |
这个对照实验建议保留成测试用例，因为后续改索引策略或图结构时，能快速判断效果是变好还是变差。
6. 常见问题排查
6.1 解析不到符号或跨文件引用
现象：索引里缺了一部分函数，或者调用边明显缺失。
可能原因：
- tree-sitter grammar 未匹配实际语言版本；
- 代码是通过装饰器、代码生成或反射动态定义的；
- import 别名和目标符号的映射没有处理。
排查顺序：
- 先用可视化或调试输出检查 AST 里是否出现目标节点类型；
- 单独解析一个包含跨文件 import 的文件，确认关系抽取逻辑；
- 检查符号 ID 是否包含完整文件前缀，避免同名函数互相覆盖。
处理建议：给解析器加失败日志，记录没有识别出的文件类型和语法结构；动态调用关系先用“候选调用”标记，不要直接丢弃。
6.2 图查询耗时过大
现象：增加graph_depth后响应变慢，甚至超时。
可能原因：图的出边和入边太多，尤其是工具函数会被大量组件调用，导致邻居数量指数级增长。
检查方式：查询热点节点统计，看哪些函数被超过 100 个节点调用。
处理建议：限制单层邻居上限；先做向量召回缩小种子范围；对公共工具函数单独做摘要节点，不让每个调用方都展开完整实现。
6.3 检索结果和代码上下文对不上
现象：大模型回答里提到一个函数，但该函数并不是当前检索链路里的活跃节点。
可能原因：embedding 模型对不同语言符号的区分度不稳定，或者提示词模板里没有约束模型只能使用提供节点。
处理建议：在提示词里加硬约束“只能基于给定节点回答”；回答中引用节点时要求给出符号 ID；在 API 响应里返回context_nodes，方便定位是哪一步检索出了问题。
6.4 大模型回答引用了错误文件
现象：回答内容合理，但提到的文件路径或行号与真实代码不符。
可能原因：图节点摘要里包含过多代码噪音，模型被相似代码误导；或者向量召回的 TopK 中混入了多个相似函数。
检查方式：打印context_nodes，看真实传给模型的节点是否已经包含错误文件。
处理建议：在节点摘要中加入“文件路径 + 符号 ID + 签名”作为前缀，提高区分度；生产环境可以把 rerank 模型加入链路，对召回结果做二次排序。
7. 生产落地建议与扩展方向
7.1 从实验到生产要补的基础能力
code-graph-rag在本地小仓库跑通只是第一步，进入生产环境还要补齐这些能力：
- 配置外置化，包括 llm 地址、embedding 模型、图数据库连接串、索引路径；
- 日志和监控，至少记录解析耗时、索引数量、检索耗时、生成耗时；
- 权限控制，代码图谱和提示词涉及业务源码时，要控制访问范围和审计；
- 回滚机制，索引或图数据更新后要能切回上一版本；
- 资源评估，图节点量和向量量增长后，内存、磁盘和显存都要重新评估。
7.2 增量更新与多分支处理
生产代码库变化很快，每次全量重建既慢又浪费资源。建议把解析结果按文件哈希做增量判断：文件没变就复用旧节点，文件变了才重新解析并更新相关边。多分支并行时，可以按分支名建独立的命名空间，避免不同分支的符号互相覆盖。这个问题不解决，问答服务上线后维护成本会比开发成本还高。
7.3 和 Agent、MCP 结合后的进一步扩展
code-graph-rag的图结构本身是一种比较理想化的“外部工具”。把它封装成 MCP 工具后，Agent 可以在不提前知道答案的情况下按需调用：先查调用链，再读源码，再改代码，最后生成说明。这个方向比单纯的问答更进一步，也是 RAG 从“被动回答问题”向“主动完成任务”演进时，GraphRAG 相比普通向量 RAG 更有优势的地方。
同时可以引入重排模型优化召回顺序，并在回答里保留引用溯源，输出每个结论对应的符号 ID、文件路径和调用路径。引用溯源做得越细，问答结果的可信度越高，调试成本也越低。这套能力做完后，code-graph-rag就不再只是一个问答 Demo，而是可以嵌入开发流程的代码理解基础设施。对一个刚开始做代码 GraphRAG 的团队来说，先用小仓库把解析、建图、检索、生成四层链路跑通，再逐步替换存储方案和处理更大规模代码库，是比较稳妥的路线。
