Graphify：为代码库构建知识图谱，以图遍历替代向量检索

Graphify 是一个 Python 工具，同时也是一个 Claude Code skill。它把分析工作一次性做完，把所有内容压缩成一张可查询的知识图谱，放到磁盘上。后续查询走图谱遍历，不再重新读取原始文件。项目简介的数字是：在混合语料库上每次查询的 token 量降低 71.5 倍。虽然这个数字是项目方自己测的是否站得住脚还要验证，但是他的底层架构思路比同类工具普遍要更细致一些。

大型代码库的 Token 税

上下文窗口一直在在变大——Claude Sonnet 4.6 支持 200K，GPT-5.4 已经到 1M——但麻烦的从来不是窗口大小而是成本和延迟。如果每次查询都把 200 个文件喂进去不仅贵而且慢；而且对任何一个具体问题来说，那 200 个文件里的绝大多数信息都是无关的。等于为了找一个段落把整座图书馆搬过来。

业界的标准答案是 RAG：把文件切块、嵌入、丢进向量库，查询时取 top-K 块。对散文类文档，RAG 工作得很好——语义相似度本身就是一个靠谱的检索信号。但对代码就不一样了：函数和它的调用者之间的关系是结构性的，不是语义性的。"process_payment 调用 validate_card"这种事实不存在于嵌入空间里，它存在于调用图里。

Graphify 的方法不一样，他不嵌入文件、不靠相似度检索，而是把实体和关系建成一张显式图谱，查询时在图上做遍历。这种方式其实更接近一个资深工程师摸陌生代码库的方式——先在脑子里搭起系统的结构，再顺着结构走，而不是对源代码做一次模糊搜索。

Graphify 产出什么

在某个目录下跑一次 /graphify，会在 graphify-out/ 目录里生成几样东西：一个用 vis.js 渲染的交互式 HTML 图谱，节点是实体（函数、类、概念、文档章节），边是关系（调用、import、引用、推断出来的依赖）；一份用于程序化查询的持久化 JSON 图谱；一份 Markdown 报告，标出度数高的节点和社区聚类。可选输出还包括 Obsidian vault、Neo4j 数据库、SVG、GraphML 文件，以及把整张图谱作为 LLM 可调用工具暴露出来的 MCP server。

聚类用的是 Leiden 社区检测算法。一个同时包含 auth、billing 和 infra 模块的 monorepo，Graphify 会自动把这三块识别成不同的社区，并把它们之间的桥接节点显式标出来。

三套不同的数据处理逻辑

理解 Graphify 最关键的部分就是，它不会用同一种方式对待所有文件类型——三个 pass 各跑各的，每一个的数据驻留策略也完全不一样。

Pass 1：确定性 AST 提取（代码不出本机）

源代码文件交给 tree-sitter，一个基于规则的确定性解析器。可以把它理解为编译器的前端：读文件、套形式语法、吐出语法树。整个过程没有语言模型介入，没有任何网络调用，源代码不会离开你的机器。

tree-sitter 支持 23 种语言，Python、TypeScript、JavaScript、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP 都在内。输出是一组节点和边的字典，把源文本中显式存在的每一个函数、类、import 和调用关系都编码出来。

这一步重要在两点。一是免费，没有 API 成本；二是精确——AST 提取出的关系会带上 EXTRACTED 置信度标签，意味着它们是事实，不是猜测。

Pass 2：本地音频转录（录音也不出本机）

把 Graphify 指向一个含有音频或视频的目录，它会用 faster-whisper 在本机完成转录，音频不上传到任何地方。这个 pass 是可选的，需要装 graphifyy[video]：

pip install "graphifyy[video]"

faster-whisper 是 OpenAI Whisper 模型的 CTranslate2 加速实现。在一台普通笔记本上，转录一小时的会议音频只要几分钟。生成的转录文本会作为文档节点喂进图谱，和别的文本一视同仁。

Pass 3：语义提取（文档和图像会发到你的 AI API）

文档（Markdown、PDF、RST）和图像（PNG、JPG、WebP、GIF）没法用语法解析——它们的结构是语义层面的，不是句法层面的。要从一张白板照片或一份研究 PDF 里提取实体和关系，Graphify 会调用你已经配好的 AI 平台，可能是 Anthropic、OpenAI 或别的。

关键词是"你的"。Graphify 用的是你 AI 平台环境里已经配好的凭证，没有中央中继服务器。流量从你的机器直接发到 Anthropic（或者 OpenAI 等等），用的就是你日常给编码助手用的那把 API key。

Graphify 自己什么都不收。SECURITY.md 写得很直白："在图谱分析期间不发起任何网络调用。"项目同时声明：没有遥测、没有使用追踪、没有任何形式的分析。Graphify 也不存凭证。

完整的数据流大致如下。

需要点出的细节：你的 AI 提供商（Anthropic、OpenAI）确实会看到你的文档和图像内容，约束条件是你和它们之间的 API 协议。如果文档里有敏感信息，跑 Pass 3 之前先翻一遍提供商的数据处理政策。也可以把 Graphify 限制成仅代码模式，把 Pass 3 整个跳过。

置信度系统：知道图谱"知道"到什么程度

图谱里的每条边都带一个置信度标签，三选一。这是一个看起来很小的设计决定，落到使用上影响很大。

EXTRACTED 表示这条关系在源代码里是显式存在的。validate_card 被 process_payment 调用，这写在 AST 里，可以直接信任。

INFERRED 表示这条关系是模型从上下文推理出来的。语义提取器看到 PaymentService 和 FraudDetector 在文档里总是一起出现，于是推断出一条依赖。可能对，也可能只是巧合。

AMBIGUOUS 表示模型自己也拿不准。这类边会留在图谱里，但没有人工复核就不应该被拿去做判断依据。

打个比方：EXTRACTED 像带页码的引文，INFERRED 像一句"另见某处"的脚注，AMBIGUOUS 像贴了张"再核实一下"的便签。Graphify 的做法是把三种都给你，并打好标签；它没有把所有东西包装成一副笃定的样子。

上手

这个包需要Python 3.10+，安装好 Claude Code。

# 安装包
pip install graphifyy
# 把 skill 注册到你的 AI 平台
graphify install

graphify install 会探测你已配置的平台，把 skill 定义注入到对应的配置文件里——比如 Claude Code 的 ~/.claude/CLAUDE.md。

可选依赖按需装：

# 本地音频/视频转录
pip install "graphifyy[video]"
# Microsoft Office 文件支持（.docx、.xlsx）
pip install "graphifyy[office]"
# MCP server（把图谱作为 LLM 工具暴露）
pip install "graphifyy[mcp]"
# 一次装全
pip install "graphifyy[all]"

运行命令：

# 在 AI 助手里对当前目录做标准分析
/graphify
# 深度模式：更激进的关系推断
/graphify --deep
# 处理特定子目录
/graphify ./src/auth
# Watch 模式：文件变化时重建图谱
/graphify --watch
# 查询已有图谱
/graphify query "how does user authentication flow through the system?"
# 查找两个实体之间的最短路径
/graphify path "UserService" "DatabasePool"
# 用自然语言解释某个实体
/graphify explain "PaymentProcessor"

后续运行时，Graphify 会比对 SHA256 哈希——只有改动过的文件会被重新处理。第一次导入是贵的那一次，重复查询很便宜。

也可以让它接管 git hook，每次提交都自动重建图谱：

# 在仓库内，Graphify 可以安装自己的 git hooks
/graphify --install-hooks

之后 git commit 或 git checkout 都会触发一次增量更新，AI 助手看到的图谱永远对应当前分支的状态。

关于 71.5× 这个数字

README 里写的是：在混合语料库上，相比直接读原始文件，Graphify 把 token 用量降低了 71.5 倍。这个数字来自项目自己的 worked/ 目录是在精挑过的数据集上跑出来的。

只从架构上讲这个倍数是合理的。一个一万个函数的代码库，问"什么调用了 process_payment？"，图谱遍历返回的是几个节点 ID；读原始文件回答同一个问题，得把所有可能包含答案的文件都加载进来。具体倍数完全取决于语料库规模和查询的精确度——稀疏的、结构性的查询收益最大，宽泛的概念性查询收益要小得多。

但是如果在公共测试集上把 Graphify 的图谱查询和原始文件、RAG 这两个基线放在一起做的独立基准。这种基准出现之前，71.5× 可能就是一个参考了，，因为实际倍数会随语料库规模、文件类型组合和查询模式而变。

Graphify 适合什么场景

适合：同一个仓库里既有代码、又有架构文档、设计 PDF 和录制会议这种混合媒体项目；在稳定的代码库上反复查询的场景，因为缓存收益会随时间累积；用 Claude Code 做编码助手、想压低单次会话 API 成本的团队；调用图复杂、语义搜索吃力的项目，比如深层继承链或大量基于回调的架构。

不太适合的也很清楚：文件不到 20 个的新项目，图谱本身的开销不划算；内容几乎全是散文文档的仓库，对开放式语义问题，扁平 RAG 大概率跑得过图谱遍历；AI 提供商的数据政策禁止把文档内容发给其 API 的环境——文档和图像走的就是 Pass 3，绕不开；以及需要可验证、可复现分析的项目，INFERRED 和 AMBIGUOUS 边如果照单全收，会把人带偏。

几个值得注意的局限

Graphify 是个人开源项目，目前版本 v0.4.10，没有机构背书。开发是活跃的，但是目前看长期维护怎么样不好说。如果要把它放进生产工具链，得保留一点谨慎。

包名也有点小问题：工具叫 graphify，PyPI 上的包却是 graphifyy（双 y）。README 说这是临时状态。安装前请先确认当前的规范包名——热门开发工具被抢注名字这种事不少见。

接下来值得关注的方向

MCP server 集成这块值得盯着。随着 MCP 在各类 AI 编码助手里逐步铺开，Graphify 把代码库图谱作为一组 LLM 可调用工具暴露出来的能力，会变成自主 agent 的一块基础设施——那些 agent 真正需要的，是对代码库的结构化理解，而不只是文件搜索。

https://avoid.overfit.cn/post/09e247ff0dc7461b84106a7486e05d06

作者：Mustafa Genc