ChatbotAI/SETUP.md

Panduan Setup — Sistem Pangkalan Pengetahuan

Keperluan Sistem

• PHP 8.3+ (PHP 8.5 disokong)
• MySQL 8.0+
• Composer 2.x
• Ollama (berjalan pada localhost:11434)
• Qdrant (berjalan pada localhost:6333)
• Node.js (optional, untuk Vite)

---

Langkah 1: Konfigurasi .env

# Salin contoh .env
cp .env.example .env

# Jana app key
php artisan key:generate

Edit .env dengan tetapan anda:

# Database MySQL
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=knowledge_base
DB_USERNAME=root
DB_PASSWORD=your_password_here

# Ollama (tukar model ikut yang anda ada)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_CHAT_MODEL=llama3
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

# Qdrant
QDRANT_BASE_URL=http://localhost:6333
QDRANT_VECTOR_SIZE=768

---

Langkah 2: Setup Database

# Buat database (dalam MySQL)
mysql -u root -p -e "CREATE DATABASE knowledge_base CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Jalankan migrasi
php artisan migrate

# Seed data awal (kategori + user admin + sample FAQ)
php artisan db:seed

---

Langkah 3: Pull Model Ollama

# Model embedding (wajib)
ollama pull nomic-embed-text

# Model chat (pilih satu)
ollama pull llama3       # atau
ollama pull mistral      # atau
ollama pull qwen2        # (lebih ringan)

---

Langkah 4: Setup Qdrant

# Jalankan Qdrant dengan Docker
docker run -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/qdrant_storage:/qdrant/storage:z \
  qdrant/qdrant

# Collection akan dibuat secara automatik semasa pertama embed

---

Langkah 5: Semak Kesihatan Sistem

php artisan kb:health-check

Output yang dijangka:

════════════════════════════════════════
  PEMERIKSAAN KESIHATAN SISTEM
════════════════════════════════════════

📦 MySQL
   ✅ Berjaya sambung ke: knowledge_base

🤖 Ollama
   ✅ Online
   ✅ Model Chat:    llama3
   ✅ Model Embed:   nomic-embed-text

🗄️  Qdrant
   ✅ Online
   ✅ Collection:    knowledge_base
   📊 Vectors:      0

⏳ Queue
   ✅ Driver konfigurasi untuk async.

════════════════════════════════════════
  ✅ SEMUA PERKHIDMATAN OK
════════════════════════════════════════

---

Langkah 6: Setup Storage

# Link public storage
php artisan storage:link

---

Langkah 7: Jalankan Queue Worker

# Development
php artisan queue:work --timeout=600 --tries=2

# Production (gunakan Supervisor)
php artisan queue:work --queue=default --sleep=3 --tries=2 --timeout=600

---

Langkah 8: Jalankan Aplikasi

php artisan serve

Akses:

• Chatbot: http://localhost:8000/chatbot
• Admin: http://localhost:8000/admin
• Login: admin@example.com / password

---

Arahan Artisan Berguna

# Semak kesihatan sistem
php artisan kb:health-check

# Reindex satu dokumen
php artisan kb:reindex-document --document_id=1

# Reindex semua dokumen yang gagal
php artisan kb:reindex-document --all-failed

# Reindex semua dalam kategori pelesenan
php artisan kb:reindex-category --slug=pelesenan

# Preview tanpa jalankan (dry run)
php artisan kb:reindex-category --slug=pelesenan --dry-run

# Monitor queue
php artisan queue:monitor default

---

Nota Production

1. Tukar kata laluan admin di admin panel atau melalui tinker
2. Set QUEUE_CONNECTION=redis dan gunakan Supervisor untuk queue worker
3. Set APP_DEBUG=false dalam .env
4. Setup backup untuk storage/app/documents/ (fail PDF asal)
5. Rate limiting chatbot sudah dikonfigurasi (20 req/min per IP) — laraskan KB_CHAT_RATE_LIMIT
6. Qdrant — tambah API key untuk keselamatan (QDRANT_API_KEY=xxx)

---

Struktur Direktori Penting

app/
├── Actions/           ← Single-purpose business logic
├── Console/Commands/  ← Artisan commands (kb:*)
├── Http/Controllers/  ← Admin & Chatbot controllers
├── Jobs/              ← Queue jobs
├── Models/            ← Eloquent models
└── Services/
    ├── Document/      ← PDF extraction & chunking
    ├── KnowledgeBase/ ← Ingestion, RAG, Audit
    ├── Ollama/        ← Ollama HTTP client
    └── Qdrant/        ← Qdrant HTTP client

config/
├── knowledgebase.php  ← Konfigurasi umum KB
├── ollama.php         ← Konfigurasi Ollama
└── qdrant.php         ← Konfigurasi Qdrant

storage/app/documents/ ← Fail PDF asal (JANGAN padam)