SGLang启动参数详解

SGLang 启动命令参数总结介绍

类别	参数名	描述 (功能)	默认值/选项示例	关键用途
模型与分词器	--model-path / --model	指定模型权重路径或 Hugging Face ID。	必填项，如 meta-llama/Llama-3-8B-Instruct	加载模型
	--tokenizer-path	指定分词器路径。	同 --model-path	加载分词器
	--load-format	模型权重加载格式。	auto (自动) / safetensors, pt, gguf 等	优化加载速度/兼容性
	--context-length	模型的最大上下文长度。	从模型配置中读取	限制最大序列长度
HTTP 服务器	--host	HTTP 服务器绑定的主机地址。	127.0.0.1	配置服务访问地址
	--port	HTTP 服务器的端口号。	30000	配置服务端口
	--api-key	设置服务的访问 API Key。	None	API 鉴权
显存与调度	--mem-fraction-static	用于静态分配（模型+KV Cache）的显存比例。	0.9	显存管理，解决 OOM (可调小至 0.7)
	--max-running-requests	允许同时运行的最大请求数。	None	控制并发度
	--chunked-prefill-size	Chunked Prefill 的块大小。	None	解决长 Prompt 的 OOM 问题
	--schedule-policy	请求调度策略。	fcfs (先来先服务)	优化请求处理顺序
并行与分布式	--tp-size / --tensor-parallel-size	张量并行 (TP) 的大小，即模型切分所用的 GPU 数量。	1	单节点多卡加速
	--dp-size / --data-parallel-size	数据并行 (DP) 的大小，即模型实例数量。	1	提高吞吐量
	--nnodes	多节点分布式集群中的节点总数。	1	多节点部署
	--dist-init-addr	分布式初始化地址 (host:port)。	None	多节点通信配置
量化与精度	--dtype	模型权重和激活的数据类型。	auto	精度设置 (float16, bfloat16 等)
	--quantization	指定量化方法。	None	显存优化 (awq, fp8, gptq 等)
	--kv-cache-dtype	KV Cache 的数据类型。	auto	进一步优化 KV Cache 显存 (fp8_e5m2)
运行时优化	--enable-torch-compile	启用 PyTorch Compiler 加速。	False	提高小模型或小批次的性能
	--random-seed	随机种子。	None	实现确定的推理结果
日志与监控	--log-requests	记录所有请求的详细元数据和输入/输出。	False	调试和请求分析
	--enable-metrics	开启 Prometheus 监控指标。	False	生产环境监控

---

下面是一个多卡启动的完整命令示例 ，并简要说明一个关键性能参数的高级用法。

1. 多卡启动的完整命令示例 (TP=2)

以下示例展示了如何在一台机器 上使用 2 张 GPU 运行 Llama-3-8B 模型，并进行了关键性能调优：

参数	示例值	目的/说明
--model-path	meta-llama/Meta-Llama-3-8B-Instruct	指定要加载的模型。
--tp 2	2	启用张量并行，将模型切分到 2 张 GPU 上。
--mem-fraction-static 0.8	0.8	限制模型权重和 KV Cache 占用的显存比例为 80%，预留 20% 给其他操作，避免 OOM。
--dtype bfloat16	bfloat16	权重和计算使用 bfloat16 精度，平衡性能和精度。
--log-requests	(启用 Flag)	开启请求日志记录，方便调试和跟踪。
--host 0.0.0.0	0.0.0.0	允许外部网络访问该服务。
--port 30000	30000	服务运行在 30000 端口。

启动命令：

python -m sglang.launch_server \
    --model-path meta-llama/Meta-Llama-3-8B-Instruct \
    --tp 2 \
    --mem-fraction-static 0.8 \
    --dtype bfloat16 \
    --log-requests \
    --host 0.0.0.0 \
    --port 30000

2. 关键性能参数的高级用法

参数名	高级用法/细节	调优目的
--chunked-prefill-size	设置一个较小的 Token 数 (如 4096)。	减少长 Prompt 带来的显存峰值。 当输入 Prompt (预填充) 长度超过此值时，SGLang 会将 Prompt 分块处理，每次处理一个 Chunk，从而大大降低预填充阶段的峰值显存占用，避免 OOM。
--kv-cache-dtype fp8_e5m2	使用 FP8 精度存储 KV Cache。	最大化 KV Cache 存储容量。 FP8 (e.g., E5M2) 相比 BF16/FP16 可以将 KV Cache 显存占用减少一半，从而在相同显存下容纳更多的并发请求或更长的总 Token 长度。注意： 需要特定硬件和 CUDA 版本支持。

使用 SGLang 官方 Docker 镜像部署时的启动命令和主要参数介绍：

使用官方镜像部署 SGLang 服务器的流程通常是：拉取镜像 → 运行容器并挂载模型 → 在容器内执行启动命令。

1. 官方镜像拉取 (Docker Pull)

SGLang 官方通常会提供基于 PyTorch 或 CUDA 的镜像。假设您使用的是支持 CUDA 的版本：

docker pull sglang/sglang:latest
# 或者指定一个具体的版本，例如 sglang/sglang:0.3.17-cuda12.1

2. SGLang 启动命令结构

在容器内部或使用 docker run 命令启动 SGLang 服务器的通用结构如下：

python -m sglang.launch_server [主要参数...]

3. Docker 运行命令和启动参数总结

以下是一个推荐的 Docker 启动命令示例，以及其中包含的 SGLang 核心参数介绍。

🚀 Docker 运行示例 (单卡)

docker run -d \
    --gpus all \
    --ipc=host \
    -p 30000:30000 \
    -v /your/local/models:/app/models \
    sglang/sglang:latest \
    python -m sglang.launch_server \
    --model-path /app/models/Llama-3-8B-Instruct \
    --host 0.0.0.0 \
    --port 30000 \
    --tp 1 \
    --dtype bfloat16 \
    --mem-fraction-static 0.9

⚙️ 启动参数介绍总结 (Server Arguments)

参数名	类型/示例	描述 (功能)	部署考量
--model-path	/app/models/Llama-3-8B	必填。 指定模型权重在容器内的路径。	确保此路径对应到 Docker 挂载的卷 (-v)。
--host	0.0.0.0	服务器监听的地址。	在 Docker 内部必须设置为 0.0.0.0 才能通过主机 IP 访问。
--port	30000	服务器监听的端口。	需与 Docker 端口映射 (-p) 保持一致。
--tp (或 --tensor-parallel-size)	1 / 2 / 4	张量并行大小，即用于运行模型的 GPU 数量。	单卡部署 设为 1；多卡加速 设为 GPU 总数，需确保 --gpus all。
--dtype	bfloat16 / float16	模型权重和计算精度。	bfloat16 是主流 LLM 推荐的，可兼顾精度和性能。
--mem-fraction-static	0.9 / 0.7	用于模型和 KV Cache 的显存比例。	调优核心参数：减少 OOM 时可调小 (如 0.7)；最大化吞吐量 时可调大 (如 0.95)。
--quantization	awq / fp8	模型量化方法。	用于部署量化模型，进一步减少显存占用。
--kv-cache-dtype	fp8_e5m2	KV Cache 的数据类型。	高级优化： 进一步将 KV Cache 显存减半，提高并发容量。
--api-key	my_secret_key	设置 API Key，保护 API 接口。	推荐在生产环境中启用。

---

⚠️ Docker 部署关键点

1. GPU 访问 : 必须在 docker run 中添加 --gpus all（或指定 GPU ID），以便容器能访问 NVIDIA GPU。
2. 共享内存 : 必须设置 --ipc=host 或 --shm-size，因为 SGLang (基于 vLLM) 需要大量的共享内存进行进程间通信。
3. 模型挂载 : 使用 -v /your/local/models:/app/models 将您主机上的模型目录映射到容器内的目录 (/app/models)，然后 --model-path 必须指向容器内的路径。
4. 网络映射 : 使用 -p HostPort:ContainerPort 将容器端口映射到主机端口。