企业官网建设流程全解析

很多做代码问答、代码搜索的开发者，应该已经试过把代码库丢给通用 RAG 方案。早期 demo 跑起来很惊艳，但一旦放到真实项目里，问题就出来了：问“这个订单流程里，谁调用了支付接口”，它可能给你找出一堆不相干的相似文件；问“改这个函数会影响哪些模块”，它给出的上下文又总是缺了关键的调用链。问题不在 embedding 模型，也不在 LLM，而在我们把代码当成了“散文”去检索。

Code Graph RAG 这类方案的核心判断是：代码库的语义，不是一堆孤立文件语义的叠加，而是由调用关系、依赖关系、继承关系、引用关系构成的图结构。只有把代码先解析成一张知识图谱，让检索同时发生在“语义空间”和“图结构空间”，代码 RAG 才能真正回答“谁影响谁、谁被谁调用、改这里会波及哪里”这类结构性问题。本文会先从传统代码检索和普通 RAG 的失效点讲起，再拆解 code-graph-rag 的核心原理、最小实现、验证方法和工程坑位。读完后，你可以搭建一个能跑通的最小代码图谱问答 demo，并知道怎么把它扩展成团队可用的工具。

1. 这篇文章真正要解决的问题

先想清楚一个场景：你接手的项目有几十万行代码，分布在几十个模块里。你现在的需求是“把这个项目里的核心支付流程梳理清楚，并回答后续新人的提问”。传统做法有两条路。

第一条是 grep / IDE 全局搜索。它能找到字符串、符号名，但无法回答跨文件、跨模块的调用链问题。你搜一个函数名，得到一堆引用位置，哪个是入口、哪个是回调、哪条是异步链路，还是得靠人肉点开一个个文件看。

第二条是把所有代码切片后丢进向量数据库，做普通 RAG。这种方式对“这个函数是干什么的”这类局部问题有点效果，但面对“修改 A 模块会影响到哪些下游服务”这类依赖关系问题，召回结果往往是把语义相似的片段堆给你。而语义相似不等于结构相关，很多被影响的模块跟触发点之间，并不存在文本层面的相似性。

Code Graph RAG 要解决的，正是传统方案的第三个盲区：把代码库中“语义相似”和“结构相关”分开，用图谱捕获结构相关，用向量检索捕获语义相似，两者结合后再让大模型回答问题。如果你正在做代码库问答、AI 代码评审、智能文档、代码搜索、甚至 Agent 自动改代码，这篇文章的内容会直接帮你少走两个月的弯路。

2. Code Graph RAG 的核心概念与原理

2.1 RAG：先别急着把代码切片

RAG 的标准流程我们很熟：文档切块、向量化、检索 top-k、拼接 prompt、喂给大模型。这个流程处理普通文章没问题，因为文章的信息基本是线性的，一段话的上下文通常在前文和后文里。

但代码是强结构的。函数 A 调用了函数 B，B 定义在另一个文件里，A 和 B 的文本内容可能完全不像，但它们在编译和运行上有着确定性的强关联。如果切片时把一个函数拆成两半，把类的定义和方法的实现切到不同块里，检索效果会直线下降。普通 RAG 的 bge 模型和 OpenAI embedding 都学不到这种结构关系，因为它们的训练目标就是语义相似度，不是调用关系。

所以代码 RAG 的第一个前提是：不能按字符长度切片，必须按语法单元切片。最小单位至少是函数、类、方法，同时保留它们所在文件的路径和层级。

2.2 代码知识图谱：节点和边到底是什么

Graph RAG 的核心是把实体和关系显式建模。在代码场景里，图谱的节点和边可以这样定义：

有了这张图，一个复杂问题就可以转化为图查询：问“谁调用了create_order”，直接查这个节点的入边；问“改OrderService会波及哪些模块”，从该节点出发做 BFS，收集所有可达模块。

2.3 双通道检索：语义召回 + 图扩展

Code Graph RAG 与传统 RAG 最大的区别是检索策略。普通 RAG 是“一个问题 → embedding 相似度 → top-k 片段”。Code Graph RAG 是：

1. 用自然语言问题向量化，召回若干种子节点（可能是函数、类或文件）。
2. 以种子节点为中心，在图谱上做邻居扩展，拿到调用链、依赖边、引用路径。
3. 把图扩展得到的结构上下文和向量召回得到的文档片段一起拼进 prompt。

这个设计非常关键。语义召回负责“定位”，图扩展负责“还原结构性上下文”。后者解决的正是普通 RAG 最薄弱的跨文件依赖问题。理解这一点之后，你再看任何 code-graph-rag 类项目，都只是在“建图质量”和“检索策略”上做文章。

2.4 与传统方案对比

结论很直接：如果你的目标只是“大概能回答代码相关问题”，普通 RAG 够了；如果目标是“让 AI 理解代码库的结构，回答准确且可验证”，图结构这一步是绕不开的。

3. 环境准备与前置条件

3.1 语言与工具选型

本文演示以 Python 为主，因为图谱处理和原型验证的生态最成熟。你不需要一开始就上大型框架，用下面几个库就能跑通最小闭环：

• Python 3.9+，版本以你实际环境为准
• networkx：图存储与图遍历
• tree-sitter或其 Python 封装：解析多种语言的代码语法树，推荐用于真实项目
• 一个 embedding 模型：OpenAI 的 text-embedding 系列或本地模型均可，本示例以接口调用为例
• 一个 LLM 接口：用于最终答案生成，按你公司的合规渠道接入
• 可选：LlamaIndex / LangChain，它们已封装若干检索组件，但不强制

这里特别提醒：tree-sitter 的 API 版本更新较快，不同语言绑定用法略有差异。本文示例会展示核心思路，具体函数名以你安装的版本为准。

3.2 安装依赖

pip install networkx tree-sitter tree-sitter-python requests

如果你希望用本地 embedding 模型，可以加一个sentence-transformers。但如果公司已有统一的 embedding 服务，优先复用，避免本地模型部署的额外运维成本。

4. 构建代码知识图谱的核心流程

建图是整个 code-graph-rag 的基石。图的质量直接决定后续检索效果。建图流程可以拆成四步：解析源码、提取符号、建立关系、写入图谱。

4.1 用 AST 解析函数和类

先拿 Python 内置的ast模块做一个轻量版解析。它能提取函数、类、导入关系，适合快速原型。真实项目建议换 tree-sitter，原理一致。

# 文件路径：code_graph_rag/parser.py import ast from pathlib import Path def parse_python_file(filepath): """解析一个 Python 文件，返回其中的函数、类、导入信息。""" code = Path(filepath).read_text(encoding='utf-8') tree = ast.parse(code) functions = [] classes = [] imports = [] for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): functions.append({ 'name': node.name, 'lineno': node.lineno, 'end_lineno': getattr(node, 'end_lineno', node.lineno), }) elif isinstance(node, ast.ClassDef): class_info = { 'name': node.name, 'lineno': node.lineno, 'end_lineno': getattr(node, 'end_lineno', node.lineno), 'methods': [], } for child in node.body: if isinstance(child, ast.FunctionDef): class_info['methods'].append(child.name) classes.append(class_info) elif isinstance(node, ast.Import): for alias in node.names: imports.append(alias.name) elif isinstance(node, ast.ImportFrom): module = node.module or '' for alias in node.names: imports.append(f'{module}.{alias.name}') return { 'filepath': filepath, 'functions': functions, 'classes': classes, 'imports': imports, }

这段代码做了三件事：遍历 AST 找出函数和类，同时抓取 import 语句。它是后续建图的数据来源。

4.2 建立文件、类、函数节点和关系边

拿到每个文件的符号信息后，就可以构建图了。这里用 networkx 保存所有节点和边。

# 文件路径：code_graph_rag/graph_builder.py import networkx as nx from code_graph_rag.parser import parse_python_file def build_graph(file_list): """传入文件路径列表，构建代码知识图谱。""" graph = nx.MultiDiGraph() for filepath in file_list: info = parse_python_file(filepath) # 文件节点 file_node = f'file:{filepath}' graph.add_node(file_node, type='file', path=filepath) for func in info['functions']: func_node = f'func:{filepath}::{func["name"]}' graph.add_node(func_node, type='function', name=func['name']) graph.add_edge(file_node, func_node, relation='defines') for cls in info['classes']: cls_node = f'class:{filepath}::{cls["name"]}' graph.add_node(cls_node, type='class', name=cls['name']) graph.add_edge(file_node, cls_node, relation='defines') for method in cls['methods']: method_node = f'func:{filepath}::{cls["name"]}.{method}' graph.add_node(method_node, type='method', name=method) graph.add_edge(cls_node, method_node, relation='has_method') for imp in info['imports']: graph.add_node(f'module:{imp}', type='module', name=imp) graph.add_edge(file_node, f'module:{imp}', relation='imports') return graph

这里有一个新手很容易忽略的点：节点 ID 必须唯一且可溯源。func:{filepath}::{func_name}这种设计，保证同一函数在后续检索时能直接定位到文件路径和行号，RAG 回答时才能给出准确的代码位置。

调用关系的抽取在真实项目中要结合 AST 里的Call节点，代码量会大不少。原型阶段可以先用 import 和定义关系跑通，再逐步补调用关系。

4.3 写入向量索引

图建好后，还要给每个节点做向量化，才能支持“自然语言 → 种子节点”的召回。这一步把函数签名、注释、docstring、代码片段拼成一段文本，调用 embedding 接口得到向量。

# 文件路径：code_graph_rag/indexer.py def build_node_text(node_id, node_data, source_cache): """把图谱节点的上下文拼成用于 embedding 的文本。""" node_type = node_data.get('type', '') name = node_data.get('name', '') path = node_data.get('path', '') if node_type == 'func' or node_type == 'method': code = source_cache.get(node_id, '') return f"function: {name}\nfile: {path}\ncode:\n{code[:2000]}" elif node_type == 'class': return f"class: {name}\nfile: {path}" elif node_type == 'file': return f"file: {path}" return f"{node_type}: {name}"

实际项目中，向量化建议放到建图阶段一起做。先在本地把所有源码缓存成node_id -> code_text的映射，再批量调用 embedding。不要边遍历边调用 API，效率和成本都不可控。

5. 图检索 + RAG 问答实现

图建好、向量索引建好之后，就到了关键一步：如何把自然语言问题变成图谱上的查询，再组织成高质量上下文喂给 LLM。

5.1 双通道检索流程

我用一个实际例子来说明。假设代码库里有OrderService.create_order()、PaymentService.pay()、InventoryService.deduct()，用户的问题是：“创建订单的流程中，支付和库存扣减是怎么被调用的？”

普通 RAG 会把问题 embedding，检索到一批代码片段，但很可能漏掉调用链。Code Graph RAG 的流程是这样：

1. 向量检索召回种子节点。这里可能召回OrderService.create_order和PaymentService.pay。
2. 以种子节点为中心，在图谱上做 BFS，扩展层级建议 2 到 3 层。拿到OrderService -> pay -> deduct路径。
3. 把路径上的节点文本和边关系拼成上下文。
4. 将上下文和问题一起发送给 LLM。

下面这段代码演示了“种子节点 + BFS 扩展”的核心逻辑。

# 文件路径：code_graph_rag/retriever.py import networkx as nx def graph_expand(graph, seed_nodes, depth=2): """从种子节点出发，扩展图上的邻居节点。""" visited = set() result_nodes = set(seed_nodes) for node in seed_nodes: if node not in graph: continue # 以节点为中心，按深度做遍历 for neighbor in nx.single_source_shortest_path(graph, node, cutoff=depth): visited.add(neighbor) return visited def build_context_from_nodes(graph, nodes): """把一组图节点转换成可读的文本上下文。""" lines = [] for node in sorted(nodes): data = graph.nodes[node] node_type = data.get('type', 'unknown') name = data.get('name', '') path = data.get('path', '') lines.append(f"[{node_type}] {name} ({path})") return "\n".join(lines)

实际工程里，BFS 不能无限制扩展。深度超过 3 层后，召回内容往往超出上下文窗口，而且回答的聚焦度会明显下降。更稳妥的做法是先做向量召回 top-5 个种子节点，再分别做 2 层邻居扩展，最后按路径相关性过滤一遍。

5.2 组装 Prompt 并调用 LLM

拿到上下文后，把图结构信息和代码片段一起放入 prompt。设计 prompt 时要明确要求模型基于给出的路径回答问题，并把引用到的文件路径列出来。这样做有两个好处：一是减少幻觉，二是让回答可以人工验证。

# 文件路径：code_graph_rag/qa.py def build_rag_prompt(question, context_text, code_snippets): prompt = f"""你是一个代码库理解助手。请根据下面的调用路径和代码片段回答问题。 ## 调用路径 {context_text} ## 关键代码 {code_snippets} ## 问题 {question} 要求： 1. 先直接回答问题。 2. 给出依据时，必须引用具体文件路径和函数名。 3. 如果信息不足，请明确说“图谱中未找到足够证据”，不要猜测。 回答：""" return prompt

LLM 调用环节，建议把 embedding 接口和 LLM 接口都封装成独立的 client。这样切换模型供应商时不需要改上层的图谱逻辑。内部实现代码我就不在这里展开，关键在于所有外部调用都要做超时、重试和日志记录。

5.3 让图谱中的调用关系更完整

前面我们用 AST 里提取了函数和类，但函数之间的call关系还没有建立。这一步在真实项目中价值最高，也最容易做。以 Python 为例，ast.Call节点的func是一个ast.Name或ast.Attribute，可以从中提取被调用的函数名。然后在同一文件作用域内，把函数名映射到函数节点，建立call边。

# 文件路径：code_graph_rag/call_graph.py import ast from pathlib import Path def extract_calls_from_file(filepath): """提取文件内定义的函数及其调用的函数名。""" code = Path(filepath).read_text(encoding='utf-8') tree = ast.parse(code) calls = [] for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): func_name = node.name called = [] for child in ast.walk(node): if isinstance(child, ast.Call): if isinstance(child.func, ast.Name): called.append(child.func.id) elif isinstance(child.func, ast.Attribute): called.append(child.func.attr) calls.append((func_name, called)) return calls

这个实现能捕获“函数名级别的调用”，跨文件调用需要结合 import 映射和类的完整限定名，复杂度会上一个台阶。但这正是 code-graph-rag 风格方案的可演进方向：先粗后细，先跑通链路再逐步增强建图准确率。

6. 运行结果与效果验证

6.1 运行命令

假设你已经把所有代码放入code_graph_rag/目录，并写好一个统一入口，可以这样运行：

python -m code_graph_rag.cli \ --repo-path ./sample_project \ --question "create_order 函数为什么会调用 pay 方法？"

实际输出可能长这样：

[Retriever] 向量召回种子节点： - func:./sample_project/services/order_service.py::create_order - func:./sample_project/services/payment_service.py::pay [Graph] BFS 扩展节点数：24 [Graph] 扩展路径： create_order -> pay (call) pay -> deduct_stock (call) [LLM] 回答： 创建订单时，OrderService.create_order 会调用 PaymentService.pay 完成支付， 支付成功后接着调用 InventoryService.deduct_stock 扣减库存。 依据： ./sample_project/services/order_service.py 第 12 行 ./sample_project/services/payment_service.py 第 45 行

6.2 如何判断成功

一个合格的 code-graph-rag 问答，至少要满足三点：

1. 回答中提到的每个函数和文件路径，都能在图谱节点里找到对应实体。
2. 涉及“影响范围”“调用链”“依赖”的问题，回答能落到具体路径，而不是泛泛而谈。
3. 当图谱里没有足够信息时，模型能承认信息不足。

如果运行失败，第一步先看图谱构建阶段有没有解析报错。代码解析是最容易出问题的地方，尤其是 Python 版本语法兼容性、某些动态生成的代码文件、以及超过内存限制的超大文件。

7. 常见问题与排查思路

这些坑位里，比较隐蔽的是“图谱更新”。很多团队搭完 demo 后没有建立增量更新机制，代码库一变更，图谱就成了过时数据，回答自然出错。生产环境必须把建图接入 CI/CD 或者在 Git 提交后触发增量重建。

8. 最佳实践与工程建议

8.1 从小范围试点开始

不建议一开始就对全公司的大仓库做全量建图。代码动辄几十万文件，解析、向量化、图谱存储都有成本。先从核心业务模块拉出一个子图，验证效果和性能指标，再逐步扩展。小范围的另外一个好处是图谱质量更容易人工 review，能快速发现节点和边定义的问题。

8.2 把图谱、向量索引与代码版本绑定

每次建图都要记录对应的 commit 或 branch。检索时优先使用与当前代码版本匹配的图谱。如果做不到实时更新，至少要保证图谱版本和代码版本有映射关系。反过来，回答问题时也能指出“基于 2024-03-01 的提交 8f3a2b 分析”，让使用者知道时效边界。

8.3 明确图节点与代码权限边界

代码图谱是把全仓库的符号信息集中存储。在生产环境中，要注意仓库访问权限和机密代码的暴露范围。如果团队里有人只允许访问部分代码，他通过 RAG 问答可能间接获知他本不该看到的类名、模块名和调用路径。建图前要梳理权限边界，必要时对文件路径做黑名单或按权限生成不同的子图。

8.4 检索日志是调优的核心资产

记录每一次“问题 → 召回种子节点 → 图扩展路径 → LLM 回答”，然后定期翻看。你会很快发现三类问题：种子节点召回不准、图扩展路径太长、prompt 引导不够。这些都是可以迭代优化的方向，没有日志就无法定位。建议在检索引擎里默认开启 trace 级别的结构化日志。

8.5 考虑增量更新

增量更新是生产化绕不开的话题。最简单的做法是结合 Git 历史，只重新解析变更过的文件，并只更新受影响节点和边。如果变更涉及跨文件调用，还需要级联更新。能接受较粗粒度的话，可以用“每日全量 + 实时增量”的组合，降低增量解析的复杂度。

8.6 评测集先行

在投入大量时间优化图谱之前，先准备一个评测集。可以从真实开发问题中挑 30 到 50 个问题，标注标准答案和答案来源文件。每改动一次检索策略或图谱构建逻辑，都跑一遍评测集，量化回答准确率的变化。这种做法能避免“凭感觉优化”的状态。评测集不必一开始就追求规模，关键是覆盖几类典型问题：局部功能理解、跨文件调用链、影响范围分析、异常路径查找。

9. 总结与后续学习方向

Code Graph RAG 的核心不是换一个新的 RAG 框架，而是把“代码库是结构化知识”这个常识真正落到系统设计里。当检索从单一向量相似度，变成“向量召回种子 + 图结构扩展”的双通道模式后，代码问答的准确率和可解释性都会有质的提升。本文从 AST 解析、图谱构建、向量化、双通道检索到 LLM 问答组装，覆盖了一个最小完整闭环。顺着这条路，你下一步可以做三件事：第一，用一个小型开源项目跑通整套流程；第二，建立 30 道题的代码问答评测集；第三，把调用关系解析从单文件层面升级到全量跨文件。这个方向后续还可以延伸到代码变更影响分析、Agent 自动代码修复、新员工代码培训等场景。建议先把最小 demo 落地，再按业务痛点逐步增强建图和检索能力。