HỆ THỐNG PHÂN TÍCH DỮ LIỆU BẰNG NGÔN NGỮ TỰ NHIÊN
P-154
AI Text-to-SQL Self-Service Analytics
Tổng quan hệ thống — Admin Portal & kiến trúc (nhánh UI-Admin)
React 19 + Vite
FastAPI
LangGraph Agent
PostgreSQL/Supabase
AI20K Build Phase — Cohort 3
BỐI CẢNH
Vấn đề: khoảng cách giữa dữ liệu và người ra quyết định
● Phụ thuộc đội kỹ thuật. Người dùng nghiệp vụ (sales, quản lý) không biết viết SQL, phải chờ đội kỹ thuật cho từng câu hỏi số liệu.
● Chatbot gắn thẳng LLM vào DB rất rủi ro. Model có thể tự suy diễn chỉ số, chọn sai bảng, hoặc chạy SQL không an toàn nếu không kiểm soát.
● Thiếu governance quyền dữ liệu. Không có cơ chế rõ ràng để cấp/duyệt quyền truy cập dữ liệu theo từng dataset, từng user.
● Thiếu minh bạch & audit. Không có lịch sử truy vấn, không rõ ai đã hỏi gì, dùng dataset nào, kết quả ra sao.
Rủi ro nếu làm sai
• Model tự bịa số liệu (hallucination)
• Truy vấn ghi/xoá ngoài ý muốn
• Lộ dữ liệu nhạy cảm cho sai người
• Không có dấu vết để kiểm toán
→ Cần một lớp kiểm soát giữa LLM và cơ sở dữ liệu thật.
P-154 · AI Text-to-SQL Self-Service Analytics
02 / 13
GIẢI PHÁP
P-154: LLM chỉ diễn giải ý định — backend giữ toàn quyền kiểm soát
Người dùng đăng nhập bằng Supabase, đặt câu hỏi tiếng Việt, chọn dataset phù hợp và xem trước SQL. Hệ thống chỉ thực thi sau khi người dùng xác nhận.
Xác thực & phân quyền
Đăng nhập qua Supabase JWT; backend kiểm tra ownership, role và data entitlement theo từng dataset.
Sinh & kiểm tra SQL
LangGraph điều phối: hiểu ý định → chọn dataset → sinh SQL → validate bằng SQLGlot trước khi cho xem.
Human-in-the-loop
Người dùng luôn xem bản tóm tắt + SQL và phải xác nhận (hash) trước khi hệ thống thực thi.
Thực thi an toàn
Query chỉ chạy trên view `analytics_safe`, bằng role PostgreSQL chỉ đọc (read-only).
P-154 · AI Text-to-SQL Self-Service Analytics
03 / 13
KIẾN TRÚC
Kiến trúc tổng quan — Modular Monolith
Browser
React 19 + Vite UI
User: chat, SQL preview, kết quả
Admin: duyệt quyền, quản trị hệ thống
FastAPI Backend
REST API (/api/v1)
Conversation & LangGraph Agent
SQL Guardrails · Access Service
Read-only Query Executor
Supabase
Auth: JWT & JWKS
PostgreSQL
app: users, conversations, query runs, access requests
semantic: catalog & governed metrics
analytics_safe: view chỉ đọc đã duyệt
Agent chỉ được chọn trong catalog dataset/table do backend cấp phép — không tự tạo schema hay bảng mới.
P-154 · AI Text-to-SQL Self-Service Analytics
04 / 13
LUỒNG NGHIỆP VỤ
Luồng Text-to-SQL với Human-in-the-Loop (HITL)
1
Đặt câu hỏi
Người dùng nhập câu hỏi tiếng Việt trong hội thoại.
2
Làm rõ & chọn dataset
Agent hỏi lại nếu thiếu thông tin; tìm dataset phù hợp trong catalog.
3
Kiểm tra quyền
Nếu chưa có quyền → gửi yêu cầu cấp quyền, chờ Admin duyệt.
4
Sinh & kiểm tra SQL
LLM sinh SQL trên metadata được phép; SQLGlot validate cú pháp & phạm vi.
5
Xác nhận (HITL)
Người dùng xem tóm tắt + SQL, xác nhận bằng hash trước khi chạy.
6
Thực thi & kết quả
Kiểm tra lại quyền, chạy read-only trên analytics_safe, trả bảng/biểu đồ/giải thích.
P-154 · AI Text-to-SQL Self-Service Analytics
05 / 13
BẢO MẬT & GUARDRAILS
Nhiều lớp kiểm soát giữa LLM và dữ liệu thật
Read-only theo thiết kế
Mọi truy vấn chỉ chạy SELECT trên view analytics_safe, bằng role PostgreSQL chỉ đọc riêng.
Kiểm tra quyền hai lần
Kiểm tra entitlement trước khi sinh SQL, và kiểm tra lại ngay trước khi thực thi.
SQL validation
SQLGlot kiểm tra cú pháp, phạm vi bảng/cột trước khi hiển thị cho người dùng.
Xác nhận bắt buộc (HITL)
SQL không tự chạy — người dùng phải xác nhận bằng hash trước khi hệ thống thực thi.
Phạm vi metadata hẹp
Agent chỉ thấy metadata chi tiết của dataset đã được cấp quyền, không thấy toàn schema.
Audit đầy đủ
Mọi quyết định Admin và lịch sử truy vấn được ghi lại trong PostgreSQL để truy vết.
P-154 · AI Text-to-SQL Self-Service Analytics
06 / 13
ADMIN PORTAL
Quản trị hệ thống — 4 khu vực chính
frontend/src/pages/AdminPortalPage.tsx
Tổng quan
Số liệu nhanh: số database an toàn, dataset chờ duyệt, user đang hoạt động, yêu cầu cấp quyền.
Quản lý dữ liệu
Duyệt / từ chối / lưu trữ dataset; chỉ dataset APPROVED mới xuất hiện trong catalog runtime.
Quản lý người dùng
Tạo user (theo UUID Supabase đã mời), đổi role USER/ADMIN, khoá/mở khoá, gán quyền dataset.
Logging
Theo dõi lịch sử câu hỏi, dataset sử dụng và trạng thái thực thi của toàn hệ thống.
Admin chỉ xét duyệt quyền/dataset — không tự động được cấp quyền đọc toàn bộ dữ liệu nghiệp vụ.
P-154 · AI Text-to-SQL Self-Service Analytics
07 / 13
ADMIN PORTAL · QUẢN LÝ DỮ LIỆU
Vòng đời duyệt Dataset
PENDING_REVIEW
Dataset mới đăng ký, chờ Admin xem mô tả nghiệp vụ, owner, sensitivity level.
APPROVED
Được duyệt → xuất hiện trong catalog runtime, Agent có thể chọn khi user có entitlement.
REJECTED
Từ chối kèm ghi chú lý do, không xuất hiện trong catalog.
ARCHIVED
Ngừng sử dụng nhưng vẫn giữ lịch sử để tra cứu/audit.
Ghi chú xét duyệt & ownership
Mỗi dataset có owner và ghi chú duyệt (review comment) đi kèm quyết định. Admin có thể chuyển trạng thái qua lại (ví dụ đưa về PENDING_REVIEW để yêu cầu bổ sung thông tin) trước khi APPROVE hoặc REJECT hẳn. API: GET/POST /admin/datasets (admin_catalog.py).
P-154 · AI Text-to-SQL Self-Service Analytics
08 / 13
ADMIN PORTAL · QUẢN LÝ NGƯỜI DÙNG
Tạo user, phân role và cấp quyền dataset
● Tạo user theo UUID Supabase. Admin nhập Auth user UUID sau khi mời qua Supabase — service role không lộ trong ứng dụng.
● Phân role hệ thống. Mỗi user có role USER hoặc ADMIN; role không tự cấp quyền đọc dữ liệu nghiệp vụ.
● Khoá / mở khoá tài khoản. Đổi trạng thái ACTIVE ↔ INACTIVE ngay trong bảng quản lý.
● Gán quyền dataset (entitlement). Chọn user → tick các dataset đã APPROVED → lưu quyền cho riêng user đó.
Nguyên tắc phân quyền
• Role (USER/ADMIN) quyết định quyền thao tác trong ứng dụng (ví dụ: xét duyệt).
• Entitlement theo dataset quyết định user được hỏi dữ liệu nào — quản lý độc lập với role.
• Một ADMIN vẫn cần entitlement riêng nếu muốn tự đặt câu hỏi trên một dataset cụ thể.
API liên quan: admin_users.py, admin_catalog.py (entitlements).
P-154 · AI Text-to-SQL Self-Service Analytics
09 / 13
ADMIN PORTAL · LOGGING
Audit toàn hệ thống — minh bạch & truy vết
● Lịch sử câu hỏi. Ghi lại thời gian, câu hỏi gốc, dataset sử dụng và trạng thái thực thi/duyệt của từng lượt hỏi.
● Audit sự kiện Admin. Mọi quyết định duyệt dataset, cấp quyền, tạo/sửa user đều được ghi nhận (admin-audit).
● Yêu cầu cấp quyền. Theo dõi vòng đời access request: gửi → yêu cầu bổ sung → duyệt/từ chối.
Vì sao quan trọng
Không có audit, tổ chức không thể trả lời: ai đã hỏi gì, dữ liệu nào bị truy cập, ai đã cấp quyền và khi nào.
Log này là cơ sở cho compliance nội bộ và điều tra sự cố nếu có truy vấn bất thường.
P-154 · AI Text-to-SQL Self-Service Analytics
10 / 13
CÔNG NGHỆ
Tech Stack
Frontend
React 19 · Vite · TypeScript · TanStack Query
Backend
FastAPI · Python · REST /api/v1 · OpenAPI
AI Agent
LangGraph state machine · HITL checkpoint
LLM
OpenAI (gpt-4o) hoặc provider demo deterministic
Database
PostgreSQL 16 · schema app/semantic/analytics_safe
Migration
Alembic
Auth
Supabase Auth · JWT/JWKS
Observability
Langfuse (tùy chọn, fail-open)
P-154 · AI Text-to-SQL Self-Service Analytics
11 / 13
DEMO
Luồng demo gợi ý
● Doanh thu năm 2025 là bao nhiêu?
● Doanh thu tháng 1 năm 2026 là bao nhiêu?
● Doanh thu căn hộ tại Hà Nội trong năm 2025 là bao nhiêu?
● Doanh thu tại Quận 1 trong quý 2 năm 2025 là bao nhiêu?
● Doanh thu là bao nhiêu? → hệ thống cần hỏi lại thời gian/phạm vi thay vì tự chạy truy vấn.
Cách trình bày
1. Nhập câu hỏi
2. Xem AI hiểu yêu cầu + SQL sinh ra
3. Nhấn Xác nhận và chạy
4. Xem bảng / biểu đồ / giải thích
Với câu hỏi thiếu phạm vi thời gian: cho thấy hệ thống hỏi lại thay vì đoán.
P-154 · AI Text-to-SQL Self-Service Analytics
12 / 13
Cảm ơn.
P-154 — AI Text-to-SQL Self-Service Analytics
Repo: AI20K-Build-Phase-Cohort-3/P-154 · Nhánh UI-Admin
P-154
13 / 13