vllm-project/semantic-router

Define distributed Router Learning state semantics

Open

#2,243 opened on Jun 18, 2026

View on GitHub
 (0 comments) (0 reactions) (0 assignees)Go (699 forks)github user discovery
area/corearea/multi-turnarea/networkingenhancementhelp wantedpriority/P2roadmap

Repository metrics

Stars
 (4,293 stars)
PR merge metrics
 (PR metrics pending)

Description

Parent: #2238 Single-replica baseline: #2258

Goal

Define Router Learning state behavior for multi-replica deployments after the single-replica local-state model in #2258.

What #2258 Assumes

  • Request-time adaptation state is local to one router process.
  • Replay is an event log, not a synchronous request-time state lookup.
  • Experience should be snapshot-style and loaded locally before it is used.
  • Missing state/experience degrades safely instead of failing the request.

Modes To Design

  1. Single replica: all live state is local; simplest and lowest latency.
  2. Sticky multi-replica: clients or infrastructure route the same session/conversation/user to the same router replica.
  3. Shared experience + local state: replicas periodically load shared snapshots while hot state remains local.
  4. Shared hot state: optional future mode only if latency and failure behavior are acceptable.

Questions To Resolve

  • Which identities should sticky routing use: session, conversation, tenant, user, workspace, provider, or configured identity keys?
  • Which state is local-only, eventually consistent, or strongly consistent?
  • How should replicas recover useful state after restart?
  • How should Replay events reconcile with state and experience snapshots?
  • What diagnostics should show state misses, stale experience, non-sticky routing, or degraded mode?
  • What Kubernetes/Envoy guidance is needed for sticky routing?

Constraints

  • No required synchronous external storage call on every routed request.
  • Replay writes can be durable and asynchronous.
  • Raw identity values should not leak into public diagnostics.
  • Missing or stale distributed state should degrade to base routing, local state, or observe mode.

Acceptance Criteria

  • A design covers single-replica, sticky multi-replica, shared-experience/local-state, and shared-hot-state modes.
  • Latency and failure-mode tradeoffs are explicit.
  • Kubernetes deployment guidance explains when sticky routing is required.
  • Diagnostics explain missing, stale, unavailable, or non-sticky state behavior.

Contributor guide