Menulis endpoint yang bekerja di laptop adalah setengah pekerjaan. Setengah lainnya adalah memastikan aplikasi itu tetap berjalan benar ketika di-deploy: environment variable yang hilang, container yang di-restart, trafik yang datang saat proses sedang mati. Untuk aplikasi biasa, kesalahan ini terasa menjengkelkan. Untuk aplikasi yang memanggil model AI — di mana satu request bisa makan waktu beberapa detik dan biaya nyata — kesalahan deploy yang sama bisa berarti request pengguna terputus di tengah jalan atau tagihan token yang sia-sia.

Artikel ini membahas empat pola deploy yang paling sering relevan untuk aplikasi berbasis LLM: validasi konfigurasi sejak awal (fail-fast), perbedaan health check dan readiness check, image Docker yang aman, dan graceful shutdown — termasuk satu kesalahan umum yang justru berasal dari niat menangani shutdown dengan “benar”.

1. Fail-Fast: Jangan Biarkan API Key Hilang Baru Ketahuan Saat Request Pertama

Pola paling umum yang salah: aplikasi tetap berhasil start meski API_KEY untuk model tidak ada di environment, lalu baru gagal ketika ada pengguna yang mengirim request pertama. Container terlihat “sehat” di sistem orkestrasi, padahal sebenarnya tidak bisa melayani apa pun.

import os, sys

def wajib_env(nama: str) -> str:
    nilai = os.environ.get(nama)
    if not nilai:
        print(f"FATAL: environment variable {nama} wajib diisi, proses berhenti.", file=sys.stderr)
        sys.exit(1)
    return nilai

# Panggil ini di level modul, SEBELUM app dibuat - bukan di dalam endpoint
API_KEY = wajib_env("MODEL_API_KEY")

Diuji dengan menjalankan proses tanpa MODEL_API_KEY di environment: proses langsung keluar dengan kode 1 dan pesan error yang jelas ke stderr, sebelum satu baris kode Uvicorn pun dijalankan. Bandingkan dengan kalau validasi ini ditaruh di dalam fungsi endpoint — container akan tampak start dengan sukses, lolos health check, baru gagal saat pengguna pertama mengirim request, biasanya dengan pesan error generik yang tidak jelas asalnya. Fail-fast memindahkan kegagalan ke titik paling awal yang mungkin: saat deploy, bukan saat pengguna sedang menunggu.

2. Health Check vs Readiness Check: Dua Pertanyaan yang Berbeda

@app.get("/health")
async def health():
    return {"status": "ok", "uptime_detik": round(time.time() - mulai_waktu, 1)}

@app.get("/ready")
async def ready():
    # Di sini idealnya cek koneksi DB/cache, BUKAN memanggil API model sungguhan
    # (memanggil model di setiap readiness check = biaya token yang tidak perlu)
    return {"status": "ready"}

3. Dockerfile yang Aman untuk Aplikasi AI

Tidak ada yang eksotis di sini — prinsip Docker yang baik untuk aplikasi apa pun juga berlaku untuk aplikasi AI, dengan satu tambahan: HEALTHCHECK yang memanggil endpoint /health, bukan sekadar mengecek proses masih ada.

FROM python:3.11-slim AS base
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
RUN useradd -m appuser
USER appuser

HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Tiga hal yang mudah terlewat: pertama, USER appuser memastikan proses tidak berjalan sebagai root di dalam container — kalau ada kerentanan di dependency, dampaknya lebih terbatas. Kedua, --start-period=5s memberi waktu aplikasi untuk startup (termasuk validasi fail-fast di atas) sebelum health check pertama dianggap gagal. Ketiga, base image -slim mengurangi permukaan serangan dan ukuran image dibanding image Python penuh.

4. Graceful Shutdown — dan Jebakan dari Kode yang Niatnya Baik

Ini bagian yang paling sering salah dipahami. Insting banyak developer backend: tangkap sinyal SIGTERM secara manual supaya bisa “membersihkan” sebelum proses mati. Untuk aplikasi AI, di mana satu request yang sedang diproses model bisa berjalan beberapa detik, menangani ini dengan cara yang salah berarti request itu terputus paksa di tengah jalan.

Baca Juga:

Webhook untuk Hasil AI Async: Signature, Retry, Idempotensi

Solusi yang diuji dan bekerja bersih: jangan pasang signal handler manual sama sekali. Uvicorn sudah menangani SIGTERM dengan benar secara bawaan — ia berhenti menerima koneksi baru, menunggu request yang sedang berjalan selesai, baru mematikan proses. Untuk logika pembersihan (menutup koneksi database, flush log), gunakan lifespan milik FastAPI:

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    print("startup: koneksi dibuka")
    yield
    # Baris setelah yield ini otomatis jalan saat Uvicorn menerima SIGTERM
    # dan memulai graceful shutdown - tidak perlu signal.signal() manual.
    print("shutdown: menutup koneksi dengan bersih")

app = FastAPI(lifespan=lifespan)

Diuji dengan skenario nyata: mengirim request ke endpoint yang sengaja lambat (menunggu 2 detik, mensimulasikan panggilan model), lalu mengirim SIGTERM 0,3 detik setelah request masuk. Hasilnya, Uvicorn mencetak “Waiting for connections to close”, request tetap selesai dengan status 200 setelah 2 detik penuh, baru kemudian blok shutdown di lifespan berjalan tanpa error, dan proses keluar bersih. Tidak ada request yang terputus, tidak ada traceback.

Ringkasan Perbandingan Pendekatan

Pertanyaan yang Sering Muncul

Kesimpulan

Deploy aplikasi AI ke production tidak butuh alat yang berbeda dari aplikasi backend pada umumnya — yang berbeda adalah konsekuensi dari kesalahan yang sama. Validasi konfigurasi sejak startup, pisahkan makna health check dari readiness check, dan biarkan framework (Uvicorn, FastAPI lifespan) yang menangani sinyal shutdown daripada menulis ulang logikanya sendiri. Pengujian di atas menunjukkan hal yang berlawanan dengan intuisi: kode tambahan yang ditulis dengan niat menangani shutdown “dengan benar” justru bisa menjadi sumber bug baru kalau menabrak mekanisme yang sudah disediakan framework.

Artikel terkait: FastAPI untuk aplikasi AI dan skill backend untuk AI engineering.