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

> Graphify là một skill cho trợ lý lập trình AI (Claude Code, Cursor, Codex, Gemini CLI và hơn 20 công cụ khác). Bạn gõ /graphify và nó dựng cả dự án thành một đồ thị tri thức để truy vấn thay vì lục từng file. Cài bằng hai lệnh, cần Python 3.10 trở lên và uv hoặc pipx.

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

Graphify là một skill cho trợ lý lập trình AI. Bạn gõ `/graphify` trong Claude Code, Cursor, Codex, Gemini CLI hay vài chục công cụ tương tự, nó đọc cả dự án rồi dựng thành một **đồ thị tri thức** (knowledge graph). Sau đó bạn hỏi đáp trên đồ thị này thay vì để AI mở hết file này đến file khác để tìm.

Vấn đề nó giải quyết rất quen thuộc. Dự án càng lớn, AI càng mất nhiều lượt đọc file mới hiểu được cấu trúc. Người mới vào dự án thì không biết bắt đầu từ đâu, file nào quan trọng, phần nào nối với phần nào. Graphify trả lời bằng một bản đồ: khái niệm nào được nối với nhiều thứ nhất, dự án chia thành những cụm nào, hai thứ cách nhau mấy bước.

Điểm đáng giá nhất: phần **code được phân tích hoàn toàn trên máy bạn**, bằng tree-sitter AST, không dùng LLM và không gửi gì ra ngoài. Mỗi kết nối trong đồ thị đều có nhãn cho biết nó được đọc thẳng từ mã nguồn hay do công cụ suy ra. Repo hiện có khoảng 146.779 sao và 14.077 fork, giấy phép Apache-2.0.

```repo
- repo | Graphify-Labs/graphify
- kind | Skill
- desc | Skill /graphify biến code, tài liệu, PDF của dự án thành đồ thị tri thức để hỏi đáp, chạy cục bộ cho phần code, dùng được với Claude Code, Cursor, Codex, Gemini CLI.
- stars | 147k
- lang | Python
- license | Apache-2.0
```

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

Đây là những thứ bạn nhận được ngay sau khi cài, theo mô tả của tác giả:

- **Bản đồ cả dự án, không chỉ code.** Code, tài liệu, PDF, ảnh, video và âm thanh đều được đưa vào cùng một đồ thị. Bạn hỏi một câu và nhận câu trả lời xuyên qua nhiều loại tài liệu.
- **Nút "thần" (god nodes).** Đó là những khái niệm có nhiều kết nối nhất. Nhìn vào là biết mọi thứ trong dự án đang chảy qua đâu.
- **Chia cụm (communities).** Đồ thị được tách thành các hệ thống con bằng thuật toán Leiden, tên cụm đặt không cần LLM. Người mới nhìn vào hiểu ngay dự án gồm những mảng nào.
- **Liên kết chéo giữa các file.** Các quan hệ như `calls`, `imports`, `inherits`, `mixes_in` được nối qua khoảng 40 ngôn ngữ lập trình.
- **Hỏi, tìm đường, giải thích.** Bạn hỏi một câu, vạch đường đi giữa hai thứ, hoặc nhờ giải thích một khái niệm. Tất cả chạy trên file `graph.json`, không phải đọc lại mã nguồn.
- **Lý do thiết kế thành nút riêng.** Các comment `# NOTE:`, `# WHY:` và trích dẫn ADR/RFC trở thành nút trong đồ thị, nối với đoạn code liên quan. Ý định của người viết không còn nằm lẻ loi trong comment.
- **Mỗi cạnh có nhãn tin cậy.** `EXTRACTED` nghĩa là có ghi rõ trong nguồn, `INFERRED` nghĩa là Graphify suy ra. Bạn biết chỗ nào chắc, chỗ nào cần kiểm lại.
- **Không dùng vector.** Không embedding, không vector store. Đây là đồ thị thật để đi qua từng cạnh.

Tác giả cũng đưa ra bảng benchmark. Ví dụ trên LOCOMO (n=300), recall@10 của Graphify là 0.497, và bước dựng đồ thị tốn 0 LLM credit. Chi tiết và cách chạy lại số liệu nằm trong file BENCHMARKS.md của repo. Bạn nên coi đây là số liệu của tác giả.

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

Theo README, bạn cần:

- **Python 3.10 trở lên.** File `pyproject.toml` ghi rõ yêu cầu `>=3.10,<3.15`. Kiểm tra bằng `python --version`.
- **uv (khuyến nghị) hoặc pipx** để cài lệnh `graphify`. Kiểm tra bằng `uv --version` hoặc `pipx --version`.
- **Một trợ lý AI lập trình** mà bạn đã dùng sẵn: Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot và nhiều công cụ khác. Hệ điều hành hỗ trợ là macOS, Linux và Windows.

Nếu chưa có uv, README gợi ý:

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

Đó là cách cho macOS (Homebrew). Trên Windows:

```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
```

Với phần code, bạn không cần API key. Còn bước "semantic" cho tài liệu, PDF, ảnh, video thì dùng model của trợ lý bạn đang chạy, hoặc một API key nếu bạn tự cấu hình backend.

```note
Phần code được phân tích hoàn toàn trên máy bạn. Nhưng bước xử lý tài liệu, PDF, ảnh, video sẽ gọi một model (của trợ lý hoặc backend bạn cấu hình). Nếu tài liệu nhạy cảm, hãy kiểm tra bạn đang dùng backend nào trước khi chạy.
```

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

```steps
- Cài Python và uv | Đảm bảo có Python 3.10+ và uv (hoặc pipx)
- Cài lệnh graphify | Dùng uv tool install graphifyy (hai chữ y)
- Đăng ký skill | Chạy graphify install để gắn skill vào trợ lý AI
- Mở trợ lý trong thư mục dự án | Mở Claude Code, Cursor... ở đúng thư mục cần phân tích
- Chạy /graphify . | Dựng đồ thị và nhận ba file kết quả
```

### Cài lệnh graphify

Mở terminal (Terminal trên macOS/Linux, PowerShell trên Windows). Chạy một trong các lệnh sau, chọn một cách thôi:

```bash
uv tool install graphifyy      # cách khuyến nghị, môi trường tách biệt
pipx install graphifyy         # cách thay thế
pip install graphifyy          # có thể phải chỉnh PATH
```

Chú ý: tên gói là **graphifyy với hai chữ y**. README nhấn mạnh các gói `graphify*` khác trên PyPI không liên quan đến dự án. Sau khi cài, lệnh bạn gõ vẫn là `graphify` (một chữ y).

Nếu cài bằng uv xong mà terminal báo không tìm thấy lệnh `graphify`, chạy:

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

Rồi đóng terminal, mở lại.

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

Chạy đúng một lần:

```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, không cần cấu hình riêng cho từng công cụ.

Một số trợ lý cần lệnh riêng. Ví dụ:

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

Bạn có thể xem toàn bộ bảng lệnh theo từng nền tảng (Copilot CLI, Aider, Kiro, Antigravity…) trong mục cài đặt của README. Người dùng Codex cần thêm `multi_agent = true` dưới mục `[features]` trong file `~/.codex/config.toml` để chạy trích xuất song song.

Muốn cài skill vào riêng một dự án (để cả nhóm dùng chung) thay vì vào máy bạn, thêm `--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`, và in gợi ý `git add` cho những file có thể commit.

### Dựng đồ thị đầu tiên

Mở terminal ở đúng thư mục dự án, khởi động trợ lý AI, rồi gõ trong khung chat của nó:

```
/graphify .
```

Dấu chấm nghĩa là "thư mục hiện tại". Người dùng Codex gõ `$graphify .` thay vì `/graphify .`.

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

Mặc định chưa có hỗ trợ PDF, Word, video… Bạn cài thêm đúng cái cần:

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

`pdf` thêm đọc PDF, `office` thêm file `.docx` và `.xlsx`, `video` thêm phiên âm video/âm thanh. Ngoài ra còn các extra như `mcp`, `watch`, `svg`, `neo4j`, `ollama`, `openai`, `gemini`, `anthropic`; bạn xem bảng đầy đủ trong README.

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

Sau khi `/graphify .` chạy xong, trong dự án sẽ có thư mục `graphify-out/` với ba file:

- `graph.html`: mở bằng trình duyệt bất kỳ, bấm vào nút, lọc, tìm kiếm.
- `GRAPH_REPORT.md`: bản tóm tắt gồm khái niệm chính, các kết nối bất ngờ và câu hỏi gợi ý.
- `graph.json`: toàn bộ đồ thị, để truy vấn lúc nào cũng được mà không phải đọc lại file.

Có ba file này là bạn đã thành công. Hãy mở `graph.html` xem thử, rồi đọc `GRAPH_REPORT.md` để thấy dự án được chia thành những cụm nào.

Nếu chỉ muốn kiểm tra lệnh `graphify` có nằm trong PATH hay chưa, bạn mở terminal mới và thử các lệnh truy vấn ở phần dưới. Máy báo "command not found" nghĩa là PATH chưa đúng (xem phần lỗi thường gặp).

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

### Người mới vào một dự án lạ

Bạn là lập trình viên mới nhận một codebase vài trăm file, không ai có thời gian chỉ dẫn. Chạy `/graphify .` ở thư mục gốc. Mở `GRAPH_REPORT.md` để xem các khái niệm trung tâm (god nodes) và các cụm hệ thống con. Rồi mở `graph.html` để lần theo từng cụm.

Kết quả: sau vài phút bạn biết phần nào là lõi, phần nào là phụ, thay vì đọc từng file từ trên xuống.

### Hiểu một khái niệm cụ thể

Bạn gặp một class tên `APIRouter` và không biết nó dính líu đến đâu. Dùng lệnh `explain`:

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

Ví dụ trong README, chạy trên codebase FastAPI, trả về vị trí file, cụm chứa nó, số kết nối (47) và danh sách các cạnh, mỗi cạnh gắn nhãn `[EXTRACTED]` hoặc `[INFERRED]`. Bạn biết ngay class này được import từ đâu, gọi cái gì, và cạnh nào chỉ là suy ra.

> Đồ thị cho bạn biết cái gì nối với cái gì, và nhãn cho bạn biết chỗ nào đọc thẳng, chỗ nào chỉ là suy ra.
>
> — Ông T

### Tìm đường nối giữa hai thứ

Trước khi sửa một chức năng, bạn muốn biết nó có ảnh hưởng đến phần kia không. Dùng lệnh `path`:

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

Kết quả là đường ngắn nhất giữa hai nút (README ví dụ 3 bước), kèm độ tin cậy của cả đường, lấy theo cạnh yếu nhất. Nếu đường nối chỉ toàn cạnh `INFERRED`, bạn nên kiểm tra lại bằng tay trước khi tin.

### Hỏi bằng ngôn ngữ thường

Bạn là người làm sản phẩm, không rành code nhưng cần hiểu dự án. Dùng lệnh `query` với một câu hỏi thường:

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

Thay phần trong ngoặc bằng câu hỏi thật. Lệnh trả về một đồ thị con liên quan đến câu hỏi, đủ để bạn hoặc trợ lý AI nắm phạm vi mà không cần đọc cả dự án.

Với tài liệu như PDF hay file Word đi kèm dự án (đặc tả, quyết định thiết kế), bạn cài thêm extra `pdf` hoặc `office` ở trên rồi dựng lại đồ thị. Chúng sẽ nằm chung đồ thị với code.

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

### Báo không tìm thấy lệnh graphify

Đây là lỗi hay gặp nhất khi cài bằng uv hoặc pip: thư mục chứa lệnh chưa nằm trong PATH. Với uv, chạy `uv tool update-shell` rồi mở terminal mới. README nói `pip install graphifyy` có thể cần chỉnh PATH, nên nếu vấp bạn hãy chuyển sang uv hoặc pipx. Trang Installation và Troubleshooting trên docs.graphify.com có hướng dẫn thêm.

### Cài nhầm gói tên gần giống

Tên đúng là `graphifyy` với hai chữ y. Gõ `graphify` một chữ y trên PyPI có thể ra gói khác, không phải của dự án. Hãy kiểm tra lại lệnh cài, và cài đúng tên.

### Phiên bản Python không phù hợp

Project yêu cầu Python từ 3.10 đến dưới 3.15. Nếu máy bạn cũ hơn, cài Python mới hơn. Dùng uv thì nó tự quản lý Python nên ít vấp hơn.

### Gõ /graphify nhưng trợ lý không nhận ra

Thường là chưa chạy `graphify install`, hoặc trợ lý của bạn cần lệnh riêng (ví dụ `graphify cursor install`, `graphify install --platform codex`). Chạy lại lệnh đúng cho nền tảng của bạn, rồi khởi động lại trợ lý. Nhớ rằng Codex dùng `$graphify`, không phải `/graphify`.

### PDF, Word hoặc video không được đưa vào đồ thị

Các định dạng này cần extra tương ứng (`pdf`, `office`, `video`). Cài bằng `uv tool install "graphifyy[pdf]"` và tương tự, rồi chạy lại `/graphify .`. Nếu bước semantic báo thiếu model hoặc key, kiểm tra backend bạn đã cấu hình; README liệt kê các extra `openai`, `gemini`, `anthropic`, `ollama`, `bedrock` cho việc này.

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

**Điểm mạnh.** Cài nhanh, chạy được trên nhiều trợ lý và nhiều hệ điều hành. Phần code xử lý cục bộ, không tốn LLM, có thể lặp lại với cùng kết quả. Mỗi cạnh có nhãn rõ ràng nên bạn không bị đánh lừa bởi suy đoán. Repo vẫn được cập nhật trong vài tháng gần đây và có tài liệu riêng khá đầy đủ.

**Giới hạn.** Bạn vẫn cần một trợ lý AI đang chạy để dùng skill, và phần tài liệu, ảnh, video cần một model để xử lý, nên nó không hoàn toàn "không rời máy" cho những loại này. Các cạnh `INFERRED` là suy luận, đừng coi như sự thật tuyệt đối. Benchmark là số liệu do tác giả đưa ra; nếu quan trọng, bạn nên thử trên dự án của chính mình.

**Khi nào chọn cách khác.** Dự án chỉ vài file thì đọc trực tiếp là đủ, không cần dựng đồ thị. Nếu bạn cần đồ thị luôn cập nhật xuyên nhiều repo, cùng các kết nối với Sentry hay Jira, tác giả có bản đám mây riêng là Graphify Cloud. Bản đó khác bản mã nguồn mở trong repo này, và mình không có thêm thông tin chi tiết về nó ngoài những gì README nói.

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

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

Repo mã nguồn mở dưới giấy phép Apache-2.0, và README nói phần dựng đồ thị từ code tốn 0 LLM credit. Phần xử lý tài liệu, PDF, ảnh, video dùng model của trợ lý bạn hoặc một API key bạn cấu hình, nên chi phí tuỳ vào nhà cung cấp đó. Ngoài ra tác giả có sản phẩm Graphify Cloud riêng, README nói có thể bắt đầu miễn phí.

### Cần GPU để chạy Graphify không?

Tư liệu không yêu cầu GPU. Điều kiện được nêu là Python 3.10 trở lên và uv hoặc pipx. Phần code được phân tích bằng tree-sitter trên máy, không cần model.

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

Được. README nêu hỗ trợ macOS, Linux và Windows. Trên Windows bạn có thể cài uv bằng `winget install astral-sh.uv`, rồi chạy `uv tool install graphifyy` và `graphify install`.

### Code của mình có bị gửi lên mạng 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 gì rời khỏi máy bạn. Riêng bước semantic cho tài liệu, PDF, ảnh, video sẽ dùng model của trợ lý hoặc backend bạn cấu hình, nên dữ liệu loại này có thể đi qua nhà cung cấp model đó.

### 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 và hơn 20 công cụ khác như OpenCode, Aider, Kiro, Antigravity. Mỗi công cụ có lệnh cài riêng trong bảng nền tảng. Người dùng Codex gõ `$graphify` thay vì `/graphify`.

### Graphify khác gì với tìm kiếm bằng vector hay RAG thông thường?

README nói Graphify không dùng embedding hay vector store. Nó dựng một đồ thị thật mà bạn đi qua từng cạnh, và mỗi cạnh gắn nhãn EXTRACTED hoặc INFERRED. Mình không có thêm tư liệu so sánh chi tiết với từng công cụ khác ngoài các bảng benchmark trong BENCHMARKS.md.

### Cài xong rồi thì xem kết quả ở đâu?

Kết quả nằm trong thư mục `graphify-out/` gồm ba file: `graph.html` (mở bằng trình duyệt), `GRAPH_REPORT.md` (tóm tắt các điểm chính) và `graph.json` (toàn bộ đồ thị để truy vấn lại).
