184 lines
6.0 KiB
Plaintext
184 lines
6.0 KiB
Plaintext
PANDUAN GABUNGAN: CHATBOT + API GEMINI + BACKEND PYTHON (app.py)
|
|
|
|
============================================================
|
|
A. KENAPA SEBELUMNYA TIDAK ADA PENJELASAN PYTHON app.py?
|
|
============================================================
|
|
|
|
Sebelumnya arsitektur chatbot di project ini langsung memanggil Gemini dari Laravel (PHP)
|
|
melalui file app/Services/GeminiService.php.
|
|
|
|
Artinya:
|
|
- Tidak ada service Python terpisah.
|
|
- API key Gemini dibaca langsung dari env Laravel.
|
|
|
|
Sekarang sudah disiapkan backend Python (app.py) agar alur lebih fleksibel:
|
|
- Laravel -> Python backend -> Gemini API
|
|
- Kunci API dapat difokuskan di backend Python.
|
|
|
|
|
|
============================================================
|
|
B. STRUKTUR BARU YANG DITAMBAHKAN
|
|
============================================================
|
|
|
|
Folder baru:
|
|
- public/python_backend/app.py
|
|
- public/python_backend/requirements.txt
|
|
|
|
Perubahan konfigurasi:
|
|
- config/services.php
|
|
tambah:
|
|
- services.gemini.backend_url
|
|
- services.gemini.backend_token
|
|
|
|
- .env.example
|
|
tambah:
|
|
GEMINI_API_KEY=
|
|
GEMINI_BACKEND_URL=http://127.0.0.1:8001
|
|
GEMINI_BACKEND_TOKEN=
|
|
|
|
Perubahan service Laravel:
|
|
- app/Services/GeminiService.php
|
|
- jika GEMINI_BACKEND_URL terisi, Laravel coba kirim request ke Python backend dulu
|
|
- jika backend Python gagal, otomatis fallback ke pemanggilan Gemini langsung (mode lama)
|
|
|
|
|
|
============================================================
|
|
C. CARA KERJA ARSITEKTUR CHATBOT SEKARANG
|
|
============================================================
|
|
|
|
1) User kirim chat dari UI Laravel.
|
|
2) ChatbotController memanggil GeminiService::chat(...).
|
|
3) GeminiService menyiapkan payload chat (contents + generationConfig).
|
|
4) Jika GEMINI_BACKEND_URL terisi:
|
|
- request dikirim ke Python: POST /api/chat
|
|
5) Python backend mencoba model berurutan:
|
|
- gemini-2.5-flash
|
|
- gemini-2.0-flash
|
|
- gemini-2.0-flash-lite
|
|
6) Jika Python sukses -> balasan dikembalikan ke Laravel.
|
|
7) Jika Python gagal -> Laravel fallback ke direct Gemini API.
|
|
8) Jika semua gagal -> fallback response lokal di GeminiService.
|
|
|
|
|
|
============================================================
|
|
D. ENDPOINT PYTHON BACKEND
|
|
============================================================
|
|
|
|
1) GET /health
|
|
Fungsi: cek backend hidup + status key
|
|
|
|
2) POST /api/chat
|
|
Body JSON:
|
|
{
|
|
"payload": { ... Gemini payload ... },
|
|
"models": ["gemini-2.5-flash", "gemini-2.0-flash", "gemini-2.0-flash-lite"]
|
|
}
|
|
|
|
Response sukses:
|
|
{
|
|
"success": true,
|
|
"message": "...jawaban model...",
|
|
"model": "gemini-2.5-flash"
|
|
}
|
|
|
|
Response gagal:
|
|
{
|
|
"success": false,
|
|
"message": "Semua model gagal",
|
|
"error": "...detail..."
|
|
}
|
|
|
|
|
|
============================================================
|
|
E. BATASAN / LIMIT CHATBOT (REKOMENDASI PRAKTIS)
|
|
============================================================
|
|
|
|
Saat ini yang sudah ada:
|
|
- history chat dari frontend dibatasi maksimal 20 item.
|
|
- text history dipotong maksimal 1500 karakter per item sebelum dikirim.
|
|
|
|
Batasan yang disarankan agar stabil dan hemat biaya:
|
|
1) Batasi input user per pesan (contoh: 500-1000 karakter).
|
|
2) Batasi requests per menit per user (rate limit).
|
|
3) Batasi token output (sudah ada maxOutputTokens=4096, bisa diturunkan jika perlu).
|
|
4) Simpan cooldown jika terkena 429 berulang.
|
|
5) Tetapkan timeout request (sudah ada timeout di PHP dan Python).
|
|
6) Log usage untuk audit (siapa, kapan, berapa panjang pesan).
|
|
|
|
|
|
============================================================
|
|
F. LANGKAH MENJALANKAN BACKEND PYTHON
|
|
============================================================
|
|
|
|
1) Masuk ke folder python backend
|
|
cd public/python_backend
|
|
|
|
2) Buat virtual environment (opsional tapi disarankan)
|
|
python -m venv .venv
|
|
.venv\Scripts\activate
|
|
|
|
3) Install dependency
|
|
pip install -r requirements.txt
|
|
|
|
4) Set environment variable untuk backend Python
|
|
(PowerShell contoh)
|
|
$env:GEMINI_API_KEY="ISI_API_KEY_GEMINI"
|
|
$env:BACKEND_TOKEN="TOKEN_RAHASIA_BACKEND" # opsional tapi disarankan
|
|
$env:PY_BACKEND_HOST="127.0.0.1"
|
|
$env:PY_BACKEND_PORT="8001"
|
|
|
|
5) Jalankan server Python
|
|
python app.py
|
|
|
|
6) Test health endpoint
|
|
buka: http://127.0.0.1:8001/health
|
|
|
|
|
|
============================================================
|
|
G. KONFIGURASI LARAVEL AGAR PAKAI BACKEND PYTHON
|
|
============================================================
|
|
|
|
Di .env Laravel, isi:
|
|
- GEMINI_BACKEND_URL=http://127.0.0.1:8001
|
|
- GEMINI_BACKEND_TOKEN=TOKEN_RAHASIA_BACKEND
|
|
|
|
Opsional:
|
|
- GEMINI_API_KEY=... (tetap boleh ada untuk fallback direct mode)
|
|
|
|
Setelah ubah env:
|
|
- php artisan optimize:clear
|
|
|
|
|
|
============================================================
|
|
H. KEAMANAN API KEY GEMINI
|
|
============================================================
|
|
|
|
Praktik aman:
|
|
1) Jangan hardcode API key di kode sumber.
|
|
2) Simpan API key di env backend Python.
|
|
3) Gunakan BACKEND_TOKEN agar endpoint Python tidak bisa dipakai bebas.
|
|
4) Jalankan backend Python di localhost/internal network.
|
|
5) Jangan commit file .env ke GitHub.
|
|
|
|
|
|
============================================================
|
|
I. SATU FILE RINGKAS UNTUK SIDANG (NARASI SINGKAT)
|
|
============================================================
|
|
|
|
Arsitektur chatbot awal memanggil Gemini langsung dari Laravel. Agar manajemen API key
|
|
lebih aman dan fleksibel, ditambahkan backend Python app.py sebagai gateway. Laravel
|
|
mengirim payload ke Python endpoint /api/chat, lalu Python meneruskan ke Gemini dengan
|
|
mekanisme pemilihan model bertahap. Jika backend Python gagal, Laravel tetap memiliki
|
|
mekanisme fallback ke direct Gemini sehingga layanan chatbot lebih robust. Sistem juga
|
|
menerapkan pembatasan history dan panjang pesan, dan dapat ditingkatkan dengan rate limit
|
|
per pengguna agar performa tetap stabil.
|
|
|
|
|
|
============================================================
|
|
J. CATATAN PENTING
|
|
============================================================
|
|
|
|
- Jika GEMINI_BACKEND_URL tidak diisi, sistem tetap berjalan seperti mode lama.
|
|
- Jika GEMINI_BACKEND_URL diisi tapi backend Python mati, sistem otomatis fallback direct.
|
|
- Untuk mode produksi, disarankan Python backend aktif + token + monitoring log.
|