SGLang 服务器参数配置

本文系统整理 SGLang 服务端 sglang.launch_server 的核心启动参数，覆盖模型加载、并行策略、内存管理、请求调度、量化、调试与监控等方面。

1. 基础配置

1.1 模型与路径

--model-path /mnt/models/DeepSeek-R1    # 模型文件路径
--tokenizer-path /mnt/models/tokenizer  # 分词器路径
--load-format gguf                      # 模型加载格式：gguf / pytorch / safetensors

• 路径需具备可读权限。
• 模型与分词器版本需严格匹配，避免初始化失败。

1.2 设备与并行策略

--device cuda    # 计算设备：cuda / cpu
--tp 4           # 张量并行度（Tensor Parallelism）
--dp-size 2      # 数据并行度（Data Parallelism）
--ep-size 1      # 专家并行度（MoE 模型专用）

配置建议：

• 8 卡服务器推荐 --tp 4 --dp-size 2。
• 显存不足时优先降低 --tp。

2. 性能参数

2.1 内存与显存管理

--mem-fraction-static 0.85   # 静态显存分配比例
--kv-cache-dtype auto        # KV Cache 数据类型：fp16 / bf16 / auto
--max-total-tokens 128000    # 最大上下文总 Token 数

显存不足时的调整优先级：

1. 降低 --max-total-tokens 至 102400 或更小。
2. 启用量化，如 --quantization fp8。
3. 降低 --mem-fraction-static 至 0.8。

2.2 请求处理控制

--max-running-requests 16    # 并发请求上限
--max-prefill-tokens 8192    # 单次 Prefill 最大 Token 数
--chunked-prefill-size 2048  # 分块 Prefill 大小

高并发场景建议：

• 增加 --max-running-requests 至 32，同时监控 GPU 利用率（目标 70%–90%）。

2.3 调度与负载均衡

--schedule-policy lpm                   # 调度策略：lpm / fcfs
--load-balance-method round-robin       # 负载均衡方式
--dist-init-addr 192.168.1.100:29500    # 多节点通信地址

多机部署要求：

• 网络延迟 < 1 ms。
• 防火墙开放 29500 端口。
• 使用 --nnodes 3 --node-rank 0 指定节点角色。

2.4 量化与推理加速

--quantization fp8                  # 启用 FP8 量化
--attention-backend flashinfer      # 注意力计算后端
--triton-attention-num-kv-splits 4  # Triton 注意力 KV 分割数

量化对显存与精度的影响（经验值）：

精度	显存占用	精度损失
FP32	100%	无
FP8	~45%	< 2%

3. 调试与监控

3.1 日志与指标

--log-level info            # 日志级别
--enable-metrics true       # 启用 Prometheus 指标
--metrics-port 8008         # 指标暴露端口

关键监控指标：

• sglang_requests_total：请求总数
• sglang_gpu_utilization：GPU 利用率
• sglang_kv_cache_usage：KV Cache 使用率

3.2 调试工具

--debug-tensor-dump-output-folder /tmp/debug   # 张量转储目录
--enable-nan-detection true                     # 检测 NaN
--warmups 3                                     # 预热请求数

故障排查流程：

1. 启用 --log-level debug。
2. 检查张量转储文件。
3. 验证输入数据有效性。

4. 完整配置示例

python3 -m sglang.launch_server \
  --model-path /mnt/models/DeepSeek-R1 \
  --host 0.0.0.0 \
  --port 4000 \
  --device cuda \
  --tp 4 \
  --dp-size 2 \
  --mem-fraction-static 0.8 \
  --max-running-requests 32 \
  --quantization fp8 \
  --attention-backend flashinfer \
  --enable-metrics true \
  --log-level info

5. 常见问题

5.1 OOM 处理

错误类型	解决方案
显存溢出	降低 --mem-fraction-static 至 0.75
内存不足	减少 --max-total-tokens 至 96000
KV Cache 满	增加 --kv-cache-size 参数

5.2 多节点同步失败

1. 检查 --dist-init-addr 网络可达性。
2. 验证防火墙规则：

   sudo ufw allow 29500

3. 使用 --nnodes 与 --node-rank 明确节点角色。