Add read-only production runtime audit

2026-08-17 11:17:40 +07:00
parent 057d4ed9dc
commit a1de4715a4
106 changed files with 6869 additions and 1782 deletions
@@ -0,0 +1,104 @@
+# Phát triển và chạy local
+
+> Loại chính: Tutorial/How-to  
+> Kết quả: chạy được backend, web và test offline mà không gọi cloud
+
+## Điều kiện
+
+- Python 3.11+
+- Node.js và pnpm tương thích lockfile
+- Docker Desktop/Engine
+
+## Thiết lập backend và datastore
+
+```powershell
+docker compose -f infra/docker/docker-compose.yml up -d postgres qdrant
+Set-Location apps/ai-service
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -e ".[test,metrics,observability]"
+$env:EMBEDDING_PROVIDER = "disabled"
+$env:ANSWER_PROVIDER = "disabled"
+python -m uvicorn main:app --port 8079
+```
+
+Kiểm tra ở terminal khác:
+
+```powershell
+Invoke-RestMethod http://localhost:8079/health
+Invoke-RestMethod http://localhost:8079/ready
+```
+
+Mode disabled là smoke test không cần AWS/corpus; nó không có năng lực RAG production.
+Trên Windows nên restart uvicorn trực tiếp thay vì phụ thuộc `--reload` khi debug
+startup/provider state.
+
+## Chạy web
+
+```powershell
+Set-Location D:\VSF-DUOCTHU
+pnpm install --frozen-lockfile
+$env:AI_SERVICE_URL = "http://localhost:8079"
+pnpm --filter web dev
+```
+
+Mở `http://localhost:3000`. Trong mode disabled, gửi câu hỏi phải tạo refusal có
+kiểm soát thay vì crash.
+
+## Chạy RAG thật
+
+Chỉ thực hiện khi Qdrant có collection + manifest đúng và môi trường có quyền AWS:
+
+```powershell
+$env:QDRANT_URL = "http://localhost:6333"
+$env:QDRANT_COLLECTION = "duocthu_v1"
+$env:EMBEDDING_PROVIDER = "cohere-v4"
+$env:EMBEDDING_DIMENSIONS = "1024"
+$env:AWS_REGION = "us-east-1"
+$env:ANSWER_PROVIDER = "bedrock-converse"
+python -m uvicorn main:app --port 8079
+```
+
+Startup phải fail nếu manifest không khớp. Gửi request thử:
+
+```powershell
+$body = @{
+  query = "Chống chỉ định của paracetamol là gì?"
+  subject_scope = "human"
+  intent = "fact_lookup"
+  conversation_id = "local-001"
+} | ConvertTo-Json
+
+Invoke-RestMethod -Method Post `
+  -Uri http://localhost:8079/v1/rag/query `
+  -ContentType "application/json" -Body $body
+```
+
+## Chạy test
+
+```powershell
+Set-Location apps/ai-service
+$env:EMBEDDING_PROVIDER = "disabled"
+python -m pytest -q
+python -m ruff check .
+
+Set-Location ../../ingestion
+python -m pip install -e ".[dev]"
+python -m pytest -q
+
+Set-Location ..
+pnpm --filter web lint
+pnpm --filter web build
+```
+
+Một số test live datastore sẽ skip nếu hạ tầng không có. Web chưa có test runner;
+thay đổi UI/BFF cần browser smoke test cho answerable, clarify, verify_pdf và abstain.
+
+## Dừng local infra
+
+```powershell
+docker compose -f infra/docker/docker-compose.yml down
+```
+
+Không thêm tùy chọn xoá volume nếu chưa chủ động muốn xoá dữ liệu local.
+