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

> Graphify là một skill (kèm công cụ dòng lệnh) cho trợ lý lập trình AI như Claude Code, Cursor, Codex, Gemini CLI. Nó quét thư mục dự án và dựng thành đồ thị tri thức để bạn hỏi đáp thay vì lục từng file. Cài bằng 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-22 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/graphify-do-thi-tri-thuc-codebase-huong-dan-cai-dat-3

Graphify là một skill cho trợ lý lập trình AI. Bạn gõ `/graphify` trong Claude Code, Cursor, Codex hay Gemini CLI, và nó quét cả dự án (code, tài liệu, PDF, ảnh, video) rồi dựng thành một **đồ thị tri thức**. Từ đó, bạn hỏi đáp trên đồ thị thay vì bắt AI đọc lại hàng trăm file mỗi lần.

Vấn đề nó giải quyết rất đời thường: bạn vào một dự án lạ, hoặc dự án của mình đã phình to, và không biết cái gì nối với cái gì. Cứ hỏi AI là nó lại đi grep, đọc file, tốn thời gian và tốn token. Graphify làm bước đó một lần, lưu kết quả ra file, rồi các lần sau chỉ cần truy vấn.

Điểm đáng giá nhất: phần code được phân tích bằng tree-sitter AST ngay trên máy bạn, không dùng mô hình AI và không gửi gì ra ngoài. Mỗi liên kết trong đồ thị còn được gắn nhãn cho biết nó đọc thẳng từ mã nguồn hay do công cụ suy ra. Repo hiện có khoảng 146.971 sao và 14.096 fork, giấy phép Apache-2.0, và vẫn được cập nhật trong 3 tháng gần đây.

```repo
- repo | Graphify-Labs/graphify
- kind | Skill
- desc | Skill /graphify biến code, tài liệu, PDF thành đồ thị tri thức để hỏi đáp ngay trong Claude Code, Cursor, Codex, Gemini CLI; code phân tích cục bộ, không cần vector store.
- stars | 147k
- lang | Python
- license | Apache-2.0
```

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

Dưới đây là những tính năng chính, giải thích theo lợi ích thực tế.

- **Dựng đồ thị từ cả dự án.** Một lệnh `/graphify .` tạo ra ba file: `graph.html` để mở bằng trình duyệt và bấm xem, `GRAPH_REPORT.md` tóm tắt những điểm chính, `graph.json` là toàn bộ đồ thị để truy vấn lại bất cứ lúc nào mà không cần đọc lại file gốc.
- **Nút "god node".** Đây 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 đi qua đâu, rất hữu ích khi mới tiếp quản code.
- **Chia cụm (communities).** Đồ thị được chia thành các hệ thống con, tên cụm đặt tự động mà không cần LLM. Bạn thấy ngay dự án gồm những khối nào.
- **Liên kết giữa các file.** Các quan hệ như `calls`, `imports`, `inherits`, `mixes_in` được nối xuyên file, theo README là hỗ trợ khoảng 40 ngôn ngữ lập trình.
- **Hỏi, tìm đường, giải thích.** Có ba kiểu truy vấn: `query` cho câu hỏi bằng ngôn ngữ thường, `path` để xem hai thứ nối với nhau thế nào, `explain` để giải thích một khái niệm.
- **Nhãn độ tin cậy.** Mỗi cạnh là `EXTRACTED` (có sẵn trong mã nguồn) hoặc `INFERRED` (do Graphify suy ra). Bạn biết đâu là chắc chắn, đâu cần kiểm tra lại.
- **Ghi chú lý do thành nút.** Các comment kiểu `# 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.
- **Không chỉ code.** Tài liệu, PDF, ảnh, video/âm thanh cũng vào cùng một đồ thị. Phần này dùng mô hình của trợ lý bạn đang dùng, hoặc API key bạn tự cấu hình.
- **Không phải vector index.** Không có embedding, không có vector store. Đây là đồ thị thật để duyệt qua.

README còn nêu số liệu đánh giá, ví dụ recall@10 là 0.497 trên bộ LOCOMO và chi phí dựng đồ thị là 0 LLM credit. Chi tiết nằm trong file BENCHMARKS.md của repo, bạn nên tự đọc nếu quan tâm.

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

Theo README và `pyproject.toml`, bạn cần:

- **Python 3.10 trở lên.** File cấu hình ghi rõ phiên bản được hỗ trợ là từ 3.10 đến dưới 3.15. Kiểm tra bằng `python --version`.
- **uv** (README khuyến nghị) hoặc **pipx** để cài công cụ dòng lệnh.
- **Một trợ lý AI** để gõ `/graphify`: Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot và hơn 20 trợ lý khác.
- **Hệ điều hành:** macOS, Linux, Windows đều được README nhắc tới.
- **API key:** chỉ cần nếu bạn muốn xử lý tài liệu, ảnh, video bằng một backend riêng. Với code thì không cần key nào.

README không nói gì về yêu cầu GPU hay RAM tối thiểu, nên mình không khẳng định gì về phần cứng.

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

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

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

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

Lệnh đầu dành cho macOS (Homebrew), lệnh hai cho Windows, lệnh ba cho Linux như Ubuntu/Debian.

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

```steps
- Cài uv | Chuẩn bị công cụ cài đặt (hoặc dùng pipx)
- Cài Graphify | Cài gói graphifyy để có lệnh graphify
- Đăng ký skill | Chạy graphify install để gắn skill vào trợ lý
- Chạy trên dự án | Mở trợ lý trong thư mục dự án và gõ /graphify .
- Xem kết quả | Mở thư mục graphify-out
```

### Cài uv (hoặc pipx)

Nếu máy đã có uv thì bỏ qua bước này. Kiểm tra bằng:

```bash
uv --version
```

Nếu báo lỗi, dùng một trong các lệnh ở phần chuẩn bị phía trên. Người dùng Windows mở PowerShell rồi chạy lệnh `winget`. Sau khi cài xong, nên đóng terminal và mở lại để máy nhận lệnh mới.

### Cài Graphify

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

```bash
uv tool install graphifyy
```

Nếu dùng pipx thì thay bằng:

```bash
pipx install graphifyy
```

README còn liệt kê `pip install graphifyy`, nhưng cách này có thể phải tự chỉnh PATH, người mới nên tránh. 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
```

Sau đó mở terminal mới.

### Đăng ký skill với trợ lý

```bash
graphify install
```

Lệnh này tự nhận ra trợ lý bạn đang dùng và đăng ký skill, nên không cần cấu hình riêng cho từng trợ lý. Với một số trợ lý, README ghi lệnh riêng, ví dụ:

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

Bạn dùng trợ lý nào thì chọn đúng dòng đó. Danh sách đầy đủ hơn 20 nền tảng nằm trong README.

Nếu muốn skill nằm ngay trong dự án (để cả nhóm dùng chung) thay vì cài vào hồ sơ người dùng, thêm `--project`:

```bash
graphify install --project
```

Lệnh này ghi file vào thư mục hiện tại, ví dụ `.claude/skills/graphify/SKILL.md` hoặc `.agents/skills/graphify/SKILL.md`. Vì vậy hãy mở terminal đúng thư mục gốc dự án trước khi chạy.

```note
Người dùng Codex cần thêm dòng multi_agent = true dưới mục [features] trong file ~/.codex/config.toml để chạy trích xuất song song. Và trong Codex bạn gõ $graphify chứ không phải /graphify.
```

### Chạy trên dự án của bạn

Mở trợ lý AI ngay trong thư mục dự án, rồi gõ:

```
/graphify .
```

Dấu chấm nghĩa là "thư mục hiện tại". Chờ nó chạy xong, bạn sẽ có thư mục `graphify-out`.

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

Mặc định chưa có hỗ trợ PDF, Word, Excel hay video. Cần loại nào thì cài thêm loại đó, theo bảng trong README:

```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. README còn có `mcp`, `watch` (tự dựng lại khi file đổi), `openai`, `gemini`, `anthropic`, `ollama` và vài loại khác. Đừng cài hết một lượt, chỉ lấy cái bạn cần.

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

Sau khi chạy `/graphify .`, kiểm tra theo thứ tự:

1. Có thư mục `graphify-out` trong dự án, với đủ ba file `graph.html`, `GRAPH_REPORT.md`, `graph.json`.
2. Mở `graph.html` bằng trình duyệt bất kỳ. Bạn sẽ thấy đồ thị có thể bấm vào nút, lọc và tìm kiếm.
3. Mở `GRAPH_REPORT.md` để đọc các khái niệm chính, các liên kết bất ngờ và câu hỏi gợi ý.
4. Thử một lệnh truy vấn. README cho ví dụ trên codebase FastAPI:

```bash
graphify explain "APIRouter"
graphify path "FastAPI" "ModelField"
```

Kết quả mong đợi của `explain` là tên nút, file nguồn, cụm, số kết nối, rồi danh sách các liên kết kèm nhãn `[EXTRACTED]` hoặc `[INFERRED]`. Kết quả của `path` là đường ngắn nhất giữa hai thứ. Thay tên trong ngoặc bằng tên có thật trong dự án của bạn.

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

Dưới đây là các tình huống mình thấy hợp với khả năng mà README mô tả.

### Dev mới nhận một dự án cũ

Bạn vừa vào công ty, được giao repo hàng trăm file và gần như không có tài liệu. Chạy `/graphify .` ở thư mục gốc, sau đó mở `GRAPH_REPORT.md` đọc phần khái niệm chính và các "god node". Mở thêm `graph.html` để xem dự án chia thành những cụm nào. Chỉ sau một buổi, bạn đã có bản đồ để biết nên đọc file nào trước.

> Hỏi trên đồ thị đã dựng sẵn, thay vì bắt AI đọc lại cả dự án mỗi lần.
>
> — Ông T

### Tìm xem sửa chỗ này thì ảnh hưởng gì

Bạn định sửa một hàm lõi nhưng sợ vỡ chỗ khác. Hỏi một câu bằng tiếng thường:

```bash
graphify query "hàm nào phụ thuộc vào phần xử lý thanh toán?"
```

Lệnh trả về một đồ thị con liên quan đến câu hỏi. Nếu muốn biết hai thành phần nối với nhau thế nào, dùng `graphify path A B`, kết quả có kèm độ tin cậy của cả đường đi (tính theo mắt xích yếu nhất). Gặp cạnh `INFERRED` thì hãy tự mở code kiểm tra lại.

### Nhân viên văn phòng gom tài liệu dự án

Bạn phụ trách một dự án có thư mục lẫn lộn file Word, Excel, PDF. Cài các phần mở rộng `office` và `pdf`, rồi chạy `/graphify .` ở thư mục đó. Tài liệu sẽ được đưa vào cùng một đồ thị. Lưu ý phần này dùng mô hình của trợ lý hoặc API key bạn cấu hình, nên không hoàn toàn cục bộ như phần code.

### Tìm vì sao code được viết như vậy

Trong code có những comment `# WHY:` hay `# NOTE:`, và tài liệu có nhắc ADR/RFC. Graphify biến chúng thành nút liên kết với code. Khi hỏi về một module, bạn thấy luôn lý do thiết kế đi kèm, đỡ phải đi hỏi người đã nghỉ việc.

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

### Gõ graphify báo "command not found"

Thường do thư mục chứa lệnh chưa nằm trong PATH. Chạy `uv tool update-shell`, đóng hẳn terminal rồi mở lại. Nếu vẫn lỗi, xem mục Installation và Troubleshooting trên trang docs của dự án.

### Cài nhầm gói

Trên PyPI có nhiều gói tên gần giống. Gói chính thức là `graphifyy` (hai chữ y). Hãy gõ cẩn thận, đừng gõ `graphify` một chữ y khi cài.

### Gõ /graphify mà trợ lý không hiểu

Có thể bạn chưa chạy `graphify install`, hoặc chạy khi trợ lý chưa được nhận diện. Chạy lại lệnh đúng nền tảng (ví dụ `graphify install --platform codex`), rồi khởi động lại trợ lý. Với Codex, nhớ dùng `$graphify`.

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

Các loại này cần phần mở rộng riêng. Cài `graphifyy[pdf]`, `graphifyy[office]` hoặc `graphifyy[video]` tuỳ loại file. Phần xử lý nội dung này còn cần mô hình của trợ lý hoặc một backend bạn đã cấu hình.

### Đồ thị cũ sau khi sửa code

`graph.json` là bản chụp lúc dựng. Khi code đổi nhiều, hãy chạy lại `/graphify .`. README có phần mở rộng `watch` để tự dựng lại khi file thay đổi, bạn có thể tìm hiểu thêm trong tài liệu.

```note
Code được phân tích cục bộ và không gửi đi đâu. Nhưng với tài liệu, ảnh, video, nội dung sẽ đi qua mô hình của trợ lý hoặc backend bạn cấu hình. Nếu dự án có dữ liệu nhạy cảm, hãy kiểm tra kỹ trước khi đưa vào, và khô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 là xong, chạy được trên nhiều trợ lý và hệ điều hành.
- Phần code xử lý cục bộ, tất định, không tốn LLM credit.
- Mỗi liên kết có nhãn `EXTRACTED` hoặc `INFERRED`, nên bạn biết nên tin đến đâu.
- Kết quả là file thường (HTML, Markdown, JSON), dễ xem, dễ chia sẻ.
- Mã nguồn mở, giấy phép Apache-2.0.

**Giới hạn:**

- Bạn vẫn cần quen terminal và biết mở trợ lý AI trong đúng thư mục.
- Cạnh `INFERRED` là suy luận, không phải sự thật tuyệt đối.
- Xử lý tài liệu, ảnh, video phụ thuộc vào mô hình hoặc API key, nên có thể phát sinh chi phí tuỳ cách bạn cấu hình.
- Đồ thị là bản chụp nên cần dựng lại khi dự án đổi nhiều.
- README còn quảng bá bản Graphify Cloud (dịch vụ riêng, chạy liên tục). Mình không có thông tin chi tiết về giá, bạn tự xem trên trang của dự án nếu quan tâm. Bản mã nguồn mở này dùng độc lập được.

Nếu dự án chỉ vài file nhỏ thì không cần dùng, để trợ lý đọc thẳng là đủ. Nếu bạn hay phải làm quen codebase lớn hoặc nhiều tài liệu lẫn lộn, Graphify đáng thử một buổi.

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

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

Repo là mã nguồn mở với giấy phép Apache-2.0, và README nói dựng đồ thị từ code tốn 0 LLM credit. Phần xử lý 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 phí từ bên đó. Dự án cũng có bản Graphify Cloud riêng, chưa có thông tin giá trong tư liệu.

### Cần Python phiên bản nào?

README yêu cầu Python 3.10 trở lên, và file pyproject.toml ghi rõ từ 3.10 đến dưới 3.15. Bạn kiểm tra bằng lệnh python --version. Nên cài thêm uv (hoặc pipx) để cài công cụ dòng lệnh.

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

Có. README nói một lần cài dùng cho mọi trợ lý và mọi hệ điều hành, gồm macOS, Linux và Windows. Trên Windows có thể cài uv bằng lệnh winget install astral-sh.uv trong PowerShell.

### Code của mình có bị gửi lên mạng không?

Theo README, code được phân tích bằng tree-sitter ngay trên máy, không dùng LLM và không rời máy bạn. Riêng phần tài liệu, PDF, ảnh, video cần bước phân tích ngữ nghĩa bằng mô hình của trợ lý hoặc backend bạn cấu hình, nên nội dung đó sẽ đi qua dịch vụ tương ứng.

### Cần GPU không?

Tư liệu không nói Graphify yêu cầu GPU. Phần code được phân tích bằng AST theo cách tất định, không dùng mô hình. Với phần phiên âm video hay chạy mô hình cục bộ qua Ollama, README không nêu yêu cầu phần cứng cụ thể.

### Khác gì 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ỗi cạnh được gắn nhãn EXTRACTED hoặc INFERRED, và bạn truy vấn bằng query, path, explain. README có bảng so sánh với một số hệ thống khác, xem file BENCHMARKS.md trong repo để biết chi tiết.

### Hỗ trợ những trợ lý AI nào?

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