# graphify

> 来源：[GitHub](https://github.com/safishamsi/graphify) · ⭐ 13820 stars

## 项目简介

在当今的软件开发与研究中，我们常常被海量的代码库、技术文档、学术论文和设计图纸所淹没。如何高效地理解、检索和利用这些非结构化的知识，成为了一个巨大的挑战。传统的全文搜索虽然有用，但往往缺乏对内容之间深层语义关联的理解，难以回答诸如“这个函数是如何被调用的？”或“这篇论文中的方法与那个项目中的实现有何关联？”等复杂问题。

graphify 项目应运而生，它旨在将任意文件夹中的代码、文档、论文或图像，转换成一个可查询的**知识图谱**。其核心价值在于，它不仅仅是一个文件索引器，更是一个理解内容语义并构建实体关系的智能助手。通过将非结构化数据转化为结构化的知识网络，graphify 使得开发者或研究者能够以“图”的视角，进行更深入、更关联的探索和问答，极大地提升了代码理解和知识管理的效率。

## 核心特性

*   **多模态知识提取**：graphify 不仅支持纯文本（如代码、Markdown、PDF论文），还能处理图像，从中提取文字和潜在的视觉信息，并将其整合到统一的知识图谱中。
*   **智能关系构建**：项目利用大语言模型（如 Claude、GPT 系列）分析提取出的文本块（代码函数、文档段落等），自动识别实体（如函数名、类名、概念）并推断它们之间的关系（如调用、继承、引用、解释），从而构建出丰富的语义网络。
*   **自然语言查询**：构建好的知识图谱支持使用自然语言进行查询。你可以直接问“`calculate_score` 函数在哪里被调用？”或“帮我总结一下关于‘神经网络优化’的所有内容”，系统会从图谱中找出相关节点和路径给出答案。
*   **AI 助手技能集成**：graphify 被设计为 AI 编程助手（如 Claude Code、Cursor 等）的一个“技能”。这意味着你可以在自己喜欢的 IDE 或 AI 助手界面中，直接对当前项目运行 graphify 并提问，实现与开发环境的无缝集成。
*   **本地化与隐私**：整个处理流程可以在本地运行，你的源代码和文档数据无需上传至第三方服务器，保障了敏感项目的隐私和安全。

## 技术实现

graphify 的技术栈以 Python 为核心，巧妙地结合了现代 NLP、图数据库和 LLM 技术。其架构设计可以概括为以下几个关键步骤：

1.  **文档加载与分块**：首先，使用 `langchain` 等框架的文档加载器，支持多种格式（`.py`, `.md`, `.pdf`, `.jpg` 等）。加载后的长文档会被智能地分割成有意义的“块”（Chunks），例如按函数、类或章节分割，这是后续精细分析的基础。

2.  **向量化与嵌入**：每个文本块通过嵌入模型（如 OpenAI 的 `text-embedding-ada-002` 或开源的 `BGE` 模型）被转换为高维向量（Embedding）。这些向量被存储在向量数据库（如 `Chroma`）中，为后续的语义搜索提供支持。

3.  **关系提取与图谱构建**：这是项目的核心。系统会利用大语言模型（LLM）分析每个文本块。通过精心设计的提示词（Prompt），要求 LLM 识别块内的主要实体（节点）以及这个块所描述的实体之间的关系（边）。例如，对于一个函数定义的代码块，LLM 可能识别出函数名作为一个节点，并解析出函数体内调用的其他函数，从而创建“调用”关系边。所有提取出的节点和边被汇总，最终在 `NetworkX` 或 `Neo4j` 这样的图引擎中构建出知识图谱。

4.  **查询接口**：当用户进行自然语言查询时，查询语句首先被转换成向量，并在向量数据库中进行语义搜索，找到最相关的文本块作为上下文。然后，将用���问题和相关上下文一同提交给 LLM，LLM 结合已构建的知识图谱信息（可以通过图查询如 Cypher 来获取关联路径），生成结构化的最终答案。

这种“向量搜索召回 + 图谱关系推理 + LLM 综合回答”的三层架构，实现了既广又深的知识检索能力。

## 快速上手

以下是一个基本的本地使用示例。首先确保安装好 Python（3.8+）和 `pip`。

1.  **克隆项目并安装依赖**：
    ```bash
    git clone https://github.com/safishamsi/graphify.git
    cd graphify
    pip install -r requirements.txt
    ```

2.  **配置环境变量**：你需要一个 LLM 的 API 密钥（如 OpenAI 或 Anthropic）。编辑 `.env` 文件或直接设置环境变量。
    ```bash
    export OPENAI_API_KEY='your-api-key-here'
    # 或者使用开源的本地模型，需相应配置
    ```

3.  **运行 graphify 处理你的项目文件夹**：假设你要分析当前目录下的 `my_project` 文件夹。
    ```bash
    python -m graphify.process --input-dir ./my_project --output-dir ./my_project_graph
    ```
    这个过程会读取文件、分块、调用 LLM 分析并构建图谱，可能需要一些时间。

4.  **启动查询界面**：处理完成后，可以启动一个本地的交互式界面进行查询。
    ```bash
    python -m graphify.query --graph-dir ./my_project_graph
    ```
    随后在打开的 Web 界面或命令行中，你就可以输入自然语言问题来探索你的项目知识图谱了。

## 应用场景

1.  **遗留代码库剖析**：当你接手一个庞大而陌生的遗留系统时，直接阅读代码效率低下。使用 graphify 对整个代码库进行分析后，你可以直接提问：“入口函数 `main()` 的执行流程涉及到哪些核心模块？” 或者 “修改 `DatabaseConnector` 这个类会影响到哪些服务？” 图谱会清晰地展示出调用链和依赖关系，帮你快速绘制出系统的心智地图。

2.  **学术研究与文献综述**：研究人员可以将某个领域的大量 PDF 论文放入一个文件夹。graphify 可以提取每篇论文的核心方法、数据集和结论，并构建论文间的对比、引用或发展关系图。你可以查询：“有哪些论文在 `BERT` 模型的基础上提出了轻量化改进？” 系统能列出相关论文并简述其改进点，加速文献调研。

3.  **多模态项目文档理解**：一个项目可能包含设计稿（图片）、产品需求文档（Word/PDF）、以及实现代码。graphify 能够跨模态关联信息。例如，你可以问：“根据登录页面的设计稿，前端代码中对应的组件是哪几个？” 项目通过分析图像中的文字和代码中的组件描述，有可能建立起它们之间的关联，实现从设计到代码的追溯。

## 总结

graphify 是一个极具前瞻性的项目，它巧妙地将当下最热的 LLM 与知识图谱技术结合，解决了开发者与研究者面临的核心痛点——信息过载与关联缺失。它不仅是又一个文件搜索工具，更是一个致力于**理解**内容语义的智能中间层。该项目非常适合需要深度探索复杂代码库的工程师、进行文献管理的学者，以及任何希望将自己散乱的项目资料转化为系统化、可推理知识的团队。尽管在处理超大规模数据时可能面临成本和速度的挑战，但其展现出的技术路径和应用潜力，无疑为未来的个人知识管理和智能编程助手指明了方向。