vietnamese RAG ops — every change goes through the gate.
Nền tảng LLMOps/RAGOps full-scope cho hệ thống hỏi đáp Quy chế đào tạo + FAQ sinh viên Trường ĐH Công nghiệp TP.HCM (IUH) dựa trên Retrieval-Augmented Generation — khóa luận tốt nghiệp.
Đọc để hiểu hệ thống trong một lượt: docs/system/05_system_walkthrough.md — luồng xử lý thật, bản đồ code, quyết định thiết kế, số liệu, giới hạn, sự cố đã gặp.
Bản đồ tài liệu đầy đủ: docs/system/README.md · Bản đồ đề tài: docs/sumarize.md · Blueprint: docs/llmops_thesis_blueprint.md · Nhật ký 12 phase: docs/system/CHECKLIST_IMPLEMENTATION.md · Kết quả thực nghiệm: docs/system/experiments/ · Khảo sát gửi GVHD: docs/surveys/
| Phase | Nội dung | Trạng thái |
|---|---|---|
| 1 | Skeleton, config, healthcheck, CI | ✅ hoàn tất |
| 2 | Dữ liệu IUH + golden set 300 câu | ✅ hoàn tất |
| 3 | DataOps: chunk/embed/index (Module 1) | ✅ hoàn tất |
| 4 | Retrieval experiment (Module 2) | ✅ hoàn tất |
| 5 | RAG runtime (Module 3) | ✅ hoàn tất |
| 6 | PromptOps registry (Module 4) | ✅ hoàn tất |
| 7 | Model Gateway — LiteLLM + fallback (Module 3) | ✅ hoàn tất |
| 8 | Evaluation Engine (Module 5) | ✅ hoàn tất |
| 9 | CI/CD Quality Gate (Module 6) | ✅ hoàn tất |
| 10 | Observability — Langfuse + Prometheus/Grafana (Module 7) | ✅ hoàn tất |
| 11 | Feedback Loop + Optimization/Routing (Module 8/9) | ✅ hoàn tất |
| 12 | Thực nghiệm tổng hợp + báo cáo + demo | 🔶 đang làm (6/6 experiment report + tổng hợp + RQ1-RQ5 đã xong; còn lại: chương báo cáo khóa luận + slide bảo vệ) |
Frontend showcase (Next.js) được xây sớm hơn kế hoạch, bắt đầu giữa Phase 8 — xem frontend/README.md. Trang /dashboard hiển thị số liệu thật của cả 6 tầng Phase 4-12 (retrieval, promptops, evaluation, quality gate, model & observability, feedback & tối ưu).
# 1. Cấu hình
copy .env.example .env
# điền: POSTGRES_PASSWORD, GEMINI_API_KEY (bắt buộc để trả lời thật),
# LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY (tuỳ chọn, xem Phase 10)
# 2. Hạ tầng lõi + backend
docker compose up -d qdrant postgres valkey litellm prometheus grafana
python scripts/init_postgres_schema.py
python scripts/seed_prompts.py
uvicorn src.api.main:app --port 8000
# (nếu chưa ingest dữ liệu lần nào: python scripts/ingest_data.py --recreate-collection)
# 3. Frontend (terminal khác)
cd frontend
npm install
npm run devMở http://localhost:3000 (showcase + /demo hỏi-đáp thật + /dashboard số liệu thực nghiệm), API tại http://localhost:8000/docs, Grafana tại http://localhost:3001. Chi tiết frontend: frontend/README.md. Chi tiết deploy đầy đủ (thứ tự service, biến môi trường, healthcheck): docs/system/operations/deployment_docker_compose.md.
# 1. Tạo môi trường (Python 3.11+)
python -m venv .venv
.venv\Scripts\activate # Windows
pip install -e ".[dev,dataops,ragops,observability,reporting]"
# 2. Cấu hình
copy .env.example .env
# 3. Hạ tầng (Qdrant/Postgres/Valkey/LiteLLM) qua Docker, API chạy local
docker compose up -d qdrant postgres valkey litellm
uvicorn src.api.main:app --reload --port 8000Kiểm tra:
curl http://localhost:8000/health
curl http://localhost:8000/health/dependencies
# Swagger UI: http://localhost:8000/docspytest -q # unit + integration (tự skip phần cần Postgres/Qdrant nếu service tắt)
ruff check .config/ # Config có version: retrieval, prompts, model_gateway, quality_gate, optimization
data/ # raw / processed / chunks / test_sets / eval / traces
frontend/ # Next.js showcase + demo + dashboard (npm install && npm run dev)
src/
├── api/ # FastAPI runtime — qa, feedback, prompts, metrics, health
├── common/ # settings, config_loader
├── dataops/ # Module 1 — ingest/clean/chunk/embed/index (Phase 3)
├── retrieval/ # Module 2 — retrieval experiments (Phase 4)
├── rag/ # Module 3 — RAG orchestrator + Model Gateway client (Phase 5/7)
├── promptops/ # Module 4 — prompt registry (Phase 6)
├── evaluation/ # Module 5 — eval 4 tầng (Phase 8)
├── qualitygate/ # Module 6 — PASS/WARN/BLOCK (Phase 9)
├── observability/ # Module 7 — Langfuse tracing + Prometheus metrics (Phase 10)
├── feedback/ # Module 9 — feedback API + error classifier + clustering (Phase 11)
└── optimization/ # Module 8 — semantic cache/compression/routing (Phase 11)
scripts/ # CLI: ingest, run_evaluation, check_gate, run_experiment*, seed_*
tests/ # unit / integration
docs/
├── system/ # bộ tài liệu hệ thống — bắt đầu từ system/README.md
│ ├── 05_system_walkthrough.md # ⭐ hiểu hệ thống thật trong 1 lượt đọc
│ ├── CHECKLIST_IMPLEMENTATION.md # nhật ký 12 phase + nợ kỹ thuật
│ ├── modules/ # 10 module doc
│ ├── contracts/ # API/data/config schema + định nghĩa metric
│ ├── experiments/# kế hoạch + toàn bộ report kết quả thật
│ └── operations/ # deploy, bảo mật, test, runbook sự cố
├── surveys/ # bản khảo sát hiện trạng gửi GVHD (.md + .docx)
├── figures/ # hình minh hoạ báo cáo
├── sumarize.md # bản đồ tổng thể đề tài
└── llmops_thesis_blueprint.md # dàn ý + kế hoạch khóa luận đầy đủ
- Mọi artifact quan trọng có version (
config/README.md). - Không hard-code provider/model — mọi model call đi qua gateway config.
- Mọi thay đổi rủi ro phải qua evaluation + quality gate trước khi active.
- Không trả lời khi thiếu căn cứ trong tài liệu (refusal + citation bắt buộc).
- Mọi số liệu thực nghiệm là số liệu thật, đo qua stack thật (Qdrant/Postgres/LiteLLM/Gemini) — không bịa; kết quả tiêu cực được ghi lại trung thực, không giấu (xem
docs/system/experiments/). - Không commit secret;
.envnằm ngoài git.