Graphify: biến codebase thành knowledge graph cho trợ lý AI

Graphify là gì

Graphify (kho Graphify-Labs/graphify) là công cụ biến toàn bộ dự án của bạn, gồm mã nguồn, tài liệu, SQL schema, file cấu hình và PDF, thành một knowledge graph có thể truy vấn. Thay vì để trợ lý AI dùng grep lục lọi từng file, bạn chỉ cần gõ /graphify và nhận về một đồ thị thể hiện các khái niệm cùng mối liên hệ giữa chúng.

Công cụ được viết bằng Python, phát hành theo giấy phép Apache 2.0 và hoạt động như một skill cho Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot cùng hơn 20 trợ lý khác. Nếu bạn là lập trình viên thường làm việc với trợ lý AI trên codebase lớn, hoặc cần nhanh chóng nắm kiến trúc một dự án lạ, Graphify rất đáng để thử.

Ba điểm khác biệt chính

• Phân tích mã hoàn toàn cục bộ: mã nguồn được phân tích bằng AST của tree-sitter, có tính xác định, không dùng LLM và không có gì rời khỏi máy bạn. Riêng tài liệu, PDF, hình ảnh và video sẽ cần model của trợ lý hoặc API key bạn cấu hình cho bước phân tích ngữ nghĩa.
• Mỗi cạnh đều được giải thích: mỗi liên kết được gắn nhãn EXTRACTED (có sẵn rõ ràng trong mã) hoặc INFERRED (do Graphify suy ra), nên bạn biết đâu là thông tin đọc trực tiếp, đâu là suy luận.
• Không phải vector index: không embedding, không vector store. Đây là một đồ thị thực sự mà bạn có thể duyệt qua.

Các tính năng nổi bật

God nodes và communities

Graphify chỉ ra những khái niệm được kết nối nhiều nhất (god nodes), nơi mọi thứ đi qua. Đồ thị cũng được chia thành các cộng đồng, tức các hệ thống con, bằng thuật toán Leiden, với nhãn được đặt mà không cần LLM.

Liên kết xuyên file cho khoảng 40 ngôn ngữ

Các quan hệ như calls, imports, inherits, mixes_in được phân giải qua nhiều file cho khoảng 40 ngôn ngữ lập trình nhờ tree-sitter.

Query, path, explain

Bạn có thể đặt câu hỏi bằng ngôn ngữ tự nhiên, tìm đường đi giữa hai thành phần hoặc giải thích một khái niệm, tất cả đều chạy trên file graph.json. Ví dụ trong README:

graphify explain "APIRouter"
graphify path "FastAPI" "ModelField"
graphify query "what connects auth to the database?"

Ghi chú và tài liệu trở thành node

Các comment dạng # NOTE:, # WHY: cùng trích dẫn ADR/RFC được biến thành node riêng, liên kết thẳng tới đoạn mã liên quan.

Không chỉ có mã

Tài liệu, PDF, hình ảnh, video và âm thanh đều có thể đưa vào cùng một đồ thị. Lệnh /graphify add còn cho phép thêm một bài báo từ arXiv hoặc một video YouTube (được chuyển thành văn bản).

Kết quả bạn nhận được

Sau khi chạy, Graphify tạo ra ba file trong thư mục graphify-out/:

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

Ứng dụng thực tế

• Làm quen dự án mới: xem god nodes và communities để hiểu kiến trúc thay vì đọc từng file.
• Giúp trợ lý AI tra cứu thông minh hơn: lệnh graphify <platform> install ghi cấu hình để trợ lý ưu tiên truy vấn đồ thị thay vì grep. Với Claude Code và Gemini CLI, một hook sẽ tự kích hoạt trước các lệnh tìm kiếm.
• Review pull request: lệnh graphify prs hiển thị bảng PR, còn graphify prs --conflicts chỉ ra các PR chạm cùng community, có nguy cơ xung đột khi merge.
• Làm việc nhóm: commit hoặc chia sẻ đồ thị để cả nhóm dùng chung một ngữ cảnh.
• Tự động cập nhật: graphify hook install giúp dựng lại đồ thị khi commit hoặc đổi branch.

Bắt đầu sử dụng

Bạn cần Python 3.10 trở lên và uv (hoặc pipx). Lưu ý: gói chính thức trên PyPI là graphifyy với hai chữ y, các gói graphify* khác không liên quan. Lệnh CLI vẫn là graphify.

1. Trên Windows, cài uv bằng winget:

   winget install astral-sh.uv

2. Cài Graphify CLI:

   uv tool install graphifyy

   Hoặc dùng pipx install graphifyy. Nếu không tìm thấy lệnh graphify, hãy chạy uv tool update-shell.
3. Đăng ký skill cho trợ lý AI của bạn:

   graphify install

   Lệnh này tự nhận diện trợ lý bạn đang dùng. Với nền tảng cụ thể, thêm --platform, ví dụ graphify install --platform codex.
4. Mở trợ lý AI và gõ:

   /graphify .

   Riêng Codex dùng $graphify thay cho /graphify.

Một số lệnh hữu ích khác:

/graphify ./docs --update     # chỉ trích xuất lại file đã đổi
/graphify . --no-viz          # bỏ qua HTML, chỉ tạo report và JSON
/graphify . --wiki            # tạo wiki markdown từ đồ thị
graphify uninstall            # gỡ khỏi mọi nền tảng

Các tính năng như đọc PDF, file Office, video, MCP server hay xuất sang Neo4j được tách thành gói tùy chọn, ví dụ uv tool install "graphifyy[pdf]", hoặc graphifyy[all] để cài tất cả.

Quyền riêng tư

• Mã nguồn được xử lý cục bộ. Nếu chỉ có mã, graphify extract chạy offline hoàn toàn, không cần API key.
• Video và âm thanh được chuyển thành văn bản cục bộ bằng faster-whisper.
• Tài liệu, PDF, hình ảnh sẽ được gửi tới model của trợ lý hoặc backend bạn cấu hình. Muốn chạy hoàn toàn cục bộ, bạn có thể dùng --backend ollama, hoặc đặt GRAPHIFY_BACKEND=none để chỉ giữ đồ thị mã.
• Không có telemetry. Tuy nhiên các câu truy vấn được ghi log vào ~/.cache/graphify-queries.log, bạn có thể tắt bằng GRAPHIFY_QUERY_LOG_DISABLE=1.

Ghi chú thêm

Graphify chạy trên macOS, Linux và Windows, dùng giấy phép Apache 2.0. Dự án hiện có hơn 132 nghìn sao trên GitHub, phiên bản mới nhất là v0.9.94. Nhóm phát triển cũng có dịch vụ trả phí Graphify Cloud với đồ thị luôn cập nhật, hỗ trợ monorepo, nhiều repo và kết nối Sentry, Jira. Phần mã nguồn mở bạn vẫn dùng độc lập được.

Kết luận

Nếu bạn muốn trợ lý AI hiểu codebase theo cấu trúc thay vì grep mò mẫm, Graphify là lựa chọn thú vị: phân tích cục bộ, mỗi liên kết đều rõ nguồn gốc và cài đặt chỉ mất vài lệnh. Hãy ghé Graphify-Labs/graphify trên GitHub để xem tài liệu đầy đủ và thử ngay trên dự án của bạn.