Graphify: lập bản đồ code, SQL schema và tài liệu để truy vết ngữ cảnh

Graphify tạo knowledge graph từ code, tài liệu, SQL schema và cấu hình để truy vết quan hệ thay vì chỉ tìm chuỗi trong tệp. Với đội BI, đây là công cụ đáng thử để gom ngữ cảnh trước khi nhờ AI giải thích lineage hoặc viết SQL.

Một dashboard doanh thu lệch số. Người làm trước đã rời nhóm; còn lại là SQL, tài liệu định nghĩa KPI, cấu hình dashboard và ghi chú rải rác.

Bạn hỏi AI: “Revenue lấy từ bảng nào?” Nếu thiếu một đoạn JOIN, một bộ lọc ngày hoặc ghi chú về hoàn tiền, AI vẫn có thể trả lời rất tự tin — nhưng sai ngữ cảnh.

Graphify là một công cụ nhằm giải bài toán gom ngữ cảnh này. Theo README, nó biến codebase, tài liệu, SQL schema, cấu hình và một số loại tệp khác thành knowledge graph: đồ thị gồm các thực thể và quan hệ giữa chúng.

Với data analyst và BI developer, giá trị không nằm ở việc có thêm một biểu đồ đẹp. Điểm đáng thử là khả năng lần theo đường liên kết giữa code, schema và tài liệu trước khi yêu cầu AI giải thích một KPI hay đề xuất SQL.

Graphify công bố những gì?

Theo README, bạn có thể gọi /graphify trong AI coding assistant để lập bản đồ dự án. Phần code được phân tích cục bộ bằng tree-sitter AST: có tính xác định, không dùng LLM và không đưa code ra khỏi máy theo mô tả của dự án.

Graphify nhấn mạnh rằng đây không phải vector index: không dùng embeddings hay vector store, mà lưu các thực thể và quan hệ dưới dạng đồ thị. Người dùng có thể truy vấn graph, xem giải thích về một nút hoặc lần đường đi giữa hai nút.

Các cạnh trong graph được gắn nhãn:

EXTRACTED: quan hệ xuất hiện trực tiếp trong nguồn. INFERRED: quan hệ được Graphify suy ra trong quá trình phân giải.

Đây là một phân biệt hữu ích, nhưng cần hiểu đúng: EXTRACTED chỉ cho biết quan hệ được ghi nhận từ nguồn. Nó không tự chứng minh công thức KPI đúng, JOIN không nhân bản dòng hay số liệu đã khớp với báo cáo nghiệp vụ.

README cũng cho biết các ghi chú như # NOTE: và # WHY:, cùng tham chiếu ADR/RFC, có thể trở thành nút và được liên kết với code.

Dùng cho BI: công cụ làm được gì, người phân tích vẫn phải làm gì?

Graphify mô tả khả năng lập graph từ code, tài liệu, PDF, ảnh, video, SQL schema và cấu hình. Còn các bước như xác nhận lineage KPI, kiểm tra số tổng hay đánh giá điều kiện JOIN là quy trình kiểm tra do đội dữ liệu thực hiện, không phải kết luận tự động mà README cam kết.

Ví dụ, với một dự án báo cáo có các bảng:

| Bảng | Cột đáng chú ý | Điều cần xác minh | |---|---|---| | orders | orderid, customerid, orderdate, amount | Giao dịch gốc | | customers | customerid, segment | Thuộc tính khách hàng | | refunds | orderid, refundamount | Khoản hoàn tiền |

Nếu KPI là “Net Revenue”, việc graph thể hiện cả ba bảng mới chỉ là điểm bắt đầu. Người phân tích vẫn cần xác nhận:

KPI có thực sự trừ refundamount hay không? Khóa nối có phải orderid không? Bộ lọc dùng ngày giao dịch, ngày cập nhật hay ngày hoàn tiền? Công thức nghiệp vụ nằm trong SQL, semantic layer hay tài liệu định nghĩa KPI?

Cài đặt và tạo graph đầu tiên

README nêu yêu cầu Python 3.10 trở lên, cùng uv hoặc pipx.

bash uv tool install graphifyy # hoặc: pipx install graphifyy graphify install # phát hiện assistant và đăng ký skill

Sau đó, trong AI coding assistant:

text /graphify .

README liệt kê Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot và hơn 20 assistant khác; đồng thời nêu hỗ trợ macOS, Linux và Windows. Dù vậy, hãy kiểm tra trực tiếp khả năng tích hợp trong môi trường đang dùng.

Sau khi chạy, Graphify tạo ba tệp đầu ra:

text graphify-out/ ├── graph.html ├── GRAPHREPORT.md └── graph.json

graph.html: mở bằng trình duyệt để click nút, lọc và tìm kiếm trong graph. GRAPHREPORT.md: tóm tắt các khái niệm đáng chú ý, kết nối nổi bật và câu hỏi gợi ý. graph.json: graph đầy đủ để truy vấn lại mà không cần đọc lại toàn bộ tệp nguồn.

Graph còn lưu graph.schemaversion và graph.graphifyversion. Đây là hai trường đáng lưu ý nếu đội muốn dùng graph.json trong một quy trình nội bộ và cần nhận biết thay đổi định dạng hoặc phiên bản tạo graph.

Thử trên một repo analytics nhỏ trước

Đừng đưa ngay toàn bộ kho BI lớn vào quy trình. Một bài thử nhỏ sẽ cho biết Graphify nhìn thấy được bao nhiêu quan hệ hữu ích trong cấu trúc dự án thực tế của đội.

Có thể tạo hoặc chọn một repo thử nghiệm không chứa dữ liệu nhạy cảm:

text analytics-demo/ ├── models/ │ └── fctnetrevenue.sql ├── schemas/ │ └── warehouseschema.sql ├── docs/ │ └── kpinetrevenue.md └── dashboard/ └── revenueconfig.yml

Trong đó:

fctnetrevenue.sql chứa logic tổng hợp doanh thu và hoàn tiền. warehouseschema.sql chứa định nghĩa bảng, cột và khóa. kpinetrevenue.md mô tả công thức KPI cùng quy ước ngày. revenueconfig.yml là cấu hình tham chiếu tới model hoặc chỉ số, nếu hệ thống của bạn có dạng tệp này.

Sau khi chạy /graphify ., hãy mở graph.html và GRAPHREPORT.md, rồi đánh giá bằng các câu hỏi cụ thể:

Graph có hiện các bảng, cột hoặc thực thể SQL mà đội cần kiểm tra không? Có thể lần từ model SQL đến các đối tượng được tham chiếu trong schema hay tài liệu không? Những liên kết nào là EXTRACTED, và những liên kết nào là INFERRED? Có thể quay lại đúng tệp nguồn để kiểm tra mỗi kết luận quan trọng không? Các quan hệ bị thiếu hoặc hiểu sai tập trung ở loại tệp nào?

Đây không phải một benchmark về độ chính xác. Mục tiêu là xác định Graphify có tạo ra đủ ngữ cảnh và đường dẫn có thể kiểm chứng cho repo của bạn hay không.

Hỏi theo đường dẫn, không hỏi bằng trí nhớ

README minh họa các lệnh để giải thích một nút và tìm đường đi ngắn nhất giữa hai nút:

text graphify explain "APIRouter"

text graphify path "FastAPI" "ModelField"

README cũng mô tả graphify query "<question>" trả về một subgraph theo phạm vi của câu hỏi bằng ngôn ngữ tự nhiên.

Khi áp dụng vào analytics, đội có thể dùng graph như một lớp dẫn chứng trước khi yêu cầu assistant tổng hợp. Ví dụ, một yêu cầu kiểm tra do người dùng đặt ra có thể là:

text Dựa trên graph hiện có, hãy truy vết KPI <tên KPI> về các bảng, cột và tài liệu liên quan.

Yêu cầu: Liệt kê quan hệ theo từng bước. Phân biệt cạnh EXTRACTED và INFERRED. Nêu tệp hoặc vị trí nguồn cho từng kết luận quan trọng. Chỉ ra điểm chưa đủ bằng chứng, đặc biệt là JOIN, NULL và bộ lọc ngày. Không tự tạo tên bảng hoặc cột không có trong graph.

Đây là cách dùng được đề xuất để giảm suy đoán, không phải tính năng xác thực nghiệp vụ mà Graphify công bố.

EXTRACTED không đồng nghĩa với “đã đúng”

Một cạnh EXTRACTED có thể cho thấy một tệp SQL tham chiếu đến bảng, một file import module khác, hoặc tài liệu nhắc tới một khái niệm. Nhưng nó không trả lời các câu hỏi nghiệp vụ quan trọng như:

LEFT JOIN có tạo ra nhiều dòng trên mỗi đơn hàng không? NULL được xử lý như doanh thu bằng 0, thiếu dữ liệu hay bị loại? KPI có loại đơn bị hủy, test order hoặc hoàn tiền trễ không? Dashboard đang dùng đúng model và đúng phiên bản định nghĩa hay không?

Vì vậy, với SQL hoặc DAX do AI đề xuất, quy trình review vẫn nên gồm:

Đối chiếu bảng fact, dimension và khóa nối với tệp nguồn. Kiểm tra công thức KPI trong tài liệu liên quan. Rà soát rủi ro nhân bản dòng do JOIN. Kiểm tra cách xử lý NULL và bộ lọc thời gian. Chạy truy vấn trong môi trường phù hợp. Đối chiếu số tổng với báo cáo hoặc tập dữ liệu đã được xác nhận.

Graph giúp truy vết căn cứ nhanh hơn; nó không thay thế kiểm thử logic và kết quả tính toán.

Cần thử SQL dialect và DAX riêng

README được cung cấp không nêu chi tiết về mức hỗ trợ cho từng SQL dialect, cách diễn giải DAX, hay độ chính xác với mô hình BI phức tạp.

Trước khi áp dụng cho một kho lớn, nên kiểm tra trên các mẫu đại diện cho hệ thống của bạn:

SQL dialect đang dùng, chẳng hạn cú pháp hàm ngày, CTE, MERGE, QUALIFY hoặc cú pháp riêng của warehouse. JOIN nhiều tầng, CTE lồng nhau, view và model được gọi chéo. Tên bảng có schema hoặc database prefix. DAX có measure tham chiếu measure khác, filter context và quan hệ giữa bảng. Cấu hình dashboard hoặc semantic layer mà đội đang lưu trong repository.

Tiêu chí không phải là graph phải thay người dùng hiểu toàn bộ mô hình. Tiêu chí thực tế hơn là: nó có chỉ đúng tệp, đúng đối tượng và đủ đường dẫn để người review kiểm tra nhanh hơn không?

Lưu ý về dữ liệu và cách triển khai

README nói code map miễn phí và chạy hoàn toàn cục bộ. Với docs, PDF, ảnh và video, README nêu rằng công cụ dùng model của assistant hoặc API key đã cấu hình cho bước phân tích ngữ nghĩa.

Vì vậy, không nên mặc định mọi loại nội dung đều chỉ được xử lý cục bộ. Trước khi chạy trên dự án thật, hãy kiểm tra cấu hình assistant và API đang dùng; ưu tiên schema, mô tả cột và dữ liệu mẫu đã ẩn danh thay vì dữ liệu khách hàng hoặc giao dịch nhạy cảm.

Repository hiển thị giấy phép Apache 2.0. Đây là bản công cụ cài và chạy cục bộ được README hướng dẫn.

README cũng giới thiệu Graphify Cloud là sản phẩm riêng, với graph luôn được cập nhật xuyên suốt SDLC, hỗ trợ monorepo/cross-repo và các connector như Sentry, Jira. Cloud được quảng bá có dùng thử miễn phí 14 ngày. Cần tách bạch lựa chọn Cloud này với trải nghiệm CLI cục bộ khi đánh giá yêu cầu dữ liệu, vận hành và chi phí.

Checklist trước khi dùng cho dashboard thật

[ ] Chỉ thử trên thư mục đã loại dữ liệu nhạy cảm. [ ] Xác minh SQL dialect và DAX của đội bằng repo mẫu. [ ] Đọc GRAPHREPORT.md và kiểm tra trực tiếp graph.html. [ ] Dùng graphify explain với các khái niệm quan trọng. [ ] Ưu tiên các kết luận có thể quay lại tệp nguồn để xác minh. [ ] Xem cạnh INFERRED là manh mối cần kiểm chứng. [ ] Không coi cạnh EXTRACTED là bằng chứng KPI hoặc số liệu đã đúng. [ ] Chạy lại SQL hoặc DAX, rồi đối chiếu số tổng trước khi gửi kết quả cho business.

Nếu thường xuyên phải lần xem dashboard lấy số từ đâu, Graphify là một công cụ đáng thử để tạo lớp ngữ cảnh giữa kho tệp rời rạc và AI assistant. Hãy để AI đi theo bản đồ; phần xác nhận logic và con số vẫn thuộc về người phân tích.