safishamsi/graphify · 上手攻略

仓库：safishamsi/graphify（现重定向至 Graphify-Labs/graphify）
链接：https://github.com/Graphify-Labs/graphify
分类：rag / database / multimodal
作者：Jay
更新：2026-07-11

它是什么

Graphify 是一款面向 AI 编程助手的代码知识图谱生成工具（code knowledge graph generator）。它的核心思路是：将任意代码仓库（Python、JavaScript、SQL、R、Shell 等）的代码结构转换为一张可查询的知识图谱，替代传统的 grep/全文搜索方式，让 AI 助手可以直接"问问题"获取精准的代码上下文。

形象地说：传统 RAG 是把代码切成片存在向量数据库里，Graphify 则是把代码的调用关系、继承关系、import 关系全部解析成一张图，让 AI 直接沿着边走。

注意： safishamsi/graphify 是旧重定向地址，实际仓库为 Graphify-Labs/graphify。PyPI 包名为 graphifyy（双 y），CLI 命令为 graphify。

解决什么问题

AI 编程助手在处理大型代码库时面临两个核心问题：

上下文窗口有限：想把整个仓库读入对话是不现实的，AI 只能盲人摸象式地看到部分文件。
向量搜索不精准：语义相似的代码片段不一定是你需要的那段——调用关系、继承链、跨文件的依赖路径，是向量搜索捕捉不到的结构化信息。

Graphify 用知识图谱替代向量索引： - 每条边标注来源（EXTRACTED = 代码里明确写的；INFERRED = 跨文件解析推导的），告诉你哪些是直接读到的、哪些是推理出来的。 - 可以查询"A 和 B 之间怎么关联的"（path），也可以问"这个 APIRouter 依赖了什么"（explain），还可以直接提问获取子图（query）。

快速安装

前置依赖

Python 3.10+
uv（推荐）或 pipx / pip bash # 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh

安装 CLI

# 推荐（隔离环境）
uv tool install graphifyy

# 或 pipx
pipx install graphifyy

# 或 pip（可能需要手动配置 PATH）
pip install graphifyy

PowerShell 用户注意：使用 graphify . 而不是 /graphify .（PowerShell 中 / 是路径分隔符，不是命令前缀）。

注册到 AI 编程助手

graphify install

这会在 AI 助手的 skills 目录安装 SKILL.md，注册后 AI 看到 /graphify . 命令就知道如何调用。

如需项目级安装（仅当前仓库可用）：

graphify install --project
graphify install --project --platform codex

安装后验证

# 确认命令可用
graphify --version

# 如命令找不到，运行
uv tool update-shell  # uv 安装后
pipx ensurepath      # pipx 安装后
# 或将 ~/.local/bin（Linux）或 ~/Library/Python/3.x/bin（macOS）加入 PATH

核心用法

基本工作流

# 进入目标代码仓库
cd /path/to/your/project

# 生成知识图谱（生成 graph.html + GRAPH_REPORT.md + graph.json）
/graphify .

注意：PowerShell 中用 graphify .（无前导斜杠）。

三种查询模式

1. 解释某个概念（explain）

graphify explain "APIRouter"

输出示例：

Node: APIRouter
Source: routing.py L2210
Community: 2
Degree: 47

Connections (47):
 --> RequestValidationError [uses] [INFERRED]
 --> Dependant [uses] [INFERRED]
 --> .get() [method] [EXTRACTED]
 <-- __init__.py [imports] [EXTRACTED]
 ...

2. 找两点之间的路径（path）

graphify path "FastAPI" "ModelField"

输出示例：

Shortest path (3 hops):
 FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

3. 自然语言查询（query）

graphify query "How does the authentication flow work in this codebase?"

返回与问题相关的子图（scoped subgraph）。

输出文件说明

文件	说明
`graph.html`	可交互的图谱可视化，在浏览器打开，点击节点、筛选、搜索
`GRAPH_REPORT.md`	高亮摘要：关键概念、意外关联、可后续探索的问题
`graph.json`	完整图谱数据，可随时查询，无需重新读取文件

技术原理

代码解析：纯本地（零 LLM 调用）

Graphify 对代码的 AST 解析使用 tree-sitter，这是一套多语言增量解析器，支持约 40 种语言。解析过程： - 完全本地执行，无 LLM 调用，不产生 token 费用 - 不上传任何代码，所有数据留在本地机器

文档/多媒体：可选 LLM 增强

对于文档（Docs）、PDF、图片、视频/音频，Graphify 会进行语义解析，这一过程会调用你配置的 LLM API（如果配置了）。这一步是可选的——纯代码场景完全免费。

边类型

边类型	含义
`imports`	import / require 声明
`calls`	函数调用
`inherits`	类继承
`mixes_in`	Mixin 混入
`uses`	类型使用关系（INFERRED）
`references`	变量引用（INFERRED）

基准测试

官方基准（在 LOCOMO 和 LongMemEval-S 数据集上，盲测 judge 验证）：

指标	Graphify	对比方案
LOCOMO recall@10	0.497	mem0: 0.048, supermemory: 0.149
LOCOMO QA accuracy	45.3%	supermemory: 49.7%, mem0: 27.3%
LongMemEval-S QA accuracy	76%	与 dense RAG 持平
LLM 消耗	$0	其他方案按 token 计费

Graphify 在 recall 上显著领先传统 memory 系统，LLM 消耗为零（代码解析部分）。

典型适用场景

1. 大型代码库导航 面对数百万行代码的遗留项目，graphify explain "ClassName" 直接告诉你这个类依赖了什么、被谁引用了，省去大量 grep 时间。

2. AI 助手的代码记忆 把图谱给 AI 助手，让它在回答"这段代码为什么这么写"时能追溯完整的调用链，而不只是片段。

3. 新人 onboarding 新加入项目的工程师可以跑 graphify path "A" "B" 快速理解两个核心模块之间的关联路径。

4. 重构前的依赖分析 graphify query "所有涉及数据库连接的地方" → 获取子图 → 了解改动影响范围。

5. 跨语言项目 同时支持 ~40 种语言，跨语言 import/call 关系也能解析（via tree-sitter）。

坑与注意

PyPI 包名是 graphifyy（双 y），不是 graphify。graphify 是 CLI 命令名，包名不同。其他 graphify* 命名的 PyPI 包均与此项目无关。
/graphify . 在 PowerShell 中无效：PowerShell 把 / 视为路径分隔符，应使用 graphify .。
命令找不到：uv tool install 和 pipx install 会把 graphify 放到隔离的 bin 目录（~/.local/bin 等），需要运行 uv tool update-shell 或 pipx ensurepath 后重新打开终端。
使用 uvx / uv tool run 时：必须指定包名 graphifyy，不是命令名 graphify： bash uvx --from graphifyy graphify install # ✅ 正确 uvx graphify install # ❌ 失败
文档/多媒体语义解析会调用 LLM：如需关闭，在配置中不设置 API Key，图谱仅包含代码结构信息。
图谱构建需要时间：大型仓库（图谱可能很大）的 graph.json 文件较大，注意磁盘空间。
与 Graphify-Labs/graphify 的关系：safishamsi/graphify 和 Graphify-Labs/graphify 是同一仓库（旧地址和新地址），slugs 均合法，指南内容一致。

与同类对比

方案	索引类型	代码感知	LLM 成本	本地化
Graphify	知识图谱（tree-sitter AST）	跨文件调用链	$0（代码）	完全本地
mem0	向量 + memory	无	按 token	部分本地
supermemory	向量索引	无	按 token	云端优先
Sourcery	规则 + LLM	仅单文件	按 token	在线
Sourcegraph Cody	向量 + LLM	部分	按 token	云端

Graphify 的核心优势：完全本地解析代码结构（零 token）+ 知识图谱的可解释性（每条边都有 EXTRACTED/INFERRED 标注）。

一句话推荐结论

在 AI 编程助手中处理中大型代码库时，用 /graphify . 生成一张知识图谱，替代 grep 和向量搜索——完全本地、零 LLM 成本、每条关联都有来源标注，让 AI 真正"看懂"代码结构而非盲人摸象。