SGLang Model Gateway 怎么在多 worker 部署中配置负载均衡与路由策略【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang当你用 SGLang 启动了多个 worker 进程多卡、多机或数据并行副本之后客户端需要知道每个 worker 的地址、自行处理失败和重试。SGLang Model Gateway 就是为这个场景设计的入口层它把多个 HTTP 或 gRPC worker 汇聚成一个 OpenAI 兼容的单一端点通过--policy指定的负载均衡策略分发请求并提供 worker 注册、健康检查、重试、熔断和排队等流量控制能力。本文覆盖多 worker 部署的完整操作路径启动 worker、启动网关、选择与调优路由策略最后用管理 API 和 Prometheus 指标验证结果。准备条件需要两类组件SGLang worker每个节点用 SGLang 运行时启动一个独立 server以文档中的示例为例meta-llama/Meta-Llama-3.1-8B-Instruct为文档示例模型替换为你实际部署的模型# Worker 18000 端口 python -m sglang.launch_server --model meta-llama/Meta-Llama-3.1-8B-Instruct --port 8000 # Worker 28001 端口 python -m sglang.launch_server --model meta-llama/Meta-Llama-3.1-8B-Instruct --port 8001网关本体。文档给出三种安装方式按环境任选其一# 方式一Python 包后文的 python -m sglang_router.launch_router 命令都依赖它 pip install sglang-router # 方式二Docker 镜像x86_64 与 ARM64 均支持 docker pull lmsysorg/sgl-model-gateway:latest # 方式三Rust 源码构建 cd sgl-model-gateway cargo build --release用pip install sglang-router或 Rust 二进制均可后续命令分别用python -m sglang_router.launch_router与./target/release/sgl-model-gateway启动参数相同。启动多 worker 路由主路径worker 就绪后在网关节点上把它们的地址通过--worker-urls传给 router。下面的命令沿用文档示例的worker1/worker2主机名实际操作时替换为你 worker 的真实 IP 或主机名python -m sglang_router.launch_router \ --worker-urls http://worker1:8000 http://worker2:8001 \ --policy cache_aware \ --host 0.0.0.0 --port 30000两个容易踩的坑--host默认是127.0.0.1--port默认是30000。要让外部客户端访问网关必须显式传--host 0.0.0.0。--worker-urls接收 HTTP 或 gRPC 地址列表后续通过POST /workers动态注册的 worker 不会自动继承 router 的 API key需要在请求体中显式提供。选择路由策略五种 policy 及适用场景--policy决定请求落到哪个 worker。文档列出的策略如下Policy行为启动参数random均匀随机选择--policy randomround_robin按顺序循环轮转--policy round_robinpower_of_two随机抽两个 worker选负载更轻的一个--policy power_of_twocache_aware结合前缀缓存命中与负载均衡默认--policy cache_awarebucket按动态边界把 worker 分成负载桶--policy bucket对重复 prompt 较多的场景多轮对话、共享 system prompt文档在生产建议中明确推荐cache_aware并称其可带来约 30% 的延迟下降文档原文给出的建议值非通用承诺它通过维护 prompt 前缀树把重复流量路由到已有缓存的 worker同时用负载阈值防止倾斜。cache_aware 策略的调优参数当缓存命中与负载均衡需要权衡时可调整以下参数默认值来自文档配置表--cache-threshold 0.5 \ --balance-abs-threshold 32 \ --balance-rel-threshold 1.5 \ --eviction-interval-secs 120 \ --max-tree-size 67108864参数默认值含义--cache-threshold0.3缓存命中的最小前缀匹配比例--balance-abs-threshold64触发再平衡的绝对负载差--balance-rel-threshold1.5触发再平衡的相对负载比--eviction-interval-secs120缓存树淘汰周期秒--max-tree-size67108864缓存树最大节点数注意一处文档差异sgl-model-gateway/README.md 的 Load Balancing Policies 一节把淘汰周期参数写作--eviction-interval而 文档页 的 Cache-Aware Policy Tuning 一节写作--eviction-interval-secs两者含义相同以实际 CLI--help输出为准。流量控制与故障容错路由策略之外这几个参数决定请求在多 worker 间如何排队、重试和隔离故障属于多 worker 部署的常规配置python -m sglang_router.launch_router \ --worker-urls http://worker1:8000 http://worker2:8001 \ --max-concurrent-requests 256 \ --queue-size 128 \ --queue-timeout-secs 30--max-concurrent-requests并发上限默认-1不限制。超出上限的请求进入 FIFO 队列队列满返回429 Too Many Requests队列等待超过--queue-timeout-secs返回408 Request Timeout。文档的调优建议是取 worker 数量的 2–4 倍--queue-size取 max-concurrent 的 2 倍用于缓冲突发流量。重试对 408/429/500/502/503/504 自动指数退避重试默认最多 5 次--retry-max-retries、--retry-initial-backoff-ms、--retry-max-backoff-ms、--retry-backoff-multiplier、--retry-jitter-factor可用--disable-retries关闭。熔断每个 worker 独立的 circuit breaker连续失败达到--cb-failure-threshold默认 5后打开电路、请求直接拒绝--cb-timeout-duration-secs默认 30后进入半开探测。可用--disable-circuit-breaker关闭。健康检查后台周期性探测 worker参数为--health-check-interval-secs 30、--health-check-timeout-secs 10、--health-success-threshold 2、--health-failure-threshold 3、--health-check-endpoint /health。可选分支其他多 worker 拓扑以下分支对应不同的部署形态按需取用不与上面的常规 HTTP 链混用。gRPC 模式高吞吐worker 用--grpc-mode启动、暴露 gRPC 端点router 需要额外提供 tokenizer 来源--model-path或--tokenizer-path# Worker python -m sglang.launch_server \ --model meta-llama/Llama-3.1-8B-Instruct \ --grpc-mode \ --port 20000 # Router 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 8080gRPC 路由在网关进程内完成 tokenization、reasoning 解析和 tool call 解析文档将其定位为 SGLang worker 的高性能路径。连接模式解析为 gRPC 时--model-path/--tokenizer-path是必选项。Prefill-Decode 分离PD 模式prefill 与 decode 拆成两组 worker 时两类节点可以各自指定路由策略python -m sglang_router.launch_router \ --pd-disaggregation \ --prefill http://prefill1:30001 9001 \ --decode http://decode1:30011 \ --prefill-policy cache_aware \ --decode-policy power_of_two--prefill条目可跟一个可选的 bootstrap 端口示例中的9001--prefill与--decode均可重复传入多个地址。PD 模式会把 prefill 元数据与 decode 输出合并后流式返回给客户端。多模型 IGW 模式与动态注册一个网关实例路由多个模型时用--enable-igwworker 通过管理 API 动态注册并可带model_id、priority和 per-model 策略标签./target/release/sgl-model-gateway \ --enable-igw \ --policy cache_aware \ --max-concurrent-requests 512 # 动态注册 worker返回 202 Accepted后台任务队列处理注册 curl -X POST http://localhost:30000/workers \ -H Content-Type: application/json \ -d { url: http://worker-a:8000, model_id: mistral, priority: 10, labels: {tier: gold} }Kubernetes 服务发现worker 以 Pod 形式部署时可让网关按 label 自动发现和增删 worker省去手工维护--worker-urlspython -m sglang_router.launch_router \ --service-discovery \ --selector appsglang-worker componentinference \ --service-discovery-namespace production \ --service-discovery-port 8000前提worker Pod 按上述 label 标注网关所在 ServiceAccount 的 RBAC 允许对 pods 执行get、list、watch文档给出了 Role/RoleBinding 示例。PD 模式则改用--prefill-selector与--decode-selectorprefill Pod 可经sglang.ai/bootstrap-portannotation 暴露 bootstrap 端口。单机 co-launch小规模验证只想在一台机器上验证整套链路时launch_server可以在单进程内同时拉起 router 和一组数据并行 workerpython -m sglang_router.launch_server \ --model meta-llama/Meta-Llama-3.1-8B-Instruct \ --dp-size 4 \ --host 0.0.0.0 \ --port 30000--dp-size 4即 4 个 DP workerrouter 会按 DP size 自动配置 worker URLrouter 专属参数加--router-前缀传入如--router-policy round_robin。验证部署结果启动后用网关的管理端点逐项确认端口以--port实际值为准默认 30000# 存活检查总是返回 OK curl http://localhost:30000/liveness # 就绪检查确认有健康 worker 可用 curl http://localhost:30000/readiness # 列出 worker健康状态、当前负载、连接模式 curl http://localhost:30000/workers # 采样各 worker 当前负载 curl http://localhost:30000/get_loads # 触发一次真实的生成式健康探测 curl http://localhost:30000/health_generate/workers的文档示例响应数值仅为示例实际以你的部署为准{ workers: [ { id: 2f3a0c3e-3a7b-4c3f-8c70-1b7d4c3a6e1f, url: http://0.0.0.0:31378, model_id: mistral, priority: 50, cost: 1.0, worker_type: regular, is_healthy: true, load: 0, connection_mode: Http } ], total: 1, stats: { prefill_count: 0, decode_count: 0, regular_count: 1 } }is_healthy: true且total等于预期 worker 数说明注册与健康探测都通过。动态注册的 worker 在任务队列中处理时可用GET /workers/{worker_id}跟踪pending/processing/failed状态。持续观测方面网关的 Prometheus 端点默认在0.0.0.0:29000/metrics可用--prometheus-host/--prometheus-port修改。验证负载均衡是否生效最直接的方式是按 worker 查看请求分布smg_router_requests_total长期倾斜的 worker 就是需要调参的信号其他常用指标包括smg_worker_pool_size健康 worker 数、smg_worker_connections_active、smg_worker_cb_state熔断状态0closed1open2half-open。常见问题的处理路径以下条目来自文档 Troubleshooting 一节只列与多 worker 路由直接相关的项目worker 一直不就绪调大--worker-startup-timeout-secs默认 600或确保 worker 的健康探测在 router 启动前已可响应。负载不均 / 出现热点 worker按 worker 检查smg_router_requests_total然后调整 cache-aware 阈值--balance-abs-threshold、--balance-rel-threshold、--cache-threshold。队列溢出返回 429调大--queue-size或降低客户端并发并确认--max-concurrent-requests与下游 worker 的真实容量匹配。内存持续增长调小--max-tree-size或调低--eviction-interval-secs让缓存淘汰更激进。需要抓详细日志加--log-level debug --log-dir ./router_logs重启 router日志级别可选debug、info、warn、error。参考资料本文命令与参数取自仓库内的 SGLang Model Gateway 文档页部署模式、Load Balancing Policies、Reliability and Flow Control、Configuration Reference、Troubleshooting 各节与 sgl-model-gateway/README.mdQuick Start、Control Plane、Load Balancing Policies、Prometheus Metrics 各节。两者对个别参数命名存在出入时如--eviction-intervalvs--eviction-interval-secs已在上文标注更多端点细节可继续在上述两个文件中查阅。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考