一、AI 编程的上下文危机

用 AI 写代码越久，你越可能撞上同一堵墙：上下文不够用。

一个中等规模的代码仓库轻松几十万行，而即使是最好的模型，上下文窗口也不过 200K token。你把关键文件一个一个拖进对话，模型终于理解了，但 token 预算已经烧掉一半。更糟的是，纯文本拼接丢失了文件之间的关系——哪个函数调用了哪个模块？这段注释是在解释哪段逻辑？数据流从哪里进来、从哪里出去？

Andrej Karpathy 在 2026 年初分享了他的应对策略——/raw 笔记法：手动维护一个项目笔记文件，每次对话时加载，用完之后更新。这个方法有效，但本质上是在用人脑充当"关系数据库"。

有没有一种方式，能让机器自动理解代码库的结构和语义，用极少的 token 精准回答你的问题？

这就是 Graphify 要解决的问题。

二、Graphify 是什么

Graphify 是一个开源（MIT 协议）的知识图谱构建工具，由伦敦 Valent 公司的 AI 研究员 Safi Shamsi 于 2026 年 4 月发布，GitHub 上已获得超过 36,000 颗星。

它的核心能力用一句话概括：

把任意文件夹（代码、文档、论文、图片、视频）自动转化为一张可查询的知识图谱，用图遍历替代向量检索。

与传统的 RAG（检索增强生成）方案不同，Graphify 不走"embedding → 向量数据库 → 相似度搜索"这条路线。它选择了一条更"古典"的路径：静态分析 + 符号关系 + 图算法。

Graphify 三阶段流水线

2.1 三阶段处理流水线

阶段 做什么 Token 消耗
Pass 1: AST 静态分析 基于 tree-sitter 解析 25 种编程语言，提取函数、类、调用图、import 关系、注释中的语义描述 零
Pass 2: 本地音频转录 使用 faster-whisper 在本地转录音视频文件，音频数据不离开本机 零
Pass 3: LLM 语义提取 通过子代理并行处理文档、图片、转录文本，提取概念实体和跨文件关系 仅首次构建消耗

这个设计有一个关键洞察：能确定的东西就不要猜。

对于源代码，tree-sitter 能 100% 准确地告诉你"函数 A 调用了函数 B"。这不需要 LLM，不需要 GPU，不需要 API 调用。Pass 1 和 Pass 2 全程在本地执行，不消耗任何 token。

只有到了 Pass 3，面对自然语言文档、图片中的流程图、会议录音中的讨论时，才引入 LLM 来提取结构化概念。

2.2 三级置信度标签

Graphify 不把分析结果一概而论。图谱中的每条边和每个节点都带有一个置信度标签：

这种分级机制让 Graphify 的图谱始终可审计——你知道哪些是可以直接信任的，哪些只是模型的推测。

2.3 核心设计取舍

Graphify 做出了一个与主流趋势相反的架构选择：用 Leiden 社区发现算法（一种基于图拓扑密度的聚类算法）而非向量相似度来做知识聚类。

这意味着什么？

三、安装与快速上手

3.1 安装

pip install graphifyy          # 安装 Python 包
graphify install               # 注册到 AI 编程平台

graphify install 会在 Claude Code、Codex、Cursor 等支持的平台中注册 /graphify 命令。整个过程不修改系统 PATH，不启动后台进程。

3.2 首次使用

在你的项目根目录下，直接在 AI 助手中输入：

/graphify .

Graphify 会扫描当前目录下的所有文件，运行三阶段流水线，生成一个知识图谱。首次构建的速度取决于项目大小——一个 5 万行的 Python 项目大约需要 1-2 分钟。

3.3 输出产物

构建完成后，你会在项目根目录看到 graphify-out/：

graphify-out/
├── graph.html          # 交互式可视化图谱（基于 vis.js，可在浏览器中直接打开）
├── GRAPH_REPORT.md     # 可读的报告：关键节点、意外连接、建议的查询问题
├── graph.json          # 持久化图谱数据，可跨会话复用
└── cache/              # SHA256 缓存，重复运行只处理变更文件

打开 graph.html 你会看到一张完整的项目知识图谱——每个函数、类、模块都是一个节点，它们之间的调用、依赖、继承关系是边。你可以缩放、拖拽、搜索、点击节点查看详情。

四、核心机制深入

4.1 为什么是图，不是向量？

RAG 的典型做法是：把文档切成 chunk → 生成 embedding → 存入向量数据库 → 查询时做相似度搜索。这套方案非常成熟，但有一个根本问题——丢失了结构。

举个例子。你问"认证模块的 JWT 过期时间在哪里配置？"

向量检索擅长语义近似，图遍历擅长精确的关系追踪。在代码库场景中，后者往往更有效。

4.2 Leiden 聚类：无需向量的语义分组

Leiden 算法是 Louvain 算法的改进版，用于在大型网络中识别社区结构。Graphify 用它来为图谱做聚类：

  1. 构建一张有向图，节点是代码实体，边是它们之间的关系（调用、包含、继承、引用）
  2. Leiden 算法基于边的密度进行社区划分——同一"社区"内的节点之间有更多的连接
  3. 聚类结果中，你通常会看到天然的模块边界：认证相关的一组节点、数据库层的一组节点、API 路由的一组节点……

这种聚类完全不依赖语义——完全基于代码的结构关系。它的副作用是：聚类结果本身就是一种架构分析。

4.3 SHA256 增量缓存

Graphify 对每个文件计算 SHA256 哈希值。当你修改代码后再次运行 /graphify：

对于日常开发中只改了几个文件的情况，增量更新通常在秒级完成。

4.4 71.5 倍 Token 压缩的实验验证

Graphify 官方在一个混合了 Karpathy 仓库代码、论文 PDF 和图片的 52 文件语料上做了测试：

方式 Token 消耗
直接读取所有原始文件 基准值（100%）
通过 Graphify 图谱查询 约 1.4%

即相比把整个文件夹内容喂给 LLM，Graphify 用大约 1.4% 的 token 就能回答相同的问题。这个数字包含了 Pass 3 中 LLM 语义提取的首次 token 消耗——随着图谱复用，实际每查询一次的成本趋近于零。

五、进阶功能

5.1 监听与增量更新

/graphify . --watch     # 文件变化时自动重建图谱
/graphify . --update    # 手动增量更新，只处理变更文件

--watch 模式适合长时间的开发会话——每当你保存文件，Graphify 在后台静默更新图谱，查询时始终是最新状态。

5.2 Git Hooks 自动触发

Graphify 可以安装 Git hooks，在特定事件时自动重建图谱：

graphify hooks install        # 安装 post-commit 和 post-checkout hooks

这样每次提交或切换分支时，图谱自动刷新。对于频繁切换分支审查代码的场景特别有用——你切到 feature 分支，图谱就是 feature 分支的视角；切回 main，图谱就是 main 的视角。

5.3 MCP Server：图谱即工具

Graphify 内置了 MCP（Model Context Protocol）服务器，将图谱暴露为 LLM 可以直接调用的结构化工具：

graphify mcp                  # 启动 MCP 服务器

启动后，LLM 可以通过以下工具与图谱交互：

这意味着 AI 助手不再需要把整个 graph.json 读入上下文——它只需要按需查询几个节点和它们的关系。

5.4 多格式导出

Graphify 不仅输出自己的图谱格式，还支持导出到外部系统：

graphify export --format neo4j          # Cypher 脚本，导入 Neo4j
graphify export --format obsidian       # Obsidian Vault，Markdown 知识库
graphify export --format svg            # 静态 SVG 矢量图
graphify export --format graphml        # 通用图格式，可导入 Gephi

对于需要做可视化演示或外部分析的场景，导出能力让 Graphify 不只是一个"AI 工具"，而是一个通用知识图谱构建器。

5.5 Wiki 模式

/graphify . --wiki

--wiki 模式会生成一个 Wikipedia 风格的 Markdown 知识库，每个模块一个页面，页面之间通过链接互相引用。适合以下场景：

5.6 深度模式

/graphify ./src --mode deep

深度模式会调用更强的 LLM（如 Claude Opus），对关键模块做更细致的语义分析。对于核心业务逻辑复杂的模块，深度模式能捕捉到默认模式下可能遗漏的隐含关系。

六、graphify-rs：Rust 重写版

Graphify 发布后不久，社区贡献者 TtTRz 在 2026 年 4 月发布了 graphify-rs——一个完整的 Rust 重写版。

6.1 性能对比

指标 Python 版 Rust 版 提升倍数
处理时间（52 文件语料） ~204ms ~24ms 8.5×
内存占用 ~48MB ~1MB 48×
语言支持（tree-sitter） 25 种 10 种 —
内置 MCP 工具 0 7 个 —
子命令数 3 21 —

6.2 架构亮点

graphify-rs 是一个由 14 个 Crate 组成的 Cargo workspace，核心设计：

6.3 与 Python 版的兼容性

graphify-rs 生成的 graph.json 与 Python 版完全兼容。你可以用 Python 版构建图谱，然后用 Rust 版查询；或者在有 GPU 的环境用 Python 版做首次构建（利用 faster-whisper 做音频转录），然后在本地用 Rust 版做日常增量更新。

6.4 选择建议

两者目前都在活跃开发中，选择哪个更多取决于你的运行环境而非功能差异。

七、与同类工具的对比

工具 核心方法 是否需 LLM 是否需要向量数据库 关系追踪能力 适用场景
Graphify AST + 图算法 + Leiden 聚类 可选（Pass 3） 否 强（符号级精确关系） 代码库理解、架构分析
RAG（通用） Embedding + 向量相似度 是 是 弱（依赖语义相似度） 文档问答、知识库检索
CodeGrapher AST + 调用图 否 否 中（仅代码结构） 代码调用链分析
Sourcegraph 索引 + 正则搜索 否 否 弱（文本级匹配） 代码搜索和浏览
RepoRift LLM + 向量 + 图 是 是 中（混合方法） 跨仓库分析

Graphify 最独特的定位是不需要向量数据库的知识图谱——它用符号分析处理结构化代码，用 LLM 处理非结构化文档，用图算法做聚类。这套组合既不牺牲精确性，又保持了对自然语言内容的兼容。

八、常见问题

8.1 和 RAG 怎么选？

如果你的知识库主要是文档、博客、维基——选 RAG。向量检索在自然语言场景中效果最好。

如果你的知识库主要是代码仓库、技术规范、混合了代码和文档的项目——选 Graphify。图遍历在结构化和半结构化内容中优势明显。

两者还可以互补：用 Graphify 管理代码层知识，用 RAG 管理文档层知识，通过 MCP 统一暴露给 LLM。

8.2 大仓库性能如何？

Python 版在 5 万行项目中首次构建约 1-2 分钟。Rust 版在同规模项目中约 5-10 秒。两次构建之间，只有变更文件会被重新处理，增量更新通常秒级完成。

对于 100 万行以上的 monorepo，建议按子目录分批构建，或者使用 --update 模式持续维护。

8.3 token 真的能省那么多吗？

"71.5 倍压缩"是 Graphify 官方在特定语料（52 个混合文件）上的测试结果。实际压缩比取决于你的查询方式：

实际使用中，相比把所有文件内容塞给 LLM，Graphify 的 token 消耗通常能降低 1-2 个数量级。

8.4 不同 AI 平台都支持吗？

graphify install 支持 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、Aider 等主流平台。如果你使用的平台不在官方列表中，可以通过 MCP 模式接入——MCP 是一个开放协议，几乎所有 AI 编程平台都支持。

九、总结

核心要点回顾

要点 说明
Graphify 是什么 将任意文件夹自动构建为可查询知识图谱的 MIT 开源工具
独特之处 用图遍历替代向量检索，基于 AST 静态分析和 Leiden 聚类
token 效率 相比原始文件读取可降低 1-2 个数量级，且图谱可复用
三级置信度 EXTRACTED → INFERRED → AMBIGUOUS，图谱始终可审计
Rust 重写版 8.5 倍更快、48 倍更低内存，与 Python 版格式兼容
最佳场景 代码库理解、架构分析、混合项目（代码 + 文档 + 图片）的知识管理

适用场景

适合用 Graphify 的情况：

不太适合的情况：

一句话总结

Graphify 用图遍历取代向量匹配，在 AI 编程的上下文危机中找到了一条不依赖 embedding 的新路径。

参考资料

延伸阅读

--:--
加载中…