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`）

rust 复制代码

// 每个模型可以绑定独立策略
pub struct PolicyRegistry {
    // 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-tokenizer crate，不依赖 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`）

rust 复制代码

pub struct TokenBucket {
    inner: Arc<Mutex<TokenBucketInner>>,  // parking_lot::Mutex
    notify: 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 可配置独立路由策略：

bash 复制代码

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 每个模型独立配置

json 复制代码

{
  "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+ 指标，分类：

类别	指标
HTTP	`http_requests_total`, `http_request_duration_seconds`
Router	`router_requests_total`, `router_selections_total`
Worker	`worker_requests_active`, `worker_is_healthy`
Circuit Breaker	`circuit_breaker_state`, `circuit_breaker_failures_total`
Retry	`retry_attempts_total`, `retry_successes_total`
MCP	`mcp_tool_calls_total`, `mcp_tool_duration_seconds`

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：

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

十二、Worker 生命周期管理

12.1 Worker Trait 多态

rust 复制代码

pub trait Worker: Send + Sync {
    fn url(&self) -> &str;
    fn worker_type(&self) -> WorkerType;  // Regular | Prefill | Decode
    fn is_healthy(&self) -> bool;          // AtomicBool
    fn is_dp_aware(&self) -> bool;
    fn circuit_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 工具调用、后台执行。

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

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

1.1 Power of Two（policies/power_of_two.rs）

1.2 Round Robin（policies/round_robin.rs）

1.3 Random（policies/random.rs）

1.4 Bucket（policies/bucket.rs）

1.5 Consistent Hashing（policies/consistent_hashing.rs）

1.6 Prefix Hash（policies/prefix_hash.rs）

1.7 Manual（policies/manual.rs）

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

二、gRPC Router（routers/grpc/）

2.1 管道化架构

2.2 全 Rust Tokenizer

2.3 Rust Reasoning Parser + Tool Parser

2.4 Harmony Router

2.5 gRPC PD Router

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

3.1 断路器（core/circuit_breaker.rs）

3.2 令牌桶（core/token_bucket.rs）

3.3 重试（core/retry.rs）

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

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

4.1 请求生命周期

4.2 DP-Aware 绑定

4.3 双策略

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

5.1 核心概念

5.2 每个模型独立配置

5.3 统一 API 入口

六、可观测性（observability/）

6.1 Prometheus 指标

6.2 字符串 Interning 优化

6.3 OpenTelemetry

七、认证与安全

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

九、WASM 中间件（wasm/）

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

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

十二、Worker 生命周期管理

12.1 Worker Trait 多态

12.2 WorkerRegistry

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

12.4 WorkerRoutingKeyLoad

十三、DP-Aware 路由

13.1 含义

13.2 工作机制

13.3 PD 分离中的 DP-Aware

十四、对话历史与持久化

十五、其他 Router

Tokenize Router（routers/tokenize/）

Parse Router（routers/parse/）

OpenAI Router（routers/openai/）

Responses API（routers/openai/responses/）

1.1 Power of Two（`policies/power_of_two.rs`）

1.2 Round Robin（`policies/round_robin.rs`）

1.3 Random（`policies/random.rs`）

1.4 Bucket（`policies/bucket.rs`）

1.5 Consistent Hashing（`policies/consistent_hashing.rs`）

1.6 Prefix Hash（`policies/prefix_hash.rs`）

1.7 Manual（`policies/manual.rs`）

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

二、gRPC Router（`routers/grpc/`）

3.1 断路器（`core/circuit_breaker.rs`）

3.2 令牌桶（`core/token_bucket.rs`）

3.3 重试（`core/retry.rs`）

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

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

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

六、可观测性（`observability/`）

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

九、WASM 中间件（`wasm/`）

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

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

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

Tokenize Router（`routers/tokenize/`）

Parse Router（`routers/parse/`）

OpenAI Router（`routers/openai/`）

Responses API（`routers/openai/responses/`）