| name | NL2SQL Core Engine — 6 Pillars |
| description | Skill hướng dẫn triển khai và vận hành 6 trụ cột cốt lõi của pipeline NL2SQL:
Schema Linking, Value Profiling, Ambiguity Detection, Generation Trace, Retry & Repair, Evaluation Suite.
Triggers: Khi sửa schema, thêm bảng mới, nâng cấp prompt, thay LLM, debug SQL sai.
|
NL2SQL Core Engine — 6 Pillars Skill
🎯 Khi nào dùng Skill này?
- Sửa đổi schema hoặc thêm bảng/cột mới vào database
- Nâng cấp prompt của bất kỳ agent nào trong pipeline
- Debug tại sao AI sinh ra SQL sai
- Thay đổi hoặc nâng cấp LLM model
- Thêm Value Profiles cho bảng mới
- Mở rộng SYNONYMS để hỗ trợ thêm tiếng Việt
📁 File Map — 6 Pillars
services/nl2sql-service/
├── core/
│ ├── schema_retriever.py ← Pillar 1 (Schema Linking) + Pillar 2 (Value Profiling)
│ ├── prompts.py ← Pillar 3 (Gatekeeper prompt) + Pillar 4 (Generation Trace prompts)
│ ├── llm_client.py ← LLM abstraction layer
│ ├── schema_cache.py ← Cache schema từ Supabase
│ └── kafka_worker.py ← Pillar 5 (nhận repair requests)
│
├── services/
│ ├── nl2sql_service.py ← Orchestrator: gọi 4 agents theo thứ tự
│ └── agents/
│ ├── gatekeeper_agent.py ← Pillar 3: Ambiguity Detection
│ ├── architect_agent.py ← Pillar 4: Query Planning
│ ├── sql_generator_agent.py ← Pillar 4: SQL Generation
│ ├── validator_agent.py ← Pillar 4: Validation
│ └── sql_repair_agent.py ← Pillar 5: Self-Repair
│
└── domain/
└── models.py ← GatekeeperOutput, GeneratorOutput, etc.
services/query-service/
└── services/query_service.py ← Pillar 5: Dialect Regex Patches
test_pipeline.py ← Pillar 6: 23-case Evaluation Suite
🔧 Hướng dẫn từng Pillar
Pillar 1 — Schema Linking
Khi thêm bảng mới vào DB:
- Mở
core/schema_retriever.py
- Thêm ánh xạ tiếng Việt vào
SYNONYMS:
SYNONYMS = {
...
"từ khóa mới": ["tên_bảng_mới"],
"keyword mới": ["tên_bảng_mới"],
}
- Update
core/prompts.py → thêm ### Table: tên_bảng_mới vào schema text
Pillar 2 — Value Profiling
Khi thêm cột có giá trị enum (status, category, type...):
- Mở
core/prompts.py
- Thêm block sau bảng liên quan:
### Status Values for ten_bang.ten_cot
- Valid values: 'value1', 'value2', 'value3'
- Use EXACTLY these values in WHERE clauses.
Pillar 3 — Ambiguity Detection
Khi cần điều chỉnh độ nhạy của Gatekeeper:
- Mở
core/prompts.py → GATEKEEPER_AGENT_PROMPT
- Điều chỉnh rule phân loại VALID/INVALID
- Test với:
"Cho tôi xem dữ liệu" (phải là INVALID) và "Tổng đơn hàng tháng này" (phải là VALID)
Pillar 4 — Generation Trace
Khi cần thêm thông tin vào intermediate_steps:
- Mở
services/nl2sql_service.py
- Tìm chỗ collect
intermediate_steps
- Thêm field mới vào dict của từng agent
Pillar 5 — Retry & Repair
Khi phát hiện lỗi dialect mới từ wren_core:
- Mở
services/query-service/services/query_service.py
- Thêm regex pattern mới vào
fix_sql_dialect():
sql = re.sub(r'pattern_lỗi', 'pattern_đúng', sql, flags=re.IGNORECASE)
Pillar 6 — Evaluation Suite
Khi thêm tính năng mới:
- Mở
test_pipeline.py
- Thêm test case mới vào
TEST_CASES list
- Chạy:
python test_pipeline.py
- Kết quả lưu tại
test_report.json
⚠️ Quy tắc bắt buộc
- Sau mỗi lần sửa prompt: Chạy lại
python test_pipeline.py để đảm bảo không regression
- Sau mỗi lần thêm bảng: Cập nhật cả
SYNONYMS lẫn schema text trong prompts.py
- KHÔNG hardcode giá trị enum trong code — luôn đặt trong Value Profile của schema
- Test Pillar 3 với câu tấn công:
"DROP TABLE" phải bị chặn 100%
- Test Pillar 5 với câu ngày tháng:
"tuần này", "tháng trước" phải chạy đúng
📊 Checklist trước khi báo xong
