# Graphify: biến cả codebase và tài liệu thành đồ thị tri thức để hỏi đáp — hướng dẫn cài đặt và dùng

> Graphify là một công cụ Python cài bằng lệnh, đăng ký skill /graphify vào trợ lý AI lập trình (Claude Code, Cursor, Codex, Gemini CLI…). Nó đọc cả dự án và dựng thành đồ thị tri thức, để bạn hỏi đáp, truy đường đi giữa hai khái niệm thay vì mở từng file. Cài đặt khá đơn giản: hai lệnh, cần Python 3.10 trở lên.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-19 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/graphify-do-thi-tri-thuc-codebase-huong-dan-cai-dat-4

Graphify là một công cụ mã nguồn mở (Python, giấy phép Apache-2.0) giúp trợ lý AI lập trình "hiểu" cả một dự án. Bạn gõ `/graphify .` trong Claude Code, Cursor, Codex hay Gemini CLI, nó quét thư mục và dựng thành một **đồ thị tri thức**: mỗi khái niệm là một nút, mỗi quan hệ (gọi hàm, import, kế thừa…) là một cạnh. Sau đó bạn hỏi đáp trên đồ thị này thay vì lục từng file.

Ai nên dùng? Lập trình viên mới nhận một dự án lạ, người phải đọc code của người khác, hoặc người làm văn phòng đang nhờ AI hỗ trợ trên một kho code kèm tài liệu. Repo hiện có khoảng 146.971 sao và 14.096 fork, và vẫn được cập nhật trong 3 tháng gần đây.

Điều đáng giá nhất: phần code được phân tích bằng tree-sitter (cây cú pháp), chạy trên máy bạn, không dùng LLM, không gửi code đi đâu. Mỗi cạnh trong đồ thị đều ghi rõ là đọc thẳng từ nguồn (`EXTRACTED`) hay do công cụ suy ra (`INFERRED`), nên bạn biết chỗ nào đáng tin tuyệt đối, chỗ nào cần kiểm lại.

```repo
- repo | Graphify-Labs/graphify
- kind | Skill
- desc | Graphify là skill /graphify cho Claude Code, Cursor, Codex, Gemini CLI: biến code, tài liệu, PDF thành đồ thị tri thức để truy vấn thay vì grep từng file.
- stars | 147k
- lang | Python
- license | Apache-2.0
```

## Graphify làm được gì

Theo README, bạn nhận ba file đầu ra trong thư mục `graphify-out/`: `graph.html` (mở bằng trình duyệt, bấm vào nút, lọc, tìm kiếm), `GRAPH_REPORT.md` (tóm tắt khái niệm chính, các liên kết bất ngờ, câu hỏi gợi ý) và `graph.json` (toàn bộ đồ thị, hỏi lại lúc nào cũng được mà không phải đọc lại file).

Các tính năng chính:

- **Nút "thần" (god nodes):** liệt kê những khái niệm có nhiều kết nối nhất. Lợi ích: bạn biết ngay phần nào của dự án là trục chính, mọi thứ đều chảy qua.
- **Chia cụm (communities):** đồ thị được chia thành các hệ thống con, gán nhãn không cần LLM. Lợi ích: nhìn bản đồ tổng thể trước khi đào sâu.
- **Liên kết chéo giữa các file:** `calls` / `imports` / `inherits` / `mixes_in`, xử lý qua khoảng 40 ngôn ngữ nhờ tree-sitter. Lợi ích: lần theo được ai gọi ai dù nằm ở file khác.
- **Hỏi, truy đường đi, giải thích:** `graphify query`, `graphify path`, `graphify explain`, đều chạy trên `graph.json`.
- **Ghi chú lý do và tài liệu tham chiếu:** các comment dạng `# NOTE:` / `# WHY:` và trích dẫn ADR/RFC trở thành nút riêng, nối với code. Lợi ích: lý do thiết kế không bị chôn trong comment.
- **Không chỉ code:** tài liệu, PDF, ảnh, video/âm thanh cũng được đưa vào cùng một đồ thị.
- **Không phải vector store:** không embedding, không cơ sở dữ liệu vector. Đây là một đồ thị thật để duyệt.

Về hiệu quả, README công bố bảng đo trên cùng một khung thử nghiệm: recall@10 trên LOCOMO là 0,497; trên bài thử ERPNext chéo công cụ, độ phủ dữ kiện chính là 82,0% so với 70,8% của cách grep/đọc file. Việc dựng đồ thị tốn 0 LLM credit. Chi tiết nằm ở file BENCHMARKS.md trong repo. Đây là số liệu do chính tác giả công bố, bạn nên coi là tham khảo.

## Cần chuẩn bị gì

Theo README, bạn cần:

- **Python 3.10 trở lên.** File `pyproject.toml` ghi rõ `>=3.10,<3.15`. Kiểm tra bằng `python --version`.
- **uv** (khuyến nghị) hoặc **pipx** (phương án thay thế). Kiểm tra bằng `uv --version` hoặc `pipx --version`.
- **Một trợ lý AI lập trình** mà bạn đang dùng: Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot… README nói hỗ trợ hơn 20 trợ lý, trên macOS, Linux và Windows.
- **Key API:** chỉ cần nếu bạn muốn dùng một backend riêng cho phần phân tích ngữ nghĩa tài liệu/ảnh/video. Với code thì không cần, vì code được phân tích cục bộ.

README không nêu yêu cầu GPU hay dung lượng ổ đĩa cụ thể, nên phần đó mình không khẳng định.

```note
Tên gói chính thức trên PyPI là graphifyy (có hai chữ y). Các gói graphify* khác trên PyPI không liên quan đến dự án. Lệnh chạy vẫn là graphify. Gõ nhầm tên gói là cách dễ cài nhầm đồ lạ nhất.
```

## Cài đặt từng bước

```steps
- Chuẩn bị uv | Cài uv (hoặc pipx) và kiểm tra Python 3.10+
- Cài công cụ | Chạy uv tool install graphifyy
- Đăng ký skill | Chạy graphify install để nó nhận ra trợ lý của bạn
- Mở trợ lý AI | Vào thư mục dự án, mở Claude Code/Cursor/…
- Dựng đồ thị | Gõ /graphify . trong trợ lý
```

### Cài uv

uv là công cụ quản lý gói Python, README khuyên dùng. Chọn lệnh theo hệ điều hành của bạn.

Trên macOS (Homebrew):

```bash
brew install python@3.12 uv
```

Trên Windows, mở PowerShell:

```powershell
winget install astral-sh.uv
```

Trên Ubuntu/Debian, uv tự quản lý Python nên chỉ cần một lệnh:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Nếu muốn dùng Python của hệ thống kèm pipx thì README đưa lệnh này:

```bash
sudo apt install python3 python3-pip pipx
```

Sau khi cài xong, nên đóng rồi mở lại terminal để hệ thống nhận lệnh mới.

### Cài Graphify

Chọn một trong ba cách. Cách đầu được khuyến nghị vì cài vào môi trường riêng, không đụng các gói khác:

```bash
uv tool install graphifyy
pipx install graphifyy
pip install graphifyy
```

Chỉ cần chạy **một** dòng. Dòng `pip` có thể phải chỉnh PATH thêm, nên người mới nên chọn `uv`. Nếu cài xong mà gõ `graphify` báo không tìm thấy, README bảo chạy:

```bash
uv tool update-shell
```

Rồi mở lại terminal.

### Đăng ký skill vào trợ lý

```bash
graphify install
```

Lệnh này tự phát hiện bạn đang dùng trợ lý nào và đăng ký skill, nên không cần cài riêng cho từng trợ lý. Nếu bạn dùng trợ lý khác Claude Code, README có lệnh riêng, ví dụ:

```bash
graphify install --platform codex
graphify install --platform gemini
graphify cursor install
```

Bạn có thể cài skill vào đúng dự án hiện tại thay vì vào hồ sơ người dùng bằng cờ `--project`:

```bash
graphify install --project
graphify install --project --platform codex
```

Cách này ghi file vào thư mục hiện tại (ví dụ `.claude/skills/graphify/SKILL.md`), tiện nếu cả nhóm muốn dùng chung. Người dùng Codex lưu ý: cần thêm `multi_agent = true` dưới mục `[features]` trong `~/.codex/config.toml` để trích xuất song song, và gõ `$graphify` thay vì `/graphify`.

### Dựng đồ thị lần đầu

Mở terminal **trong thư mục dự án** của bạn, mở trợ lý AI ở đó, rồi gõ trong khung chat của trợ lý (không phải trong terminal thường):

```
/graphify .
```

Dấu chấm nghĩa là "thư mục hiện tại". Chỗ này người mới hay vấp: `/graphify` là lệnh của trợ lý AI, không phải lệnh terminal.

### Cài thêm phần mở rộng nếu cần

Muốn đọc PDF, Word/Excel hay video, bạn cài thêm "extras". Ví dụ:

```bash
uv tool install "graphifyy[pdf]"
uv tool install "graphifyy[office]"
uv tool install "graphifyy[video]"
```

`pdf` thêm đọc PDF, `office` thêm `.docx` và `.xlsx`, `video` thêm phiên âm video/âm thanh. Cũng có `mcp`, `watch` (tự dựng lại khi file đổi), `neo4j`, `svg`, `ollama`, `openai`, `gemini`, `anthropic` và vài mục khác, xem bảng trong README.

## Kiểm tra đã chạy được chưa

Bước 1: kiểm tra lệnh đã có trong terminal. README không ghi lệnh riêng cho việc này, nhưng nếu `graphify install` chạy được mà không báo "command not found" thì công cụ đã vào PATH.

Bước 2: sau khi chạy `/graphify .` trong trợ lý, mở thư mục `graphify-out/`. Thành công khi có đủ ba file: `graph.html`, `GRAPH_REPORT.md`, `graph.json`. Mở `graph.html` bằng trình duyệt, bạn sẽ thấy các nút khái niệm, tô màu theo cụm, bấm được.

Bước 3: thử một câu hỏi trên đồ thị. README minh hoạ bằng codebase FastAPI:

```bash
graphify explain "APIRouter"
```

Kết quả mong đợi là một khối thông tin: tên nút, file nguồn, cụm, bậc (số kết nối) và danh sách kết nối, mỗi dòng kèm nhãn `[EXTRACTED]` hoặc `[INFERRED]`.

## Dùng vào việc thật

### Nhận một dự án lạ và cần hiểu nhanh

Bạn là lập trình viên mới, vừa được giao một kho code vài trăm file mà người cũ đã nghỉ. Thay vì mở từng file, bạn mở trợ lý trong thư mục dự án và gõ `/graphify .`. Xong, mở `GRAPH_REPORT.md` để xem khái niệm chính, các liên kết đáng ngạc nhiên và câu hỏi gợi ý. Rồi mở `graph.html` để nhìn các cụm. Kết quả: trong buổi đầu bạn đã biết "trục" của hệ thống nằm ở đâu.

> Hỏi đồ thị trước, mở file sau: bạn đỡ lạc giữa rừng code.
>
> — Ông T

### Hỏi một câu bằng tiếng thường

Bạn cần biết phần xử lý thanh toán liên quan đến những gì. Dùng lệnh query với câu hỏi tự nhiên (thay nội dung trong ngoặc bằng câu hỏi của bạn):

```bash
graphify query "<câu hỏi của bạn>"
```

README nói lệnh này trả về một đồ thị con đã thu hẹp cho câu hỏi đó. Bạn nhận được đúng cụm nút liên quan, không phải cả dự án.

### Lần theo mối liên hệ giữa hai thứ

Trước khi sửa một hàm, bạn muốn biết nó dính tới phần nào khác. Dùng `graphify path`, như ví dụ trong README:

```bash
graphify path "FastAPI" "ModelField"
```

Kết quả là đường đi ngắn nhất (ví dụ 3 bước) giữa hai nút, cuối cùng là độ tin cậy của cả đường, tính theo bước yếu nhất. Nhờ đó bạn biết chuỗi liên hệ này chắc chắn hay chỉ là suy luận.

### Gộp tài liệu và PDF vào cùng bản đồ

Nhóm bạn có thư mục chứa code kèm đặc tả PDF và file Word mô tả nghiệp vụ. Cài thêm extras `pdf` và `office` như ở trên, rồi chạy lại `/graphify .`. Tài liệu được đưa vào cùng đồ thị với code. Lưu ý theo README: phần tài liệu, PDF, ảnh, video cần một lượt phân tích ngữ nghĩa bằng mô hình của trợ lý hoặc một API key bạn tự cấu hình. Chỉ phần code mới hoàn toàn cục bộ.

## Lỗi hay gặp và cách xử lý

**Gõ `graphify` báo không tìm thấy lệnh.** Thường do PATH chưa cập nhật. Nếu cài bằng uv, chạy `uv tool update-shell` rồi mở lại terminal. Cài bằng `pip` thì hay dính lỗi này nhất, nên chuyển sang uv hoặc pipx. README còn trỏ tới trang Installation và Troubleshooting trên docs.graphify.com.

**Cài nhầm gói.** Tên đúng là `graphifyy` (hai chữ y). Gói tên gần giống trên PyPI có thể không liên quan. Hãy kiểm tra lại dòng lệnh trước khi nhấn Enter.

**Gõ `/graphify .` không có phản ứng.** Có hai khả năng: bạn chưa chạy `graphify install`, hoặc bạn gõ lệnh vào terminal thay vì khung chat của trợ lý. Nếu dùng Codex, hãy gõ `$graphify`. Nhớ khởi động lại trợ lý sau khi đăng ký skill.

**Python quá cũ.** Dự án yêu cầu từ 3.10 đến dưới 3.15. Chạy `python --version` để kiểm tra; nếu thấp hơn, cài bản mới hơn từ python.org (hoặc để uv tự quản lý Python, như README nói).

**PDF, Word hay video không được đọc.** Các loại này cần extras tương ứng (`pdf`, `office`, `video`). Cài thêm bằng đúng lệnh `uv tool install "graphifyy[...]"` rồi chạy lại.

```note
Phần phân tích tài liệu, ảnh, video dùng mô hình của trợ lý hoặc API key bạn cấu hình, nên có thể phát sinh chi phí và nội dung tài liệu sẽ đi qua nhà cung cấp mô hình đó. Với tài liệu nhạy cảm, hãy cân nhắc trước khi chạy. Đừng dán API key vào file được commit lên Git.
```

## Có nên dùng không

**Điểm mạnh.** Cài nhanh (hai lệnh), dùng được với nhiều trợ lý và cả ba hệ điều hành. Phần code chạy cục bộ, xác định được (cùng đầu vào cho ra cùng kết quả), không tốn LLM credit. Mỗi cạnh có nhãn nguồn gốc nên dễ kiểm chứng. Đầu ra là file thường (HTML, Markdown, JSON), tiện lưu và chia sẻ.

**Giới hạn.** Đồ thị là bản chụp tại lúc dựng; code đổi thì phải dựng lại (extras `watch` hỗ trợ tự dựng lại). Nhãn `INFERRED` nghĩa là công cụ suy luận, không nên coi là chắc chắn tuyệt đối. Phần tài liệu và media cần mô hình hoặc API bên ngoài. Số liệu benchmark là do tác giả công bố. Ngoài ra, README còn nhắc tới dịch vụ Graphify Cloud do nhóm tác giả cung cấp, nhưng bản mã nguồn mở đủ dùng cho hướng dẫn này.

**Khi nào chọn cách khác.** Với dự án chỉ vài file, việc đọc trực tiếp hoặc grep đã đủ nhanh. Nếu bạn cần tìm kiếm theo độ giống nghĩa trên kho văn bản lớn, một công cụ dựa trên vector có thể hợp hơn, vì Graphify cố tình không dùng vector. Còn nếu bạn đang nhận một kho code lớn và muốn trợ lý AI trả lời có căn cứ, đây là công cụ đáng thử trước.

## Câu hỏi thường gặp

### Graphify có miễn phí không?

Repo là mã nguồn mở, giấy phép Apache-2.0, và việc dựng đồ thị từ code không tốn LLM credit theo README. Riêng phần phân tích tài liệu, ảnh, video dùng mô hình của trợ lý hoặc API key bạn cấu hình, nên chi phí tuỳ nhà cung cấp mô hình đó. README còn nhắc tới dịch vụ Graphify Cloud riêng, nhưng không cần cho bản mã nguồn mở.

### Graphify chạy được trên Windows không?

Được. README nói hỗ trợ macOS, Linux và Windows, và có lệnh cài uv cho Windows là winget install astral-sh.uv. Với Claude Code trên Windows, lệnh graphify install tự nhận diện hệ điều hành.

### Có cần GPU hoặc máy cấu hình mạnh không?

README không nêu yêu cầu GPU hay cấu hình phần cứng. Phần phân tích code dùng tree-sitter chạy trên máy bạn, không dùng LLM. Về mức tiêu tốn tài nguyên cụ thể, tư liệu chưa có thông tin.

### Code của mình có bị gửi đi đâu không?

Theo README, code được phân tích cục bộ bằng tree-sitter, không dùng LLM và không rời khỏi máy. Chỉ phần phân tích ngữ nghĩa cho tài liệu, PDF, ảnh, video mới gọi một backend, và chỉ khi bạn cấu hình một backend. Bạn vẫn nên tự cân nhắc với tài liệu nhạy cảm.

### Graphify dùng được với những trợ lý AI nào?

README liệt kê Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat, Aider, OpenCode, Kiro, Antigravity và nhiều trợ lý khác, tổng cộng hơn 20. Mỗi trợ lý có một lệnh cài tương ứng, ví dụ graphify install --platform codex hoặc graphify cursor install.

### Khác gì so với dùng grep hoặc công cụ tìm kiếm vector?

Graphify dựng một đồ thị thật các quan hệ (gọi, import, kế thừa) để bạn hỏi và truy đường đi, không dùng embedding hay vector store. README công bố trên bài thử ERPNext, độ phủ dữ kiện đạt 82,0% so với 70,8% của cách grep/đọc file; đây là số liệu của tác giả.

### Cài nhầm gói thì sao?

Gói chính thức trên PyPI là graphifyy (hai chữ y), lệnh chạy vẫn là graphify. README cảnh báo các gói graphify* khác trên PyPI không liên quan đến dự án, nên hãy kiểm tra kỹ tên gói trước khi cài.
