Graphify、OKF与RAG：您的代码库需要哪种上下文层？
基准测试显示，Graphify在准确率上与向量RAG不相上下。以下是Graphify、谷歌的OKF以及向量RAG之间的关系，包括故障触发条件及决策矩阵。
Graphify自身的基准测试文件中有一个结果，但关于该项目的诸多宣传往往忽略了这一点。在问答准确率方面，它与密集向量RAG不相上下，而在召回率上则略逊一筹。然而在各类开发者博客中，它却被称作“RAG的杀手”，而且就在同一个月，企业团队便将其与谷歌的开放知识格式（OKF）一起应用于他们的AI编程工具中。为何如此？
因为这种流行的观点是反的。Graphify和OKF并非要取代RAG，它们都是专门的组件——一个是结构层面的，另一个是叙事层面的——用于补充向量索引，且每一种的存在都是为了解决系统中特定的缺陷。如果把它们当作RAG的替代品，那就等于浪费工程资源去维护那些本不需要的知识图谱和精心整理的Markdown文档包。
接下来的内容将介绍每一层的功能、为何Graphify真正的优势在于数据导入成本而非更出色的检索能力，以及针对2026年代码库的决策矩阵。
基准测试文件的实际内容
打开Graphify仓库中的BENCHMARKS.md文件，那些未在发布文章中提及的数值就在那里。
首先来看LongMemEval-S测试，共有50个样本。Graphify的图扩展模式取得了76%的准确率和0.844的@10召回率。使用相同模型（Kimi K2.6）、相同BGE-m3嵌入器以及相同令牌预算的密集向量RAG基准模型也获得了76%的准确率和0.848的@10召回率。因此知识图谱在此处并无优势：准确率相当，而召回率稍低。更糟糕的是，供应商本身对数据集进行了报告并进行了盲测验证（评分一致性为90.6%，Cohen’s kappa值为0.81），也就是说没有外部竞争者能找出异常结果。
在LOCOMO（n=300）测试中，情况类似，只不过关键指标变成了数据摄取成本。
Graphify的准确率为45.3%，摄取该数据集的成本约为1.40美元。Supermemory的准确率更高，为49.7%，但数据摄取成本高达15.67美元，几乎是Graphify的11倍。因此Graphify在准确率方面也并不占优，它在成本和效率方面更具优势。
在两个公开基准测试中都存在这一规律：Graphify的检索性能无法超越经过精心调优的向量RAG流程，其准确率与向量RAG相当，但构建成本远低于其他内存系统。它的优势源于以下两个特点：
- 数据摄取成本低，因为AST解析完全不需要调用LLM API。
- 由于采用确定性的树形解析器，能够精确提取代码间的关系（调用、导入、类继承），且整个过程不涉及任何模型，因此不存在幻觉风险。
对于那些认为 Graphify 能取代向量数据库的人而言，这重新定义了问题。关键不在于哪种工具更优，而在于哪个层级负责处理何种上下文，以及你的智能体架构中还有哪些故障模式尚未解决。
三层架构而非三个竞争对手
合理的架构设计需要将技术现实与营销话术区分开来。现代智能体系统依赖于三个独立的上下文层级。
┌─────────────────────────────────────────────────────────────────┐
│ AI CODING AGENT CONTEXT │
└────────────────────────────────┬────────────────────────────────┘
│
┌─────────────────────────────┼─────────────────────────────┐
▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ VECTOR RAG │ │ GRAPHIFY │ │ GOOGLE OKF │
│ (Unstructured) │ │ (Structure) │ │ (Narrative) │
├───────────────────┤ ├───────────────────┤ ├───────────────────┤
│ • Docs & Tickets │ │ • AST Call Graphs │ │ • Architecture │
│ • Slack Threads │ │ • Class Hierarchies│ │ • Data Schemas │
│ • Long Tail Text │ │ • Imports/Exports │ │ • Playbooks & Run │
└───────────────────┘ └───────────────────┘ └───────────────────┘
Vector RAG
Vector RAG会将非结构化文本分割成固定大小的标记块（例如512个标记），将其嵌入向量空间中，查询时返回距离最近的top-k个结果。该方法速度快、成本低，非常适合处理独立的平面型文档。
它的根本缺陷在于结构层面：它会破坏层级结构。Prism Labs在2026年的一项分析中这样指出：当因果关系不在同一个512标记的块中时，系统就无法识别二者之间的关联。更先进的嵌入模型也无法解决这个问题，因为这是文本分块机制固有的缺陷。
Graphify
Graphify 是一个本地的、确定性的解析引擎。它能够对包括 Python、TypeScript、Go、Rust、Java、C/C++、Swift、SQL 以及 Terraform/HCL 在内的 36 种以上编程语言进行 Tree-sitter AST 解析，提取代码元素，并构建包含类型化边的结构图，这些边包括 calls、imports、inherits 和 mixes_in 等。
每条边都有一个标签。EXTRACTED 表示该边是直接从 AST 中可靠提取的，而 INFERRED 表示是通过启发式方法以较低可靠性生成的。此外，Graphify 还应用Leiden 社群检测算法来划分自然子系统，并标记出那些与众多模块有关联的“核心节点”。
运行 /graphify . 命令会生成三种本地输出文件：
graph.html是该图的交互式可视化展示。GRAPH_REPORT.md是对代码库各子系统所作的文字概述。graph.json是可供机器读取并查询的索引文件。
开放知识格式
Google Cloud于2026年6月发布了OKF。它既不是检索算法，也不是数据库引擎，而是一种与供应商无关的Markdown元数据规范。一个数据包是由纯UTF-8格式的Markdown文件组成的目录，其中仅包含最少的YAML前置信息，且仅有type这一字段是必填的。其标题格式如下：
---
type: Architecture Concept
title: Payment Gateway Routing
description: Canonical sequence for multi-tenant payment provider dispatch.
tags: [billing, architecture]
---
没有模式注册表，也没有复杂的运行时环境。这些代码包应存储在 Git 中，可使用 cat 等普通 shell 工具读取。OKF 存储的是经过整理的机构记忆，由人类编写或由智能体草拟而成：即关于系统为何如此构建的稳定叙述，而非原始代码符号或未经整理的聊天记录。
各层级如何分工
它们共同分担工作：Graphify 负责提取代码的“实际内容”，OKF 记录工程师的“知识储备”，而 vector RAG 则处理剩余的非结构化数据。
90 天内从一条推文变成拥有 63K 星标的仓库
从时间线来看，急于采用这些工具是合理的，因为整个生态系统是在短短 90 天内出现的。
2026-04-01: Karpathy posts "LLM Wiki / Knowledge Compiler" concept on X
│
2026-04-03: Safi Shamsi launches Graphify on GitHub (YC S26)
│
2026-06-01: Graphify reaches 58.3K GitHub stars & 1.2M PyPI downloads
│
2026-06-12: Google Cloud releases Open Knowledge Format (OKF) spec
│
2026-07-01: Graphify ↔ OKF hybrid integration toolkit ships (71.5x token claim)
│
2026-07-05: Graphify hits ~78K stars; Level Up Coding scrutinizes "70x token" claims
同样的内容以散文形式呈现：
- 2026年4月1日：Andrej Karpathy在X平台上分享了一个思想实验：将研究论文、代码库笔记、截图以及架构文档放入同一个文件夹中，然后通过能够理解这些内容之间关联关系的AI来查询它们，而大型语言模型则充当“知识编译器”的角色。
- 2026年4月3日：Safi Shamsi在GitHub上发布了Graphify，仅用48小时就将该想法转化为实际项目，它也被纳入了Y Combinator的S26批次项目之中。
- 2026年6月1日：该项目在GitHub上的星标数突破58,300个，从PyPI下载量则达到120万次。
- 2026年6月12日：Google Cloud推出了OKF，同时公布了其开放规范、示例包（涵盖GA4电子商务、Stack Overflow和比特币相关场景），以及一个用于提取BigQuery元数据的工具。
在那些备受关注的时期，Andrus指出，要实现近70倍的节省效果，关键取决于项目中的一个特性，而几乎没有任何后续文章公开提及这一特性。该特性就是语料库拓扑结构。用于得出70倍这一数据的测试仅使用了特定的52个文件组合（Karpathy的公开代码库、5篇研究论文、4张图表），而对于具有扁平包结构或庞大单体代码库的企业级项目，令牌节省幅度则差异很大。
哪些失败情况足以成为引入某种工具的理由
炒作并非架构上的必要条件，对当前RAG架构的模糊不满同样不算理由。新的基础设施需要背后有具体且已观察到的故障模式作为依据。
先认清现实
行业内的调查显示，在一年内表现不佳或彻底失败的企业RAG部署比例高达72%。这些失败大多源于糟糕的分块处理、过时的向量索引或不合适的嵌入模型，而非缺乏图数据库。将知识图谱强行添加到有缺陷的检索流程中，只会让问题更加严重，同时还需额外处理更多内容。
┌─────────────────────────────────────────┐
│ Does your AI coding agent underperform? │
└────────────────────┬────────────────────┘
│
┌──────────────────┴──────────────────┐
▼ ▼
[ Sifting multi-file code ] [ Loss of tribal context ]
[ dependencies & calls ] [ across team silos ]
│ │
▼ ▼
Multi-Hop Reasoning Failure Knowledge Sprawl Failure
│ │
▼ ▼
TRIGGER: Add Graphify TRIGGER: Add Google OKF
(AST Structural Graph) (Curated Narrative Spec)
触发因素一：多跳推理失败（需添加Graphify）
当答案需要关联多个文件中的事实，而这些文件之间没有任何文本重叠时，就会出现这种情况。
典型症状是：智能体无法回答诸如“如果db/migrations/04_users.sql中的架构发生变化，API层哪些部分会出问题？”之类的问题。
由于向量RAG是独立嵌入每个文本块的，它根本不了解外键引用、接口实现或跨文件调用等信息。更好的提示或更大的上下文窗口也无济于事，因为这些关系从未被纳入向量空间中。
触发因素二：零散的团队知识（需添加OKF）
当重要的机构背景信息分散在Slack频道、过时的维基页面以及开发者口口相传的记忆中时，就会出现这种情况。
这里出现的问题在于，某些工具虽然能生成语法正确的代码，但却违反了内部架构规范，调用了已废弃的内部 API，或忽视了特定领域的业务规则。
Graphify 无能为力，因为抽象语法树解析器仅能读取源代码，无法理解业务意图。OKF 则通过一种轻量级、基于 Git 版本控制的 Markdown 结构来填补这一空白，工程师可在其中记录稳定的系统规范，以便相关工具准确解析。
针对法律领域 RAG 的研究显示，由于单纯的检索无法处理跨文档的逻辑关系，标准检索工具在 17% 到 33% 的复杂查询中会出现错误结果。Atlan 的建议指出了合理的处理顺序：先使用 RAG，只有当深度成为瓶颈时再引入图结构。
各工具出问题时的成本
每增加一层都会带来新的故障模式。这两个项目都还处于初期阶段，因此在投入实际使用前需重点关注其运行风险。
Graphify的不足之处
- 过时的快照。图索引仅构建一次且保持不变。开发人员修改文件时它不会更新，因此如果没有Git的预提交钩子或CI/CD流程，该索引就会与代码实际状态脱节。过时的结构图比没有图索引更糟糕，因为分析工具会基于错误的数据给出错误结论。
- 传统单体应用中的混乱社区结构。在大型Java或C++应用中，Leiden检测方法常常会将那些仅因使用了相同的日志记录或遥测单例等基础设施而并无关联的模块归为一组。
OKF的不足之处
- 缺乏强制约束与验证机制。该格式刻意省略了模式注册表和严格规则，因此数据包的质量完全取决于编写文件的人或系统。
- 静默衰败。核心协议要求开发者容忍未知的元数据类型及失效链接。这虽能加快采用速度，却也会让相关文件逐渐变成无关联的过时文件，而不会引发任何构建错误。
- 维护负担。Markdown文档需要持续的维护工作。如果工程工作流不要求在代码变更时同步更新OKF，那么文档内容很快就会过时。
实际应用中的综合流程
对于复杂的企业代码库，2026年的最佳方案并非选择某一种工具，而是将多种工具串联成多阶段的处理流程。
┌──────────────────────────────────────────────────────────────────┐
│ USER / AGENT QUERY: "What breaks if I modify UserService.py?" │
└─────────────────────────────────┬────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ STAGE 1: OKF Progressive Disclosure Catalog │
│ Read high-level module narrative & owner specs (~2K tokens) │
└─────────────────────────────────┬────────────────────────────────┘
│ (Targeted node identified)
▼
┌──────────────────────────────────────────────────────────────────┐
│ STAGE 2: Graphify Structural Graph Query │
│ Traverses AST edges: calls, imports, inherits (Zero-LLM cost) │
└─────────────────────────────────┬────────────────────────────────┘
│ (Unstructured edge cases)
▼
┌──────────────────────────────────────────────────────────────────┐
│ STAGE 3: Vector RAG / Sparse Search │
│ Search raw Slack incident logs, GitHub issues, & PR comments │
└──────────────────────────────────────────────────────────────────┘
第一步：生成 Graphify 的结构化输出
在隔离环境中安装 Graphify，然后针对工作区运行分析工具。
# Install Graphify via uv
uv tool install graphifyy
# Register the skill with your local agent environment (Claude Code, Cursor, Codex, Gemini CLI)
graphify install
# Execute AST graph compilation inside your repository root
/graphify .
# Generated Local Artifacts:
# graph.html --> Interactive visual network representation
# GRAPH_REPORT.md --> Natural language summary of communities & god nodes
# graph.json --> Queryable AST relational graph database
完成后，可直接查询本地结构索引以查看关系路径。
# Query dependency paths between components
graphify path "UserService" "DatabasePool"
# Trace architectural blast radius before refactoring
graphify query "What components depend on AuthTokenValidator?"
第二步：将精心筛选的概念编写为OKF格式
将结构化处理结果导出为符合OKF标准的概念包，存放于.well-known/okf/或docs/knowledge/目录下。最简单的概念文件使用普通Markdown链接，这些链接可直接对应到知识图谱中的边关系。
---
type: Database Table Context
title: orders_fact
description: Canonical order transaction table joining billing and fulfillment streams.
resource: bigquery://production-data.commerce.orders_fact
tags: [finance, core-model]
timestamp: 2026-06-20T14:00:00Z
---
# Business Domain Summary
The `orders_fact` table serves as the primary source of truth for revenue calculations.
Modifications to columns must align with the [Customer Profile Spec](./customer_profile.md).
# Schema & Join Constraints
| Column Name | Data Type | Structural Constraint |
|---|---|---|
| `order_id` | STRING | Primary Key; joins with [billing_events](./billing_events.md) |
| `customer_id` | STRING | Foreign Key; see [customers](./customers.md) |
| `status` | STRING | Enum: `pending`, `completed`, `refunded` |
# Related Runbooks
- Incident Protocol: [/runbooks/billing-reconciliation.md](/runbooks/billing-reconciliation.md)
搜索与上下文工程专家Kopp指出，OKF的链接结构与GraphRAG非常契合，因为从orders_fact.md指向customers.md的链接本身就已经是知识图谱中的一条边。
ERPNext的实验结果
这种组合方法已在ERPNext上进行了测试，该开源企业级代码库包含超过一百万行的Python和JavaScript代码。
评估时使用了Claude Opus 4.8模型，每项任务的限制为14轮对话：
- 使用向量RAG和grep的基准编码智能体达到了70.8%的关键事实覆盖率。
- Graphify与OKF混合流程则实现了82.0%的关键事实覆盖率，每次查询会话的平均处理量约为140,000个标记。
在如此规模的代码库中，11.2分的提升意味着代理执行错误显著减少。这比那些虚构的令牌减少数值更能体现实际应用价值。
按代码库类型选择
在矩阵中找到您的代码库环境及其主要故障模式，从而选择合适的架构。
简述版
Graphify在无需LLM API成本的确定性结构解析方面表现最佳。OKF提供了一种便携且兼容Git的标准，适用于人类和代理编写的上下文。对于非结构化文本的搜索，Vector RAG仍然是最有效的选择。若盲目叠加多层架构而没有明确的故障模式，只会增加复杂性，对代理性能毫无帮助。
先明确问题
在将 Graphify 或 OKF 放入开发流程之前，首先需要确定三种问题中哪一种是真正存在的：过时的代码上下文、多跳依赖故障，还是零散的机构知识。
这两种工具都是现代 AI 技术栈中的有用补充，ERPNext 的测试结果也证明了它们在复杂代码库中的实际价值。不过，从一条推文发展到一个广为流传的代码仓库，这一过程本身就需要严谨的态度。请直接阅读 BENCHMARKS.md 中的数据，在自己的代码上测试候选架构，并构建符合自身工程需求的上下文环境。首先可以将自己的配置与矩阵中的单体架构、微服务架构或单仓库架构进行匹配。
相关阅读
- Milvus上的高级RAG技术：混合搜索、HyDE、查询重写与重排序 — 逐步构建Milvus RAG流程：密集向量与BM25向量、RRF混合搜索、元数据过滤、查询重写、HyDE技术、分解处理以及交叉编码器重排序。
- 30分钟内打造实用本地大语言模型：编码、文档问答与语音功能 — 利用Ollama、Qwen3和Whisper.cpp构建本地编码助手、笔记搜索脚本以及离线语音交互系统，同时介绍选择模型大小时的内存带宽相关规则。