vLLM Semantic Router v0.4: Panduan Routing Mixture-of-Models

Kebanyakan tim memilih satu model, menuliskan namanya di setiap client, lalu baru meninjau ulang saat tagihan membengkak atau ada keluhan. Masalahnya, sapaan di customer support dan refactor multi-langkah dikirim ke model mahal yang sama, dan mengganti model berarti mengubah semua caller.

vLLM Semantic Router v0.4 dengan nama kode Hermes, dirilis 24 September 2026, menawarkan jawabannya: satu nama model yang stabil di depan sebuah pool. Saya belum men-deploy-nya. Artikel ini adalah pembacaan teliti atas release post dan dokumentasi resmi proyeknya; semua angka dan nama field berasal dari halaman tersebut, dan YAML yang saya rakit sendiri dari field terdokumentasi saya tandai.

Satu nama model di depan sebuah pool

Release post menjelaskan ide intinya dengan lugas: aplikasi memakai satu nama model virtual yang stabil, lalu Router memilih backend dari pool yang sudah dikualifikasi, mengembalikan jawaban, dan mengukur hasilnya. README repositori menyebut model ID publiknya vllm-sr/auto dan menggambarkan proyek ini sebagai decision layer yang terbuka dan dapat diprogram untuk model dan compute, berlisensi Apache-2.0.

Di dalamnya, sebuah request melewati Signal, Projection, Decision, Algorithm, lalu Model, dengan plugin route menempel pada jalur yang terpilih. Client melihat tiga endpoint: /v1/messages, /v1/chat/completions, dan /v1/responses, dilayani lewat codec bersama untuk ketiga protokol di jalur buffered maupun streaming. Release post menyebut v0.5 menargetkan general availability untuk ketiga jalur itu.

Baris terakhir adalah harga jujur dari seluruh ide ini. Pilihan statis tidak bisa salah rute karena memang tidak pernah merute. Semua mesin yang dibahas di sini membeli pilihan per request dengan harga cara baru untuk salah.

Signal hanya mendeteksi

Dokumentasi signal membagi signal menjadi dua keluarga. Heuristic signal memakai aturan eksplisit, bentuk request, identitas, atau detektor ringan: Authz, Conversation, Context, Event, Input Modality, Keyword, Language, Metadata, dan Structure. Learned signal memakai embedding, classifier, atau model detektor yang dikonfigurasi: Classifier, Complexity, Domain, Embedding, Modality, Fact Check, Hallucination, Jailbreak, Safety, PII, Preference, Reask, Knowledge Base, dan User Feedback.

Signal dideklarasikan di bawah routing.signals, satu key per tipe, dan tiap entri butuh name. Contoh di halaman itu mendeklarasikan satu keyword signal dan dua embedding signal, lalu mengelompokkan embedding dalam sebuah projection agar dua intent tidak bisa menang bersamaan.

# From the signal overview in the vLLM Semantic Router docs.
routing:
  signals:
    keywords:
      - name: urgent_keywords
        operator: OR
        keywords: ["urgent", "asap"]
    embeddings:
      - name: technical_support
        threshold: 0.75
        candidates: ["installation guide", "troubleshooting steps"]
      - name: account_management
        threshold: 0.72
        candidates: ["billing information", "subscription management"]
  projections:
    partitions:
      - name: support_intents
        semantics: exclusive      # members compete; one wins
        temperature: 0.3
        members: [technical_support, account_management]
        default: technical_support

Aturan yang dinyatakan dokumentasi layak masuk checklist review Anda: signal tetap hanya untuk deteksi. Hasil routing ada di decision, pemilihan model di algorithm, perilaku di plugin. Dokumentasi juga memperingatkan bahwa learned signal dapat mengirim data ke classifier atau embedding provider remote yang dikonfigurasi, jadi baca catatan penanganan data tiap keluarga sebelum mengarahkannya ke endpoint hosted.

Decision: rule, tier, dan arti Unknown

Decision adalah pohon rule bernama beserta kandidat tujuannya. Rule menggabungkan kondisi leaf dengan AND, OR, dan NOT. Satu-satunya contoh lengkap di halaman decision merute request domain bisnis ke satu model. Di bawahnya saya menambahkan decision kedua yang dirakit hanya dari field terdokumentasi (tier, on_unknown, operator, type, name); nama leaf harus cocok dengan signal yang Anda deklarasikan, dan file ini belum saya jalankan.

routing:
  strategy: priority            # default; the other value is confidence
  decisions:
    # Verbatim shape from the decisions page.
    - name: business_route
      description: Route business requests to the business model.
      priority: 110
      rules:
        operator: AND
        conditions:
          - type: domain
            name: business
      modelRefs:
        - model: qwen2.5:3b
          use_reasoning: false

    # Assembled by me from documented fields. Not copied, not executed.
    - name: guarded_route
      tier: 1                   # lower tier wins; no tier means tier 0
      priority: 200
      rules:
        operator: AND
        on_unknown: fail_request  # classifier failure returns a 503, not a guess
        conditions:
          - type: jailbreak
            name: prompt_attack
      modelRefs:
        - model: guarded-model

Ranking punya empat langkah. Match mengevaluasi rule, dengan on_unknown memilih no_match, match, atau fail_request saat hasilnya masih Unknown; fail_request mengembalikan 503 dengan pesan yang menyebut cara memperbaikinya. Tier adalah batas keras dan tier yang lebih rendah menang. Rank memakai routing.strategy: priority secara default, atau confidence. Explain adalah bagian yang akan saya pakai setiap hari: Preview dan Replay menampilkan strategi, tier, dan alasan pemenang mengalahkan runner-up.

Confidence lebih ketat dari kedengarannya. Sebuah pool diranking dengan confidence hanya bila setiap match non-catch-all punya tepat satu evidence leaf dan semuanya berjenis skor sama, seperti probabilitas classifier atau kemiripan vektor. Signal complexity dan jailbreak tidak pernah comparable. Selain itu router diam-diam kembali ke priority dan memberi warning saat startup. Validator config juga menolak pohon yang salah bentuk, misalnya: decision billing, rules.conditions[1]: NOT requires exactly one child condition, got 2.

Algorithm: memilih satu model, atau beberapa

Algorithm berjalan setelah sebuah decision match. Selection algorithm mengembalikan satu kandidat dari modelRefs milik decision. Looper algorithm melakukan panggilan model tambahan lewat global.integrations.looper.endpoint, yang menurut dokumentasi menambah latency dan token usage serta mengirim konten antara ke setiap worker yang dikonfigurasi. Dengan satu kandidat saja, algorithm tidak perlu ditulis.

Contoh terdokumentasi memakai latency_aware. Kandidat disaring berdasarkan context, protokol, dan kapabilitas task yang dideklarasikan sebelum diberi skor, dan route yang mensyaratkan pool minimum akan gagal alih-alih diam-diam menjalankan panel yang lebih kecil. Perhatikan bahwa observasi latency bersifat per proses, jadi dua replika router bisa berbeda pendapat tentang model mana yang tercepat.

routing:
  decisions:
    - name: responsive-route
      description: Prefer the model with the best observed latency.
      priority: 100
      rules:
        operator: AND
        conditions: []          # empty: matches everything, so it acts as a catch-all
      modelRefs:
        - model: small-model
        - model: large-model
      algorithm:
        type: latency_aware
        minimum_candidates: 2   # fail the route if fewer than 2 distinct modelRefs survive
        latency_aware:
          tpot_percentile: 90
          ttft_percentile: 95

Plugin: perilaku milik satu route

Plugin berada di routing.decisions[].plugins dan hanya berlaku setelah route itu match. Layanan bersama didefinisikan sekali di bawah global, dan plugin hanya menyalakan serta menyetelnya per route. Dokumentasi mendata lima belas tipe plugin, di antaranya fast_response, system_prompt, header_mutation, tools, tool_selection, context_compression, response_cache, memory, rag, router_replay, shadow_dispatch, hallucination, dan response_jailbreak.

# From the plugin overview. The shared store is declared once under
# global.stores.response_cache; this route only switches the plugin on.
routing:
  decisions:
    - name: cached-support
      description: Reuse cached responses for support requests.
      priority: 100
      rules:
        operator: AND
        conditions: []
      modelRefs:
        - model: support-model
      plugins:
        - type: response_cache
          configuration:
            enabled: true
            ttl_seconds: 3600

Release post menambahkan detail yang menentukan apakah plugin ini layak dipercaya di production:

• Response Cache memeriksa kompatibilitas history, tools, format, model, dan recipe sebelum memakai ulang jawaban, dan pengecekan negasi atau verifier opsional yang gagal mengubah hit menjadi miss.
• Shadow Dispatch mengirim salinan request single-model yang terbatas dan disampel ke sebuah kandidat tanpa menyentuh jawaban live; Replay mencatat hasilnya, tetapi kualitas jawaban perlu dievaluasi terpisah.
• Context Compression bersifat opt-in, melindungi instruksi dan pasangan tool-call, dan mempertahankan giliran user saat ini kecuali truncation diaktifkan secara eksplisit.
• Router Memory mengekstrak fakta secara asinkron di sisi response dan melaporkan tiap fakta sebagai written, failed, atau dropped.

Model-model yang melakukan routing

Classifier-nya adalah model open, yang penting bila prompt tidak boleh dikirim ke pihak ketiga. Vela 1.0 adalah keluarga 15 model open di organisasi Hugging Face vllm-sr: sebelas encoder 307M parameter untuk tugas seperti domain, feedback, modality, fact-check, guard, safety, hazard, shield, PII, span hallucination, dan reranking, ditambah satu encoder embedding, dua model embedding multimodal Omni, dan satu basis masked-language. Shield dikontribusikan KR-Labs dan menaikkan keluarga ini dari 14 menjadi 15.

Decision 1.0 adalah set terpisah berisi enam model open-weight penghitung skor yang mengembalikan distribusi yang bisa diperiksa: Kai dan Lex pada 0.6B dengan batas input 1.024 token, lalu Eos 0.8B, Sol 2B, Nox 4B, dan Lux 9B pada 16.384 token. Pada evaluasi 54 task yang dipublikasikan proyek, Lux-9B mendapat 76,94 dan Nox-4B 73,09, dibandingkan 81,05 untuk referensi hosted Jev. Post itu menyebut Lux-9B memimpin referensi model open yang ditampilkan. Post itu juga menyatakan integrasi native Decision di Router adalah langkah berikutnya, jadi model-model ini belum menjadi bagian jalur routing yang bisa Anda deploy.

Di mana ia bisa gagal

Release post ini jujur secara tidak biasa, dan caveat-nya menjadi bagian kegagalan artikel ini. Response streaming baru diamati setelah selesai, sehingga Router tidak bisa menarik kembali byte yang sudah terkirim. Pengecekan hallucination butuh grounding context yang disuplai, tanpa itu jawaban tidak bisa diverifikasi. Fusion, Workflows, dan prompt selector masih experimental, dan support matrix mencantumkan hallucination policy, jailbreak error handling, dan response jailbreak di antara contoh experimental yang belum dikualifikasi untuk production.

Fallback punya batas keras: cross-model fallback bersifat opt-in dan berhenti begitu stream sudah committed atau side effect tool mungkin telah terjadi. Request yang sudah mulai streaming dari model yang salah tetap salah. Error classifier tetap Unknown, dan weighted projection yang bergantung padanya menahan skornya alih-alih menganggapnya nol; itu benar, sekaligus berarti rule Anda harus menangani nilai yang hilang.

Saya menambahkan satu lagi: Looper algorithm mengirim konten antara ke setiap worker yang dikonfigurasi, sehingga objective privasi ala Vault dan panel model eksternal saling bertentangan. Periksa di mana tiap worker berjalan sebelum mengaktifkan Fusion pada route yang membawa input sensitif.

Kapan ia mengalahkan pilihan statis, dan langkah Senin pagi

Ia layak dipakai bila tiga hal terpenuhi: traffic Anda memang bercampur antara request murah dan sulit, Anda punya setidaknya dua backend yang masing-masing layak untuk sebagian campuran itu, dan hasilnya bisa diukur. Bila salah satu tidak ada, pertahankan nama statis. Benchmark proyek ini ada untuk syarat ketiga. Berikut urutan kerja yang akan saya ambil.

1. Tuliskan kelas traffic Anda dan model yang akan Anda pilih manual untuk tiap kelas. Daftar itu adalah baseline statis sekaligus kumpulan decision pertama Anda.
2. Install Router dan arahkan satu client non-kritis ke model ID publik vllm-sr/auto. Mulai dari satu decision dengan satu kandidat, sehingga belum ada yang dipilih.
3. Deklarasikan on_unknown di setiap decision yang memakai classifier, dan gunakan Preview untuk memeriksa pilihan sebelum memakai Probe untuk memastikan backend sungguhan menjawab.
4. Aktifkan Shadow Dispatch pada sebagian kecil traffic agar Replay mencatat apa yang akan dilakukan sebuah kandidat, lalu nilai sendiri jawabannya, karena plugin itu tidak menilainya.
5. Evaluasi dengan sr-bench: tuning pada slice quick, lalu klaim penghematan hanya pada holdout standard yang terpisah.

# Install (stable channel), from the project README.
curl -fsSL https://vllm-sr.ai/install.sh | bash -s -- --channel stable

# List the benchmark adapters installed. This is the only command the
# sr-bench page states; planning and running are on its linked pages.
vllm-sr benchmark catalog

# Smoke-test a client against the virtual model. ROUTER_URL is yours:
# the docs I read do not name a default host or port.
curl "$ROUTER_URL/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{"model": "vllm-sr/auto", "messages": [{"role": "user", "content": "ping"}]}'

Soal sr-bench: ia mencakup sembilan benchmark dan run yang kehilangan salah satunya tidak punya skor lengkap. Smoke berisi 36 task, quick 740, dan holdout standard 3.183, dengan standard terpisah dari quick. Halaman itu memperingatkan bahwa task publik tidak bebas kontaminasi dan label GPQA yang pernah terlihat butuh pengungkapan retest meski split-nya disebut holdout. Ia tidak menyebut metrik dan tidak mempublikasikan skor, jadi angka penghematan apa pun harus Anda hasilkan sendiri.

Semantic routing adalah pertukaran, bukan peningkatan: Anda menukar nama model yang ditulis keras dengan policy yang harus diuji, diamati, dan dioperasikan. Pakai bila campuran traffic dan pengukuran holdout membenarkannya, jaga on_unknown tetap eksplisit, dan biarkan algorithm experimental di luar route production sampai support matrix berkata lain.