SGLang 模型网关（前身为 SGLang 路由器）

SGLang 模型网关（前身为 SGLang 路由器）#

SGLang 模型网关是一个用于大规模 LLM 部署的高性能模型路由网关。它集中管理工作器生命周期，通过异构协议（HTTP、gRPC、OpenAI 兼容）平衡流量，并为历史存储、MCP 工具和隐私敏感工作流程提供企业级控制。该路由器针对 SGLang 运行时进行了深度优化，但也可以路由到任何 OpenAI 兼容的后端。

目录#

  1. 概述

  2. 架构

    • 控制平面

    • 数据平面

    • 存储与隐私

  3. 部署模式

    • 同时启动路由器和工作器

    • 独立启动（HTTP）

    • gRPC 启动

    • Prefill/Decode 解耦

    • OpenAI 后端代理

  4. 工作器生命周期与动态扩展

  5. 可靠性与流量控制

  6. 负载均衡策略

  7. 服务发现（Kubernetes）

  8. 安全与认证

  9. 历史与数据连接器

  10. MCP 与高级工具

  11. API 接口

  12. 配置参考

  13. 可观测性

  14. 故障排除

概述#

  • 统一控制平面：用于在异构模型集群中注册、监控和编排常规、prefill 和 decode 工作器。

  • 多协议数据平面：通过 HTTP、PD（prefill/decode）、gRPC 和 OpenAI 兼容后端路由流量，共享可靠性基础组件。

  • 业界首个 gRPC 管线：具有原生 Rust 分词、推理解析器和工具调用执行功能，支持高吞吐量的 OpenAI 兼容服务；支持单阶段和 PD 拓扑结构。

  • 推理网关模式（--enable-igw）：动态实例化多个路由器堆栈（HTTP 常规/PD、gRPC），并为多租户部署应用按模型策略。

  • 对话与响应连接器：在路由器内部集中聊天历史记录，因此相同的上下文可在不同模型和 MCP 循环间重用，而不会将数据泄露给上游供应商（内存、无、Oracle ATP）。

  • 企业级隐私：多轮智能体 /v1/responses、原生 MCP 客户端（STDIO/HTTP/SSE/Streamable）和历史存储都在路由器边界内运行。

  • 可靠性核心：带有抖动的重试、工作器范围的熔断器、带排队的令牌桶限流、后台健康检查和缓存感知的负载监控。

  • 可观测性：Prometheus 指标、结构化跟踪、请求 ID 传播和详细作业队列统计。

架构#

控制平面#

  • 工作器管理器：发现功能（/get_server_info、/get_model_info），跟踪负载，并在共享注册表中注册/移除工作器。

  • 作业队列：序列化添加/移除请求并暴露状态（/workers/{url}），以便客户端可以跟踪上进度。

  • 负载监控器：使用实时工作器负载统计为缓存感知和 2 的幂次方策略提供数据。

  • 健康检查器：持续探测工作器并更新就绪状态、熔断器状态和路由器指标。

数据平面#

  • HTTP 路由器（常规和 PD）：实现 /generate、/v1/chat/completions、/v1/completions、/v1/responses、/v1/embeddings、/v1/rerank 及相关管理端点。

  • gRPC 路由器：将标记化的请求直接流式传输到 SRT gRPC 工作器，完全在 Rust 中运行—分词器、推理解析器和工具解析器都驻留在进程中。支持单阶段和 PD 路由。

  • OpenAI 路由器：将 OpenAI 兼容端点代理到外部供应商（OpenAI、xAI 等），同时保持聊天历史和多轮编排在本地。

存储与隐私#

  • 对话和响应历史记录存储在路由器层（内存、无或 Oracle ATP）。相同的历史记录可以为多个模型或 MCP 循环提供支持，而无需将数据发送到上游供应商。

  • /v1/responses 智能体流程、MCP 会话和对话 API 共享相同的存储层，使受监管工作负载能够合规。

部署模式#

同时启动路由器和工作器#

在一个进程中启动路由器和一组 SGLang 工作器（适用于单节点或快速入门）。CLI 接受两组参数：

  • 工作器参数（无前缀）配置 SGLang 运行时（--model、--tp-size、--dp-size、--grpc-mode 等）。

  • 路由器参数以 --router- 为前缀，直接映射到 launch_router 标志（--router-policy、--router-model-path、--router-log-level 等）。

python -m sglang_router.launch_server \
  --model meta-llama/Meta-Llama-3.1-8B-Instruct \
  --dp-size 4 \
  --host 0.0.0.0 \
  --port 30000

完整示例：

python3 -m sglang_router.launch_server \
  --host 0.0.0.0 \
  --port 8080 \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --tp-size 1 \
  --dp-size 8 \
  --grpc-mode \
  --log-level debug \
  --router-prometheus-port 10001 \
  --router-tool-call-parser llama \
  --router-health-success-threshold 2 \
  --router-health-check-timeout-secs 6000 \
  --router-health-check-interval-secs 60 \
  --router-model-path meta-llama/Llama-3.1-8B-Instruct \
  --router-policy round_robin \
  --router-log-level debug

独立启动（HTTP）#

独立运行工作器并将路由器指向它们的 HTTP 端点。

# 工作器节点
python -m sglang.launch_server --model meta-llama/Meta-Llama-3.1-8B-Instruct --port 8000
python -m sglang.launch_server --model meta-llama/Meta-Llama-3.1-8B-Instruct --port 8001

# 路由器节点
python -m sglang_router.launch_router \
  --worker-urls http://worker1:8000 http://worker2:8001 \
  --policy cache_aware \
  --host 0.0.0.0 --port 30000

gRPC 启动#

使用 SRT gRPC 工作器解锁最高吞吐量并访问原生推理/工具管线。

# 工作器暴露 gRPC 端点
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --grpc-mode \
  --port 20000

# 路由器
python -m sglang_router.launch_router \
  --worker-urls grpc://127.0.0.1:20000 \
  --model-path meta-llama/Llama-3.1-8B-Instruct \
  --reasoning-parser deepseek-r1 \
  --tool-call-parser json \
  --host 0.0.0.0 --port 8080

gRPC 路由器支持单阶段和 PD 服务。提供 --tokenizer-path 或 --model-path（HF 仓库或本地目录），以及可选的 --chat-template。

Prefill/Decode 解耦#

拆分 prefill 和 decode 工作器以实现 PD 感知的缓存和均衡。

python -m sglang_router.launch_router \
  --pd-disaggregation \
  --prefill http://prefill1:30001 9001 \
  --decode http://decode1:30011 \
  --policy cache_aware \
  --prefill-policy cache_aware \
  --decode-policy power_of_two

OpenAI 后端代理#

代理 OpenAI 兼容端点（OpenAI、xAI 等），同时保持历史记录和 MCP 会话在本地。

python -m sglang_router.launch_router \
  --backend openai \
  --worker-urls https://api.openai.com \
  --history-backend memory

OpenAI 后端模式期望每个路由器实例只有一个 --worker-urls 条目。

工作器生命周期与动态扩展#

使用 REST API 在运行时添加或移除工作器。作业被排队并跟踪，以确保最终一致性。

# 添加工作器（HTTP 或 gRPC）
curl -X POST http://localhost:30000/workers \
  -H "Content-Type: application/json" \
  -d '{"url":"grpc://0.0.0.0:31000","worker_type":"regular"}'

# 检查注册表
curl http://localhost:30000/workers

# 移除工作器
curl -X DELETE http://localhost:30000/workers/grpc://0.0.0.0:31000

传统端点（/add_worker、/remove_worker、/list_workers）仍然可用，但将被弃用。/workers/{url} 返回注册表数据和排队作业状态。

可靠性与流量控制#

重试#

python -m sglang_router.launch_router \
  --worker-urls http://worker1:8000 http://worker2:8001 \
  --retry-max-retries 5 \
  --retry-initial-backoff-ms 50 \
  --retry-max-backoff-ms 30000 \
  --retry-backoff-multiplier 1.5 \
  --retry-jitter-factor 0.2

熔断器#

python -m sglang_router.launch_router \
  --worker-urls http://worker1:8000 http://worker2:8001 \
  --cb-failure-threshold 5 \
  --cb-success-threshold 2 \
  --cb-timeout-duration-secs 30 \
  --cb-window-duration-secs 60

限流与排队#

python -m sglang_router.launch_router \
  --worker-urls http://worker1:8000 http://worker2:8001 \
  --max-concurrent-requests 256 \
  --rate-limit-tokens-per-second 512 \
  --queue-size 128 \
  --queue-timeout-secs 30

超出并发限制的请求将在 FIFO 队列中等待（最多 queue-size 个）。队列满时返回 429；queue-timeout-secs 过期时返回 408。

负载均衡策略#

策略

描述

使用方式

random

均匀随机选择。

--policy random

round_robin

按顺序循环通过工作器。

--policy round_robin

power_of_two

采样两个工作器并选择负载较轻的一个（需要负载监控器）。

--policy power_of_two

cache_aware

默认策略；结合缓存位置和负载均衡，回退到最短队列。

--policy cache_aware + 调优标志

关键调优标志：

--cache-threshold 0.5 \
--balance-abs-threshold 32 \
--balance-rel-threshold 1.5 \
--eviction-interval-secs 120 \
--max-tree-size 67108864

服务发现（Kubernetes）#

通过 Kubernetes Pod 选择器启用自动工作器发现。

python -m sglang_router.launch_router \
  --service-discovery \
  --selector app=sglang-worker role=inference \
  --service-discovery-namespace production \
  --service-discovery-port 8000

PD 部署可以指定 --prefill-selector 和 --decode-selector，以及 sglang.ai/bootstrap-port 注释用于 prefill 引导端口。确保 RBAC 授予 Pod 的 get/list/watch 权限。

安全与认证#

  • 路由器 API 密钥（--api-key）：客户端必须提供 Authorization: Bearer <key>。

  • 工作器 API 密钥：动态添加工作器时，在负载中包含 api_key；通过 CLI 列出工作器会继承路由器密钥。

  • 全栈认证：使用 --api-key 启动路由器，然后添加带有自己密钥的工作器：

    curl -H "Authorization: Bearer router-key" \
  -X POST http://localhost:30000/workers \
  -H "Content-Type: application/json" \
  -d '{"url":"http://worker:8000","api_key":"worker-key"}'

  • 隐私：所有对话历史记录、/v1/responses 状态和 MCP 会话都保持在路由器内部。除非明确代理，否则不会在任何远程模型供应商上持久化数据。

历史与数据连接器#

后端

描述

使用方式

memory（默认）

快速原型的内存存储。

--history-backend memory

none

无持久化；API 运行但不存储任何内容。

--history-backend none

oracle

Oracle 自主数据库支持的存储（池连接）。

--history-backend oracle

Oracle 配置（选择 DSN 或 TNS 别名）： 安装 Oracle Instant Client 并相应地设置 LD_LIBRARY_PATH。 选择一种连接方法：

# 选项 1：完整连接描述符
export ATP_DSN="(description=(address=(protocol=tcps)(port=1522)(host=adb.region.oraclecloud.com))(connect_data=(service_name=service_name)))"

# 选项 2：TNS 别名（需要钱包）
export ATP_TNS_ALIAS="sglroutertestatp_high"
export ATP_WALLET_PATH="/path/to/wallet"

提供数据库凭据和可选的池大小：

export ATP_USER="admin"
export ATP_PASSWORD="secret"
export ATP_POOL_MIN=4
export ATP_POOL_MAX=32

python -m sglang_router.launch_router \
  --backend openai \
  --worker-urls https://api.openai.com \
  --history-backend oracle

历史后端当前仅适用于 OpenAI 路由器模式。/v1/responses 的 gRPC 支持已在路线图上。

MCP 与高级工具#

  • 原生 MCP 客户端支持 STDIO、HTTP、SSE 和 Streamable 传输—无需外部配置文件。

  • 工具调用解析器涵盖 JSON、Pythonic、XML 和自定义模式，支持流式和非流式执行循环。

  • 推理解析器支持 DeepSeek-R1、Qwen3、Step-3、GLM4、Llama 系列、Kimi K2、GPT-OSS、Mistral 等更多（src/reasoning_parser）。

  • 分词器工厂接受 HuggingFace ID、本地目录和带有聊天模板覆盖的显式 tokenizer.json 文件（src/tokenizer）。

使用 CLI 标志选择解析器：

--reasoning-parser deepseek-r1 \
--tool-call-parser json \
--chat-template /path/to/template.json

API 接口#

方法

路径

描述

POST

/generate

SGLang 生成 API。

POST

/v1/chat/completions

OpenAI 兼容聊天（流式传输/工具调用）。

POST

/v1/completions

OpenAI 兼容文本补全。

POST

/v1/responses

创建后台响应（智能体循环）。

GET

/v1/responses/{id}

检索存储的响应。

POST

/v1/embeddings

转发嵌入请求。

POST

/v1/rerank

排序端点（/rerank 同义词）。

POST

/v1/conversations

创建对话元数据。

GET/POST/DELETE

/v1/conversations/{id}

获取/更新/删除对话。

GET/POST

/v1/conversations/{id}/items

列出或追加对话项。

GET/DELETE

/v1/conversations/{id}/items/{item_id}

检查/删除对话项。

GET

/workers

列出已注册的工作器及其健康状态/负载。

POST

/workers

排队工作器注册。

DELETE

/workers/{url}

排队工作器移除。

POST

/flush_cache

刷新工作器缓存（HTTP 工作器）。

GET

/get_loads

检索工作器负载快照。

GET

/liveness / /readiness / /health

健康探测。

配置参考#

核心设置#

参数

类型

默认值

描述

--host

str

127.0.0.1

路由器主机。

--port

int

30000

路由器端口。

--worker-urls

list

[]

工作器 URL（HTTP 或 gRPC）。

--policy

str

cache_aware

路由策略（random、round_robin、cache_aware、power_of_two）。

--max-concurrent-requests

int

-1

并发限制（-1 禁用限流）。

--request-timeout-secs

int

600

请求超时。

--max-payload-size

int

256MB

最大请求负载。

缓存感知调优#

参数

类型

默认值

描述

--cache-threshold

float

0.3

最小前缀匹配比例。

--balance-abs-threshold

int

64

绝对负载阈值。

--balance-rel-threshold

float

1.5

相对负载比率。

--eviction-interval-secs

int

120

缓存回收节奏。

--max-tree-size

int

67108864

缓存树中的最大节点数。

容错#

参数

类型

默认值

描述

--retry-max-retries

int

5

最大重试次数。

--retry-initial-backoff-ms

int

50

初始退避（毫秒）。

--retry-max-backoff-ms

int

30000

最大退避（毫秒）。

--retry-backoff-multiplier

float

1.5

退避乘数。

--retry-jitter-factor

float

0.2

重试抖动（0.0-1.0）。

--disable-retries

flag

False

禁用重试。

--cb-failure-threshold

int

5

打开熔断前的故障次数。

--cb-success-threshold

int

2

关闭熔断所需的成功次数。

--cb-timeout-duration-secs

int

30

冷却期。

--cb-window-duration-secs

int

60

窗口大小。

--disable-circuit-breaker

flag

False

禁用熔断器。

Prefill/Decode#

参数

类型

默认值

描述

--pd-disaggregation

flag

False

启用 PD 模式。

--prefill

list

[]

Prefill URL + 可选引导端口。

--decode

list

[]

Decode URL。

--prefill-policy

str

None

覆盖 prefill 节点的策略。

--decode-policy

str

None

覆盖 decode 节点的策略。

--worker-startup-timeout-secs

int

600

工作器初始化超时。

--worker-startup-check-interval

int

30

轮询间隔。

Kubernetes 发现#

参数

类型

描述

--service-discovery

flag

启用发现。

--selector key=value ...

list

标签选择器（常规模式）。

--prefill-selector / --decode-selector

list

PD 模式的标签选择器。

--service-discovery-namespace

str

要监视的命名空间。

--service-discovery-port

int

工作器端口（默认 80）。

--bootstrap-port-annotation

str

Prefill 引导注释（默认 sglang.ai/bootstrap-port）。

可观测性#

启用 Prometheus 指标：

python -m sglang_router.launch_router \
  --worker-urls http://worker1:8000 http://worker2:8001 \
  --prometheus-host 0.0.0.0 \
  --prometheus-port 29000

关键指标：

指标

类型

描述

sgl_router_requests_total

Counter

按端点/方法的总请求数。

sgl_router_processed_requests_total

Counter

每个工作器处理的请求数。

sgl_router_active_workers

Gauge

健康工作器数量。

sgl_router_running_requests

Gauge

每个工作器的进行中请求数。

sgl_router_cache_hits_total / misses_total

Counter

缓存感知路由命中/未命中。

sgl_router_generate_duration_seconds

Histogram

请求延迟分布。

启用请求 ID 传播：

python -m sglang_router.launch_router \
  --worker-urls http://worker1:8000 \
  --request-id-headers x-request-id x-trace-id

故障排除#

  1. 工作器从不就绪 增加 --worker-startup-timeout-secs 或确保健康探测在路由器启动前响应。

  2. 负载不均衡/热工作器 检查 sgl_router_processed_requests_total 并调整缓存感知阈值（--balance-*、--cache-threshold）。

  3. 熔断器反复跳动 增加 --cb-failure-threshold 或扩展超时/窗口持续时间。考虑临时禁用重试。

  4. 队列溢出（429） 增加 --queue-size 或减少客户端并发。确保 --max-concurrent-requests 与下游容量匹配。

  5. 内存增长 减少 --max-tree-size 或降低 --eviction-interval-secs 以实现更积极的缓存修剪。

  6. 调试

    python -m sglang_router.launch_router \
  --worker-urls http://worker1:8000 \
  --log-level debug \
  --log-dir ./router_logs

SGLang 模型网关随着 SGLang 运行时不断演进。采用新功能或贡献改进时，请保持 CLI 标志、集成和文档的一致。

目录