vllm-project/semantic-router

feat: define engine-neutral backend telemetry and replica identity contract

Open

#2,349 opened on Jul 5, 2026

View on GitHub
 (0 comments) (0 reactions) (1 assignee)Go (699 forks)github user discovery
area/model-selectionarea/observabilityenhancementhelp wantedoperationspriority/P1roadmap

Repository metrics

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

Description

Summary

Define the engine-neutral contract that inference-aware backend routing will consume before adding engine-specific integrations for vLLM, SGLang, ATOM, or future serving engines.

Parent roadmap: #2287 Parent issue: #2332 Related code: src/semantic-router/pkg/config, src/semantic-router/pkg/selection, src/semantic-router/pkg/inflight, src/semantic-router/pkg/latency, src/semantic-router/pkg/extproc, deploy/operator/controllers/backend_discovery.go

Motivation

The current router can select a logical model and already has model-level latency, in-flight, multi-factor, and cache-affinity signals. It does not yet have a normalized backend/replica identity model or a telemetry schema that can represent queue depth, GPU load, KV/cache affinity, health, and freshness across different inference engines.

Without this layer, engine-specific work will either duplicate logic or leak vLLM/SGLang/ATOM details into the router hot path.

Scope

Define a normalized backend observation contract covering:

  • logical model name, backend ref, endpoint, and replica identity;
  • serving engine kind and version when available;
  • queue depth, active requests, GPU utilization, memory pressure, and health;
  • TTFT/TPOT/E2E latency samples keyed by backend/replica;
  • KV cache, prefix cache, session, or prefix affinity hints;
  • freshness, TTL, confidence, and fail-open behavior;
  • diagnostics emitted to replay, response headers or traces where appropriate.

Non-goals

  • Do not implement an engine-specific collector here.
  • Do not require synchronous telemetry fetches on the request path.
  • Do not replace logical model selection or provider config.

Acceptance criteria

  • A backend telemetry schema and identity model can represent vLLM, SGLang, and ATOM without engine-specific fields in core selection logic.
  • Missing/stale telemetry behavior is explicit and testable.
  • Selection code can consume backend telemetry as a second-stage backend policy after logical model selection.
  • Replay/diagnostics can explain selected model, selected backend/replica, telemetry freshness, and policy reason.

Validation

make agent-report ENV=cpu CHANGED_FILES="src/semantic-router/pkg/config src/semantic-router/pkg/selection src/semantic-router/pkg/inflight src/semantic-router/pkg/latency src/semantic-router/pkg/extproc deploy/operator website/docs"
make agent-lint CHANGED_FILES="src/semantic-router/pkg/config src/semantic-router/pkg/selection src/semantic-router/pkg/inflight src/semantic-router/pkg/latency src/semantic-router/pkg/extproc deploy/operator website/docs"
make agent-ci-gate CHANGED_FILES="src/semantic-router/pkg/config src/semantic-router/pkg/selection src/semantic-router/pkg/inflight src/semantic-router/pkg/latency src/semantic-router/pkg/extproc deploy/operator website/docs"

Contributor guide