690419:1310 feat: update CI/CD to use SSH key authentication #03

2026-04-19 13:10:01 +07:00
parent 844caf477d
commit 657698558b
12 changed files with 1952 additions and 3 deletions
@@ -0,0 +1,159 @@
+# Quickstart: ADR-022 RAG — Local Development Setup
+
+**Date**: 2026-04-19 | **สำหรับ**: Developer ที่ต้องการรัน RAG pipeline บน local machine
+
+---
+
+## Prerequisites
+
+| Dependency | Version | หมายเหตุ |
+|------------|---------|----------|
+| Docker Desktop | 4.x+ | สำหรับ Qdrant + Redis |
+| Node.js | 20.x | NestJS backend |
+| pnpm | 9.x | Package manager |
+| Python | 3.11 | PyThaiNLP microservice |
+| Ollama | latest | ต้องติดตั้งบน Admin Desktop หรือ local |
+
+---
+
+## Step 1: Start Infrastructure
+
+```bash
+# เพิ่ม Qdrant + Redis ใน docker-compose.override.yml (local dev)
+docker compose -f docker-compose.yml -f docker-compose.override.yml up qdrant redis -d
+
+# ตรวจสอบ Qdrant
+curl http://localhost:6333/healthz
+# → {"title":"qdrant - serving","version":"..."}
+```
+
+---
+
+## Step 2: Setup PyThaiNLP Microservice
+
+```bash
+# บน Admin Desktop (หรือ local สำหรับ dev)
+cd backend/services/thai-preprocess   # สร้าง directory นี้ในอนาคต
+
+pip install pythainlp==5.0.* fastapi uvicorn
+
+# รัน microservice
+python -m uvicorn main:app --host 0.0.0.0 --port 8765
+
+# ทดสอบ
+curl -X POST http://localhost:8765/preprocess \
+  -H "Content-Type: application/json" \
+  -d '{"text": "มาตรา ๑๐ ของสัญญา"}'
+# → {"normalized": "มาตรา 10 ของสัญญา"}
+```
+
+---
+
+## Step 3: Configure Environment Variables
+
+```env
+# backend/.env (dev override)
+
+# Qdrant
+QDRANT_URL=http://localhost:6333
+QDRANT_COLLECTION=lcbp3_vectors
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+# Ollama (Admin Desktop หรือ local)
+OLLAMA_URL=http://localhost:11434
+OLLAMA_EMBED_MODEL=nomic-embed-text
+OLLAMA_RAG_MODEL=<กำหนดโดย ops team>   # ดู research.md R1
+
+# PyThaiNLP Microservice
+THAI_PREPROCESS_URL=http://localhost:8765
+
+# Typhoon API (อาจใช้ sandbox key สำหรับ dev)
+TYPHOON_API_KEY=<dev-key>
+TYPHOON_API_URL=https://api.opentyphoon.ai/v1
+
+# RAG Config
+RAG_TOPK=20
+RAG_FINAL_K=5
+RAG_TIMEOUT_MS=5000
+RAG_QUERY_CACHE_TTL=300   # seconds
+```
+
+---
+
+## Step 4: Pull Ollama Models
+
+```bash
+# บน Admin Desktop / local Ollama
+ollama pull nomic-embed-text     # embedding model (768 dims)
+ollama pull <OLLAMA_RAG_MODEL>   # local LLM (ดูจาก ops team)
+```
+
+---
+
+## Step 5: Run Schema Delta
+
+```sql
+-- รัน SQL delta ตาม ADR-009 (แก้โดยตรง ห้ามใช้ migration)
+-- specs/03-Data-and-Storage/deltas/06-add-rag-status-to-attachments.sql
+-- specs/03-Data-and-Storage/deltas/06b-create-document-chunks.sql
+```
+
+---
+
+## Step 6: Start NestJS Backend
+
+```bash
+cd backend
+pnpm install
+pnpm run start:dev
+```
+
+---
+
+## Step 7: Initialize Qdrant Collection
+
+```bash
+# เรียก endpoint เพื่อ create collection (ถ้ายังไม่มี)
+curl -X POST http://localhost:3001/api/rag/admin/init-collection \
+  -H "Authorization: Bearer <admin-token>"
+# → {"message": "Collection lcbp3_vectors initialized"}
+```
+
+---
+
+## Step 8: Test RAG Query
+
+```bash
+# 1. Upload + commit ไฟล์ PDF (ผ่าน DMS upload API ปกติ)
+# → rag_status จะเปลี่ยนเป็น PENDING → PROCESSING → INDEXED
+
+# 2. ตรวจสอบ status
+curl http://localhost:3001/api/rag/status/<attachment-uuid> \
+  -H "Authorization: Bearer <token>"
+# → {"data": {"ragStatus": "INDEXED", "chunkCount": 12}}
+
+# 3. RAG query
+curl -X POST http://localhost:3001/api/rag/query \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "question": "เอกสารนี้เกี่ยวกับอะไร?",
+    "projectPublicId": "<project-uuid>"
+  }'
+# → {"data": {"answer": "...", "citations": [...], "fallbackUsed": false}}
+```
+
+---
+
+## Troubleshooting
+
+| ปัญหา | สาเหตุ | แก้ไข |
+|-------|-------|-------|
+| `rag_status` ค้างที่ PROCESSING | BullMQ worker ไม่ทำงาน | ตรวจสอบ Redis connection + worker process |
+| Qdrant connection refused | Qdrant container ไม่ run | `docker compose up qdrant -d` |
+| PyThaiNLP timeout | Microservice ไม่ start | ตรวจสอบ port 8765 + Python service |
+| `fallbackUsed: true` ตลอด | Typhoon API key ผิด / network block | ตรวจสอบ `TYPHOON_API_KEY` + network |
+| `chunkCount: 0` หลัง INDEXED | Collection ยังไม่ถูก init | เรียก `/api/rag/admin/init-collection` |