Belajar 9router - Request Matching & Route Selection

#Pendahuluan

Di episode 3 kalian sudah menjalankan gateway pertama dengan satu rute yang menangkap semua request. Sekarang kita naik satu level: bagaimana membuat 9router cerdas memilih rute. Alih-alih semua request masuk ke satu model, kita akan mengarahkan setiap request ke rute yang paling tepat berdasarkan isi dan konteksnya.

Roadmap episode ini: kita akan membahas empat dimensi routing — intent, task type, user identity, dan metadata — lalu mendalami dasar rule matching dengan keyword, semantic classification, dan fallback, dan diakhiri dengan prioritas rute serta route chaining. Kalian akan keluar dari episode ini dengan kemampuan menyusun aturan matching yang tajam.

#Empat Dimensi Routing

Keputusan routing di 9router bisa mempertimbangkan empat dimensi yang saling melengkapi:

Menggabungkan dimensi-dimensi ini memungkinkan aturan yang presisi: misalnya, "pengguna premium dengan intent code dan region ap-southeast-1 diarahkan ke model code besar". Semakin banyak dimensi yang dimanfaatkan, semakin tepat keputusan routing — tapi juga semakin kompleks. Mulailah sederhana dan perkuat secara bertahap.

#Dasar Rule Matching: Keyword

Metode matching paling dasar adalah keyword: mencocokkan kata kunci yang muncul di dalam prompt. Cara ini cepat, murah, dan deterministik — sangat cocok untuk pola yang jelas. Contohnya, rute yang menangkap pertanyaan ringan dengan kata kunci "jam buka":

routes:
  - name: faq-fast
    match:
      keywords:
        - "jam buka"
        - "lokasi toko"
        - "nomor telepon"
    target:
      model: gpt-4o-mini

Rute faq-fast menangkap prompt yang mengandung salah satu kata kunci dan mengarahkannya ke model murah dan cepat. Perhatikan urutan penting: rute dengan kriteria spesifik harus diletakkan sebelum rute default, karena 9router mengevaluasi rute sesuai urutan deklarasi. Topik ini akan kita perdalam di bagian prioritas rute.

#Semantic Classification: Memahami Makna

Keyword punya kelemahan: kaku terhadap variasi bahasa. Pengguna bisa bertanya "sampai jam berapa bukanya?" tanpa menyebut kata "jam buka". Di sinilah semantic classification berperan — 9router memakai model embedding untuk mengklasifikasikan prompt ke dalam intent berdasarkan kemiripan makna.

routes:
  - name: faq-fast
    match:
      intent: faq
    target:
      model: gpt-4o-mini

Konfigurasi di atas menggunakan intent faq yang dihasilkan dari semantic classifier. 9router mengelola definisi intent dan training data di file terpisah, misalnya config/intents.yaml:

intents:
  - name: faq
    examples:
      - "sampai jam berapa bukanya?"
      - "di mana alamat kantor kalian?"
      - "apa nomor kontak yang bisa dihubungi?"
    strategy: semantic

Setiap intent memiliki contoh kalimat yang menjadi bahan pelatihan classifier. Pendekatan ini lebih fleksibel dibanding keyword, dengan konsekuensi biaya eksekusi yang sedikit lebih tinggi karena ada pemanggilan model embedding di tiap request.

#Routing Berdasarkan User Identity dan Metadata

Keputusan routing sering bergantung pada siapa penggunanya dan konteks di sekitarnya. 9router membaca user identity dari token autentikasi atau field payload, dan metadata dari header maupun atribut request:

routes:
  - name: premium-code
    match:
      user:
        tier: premium
      metadata:
        region: ap-southeast-1
      intent: code
    target:
      model: gpt-4o-premium
  - name: standard-chat
    match:
      any: true
    target:
      model: gpt-4o-mini

Dengan konfigurasi ini, hanya pengguna premium dengan intent code dan region yang cocok yang mendapat model besar; semua request lain jatuh ke rute default. Pola ini adalah fondasi dari tenant-aware routing yang akan kita bahas lebih dalam di episode 9.

#Prioritas Rute dan Fallback

Sekarang kita sampai pada konsep paling penting: urutan evaluasi. 9router mengevaluasi rute dari atas ke bawah dan memilih rute pertama yang cocok. Ini berarti urutan deklarasi adalah keputusan desain, bukan kebetulan:

Rute default dengan any: true di bagian bawah menjamin setiap request tetap terlayani. Jika tidak ada rute yang cocok, 9router mengembalikan respons error dengan kode yang jelas — bisa dicek di log. Untuk menangani kasus model tidak tersedia, setiap rute bisa mendeklarasikan fallback models:

routes:
  - name: vision-route
    match:
      taskType: vision
    target:
      model: gpt-4o-vision
      fallback:
        - model: claude-vision
        - model: gemini-vision

Jika model utama gagal atau tidak tersedia, 9router mencoba fallback secara berurutan sebelum menyerah. Ini adalah bentuk awal resilience yang akan kita perdalam di episode 18.

#Route Chaining: Lebih dari Satu Keputusan

Sejauh ini setiap rute menghasilkan satu keputusan langsung. Route chaining memungkinkan request melewati beberapa rute secara berurutan — hasil langkah pertama menjadi input langkah berikutnya. Pola ini berguna untuk alur bertingkat: pertama klasifikasikan request, lalu putuskan pemanggilan tool, kemudian baru kirim ke model.

routes:
  - name: classifier
    match:
      any: true
    chain:
      - next: tool-selector
        on: classify
  - name: tool-selector
    match:
      intent: search
    target:
      tool: search-api
    chain:
      - next: final-model
        on: tool_result
  - name: final-model
    match:
      any: true
    target:
      model: gpt-4o

Konfigurasi di atas menggambarkan alur agentic sederhana: request diklasifikasikan, jika intent-nya search maka tool pencarian dipanggil, lalu hasilnya dikirim ke model akhir. Route chaining inilah yang menjadi tulang punggung tool invocation yang kita kenalkan di episode 2 — dan akan menjadi fondasi untuk advanced routing patterns di episode 8.

#Praktik: Menguji Rule Matching

Untuk memverifikasi aturan matching kalian, kirim beberapa request dengan variasi prompt dan amati rute yang terpilih lewat metadata:

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

Ulangi dengan prompt yang berbeda — pertanyaan teknis, permintaan kode, atau pertanyaan ringan — lalu bandingkan field route di setiap respons. Kalian akan melihat bagaimana keyword, intent, dan metadata berkolaborasi menentukan rute. Jika hasil tidak sesuai harapan, jalankan kembali 9router validate dan periksa urutan rute di file konfigurasi.

#Penutup

Di episode 4 ini kalian sudah menguasai seni request matching dan route selection: empat dimensi routing, perbedaan keyword dan semantic classification, peran user identity dan metadata, aturan prioritas dan fallback, serta pola route chaining untuk alur bertingkat.

Inti yang harus dibawa pulang:

• Keputusan routing bisa mempertimbangkan intent, task type, user identity, dan metadata secara bersamaan.
• Keyword cepat dan murah untuk pola jelas; semantic classification menangkap variasi makna.
• Rute spesifik di atas, rute default di bawah — urutan deklarasi menentukan prioritas.
• Fallback models menjaga rute tetap hidup saat model utama gagal.
• Route chaining memungkinkan request melewati beberapa keputusan bertingkat, termasuk tool invocation.

Di episode 5 selanjutnya kita akan membahas model and tool selection — bagaimana memilih model target berdasarkan performance, cost, dan accuracy, menyusun multi-model stack untuk conversational, embeddings, code, dan vision, serta mengintegrasikan external tools dan API services ke dalam keputusan routing. Laboratorium matching kalian akan kita isi dengan beragam model!