Graphify: biến codebase thành knowledge graph cho AI agent

Bạn đã bao giờ giao cho AI agent một nhiệm vụ trong repo lạ, rồi ngồi xem nó grep hết file này tới file khác, đọc cả trăm dòng không liên quan, cuối cùng vẫn sửa sai chỗ chưa? Vấn đề không phải agent dốt. Vấn đề là agent không có bản đồ. Nó thấy từng cái cây, nhưng không thấy cả khu rừng: hàm này gọi hàm nào, class này kế thừa từ đâu, một thay đổi ở module A sẽ lan tới những đâu.

Graphify sinh ra để vẽ tấm bản đồ đó. Thay vì để agent tự mò mẫm trong đống file, bạn biến toàn bộ dự án thành một knowledge graph có thể truy vấn được, rồi hỏi thẳng vào graph: “APIRouter liên quan tới những gì?”, “đường ngắn nhất từ FastAPI tới ModelField đi qua những đâu?”.

Vì sao AI agent hay “lạc” trong codebase lớn

Cách làm việc mặc định của coding agent là đọc file. Gặp câu hỏi khó, nó grep từ khóa, mở vài file, đọc thêm vài file nữa. Mỗi lần đọc là một lần tốn token, và tệ hơn là tốn “ngữ cảnh đúng”: agent càng đọc lan man, càng dễ lẫn lộn giữa code thật và code chỉ na ná nhau.

Hệ quả quen thuộc với dân làm hệ thống: agent sửa đúng hàm nhưng sai tầng, bỏ sót một nơi gọi hàm cũ, hoặc tự tin giải thích một luồng xử lý mà thực ra không tồn tại trong code. Với repo nhỏ thì không sao. Với repo vài chục nghìn dòng, nhiều module, thêm schema SQL, tài liệu vận hành và PDF đặc tả thì cách đọc file kiểu đó nhanh chóng chạm trần.

Đó chính là chỗ Graphify chen vào: thay vì đọc lại file mỗi lần, agent truy vấn một graph đã được xây sẵn, trong đó quan hệ giữa các thành phần đã được ghi rõ.

Lưu ý quan trọng: Graphify không thay thế việc đọc code khi bạn cần sửa chi tiết từng dòng. Nó thay thế bước “tìm xem cái gì liên quan tới cái gì” — bước tốn token nhất và dễ sai nhất.

Graphify là gì

Dữ kiện từ repo: Graphify là công cụ mã nguồn mở của Graphify-Labs, giấy phép Apache-2.0, biến codebase cùng tài liệu, schema SQL, cấu hình và PDF thành knowledge graph có thể truy vấn. Code được parse local bằng tree-sitter AST, xác định, không dùng LLM, không rời khỏi máy. Mỗi cạnh trong graph được gắn nhãn EXTRACTED (ghi rõ trong mã nguồn) hoặc INFERRED (do công cụ suy ra khi giải quyết quan hệ). Graphify không dùng embedding, không có vector store: đó là graph thật để duyệt, không phải chỉ mục vector.

Điểm đáng tiền nhất nằm ở nhãn EXTRACTED/INFERRED. Khi agent trả lời dựa trên graph, bạn biết được đâu là quan hệ đọc thẳng từ code, đâu là quan hệ công cụ suy luận ra. Với dân sysadmin và dev đã quen cảnh AI “bịa” rất tự tin thì đây là một cơ chế kiểm chứng thực dụng, không phải khẩu hiệu.

Một điểm cần nói rõ để khỏi nhầm: Graphify có hai lớp. Lớp mã nguồn mở chạy local là thứ bài này hướng dẫn. Graphify Cloud là lớp always-on thương mại của cùng nhóm phát triển, có dùng thử 14 ngày, giữ graph sống xuyên suốt vòng đời phát triển, hỗ trợ monorepo, cross-repo và tích hợp Sentry, Jira. Hai lớp này khác nhau, đừng đánh đồng tính năng trả phí của Cloud với bản local miễn phí.

Knowledge graph khác vector store ở điểm nào

Vector RAG trả lời bằng độ tương tự: “đoạn nào giống câu hỏi nhất”. Knowledge graph trả lời bằng quan hệ: “thứ này gọi tới thứ kia, kế thừa từ thứ nọ, thuộc cụm nào”. Câu hỏi kiểu “thay đổi hàm này ảnh hưởng tới những đâu” là câu hỏi về quan hệ, và đó đúng là thứ graph làm tốt hơn vector. Ngược lại, câu hỏi kiểu “tìm đoạn văn nói về chủ đề X trong tài liệu dài” thì vector RAG vẫn có đất diễn. Hiểu ranh giới này sẽ giúp bạn khỏi thất vọng khi dùng sai công cụ cho sai việc.

Benchmark thì đọc cho vui, đừng tin tuyệt đối

Dữ kiện từ repo: README công bố LOCOMO (n=300) recall@10 đạt 0,497, QA accuracy 45,3%; LongMemEval-S (n=50) QA accuracy 76%, ngang dense RAG; và mức tiêu thụ LLM credits bằng 0 cho bước build graph.

Đánh giá cá nhân: Đây là số liệu do chính nhóm phát triển công bố, chạy trên harness của họ, chưa phải đo độc lập. Tôi trích ra để bạn hình dung hướng đi của công cụ, không nên lấy làm cam kết hiệu năng. Cách kiểm chứng đúng vẫn là tự chạy lên repo của mình và so sánh số token agent tiêu thụ trước và sau.

Cách cài đặt Graphify

Điều kiện tiên quyết theo README: Python 3.10 trở lên, kèm uv (khuyên dùng) hoặc pipx.

uv tool install graphifyy      # cài CLI (hoặc: pipx install graphifyy)
graphify install               # phát hiện assistant của bạn và đăng ký skill

Lưu ý quan trọng: Tên package trên PyPI là graphifyy — hai chữ y. README cảnh báo rõ các package graphify* khác trên PyPI không liên quan tới dự án này. Gõ sai một chữ y là cài nhầm package lạ, đừng copy lệnh từ bài viết trôi nổi mà không đối chiếu.

Sau khi cài CLI, mở AI assistant của bạn và gõ:

/graphify .

Xong. Graphify quét thư mục hiện tại và sinh ra ba file trong graphify-out/:

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

Graphify hỗ trợ Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot và hơn 20 assistant khác, chạy trên macOS, Linux và Windows. Nếu bạn làm việc theo nhóm, graph có thể commit hoặc chia sẻ để cả team truy vấn cùng một ngữ cảnh, thay vì mỗi người tự build một bản khác nhau.

Cần thêm tính năng thì cài extra

Bản CLI cơ bản đủ cho code. Muốn mở rộng, README liệt kê các extra cài kèm, ví dụ:

uv tool install "graphifyy[mcp]"    # MCP stdio server
uv tool install "graphifyy[pdf]"    # hỗ trợ PDF
uv tool install "graphifyy[watch]"  # tự build lại khi file đổi (graphify watch)

Có cả extra cho Ollama để chạy suy luận local hoàn toàn, và extra đẩy graph lên Neo4j hoặc FalkorDB nếu bạn muốn truy vấn bằng ngôn ngữ graph chuyên dụng. Nguyên tắc của tôi: bắt đầu từ bản gọn nhất, chỉ thêm extra khi thực sự đụng tới nhu cầu đó.

Truy vấn graph thay vì đọc file

Đây là phần thay đổi thói quen làm việc. Khi graph đã có, bạn không cần bảo agent “đọc file routing.py”. Bạn hỏi trực tiếp:

graphify explain "APIRouter"
graphify path "FastAPI" "ModelField"
graphify query "luồng xử lý request đi qua những component nào?"

Ví dụ README đưa ra: graphify explain "APIRouter" trả về vị trí file, dòng code, community thuộc về và toàn bộ kết nối kèm nhãn EXTRACTED/INFERRED. Lệnh graphify path thì vẽ đường ngắn nhất giữa hai khái niệm, từng bước một. Với dân vận hành hệ thống, đây là cách lần theo bug xuyên module nhanh nhất mà tôi từng thấy ở dạng công cụ local: thay vì mở mười file để đoán luồng, bạn nhìn thấy luồng.

Ngoài CLI, file graph.html cho bạn xem graph dưới dạng sơ đồ tương tác: node là khái niệm, màu sắc là các cụm subsystem được phát hiện, bấm vào là thấy kết nối. Khi onboard người mới vào dự án cũ, mở graph.html lên và đi một vòng còn hiệu quả hơn đọc README dài mười trang mà không biết bắt đầu từ đâu.

Mẹo dùng AI: Đừng hỏi graph những câu chung chung kiểu “giải thích dự án này”. Hỏi hẹp: một khái niệm, một cặp khái niệm, một luồng cụ thể. Graph trả lời tốt nhất khi câu hỏi của bạn cũng là câu hỏi về quan hệ.

Đánh giá ưu và nhược điểm

Dữ kiện từ repo: Ưu điểm gồm parse code local bằng tree-sitter trên khoảng 40 ngôn ngữ, không tốn LLM credit cho bước build graph code, không telemetry, không theo dõi sử dụng; mọi truy vấn graphify query, path, explain và MCP query_graph được ghi log vào ~/.cache/graphify-queries.log dạng JSON Lines, có thể tắt bằng GRAPHIFY_QUERY_LOG_DISABLE=1.

Ưu điểm (đánh giá cá nhân):

• Chạy local cho phần code, không đẩy mã nguồn lên server lạ — điểm cộng lớn với repo nội bộ, code khách hàng.
• Nhãn EXTRACTED/INFERRED cho phép kiểm chứng, giảm kiểu tin mù vào câu trả lời của agent.
• Ba lệnh truy vấn đủ dùng ngay, không cần học ngôn ngữ truy vấn graph mới.
• graph.html là công cụ onboard và review kiến trúc rất trực quan.

Nhược điểm và giới hạn (đánh giá cá nhân, đối chiếu README):

• Phần docs, PDF, ảnh, video cần một bước semantic pass qua model của assistant hoặc API key đã cấu hình — tức không phải mọi thứ đều “100% local, 0 LLM” như cảm giác ban đầu. Ai làm việc với tài liệu nhạy cảm cần đọc kỹ phần privacy của README trước.
• Graph chỉ tốt bằng code bạn đưa vào: repo lộn xộn, đặt tên vô nghĩa thì graph cũng phản ánh đúng sự lộn xộn đó, chỉ là lộn xộn có tổ chức hơn.
• Tính năng always-on, cross-repo, formal verification nằm ở Graphify Cloud trả phí, không có trong bản local.
• Với repo nhỏ vài trăm dòng, build graph là thừa: đọc trực tiếp còn nhanh hơn.

So sánh: Graphify, vector RAG và XERJ

Nói gọn theo cách tôi sẽ chọn công cụ:

• Cần trả lời “cái này liên quan tới cái kia như thế nào” → Graphify.
• Cần tìm đoạn văn giống câu hỏi nhất trong núi tài liệu → vector RAG truyền thống.
• Cần một công cụ tìm kiếm local cho AI agent, index code, log, tài liệu và trả kết quả kèm trích dẫn để tiết kiệm token → XERJ, công cụ tôi đã giới thiệu trước đây trên blog này: XERJ: công cụ tìm kiếm local cho AI agent.

Graphify và XERJ không thay thế nhau mà bổ sung nhau: một bên cho bạn bản đồ quan hệ, một bên cho bạn kết quả tìm kiếm kèm trích dẫn. Nếu chỉ được chọn một cho repo code thuần túy, tôi chọn Graphify vì câu hỏi về quan hệ xuất hiện nhiều hơn trong công việc sửa code hàng ngày. Nếu tài liệu và log mới là nỗi đau chính, XERJ hợp hơn. Dùng cả hai cũng được, nhưng hãy gắn mỗi công cụ với đúng việc của nó, đừng để agent gọi cả hai cho cùng một câu hỏi rồi tự rối.

Use-case thực tế cho dev và sysadmin

• Onboard dự án lạ: build graph, mở graph.html, đọc GRAPH_REPORT.md trước khi chạm vào code. Bạn sẽ biết “god node” nào là trung tâm mà mọi thứ đều chảy qua, cụm subsystem nào tách biệt, nên tránh sửa bừa ở đâu.
• Lần theo bug xuyên module: dùng graphify path giữa điểm báo lỗi và điểm nghi ngờ, thay vì đoán mò luồng chạy.
• Review PR có rủi ro lan tỏa: trước khi approve một thay đổi ở hàm lõi, hỏi graph xem hàm đó được những đâu gọi tới. Đây là bước kiểm tra rẻ mà hiệu quả, đặc biệt với hệ thống cũ thiếu test.
• Tài liệu hóa hệ thống cũ: GRAPH_REPORT.md là bản phác thảo kiến trúc có sẵn, từ đó viết tài liệu vận hành thay vì bắt đầu từ trang trắng.
• Chuẩn bị refactor: xác định cụm nào tách biệt, cụm nào ràng buộc chằng chịt, để tách refactor thành từng bước an toàn thay vì đập đi làm lại.

Những lưu ý trước khi dùng

• Quyền riêng tư: code parse local, nhưng phần semantic pass cho docs/media có thể gọi backend nếu bạn cấu hình. Muốn local hoàn toàn thì dùng backend Ollama theo hướng dẫn của README, và kiểm tra biến môi trường trước khi chạy lên dữ liệu nhạy cảm.
• Log truy vấn: mặc định mọi truy vấn được ghi vào ~/.cache/graphify-queries.log, không lưu toàn bộ nội dung subgraph theo mặc định. Muốn tắt hẳn thì đặt GRAPHIFY_QUERY_LOG_DISABLE=1.
• Dọn dẹp: gỡ khỏi mọi nền tảng bằng graphify uninstall, thêm --purge để xóa luôn thư mục graphify-out/.
• Đừng tin benchmark mù: như đã nói, số liệu benchmark là của nhóm phát triển. Thước đo thật là token và thời gian bạn tiết kiệm được trên repo của mình sau một tuần dùng thử.

Kết luận

Graphify đáng thử nếu bạn thỏa ba điều kiện: repo đủ lớn để việc đọc file thủ công trở nên tốn kém, bạn đang dùng AI coding agent hàng ngày, và bạn cần câu trả lời có thể kiểm chứng thay vì câu trả lời nghe hay. Nó không phải phép màu, không thay thế hiểu biết về hệ thống, và không biến code rối thành code sạch. Nó chỉ làm một việc, nhưng làm tốt: cho agent — và cho chính bạn — một tấm bản đồ quan hệ của codebase.

Cài đặt mất chưa tới một phút với hai lệnh. Chạy thử lên một repo bạn đang làm việc, hỏi vài câu về quan hệ, rồi so sánh với cách làm cũ. Nếu số lần agent trả lời lạc hướng giảm đi, giữ lại. Nếu không, gỡ bằng một lệnh là xong, không có gì để tiếc.