Graphify 是一款开源、本地优先的多模态知识图谱构建工具，其核心卖点十分直接：“一条命令即可将任意文件夹——无论是代码、文档、图片还是PDF——转换为可查询、持久化的知识图谱”。该工具由开发者 Safi Shamsi 于2026年4月发布后，短时间内便吸引了大量关注。它常被用作 Claude Code、OpenCode、Cursor 等AI编程助手的核心插件，旨在解决大模型在处理大型项目时长期存在的痛点：Token消耗过高、上下文容易丢失以及关系理解薄弱。
用一句话来概括Graphify的价值？就是自动将项目中的全部材料——代码、文档、多媒体——抽取为实体和关系，构建成一个显式的知识图谱。后续查询走的是图遍历，而不是全文检索，最终实现了71.5倍的Token压缩。这个数字相当惊人，意味着在同等推理能力的前提下，成本可降至原来的零头。
先聊聊怎么上手，这部分最为实用。
前置要求
运行环境需要 Python 3.10，以及任意一款AI编程助手，当前支持的有：Claude Code、Codex、OpenCode、OpenClaw、Factory Droid。
安装步骤
安装过程非常简单，仅需两条命令即可搞定：
# 1. 安装 graphify（PyPI 包名暂时为 graphifyy）
pip install graphifyy
# 2. 安装到你的 AI 编程助手
graphify install
不同平台对应不同的安装命令：
平台 安装命令
Claude Code (Linux/Mac) graphify install
Claude Code (Windows) graphify install --platform windows
Codex graphify install --platform codex
OpenCode graphify install --platform opencode
OpenClaw graphify install --platform claw
Factory Droid graphify install --platform droid
验证安装是否成功：
# 检查版本
graphify —version
# 查看帮助
graphify --help
如果遇到找不到包或pip安装失败的情况，可以尝试使用pipx或sudo安装，这些是实际操作中比较容易踩坑的地方。
使用方法
在AI编程助手中，输入以下命令即可：
# 在当前目录构建知识图谱
/graphify .
# 指定目录
/graphify ./my-project
# 深度模式——更激进地推断边提取，发现更多隐藏关系
/graphify ./raw --mode deep
# 增量更新——只重新提取变更的文件，合并到现有图谱中
/graphify ./raw --update
# 只重新聚类——在现有图谱上重新运行聚类，不重新提取
/graphify ./raw --cluster-only
Graphify 会在 graphify-out/ 目录生成以下文件：
graphify-out/
├── graph.html # 交互式图谱（点击节点、搜索、按社区过滤）
├── GRAPH_REPORT.md # 核心节点、意外连接、建议问题
├── graph.json # 持久化图谱（数周后仍可查询）
└── cache/ # SHA256 缓存（只处理变更的文件）
这里不展开所有命令的细节，详细内容可以到GitHub上查看。重点聊聊实际使用方法以及常见问题。
核心特点
Graphify有几个设计思路值得关注：
多模态全覆盖。代码、文档、图片（通过视觉模型解析）、PDF、音视频都能统一入图，打破了“仅代码分析”的局限。这对实际项目意义重大——设计图、会议录、论文都可以纳入同一个知识网络。
三级置信度标签。这个设计非常巧妙：EXTRACTED 表示代码中显式存在的实体关系（比如函数调用），置信度1.0；INFERRED 则是合理推断（如语义相似），置信度0.6–0.9；AMBIGUOUS 表示不确定，留待人工审核。这样既保证了自动化程度，又保留了人工介入的空间。
零向量数据库依赖。利用图拓扑（Leiden算法）做社区发现，无需Embedding或向量检索，数据永不离机。这对隐私敏感的场景来说是很大的加分项。
持久化与增量更新。图谱存储在本地，跨会话可以复用。支持 --update 增量刷新，还可以配置Git钩子自动触发更新。
安全可控。零遥测、无厂商锁定、本地处理，符合隐私合规要求。
成本与效率优化
- Token消耗降低71.5倍：预构建图谱后，查询只需遍历图，无需读取原始文件。
- 减少幻觉：结构化知识提供精准上下文，降低大模型错误推理的概率。
- 跨会话持久化：图谱长期有效，避免重复解析带来的浪费。
适用场景
- 大型代码库维护：快速定位调用链、依赖冲突、架构冗余，支持重构与审计。
- AI编程助手增强：为Claude Code、OpenCode等注入结构化理解能力，回答架构、流程、模块关系相关问题时更精准。
- 多模态项目管理：统一管理代码、设计图、会议录、论文，构建项目级知识网络。
- 知识沉淀与协作：导出到Obsidian或Wiki，团队共享结构化知识，降低沟通成本。
与传统工具对比
常见问题
官方解答：
个人使用中总结的几个高频问题：
Q：pip install graphify 报错/找不到包？
A：尝试安装 graphifyy（注意包名区别）：
pip install graphifyy
pip install --upgrade graphifyy
Q：安装后命令不存在/提示不是内部命令？
A：查看安装位置，将 Scripts 目录加入 PATH。
# 查看安装位置
pip show graphifyy
# Linux/macOS
export PATH="$HOME/.local/bin:$PATH"
# Windows
set PATH=%APPDATA%PythonPython311Scripts;%PATH%
Q：构建时报错 Claude API key not found / 401 Unauthorized？
A：设置环境变量：
# Linux/macOS
export ANTHROPIC_API_KEY=sk-xxx
# Windows PowerShell
$env:ANTHROPIC_API_KEY="sk-xxx"
# Claude Code用户通常自动读取 ~/.claude/credentials.json
cat ~/.claude/credentials.json
Q：超时、连接失败、速率限制？
A：限制单次Token，避免请求过大；设置超时跳过坏文件，不阻塞整体处理。
# 限制单次 Token
graphify build . --budget 2000
# 设置超时
graphify build . --timeout 30
Q：增量更新后图谱不一致，有“幽灵节点”（已删除的文件还在图里）？
A：加上 --prune 参数清理已删除节点；如果缓存损坏或哈希不一致，则全量重建。
# 增量更新并清理已删除节点
graphify build . --update --prune
# 全量重建
rm -rf graphify-out/cache
graphify build .
全文干货，大家在实际使用中有什么问题也欢迎一起讨论。
