Graphify: biến cả codebase thành đồ thị tri thức để hỏi đáp — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về Graphify-Labs/graphify — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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 →

Tóm tắt nhanh
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.
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.
Graphify-Labs/graphify
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.
I.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ì".
A.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.
B.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ứ.
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".
D.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.
E.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).
F.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.
G.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.
H.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.
II.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.
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.
III.Cài đặt từng bước
- Chuẩn bị Python và uvCài Python 3.10+ và uv (hoặc pipx)
- Cài công cụChạy uv tool install graphifyy
- Đăng ký skillChạy graphify install để nó nhận ra trợ lý của bạn
- Mở trợ lý AIVào thư mục dự án, mở Claude Code, Cursor...
- Dựng đồ thịGõ /graphify . trong trợ lý
A.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õ:
python --version
uv --versionNếu chưa có uv, README gợi ý các cách sau.
Trên macOS (Homebrew):
brew install python@3.12 uvTrên Windows:
winget install astral-sh.uvTrên Ubuntu/Debian (uv tự quản lý Python của nó nên chỉ cần lệnh này):
curl -LsSf https://astral.sh/uv/install.sh | shNếu muốn dùng Python hệ thống với pipx, README ghi:
sudo apt install python3 python3-pip pipxSau khi cài xong, nên đóng terminal rồi mở lại để máy nhận lệnh mới.
B.Cài công cụ Graphify
Chọn một trong ba cách. README khuyên dùng uv:
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 PATHNếu cài bằng uv xong mà gõ graphify báo không tìm thấy, README bảo chạy:
uv tool update-shellRồ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.
C.Đăng ký skill với trợ lý
Chạy một lần:
graphify installLệ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:
graphify install --platform codex
graphify install --platform gemini
graphify cursor installNgoà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.
D.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:
graphify install --project
graphify install --project --platform codexLệ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.
E.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:
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.
IV.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 fileCá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:
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].
V.Dùng vào việc thật
A.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ử:
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.
B.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:
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
C.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:
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.
D.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ộ.
VI.Lỗi hay gặp và cách xử lý
A.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.
B.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.
C.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.
D.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 ..
E.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.
VII.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.


