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 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.
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.
Graphify-Labs/graphify
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.
I.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.
EXTRACTEDnghĩa là có ghi rõ trong nguồn,INFERREDnghĩ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ả.
II.Cần chuẩn bị gì
Theo README, bạn cần:
- Python 3.10 trở lên. File
pyproject.tomlghi rõ yêu cầu>=3.10,<3.15. Kiểm tra bằngpython --version. - uv (khuyến nghị) hoặc pipx để cài lệnh
graphify. Kiểm tra bằnguv --versionhoặcpipx --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 ý:
brew install python@3.12 uvĐó là cách cho macOS (Homebrew). Trên Windows:
winget install astral-sh.uvTrên Ubuntu/Debian, uv tự quản lý Python nên chỉ cần một lệnh:
curl -LsSf https://astral.sh/uv/install.sh | shVớ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.
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.
III.Cài đặt từng bước
- Cài Python và uvĐảm bảo có Python 3.10+ và uv (hoặc pipx)
- Cài lệnh graphifyDùng uv tool install graphifyy (hai chữ y)
- Đăng ký skillChạy graphify install để gắn skill vào trợ lý AI
- Mở trợ lý trong thư mục dự ánMở 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ả
A.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:
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 PATHChú ý: 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:
uv tool update-shellRồi đóng terminal, mở lại.
B.Đăng ký skill vào trợ lý AI
Chạy đúng một lần:
graphify installLệ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ụ:
graphify install --platform codex
graphify install --platform gemini
graphify cursor installBạ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:
graphify install --project
graphify install --project --platform codexCá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.
C.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 ..
D.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:
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.
IV.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).
V.Dùng vào việc thật
A.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.
B.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:
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
C.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:
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.
D.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:
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.
VI.Lỗi hay gặp và cách xử lý
A.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.
B.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.
C.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.
D.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.
E.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.
VII.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).


