SGLang Model Gateway 特性详解（Cache-Aware 之外）

一、负载均衡策略（除 cache_aware）

1.1 Power of Two（policies/power_of_two.rs）

随机选 2 个健康 Worker，比较负载（优先 token 级负载，降级为请求计数），发给负载更轻的那个。O(1) 决策，无需全局状态。

1.2 Round Robin（policies/round_robin.rs）

原子计数器轮转，每次递增取模，最朴素的均匀分发。

1.3 Random（policies/random.rs）

纯随机选一个健康 Worker，基准策略，无状态。

1.4 Bucket（policies/bucket.rs）

按模型分组，每个模型绑定固定 Worker 池，适合多模型网关。

1.5 Consistent Hashing（policies/consistent_hashing.rs）

一致性哈希环，请求按 key 映射到环上顺时针找 Worker。Worker 增减时只影响相邻节点，适合会话保持。

1.6 Prefix Hash（policies/prefix_hash.rs）

按请求文本前缀做哈希，确定性路由到固定 Worker。同类请求永远落在同一 Worker。

1.7 Manual（policies/manual.rs）

手动指定 Worker，用于调试、灰度、A/B 测试。

策略注册表（policies/registry.rs+policies/factory.rs）

// 每个模型可以绑定独立策略pubstructPolicyRegistry{// default_policy: 全局默认// model_policies: HashMap<model_id, Box<dyn LoadBalancingPolicy>>// PD 模式下 prefill/decode 各有独立策略}

二、gRPC Router（routers/grpc/）

2.1 管道化架构

请求 -> Preparation -> WorkerSelection -> ClientAcquisition -> RequestBuilding -> DispatchMetadata -> RequestExecution -> ResponseProcessing -> ResponseFormatting -> 返回

每阶段可插拔、可组合，支持 Chat / Generate / Embedding / Classify / Responses 五种端点。

2.2 全 Rust Tokenizer

llm-tokenizercrate，不依赖 Python，支持 DeepSeek、Llama、Kimi K2、Qwen、GPT-OSS、Mistral、GLM4/4.7、Step-3。避免 Python tokenizer 的序列化往返和 GIL 瓶颈。

2.3 Rust Reasoning Parser + Tool Parser

• Reasoning Parser：从模型输出分离response和response
• Tool Parser：提取 Function Call JSON，不经过 Python
• 均以 crate 形式编译进 SMG，零外部依赖

2.4 Harmony Router

组合式推理引擎：自动检测请求是否需要多模型编排（Harmony），选择对应的 pipeline 执行。

2.5 gRPC PD Router

gRPC 协议下的 PD 分离路由，prefill/decode 各走独立 gRPC stream。

三、可靠性机制（4 层防御）

3.1 断路器（core/circuit_breaker.rs）

三态状态机：

Closed --连续失败 N 次--> Open --超时后--> HalfOpen ^ | +------ 连续成功 M 次 ------------------------+

默认配置：failure_threshold=5, success_threshold=2, timeout=30s。

状态用AtomicU8无锁存储（CLOSED=0, OPEN=1, HALF_OPEN=2），每次请求只做一次原子读，纳秒级开销。连续失败计数，中间成功一次就清零。

3.2 令牌桶（core/token_bucket.rs）

pubstructTokenBucket{inner:Arc<Mutex<TokenBucketInner>>,// parking_lot::Mutexnotify:Arc<Notify>,// 公平排队capacity:f64,// 最大令牌数（突发容量）refill_rate:f64,// 每秒补充令牌数}

• refill_rate > 0：限速模式（QPS 限制）
• refill_rate = 0：并发限制模式（信号量）
• 用parking_lot::Mutex而非tokio::sync::Mutex（操作极短，异步锁开销更大）
• Notify实现 FIFO 公平排队

3.3 重试（core/retry.rs）

可重试的 6 种状态码：408/429/500/502/503/504。指数退避公式：

delay = min(initial_backoff_ms * multiplier^attempt, max_backoff_ms) +/- jitter_factor 随机抖动

jitter 防止惊群效应——多请求同时失败同时重试同时打爆同一个 Worker。

3.4 健康检查（core/worker_manager.rs）

后台 task 定期GET /health探活，不健康的set_healthy(false)自动摘除。配合断路器形成两层保护：健康检查摘死节点，断路器保护抖节点。

四、PD 分离路由（routers/http/pd_router.rs）

4.1 请求生命周期

Client -> SMG -> select_prefill_worker() -> Prefill Worker（生成完整 KV Cache） KV Cache 通过 Mooncake RDMA 传给 Decode -> select_decode_worker() -> Decode Worker（逐 token 生成）

4.2 DP-Aware 绑定

prefill 和 decode 必须在同一 DP replica 上（KV Cache 物理可达）。通过data_parallel_rank字段传递 rank 信息。

4.3 双策略

prefill 和 decode 可配置独立路由策略：

smg launch --pd-disaggregation\--prefill-policy cache_aware\--decode-policy power_of_two

五、IGW 多模型网关（routers/router_manager.rs）

5.1 核心概念

RouterManager维护HashMap<model_id, Router>，根据请求的model字段自动分发到对应 Router。

5.2 每个模型独立配置

{"deepseek-v3":{"policy":"cache_aware","rate_limit":1000,"circuit_breaker":{"failure_threshold":5}},"qwen3.5-32b":{"policy":"power_of_two","rate_limit":500},"gpt-4o":{"policy":"round_robin","api_key":"sk-...","backend":"openai"}}

5.3 统一 API 入口

POST /v1/chat/completions {"model": "deepseek-v3", ...} POST /v1/chat/completions {"model": "qwen3.5-32b", ...} POST /v1/chat/completions {"model": "gpt-4o", ...} -> 全走同一个 SMG 地址

六、可观测性（observability/）

6.1 Prometheus 指标

40+ 指标，分类：

6.2 字符串 Interning 优化

metrics.rs内置全局STRING_INTERNER: DashMap<String, Arc<str>>，所有动态 label（model_id、worker_url）只分配一次，后续零拷贝复用。

6.3 OpenTelemetry

自动注入 trace context 到下游 Worker HTTP header，支持 OTLP gRPC 导出。

七、认证与安全

• API Key：Bearer token 验证
• JWT：支持 JWKS 公钥验证
• RBAC：角色权限控制
• TLS/mTLS：axum-server + rustls，支持双向 TLS

八、MCP 集成（routers/openai/responses/mcp.rs）

• 原生 MCP Client
• 支持四种传输协议：STDIO / HTTP / SSE / Streamable
• 工具调用循环：模型输出 Function Call -> SMG 执行 MCP 工具 -> 结果回填 -> 模型继续

九、WASM 中间件（wasm/）

请求/响应处理链中插入自定义 WASM 模块：

• 热加载：动态注册/移除 WASM 模块，不重启 SMG
• wasm/route.rs：WASM 模块的注册和路由 API
• 适合自定义预处理、后处理、内容过滤

十、Mesh 集群管理（routers/mesh/）

多 SMG 实例通过 CRDT 同步状态：

• 全局限流：跨实例令牌桶
• Worker 状态共享：各实例知道彼此的健康 Worker
• 策略状态同步：cache_aware 树在实例间同步
• 优雅关停：trigger_graceful_shutdown协调关停顺序

十一、K8s 服务发现（service_discovery.rs）

自动发现 K8s Pod 作为 Worker：

• 通过kubecrate 连接 K8s API
• Label selector 过滤
• Pod 上线自动注册 Worker，下线自动摘除

十二、Worker 生命周期管理

12.1 Worker Trait 多态

pubtraitWorker:Send+Sync{fnurl(&self)->&str;fnworker_type(&self)->WorkerType;// Regular | Prefill | Decodefnis_healthy(&self)->bool;// AtomicBoolfnis_dp_aware(&self)->bool;fncircuit_breaker(&self)->&CircuitBreaker;}

12.2 WorkerRegistry

DashMap<String, Arc<dyn Worker>>，key 为 URL，无锁并发读写。

12.3 步骤化工作流（core/steps/）

Worker 注册/更新/移除走步骤化编排：

DiscoverMetadata -> DiscoverDP -> CreateWorker -> Register -> Activate

每步可独立重试、可独立失败处理。

12.4 WorkerRoutingKeyLoad

维护每个 Worker 的活跃路由 key 计数，用DashMap<String, usize>做增量/减量操作，实时反映负载。

十三、DP-Aware 路由

13.1 含义

后端 SGLang 实例开了--enable-dp-attention，一个 URL 背后有多个内部 DP rank。

13.2 工作机制

1. SMG 调用 /server_info，获取 dp_size 2. 创建 dp_size 个虚拟 Worker：url@0, url@1, ..., url@(dp_size-1) 3. 路由时从 URL 提取 dp_rank，注入到请求 JSON 的 data_parallel_rank 字段 4. 发请求时用 base URL（去掉 @N 后缀）

13.3 PD 分离中的 DP-Aware

prefill 和 decode 必须在同一 DP replica 上，通过data_parallel_rank绑定。

十四、对话历史与持久化

routers/conversations/+ 多种后端：

• In-Memory：默认，重启丢失
• Disabled：不存历史
• PostgreSQL：连接池 + 凭据支持
• Oracle ATP：企业级持久化

十五、其他 Router

Tokenize Router（routers/tokenize/）

POST /v1/tokenize -> 文本 -> tokens POST /v1/detokenize -> tokens -> 文本 支持批量，支持动态注册 tokenizer

Parse Router（routers/parse/）

POST /parse/reasoning -> 分离 reasoning content POST /parse/function_call -> 提取 function call

OpenAI Router（routers/openai/）

转发到 OpenAI、xAI、Gemini 等外部厂商，保持流式 SSE 语义。

Responses API（routers/openai/responses/）

OpenAI 兼容的/v1/responses端点，支持流式/非流式、MCP 工具调用、后台执行。