vllm-project/semantic-router
View on GitHubDefine distributed Router Learning state semantics
Open
#2,243 opened on Jun 18, 2026
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
- Single replica: all live state is local; simplest and lowest latency.
- Sticky multi-replica: clients or infrastructure route the same session/conversation/user to the same router replica.
- Shared experience + local state: replicas periodically load shared snapshots while hot state remains local.
- 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.