# 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 (gói Python graphifyy) giúp trợ lý AI lập trình dựng đồ thị tri thức từ code, tài liệu, PDF, ảnh và video của dự án. Bạn gõ /graphify trong trợ lý AI rồi hỏi đáp trên đồ thị thay vì để AI đọc từng file. Cài đặt gồm hai lệnh nếu máy đã có Python 3.10+ và uv.

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

Graphify là một skill (kèm công cụ dòng lệnh) cho trợ lý AI lập trình như Claude Code, Cursor, Codex hay Gemini CLI. Bạn gõ `/graphify` trong trợ lý, 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**. Sau đó bạn hỏi đáp trên đồ thị này thay vì bắt AI đọc lại từng file.

Vấn đề nó giải quyết rất quen thuộc. Dự án lớn lên, bạn (hoặc AI) mất nhiều thời gian lục file để hiểu "cái này nối với cái kia thế nào". Graphify gom sẵn các mối quan hệ đó vào một file `graph.json`, nên lần sau bạn chỉ việc hỏi. Ai nên dùng: lập trình viên mới vào một codebase lạ, người đang tiếp quản dự án cũ, hoặc ai muốn trợ lý AI hiểu dự án nhanh hơ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 LLM, không gửi code đi đâu. Mỗi mối nối trong đồ thị đều đượ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.779 sao và 14.077 fork, dùng 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 cho Claude Code, Cursor, Codex, Gemini CLI: biến code, tài liệu, PDF thành đồ thị tri thức để hỏi, truy đường đi, giải thích khái niệm.
- stars | 147k
- lang | Python
- license | Apache-2.0
```

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

Mình tóm các tính năng chính theo kiểu "bạn được lợi gì".

### Dựng đồ thị từ code mà không tốn token

Code được đọc bằng tree-sitter AST: kết quả cố định, không dùng mô hình AI, không rời khỏi máy bạn. README ghi bước dựng đồ thị từ code tốn 0 credit LLM. Với người làm kinh doanh hay chủ dự án, điều này nghĩa là không lo hoá đơn API chỉ để "lập bản đồ" code.

### Mỗi mối nối đều có nhãn tin cậy

Mỗi cạnh trong đồ thị mang nhãn `EXTRACTED` (có ghi rõ trong mã nguồn) hoặc `INFERRED` (do Graphify suy ra). Bạn nhìn là biết chỗ nào chắc chắn, chỗ nào cần kiểm tra lại. Đây là điểm khác với nhiều công cụ trả lời "nghe có vẻ đúng" mà không nói căn cứ.

### Tìm "nút thần" và các cụm chức năng

Đồ thị chỉ ra những khái niệm có nhiều kết nối nhất (God nodes), tức nơi mọi thứ đi qua. Nó cũng chia dự án thành các cộng đồng (subsystem) theo thuật toán Leiden, đặt nhãn mà không cần LLM. Nhờ đó bạn thấy ngay "dự án này có mấy khối lớn".

### Liên kết chéo giữa các file

Các quan hệ như `calls`, `imports`, `inherits`, `mixes_in` được nối xuyên các file, hỗ trợ khoảng 40 ngôn ngữ qua tree-sitter. Bạn lần theo được "hàm này được ai gọi, kế thừa từ đâu" mà không phải tự tìm.

### Hỏi, truy đường đi, giải thích

Ba kiểu thao tác chính, đều chạy trên `graph.json`:

- hỏi một câu bằng ngôn ngữ thường (`graphify query`);
- tìm đường nối giữa hai thứ (`graphify path`);
- giải thích một khái niệm (`graphify explain`).

### Lý do thiết kế được lưu thành nút

Các comment dạng `# NOTE:` / `# WHY:` và các trích dẫn ADR/RFC trở thành nút trong đồ thị, nối với đoạn code liên quan. Lý do "vì sao viết thế này" không bị mất.

### Không chỉ có code

Tài liệu, PDF, ảnh, video/audio cũng được đưa vào cùng một đồ thị. Riêng phần này cần bước "semantic" dùng mô hình của trợ lý bạn đang dùng, hoặc một API key nếu bạn cấu hình.

### Không dùng vector store

Không có embedding hay cơ sở dữ liệu vector. Đây là một đồ thị thật để duyệt. README cũng đưa ra bảng benchmark (ví dụ recall@10 là 0.497 trên LOCOMO), chi tiết nằm trong file BENCHMARKS.md của repo.

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

Theo README, bạn cần:

| Thứ cần có | Yêu cầu | Cách kiểm tra |
|---|---|---|
| Python | 3.10 trở lên (pyproject.toml ghi `>=3.10,<3.15`) | `python --version` |
| uv (khuyên dùng) | phiên bản nào cũng được | `uv --version` |
| pipx (thay thế) | phiên bản nào cũng được | `pipx --version` |

Bạn cũng cần một trợ lý AI lập trình đã cài sẵn, ví dụ Claude Code, Cursor, Codex hay Gemini CLI. README nói hỗ trợ macOS, Linux và Windows, cùng hơn 20 trợ lý khác. Về phần cứng, tư liệu không nêu yêu cầu GPU hay RAM cụ thể.

Về tài khoản và key: dựng đồ thị từ code không cần key. Chỉ khi xử lý tài liệu, PDF, ảnh, video thì Graphify dùng mô hình của trợ lý, hoặc backend/API key mà bạn tự cấu hình.

```note
Tên gói trên PyPI là graphifyy (hai chữ y). README cảnh báo các gói graphify* khác trên PyPI không liên quan đến dự án. Lệnh bạn gõ sau khi cài vẫn là graphify. Gõ nhầm tên gói là cách dễ cài phải gói lạ nhất.
```

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

```steps
- Chuẩn bị Python và uv | Cài Python 3.10+ và uv (hoặc pipx)
- 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 Python và uv

Kiểm tra xem máy đã có Python chưa. Mở terminal (trên Windows là PowerShell, trên macOS là Terminal) và gõ:

```bash
python --version
uv --version
```

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

Trên macOS (Homebrew):

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

Trên Windows:

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

Trên Ubuntu/Debian (uv tự quản lý Python của nó nên chỉ cần lệnh này):

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

Nếu muốn dùng Python hệ thống với pipx, README ghi:

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

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

### Cài công cụ Graphify

Chọn một trong ba cách. README khuyên dùng `uv`:

```bash
uv tool install graphifyy   # khuyên dùng, 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
```

Nếu cài bằng uv 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ở terminal mới. Đây là chỗ người mới hay vấp nhất: lệnh đã cài nhưng terminal chưa biết đường dẫn.

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

Chạy một lần:

```bash
graphify install
```

Lệnh này tự phát hiện trợ lý bạn đang dùng và đăng ký skill, nên không cần cài riêng cho từng trợ lý. Với một số trợ lý, README liệt kê lệnh riêng:

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

Ngoài ra README ghi nhiều nền tảng khác (Copilot CLI, Aider, OpenCode, Kiro, Antigravity...). Bạn xem bảng "Pick your platform" trong README để lấy đúng lệnh. Riêng Codex, README dặn thêm `multi_agent = true` dưới mục `[features]` trong file `~/.codex/config.toml` để trích xuất song song.

### Cài riêng cho một dự án (tuỳ chọn)

Muốn skill nằm trong chính repo của dự án (để đồng đội cùng dùng) thì thêm `--project`:

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

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`, rồi in gợi ý `git add` cho các file có thể commit. Nhớ chạy lệnh khi đang đứng trong thư mục dự án.

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

Bản cơ bản chưa xử lý PDF, Word/Excel hay video. README có các extra, cài theo mẫu:

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

Ý nghĩa: `pdf` để đọc PDF, `office` cho `.docx` và `.xlsx`, `video` để chép lời video/audio, `watch` để tự dựng lại đồ thị khi file đổi (`graphify watch`). Còn có `mcp`, `neo4j`, `svg`, `ollama`, `openai`, `gemini`, `anthropic`... Chỉ cài cái bạn thật sự cần.

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

Mở trợ lý AI trong thư mục dự án và gõ:

```
/graphify .
```

Với Codex thì gõ `$graphify .` thay vì `/graphify .`. Khi chạy xong, theo README bạn sẽ có thư mục `graphify-out/` với ba file:

```
graphify-out/
├── graph.html       mở bằng trình duyệt: bấm nút, lọc, tìm kiếm
├── GRAPH_REPORT.md  điểm nổi bật: khái niệm chính, kết nối bất ngờ, câu hỏi gợi ý
└── graph.json       toàn bộ đồ thị, hỏi lại bất cứ lúc nào mà không đọc lại file
```

Cách kiểm tra nhanh: mở `graph.html` bằng trình duyệt, nếu thấy đồ thị với các nút bấm được là đã thành công. Đọc thử `GRAPH_REPORT.md` để xem dự án có những khái niệm trung tâm nào. Tiếp theo thử một lệnh hỏi:

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

Thay `APIRouter` bằng tên một hàm hoặc lớp có thật trong dự án của bạn. Kết quả mong đợi là một khối gồm nơi khai báo, cộng đồng, số kết nối, rồi danh sách các mối nối kèm nhãn `[EXTRACTED]` hoặc `[INFERRED]`.

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

### Dev mới nhận một dự án lạ

Bạn vừa vào công ty và được giao một codebase hàng trăm file. Thay vì mở từng file, bạn chạy `/graphify .` ở thư mục gốc. Mở `GRAPH_REPORT.md` để xem các "nút thần" và các cụm chức năng. Sau đó hỏi thử:

```bash
graphify query "request đi qua những bước nào trước khi vào hàm xử lý?"
```

Bạn nhận về một đồ thị con liên quan đến câu hỏi, đủ để biết nên đọc file nào trước. Câu hỏi nên cụ thể, dùng tên thật trong dự án thì kết quả tốt hơn.

### Hiểu một khái niệm trước khi sửa

Bạn cần sửa một lớp quan trọng nhưng sợ đụng chỗ khác. Chạy:

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

(đổi tên cho đúng dự án của bạn). Kết quả liệt kê mọi thứ mà lớp đó nối tới và được nối từ đâu, mỗi mối nối có nhãn tin cậy. Mối nối `EXTRACTED` bạn có thể tin; mối nối `INFERRED` nên mở code ra xem lại trước khi sửa.

> Hỏi đồ thị trước, đọc file sau: bạn tiết kiệm được cả buổi lục grep.
>
> — Ông T

### Tìm xem hai thứ liên quan nhau thế nào

Trưởng nhóm muốn biết module thanh toán có phụ thuộc vào module báo cáo không. Chạy:

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

Thay hai tên bằng hai khái niệm trong dự án của bạn. Theo README, kết quả là đường ngắn nhất giữa hai nút, ví dụ "3 hops", kèm độ tin cậy chung bằng độ tin cậy của chặng yếu nhất. Nếu đường nối chỉ toàn `EXTRACTED` thì quan hệ đó chắc chắn.

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

Một nhóm có thư mục `docs/` với đặc tả, PDF thiết kế và ghi chú. Sau khi cài extra `pdf` (`uv tool install "graphifyy[pdf]"`), chạy `/graphify .` ở thư mục gốc. Tài liệu, PDF được đưa vào cùng đồ thị với code, nên bạn hỏi được kiểu "tài liệu nào nói về phần code này". 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 có thể tốn token, khác với phần code là miễn phí và chạy cục bộ.

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

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

Nguyên nhân thường là thư mục chứa lệnh chưa nằm trong PATH. Nếu bạn cài bằng uv, chạy `uv tool update-shell` rồi mở terminal mới. Nếu cài bằng `pip` trên Mac/Windows, README cũng nhắc có thể phải chỉnh PATH; cách an toàn hơn là cài lại bằng `uv tool install graphifyy` hoặc `pipx install graphifyy`. README còn trỏ tới trang Installation và Troubleshooting trên docs.graphify.com cho các tình huống này.

### Cài nhầm gói trên PyPI

Tên đúng là `graphifyy` (hai chữ y). Gõ `graphify` một chữ y có thể ra gói khác, không phải của dự án. Hãy gỡ gói lạ rồi cài lại đúng tên.

### Gõ /graphify mà trợ lý không nhận

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

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

Bản cài cơ bản chưa gồm các phần này. Cài thêm extra tương ứng như `graphifyy[pdf]`, `graphifyy[office]` hoặc `graphifyy[video]`, rồi chạy lại `/graphify .`.

### Tool cài bằng uvx hoặc hook không chạy được

Phần mô tả trợ lý Pi trong README dặn cài Graphify lâu dài bằng `uv tool install graphifyy` hoặc `pipx install graphifyy`, không dùng `uvx`, rồi khởi động lại trợ lý. Nếu gặp vấn đề với hook, PowerShell hay chế độ strict, hãy xem trang Troubleshooting của dự án thay vì đoán cờ lệnh.

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

**Điểm mạnh.** Cài nhanh (hai lệnh), phần code chạy cục bộ và không tốn token LLM, mỗi mối nối có nhãn tin cậy nên dễ kiểm chứng. Hỗ trợ nhiều trợ lý AI và nhiều hệ điều hành, giấy phép Apache-2.0, repo còn hoạt động. Đồ thị lưu thành `graph.json` nên hỏi lại bao nhiêu lần cũng không phải đọc lại file.

**Giới hạn.** Mối nối `INFERRED` là do công cụ suy ra, không phải sự thật tuyệt đối, bạn vẫn cần kiểm tra khi sửa code quan trọng. Phần tài liệu, PDF, ảnh, video cần mô hình hoặc API key, nên có thể phát sinh chi phí. Công cụ khá nhiều tuỳ chọn (rất nhiều extra và nền tảng), người mới nên bắt đầu với hai lệnh đầu rồi mới thêm dần. Tư liệu tôi có chưa nêu yêu cầu phần cứng cụ thể.

**Khi nào chọn cách khác.** Nếu dự án chỉ vài file nhỏ, bạn không cần đồ thị, cứ để AI đọc trực tiếp. README cũng giới thiệu bản Graphify Cloud (trả phí hay không thì xem trang của dự án) cho nhu cầu chạy liên tục, nhiều repo, tích hợp Sentry/Jira. Còn nếu bạn chỉ cần hiểu một dự án và thích chạy cục bộ, bản mã nguồn mở là điểm bắt đầu hợp lý.

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

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

Repo mã nguồn mở dùng giấy phép Apache-2.0, và README ghi bước dựng đồ thị từ code tốn 0 credit LLM. Phần tài liệu, PDF, ả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í tuỳ nhà cung cấp. Ngoài ra có bản Graphify Cloud riêng, chi tiết xem trang dự án.

### Có cần GPU không?

Tư liệu không nêu yêu cầu GPU. Phần code được phân tích bằng tree-sitter AST ngay trên máy, không dùng LLM. Có extra cho Ollama nếu bạn muốn chạy mô hình cục bộ, nhưng đó là tuỳ chọn.

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

Được. README ghi hỗ trợ macOS, Linux và Windows. Trên Windows có thể cài uv bằng winget install astral-sh.uv, rồi dùng uv tool install graphifyy và graphify install như bình thường.

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

README nói 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 bạn. Chỉ bước semantic cho tài liệu, PDF, ảnh, video mới gọi một backend, và chỉ khi bạn cấu hình. Nên đọc thêm SECURITY.md của repo nếu cần chắc chắn.

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

README nêu Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot và hơn 20 trợ lý khác. Lệnh cài cho từng nền tảng nằm trong bảng Pick your platform của README. Riêng Codex gọi bằng $graphify thay vì /graphify.

### Graphify khác gì việc để AI tự đọc và grep file?

Graphify dựng sẵn đồ thị các mối quan hệ rồi lưu thành graph.json, nên bạn hỏi, truy đường đi, giải thích khái niệm mà không phải đọc lại file. README có so sánh benchmark, ví dụ độ phủ thông tin chính 82.0% so với 70.8% của cách grep/đọc file trên một bài thử ERPNext. Chi tiết xem BENCHMARKS.md.

### Tên gói cài là gì, có dễ nhầm không?

Tên đúng trên PyPI là graphifyy với hai chữ y. README cảnh báo các gói graphify* khác không liên quan đến dự án. Sau khi cài, lệnh vẫn là graphify.
