Belajar 9router - Instalasi & Setup Dasar

#Pendahuluan

Di episode 2 kalian sudah mengenal arsitektur internal 9router: route engine, model selector, policy engine, dan observability layer. Sekarang saatnya menurunkan konsep itu ke dalam praktik nyata — menginstal 9router, membuat project, dan mengonfigurasi route pertama.

Roadmap episode ini: kita akan membuat workspace project, menyiapkan konfigurasi dasar, mendefinisikan route rules dan model endpoints, menjalankan server lokal, lalu memverifikasi bahwa request dan response berjalan sesuai harapan. Di akhir episode kalian sudah punya gateway 9router yang hidup dan bisa menerima request nyata.

#Menyiapkan Workspace 9router

Langkah pertama adalah memastikan emulator 9router berjalan. Dari episode 0 kalian seharusnya sudah memiliki image emulator; pastikan ia aktif:

docker ps | grep 9router-local

Jika belum berjalan, jalankan ulang dengan perintah yang sama seperti di episode 0. Selanjutnya install CLI 9router sebagai alat bantu inisialisasi dan validasi project:

npm install -g @9router/cli

Setelah terinstall, buat workspace project baru dengan perintah init:

9router init my-gateway
cd my-gateway

Perintah di atas menghasilkan struktur folder standar. Struktur ini penting karena setiap file punya peran jelas:

my-gateway/
  config/           <- route rules dan policy
  endpoints/        <- definisi model endpoints
  .env.local        <- kredensial (tidak di-commit)
  package.json

Biasakan menulis konfigurasi 9router sebagai kode yang di-version control dengan git. Inisialisasi repository sejak awal akan sangat membantu saat kita membahas configuration management di episode 10.

#Konfigurasi Dasar Route Rules

Sekarang kita definisikan route rules pertama. File config/routes.yaml adalah tempat mendeklarasikan bagaimana request diarahkan. Mulailah dengan satu rute sederhana yang menangkap semua request chat:

version: "1"
routes:
  - name: default-chat
    match:
      any: true
    target:
      model: gpt-4o-mini
    description: Rute default untuk semua request chat

Mari kita bedah baris per baris:

Dengan konfigurasi ini, semua request akan diarahkan ke model gpt-4o-mini. Di episode 4 dan 5 kita akan memperkaya match dengan intent, keyword, dan metadata, serta target dengan banyak model.

#Konfigurasi Model Endpoints

Route rules menentukan kemana, sedangkan file endpoints/models.yaml mendefinisikan siapa yang dipanggil — provider mana dan dengan kredensial apa. Tambahkan endpoint untuk model yang kita pakai:

models:
  - id: gpt-4o-mini
    provider: openai
    credential: OPENAI_API_KEY
    max_tokens: 4096
    cost_per_1k: 0.00015

Beberapa hal penting:

• id harus cocok dengan nilai target.model di route rules.
• provider menunjuk konektor provider — di episode selanjutnya kalian akan mengenal OpenAI, Azure OpenAI, Anthropic, dan custom provider.
• credential merujuk nama environment variable yang menyimpan API key, bukan key itu sendiri.
• cost_per_1k digunakan untuk estimasi biaya — data penting untuk keputusan model selection di episode 5.

Pastikan kredensial tersedia sebagai environment variable, seperti yang disiapkan di episode 0:

export OPENAI_API_KEY="sk-..."

#Validasi Konfigurasi

Sebelum menjalankan server, validasi konfigurasi yang sudah ditulis. CLI 9router menyediakan perintah validasi untuk menangkap kesalahan sintaks atau referensi yang salah:

9router validate config/routes.yaml endpoints/models.yaml

Jika konfigurasi valid, perintah mengembalikan pesan sukses. Jika ada kesalahan seperti endpoint yang tidak ditemukan atau kredensial yang belum disetel, perintah akan menunjukkan baris yang bermasalah. Jadikan 9router validate sebagai gerbang sebelum setiap perubahan — ini pola yang akan kita formalisasikan di episode 19 saat membahas CI/CD.

#Menjalankan Server Lokal

Dengan konfigurasi valid, sekarang saatnya menjalankan gateway:

9router serve --port 8080

Server akan mulai mendengarkan di port 8080. Perhatikan log startup yang menampilkan route yang terdaftar dan status koneksi provider. Ini juga momen pertama kalian melihat observability layer bekerja — setiap event startup tercatat sebagai log.

Untuk development dengan auto-reload saat konfigurasi berubah, gunakan flag watch:

9router serve --port 8080 --watch

Dengan mode ini, perubahan pada file route atau endpoint akan langsung aktif tanpa restart manual — sangat mempercepat iterasi saat menguji rule matching di episode berikutnya.

#Verifikasi Routing Request dan Response

Sekarang uji gateway dengan request nyata. Gunakan curl untuk mengirim prompt dan amati bagaimana responsnya:

curl -X POST http://localhost:8080/v1/chat \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Sebutkan tiga manfaat routing AI dalam satu kalimat"}'

Request di atas masuk ke route engine, diarahkan oleh rute default-chat, dan dipanggil ke model gpt-4o-mini. Jika semuanya berjalan, respons berisi jawaban dari model. Untuk melihat detail keputusan routing, minta metadata tambahan:

curl -X POST http://localhost:8080/v1/chat \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Halo","include_route_meta":true}'

Respons akan menyertakan field tambahan seperti route yang dipilih, model yang dipanggil, latency per langkah, dan provider tujuan. Ini adalah jendela pertama kalian ke dalam observability layer — kemampuan untuk melihat keputusan routing secara eksplisit, bukan menebak-nebak.

Untuk memeriksa kesehatan gateway secara cepat, gunakan endpoint health check:

curl http://localhost:8080/health

Endpoint ini mengembalikan status ok plus informasi dasar seperti versi dan jumlah route aktif — berguna juga untuk memastikan server benar-benar berjalan sebelum menguji request lainnya.

#Penutup

Di episode 3 ini kalian sudah menjalankan siklus lengkap setup dasar: membuat workspace, menulis route rules dan model endpoints, memvalidasi konfigurasi, menjalankan server lokal, dan memverifikasi routing request dan response dengan contoh nyata. Kalian sekarang punya gateway 9router yang hidup.

Inti yang harus dibawa pulang:

• Route rules menentukan kemana request diarahkan; model endpoints menentukan siapa yang dipanggil.
• Kredensial selalu direferensikan sebagai environment variable, bukan ditulis langsung di konfigurasi.
• Selalu validasi dengan 9router validate sebelum menjalankan atau mengubah konfigurasi.
• Mode --watch mempercepat iterasi dengan auto-reload.
• Metadata routing di respons adalah pintu masuk pertama ke observability layer.

Di episode 4 selanjutnya kita akan membahas request matching dan route selection — bagaimana 9router memutuskan rute berdasarkan intent, task type, user identity, dan metadata, dasar rule matching seperti keyword dan semantic classification, hingga prioritas rute dan route chaining. Siapkan rute default-chat kalian, karena akan kita jadikan laboratorium eksperimen!