服务器参数#

本页提供命令行中用于配置语言模型服务器部署期间行为和性能的服务器参数列表。这些参数使用户能够自定义服务器的关键方面，包括模型选择、并行策略、内存管理和优化技术。

常用启动命令#

要启用多 GPU 张量并行，添加 --tp 2。如果报告错误“这些设备之间不支持对等访问”，请在服务器启动命令中添加 --enable-p2p-check。
```
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --tp 2
```
要启用多 GPU 数据并行，添加 --dp 2。如果有足够的内存，数据并行对于提高吞吐量更好。它也可以与张量并行一起使用。以下命令总共使用 4 个 GPU。我们推荐使用 SGLang 路由器进行数据并行。
```
python -m sglang_router.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --dp 2 --tp 2
```
如果在服务期间出现内存不足错误，请尝试通过设置较小的 --mem-fraction-static 值来减少 KV 缓存池的内存使用。默认值为 0.9。
```
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --mem-fraction-static 0.7
```
请参阅超参数调优，了解如何调优超参数以获得更好的性能。
对于 Docker 和 Kubernetes 运行，您需要设置共享内存，用于进程间通信。请参阅 Docker 的 --shm-size 以及 Kubernetes 清单中 /dev/shm 大小的更新。
如果在处理长提示的预填充期间出现内存不足错误，请尝试设置较小的分块预填充大小。
```
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --chunked-prefill-size 4096
```
要启用 torch.compile 加速，添加 --enable-torch-compile。它可以加速小批量大小的小模型。默认情况下，缓存路径位于 /tmp/torchinductor_root，您可以使用环境变量 TORCHINDUCTOR_CACHE_DIR 进行自定义。更多详情，请参考 PyTorch 官方文档和启用 torch.compile 缓存。
要启用 torchao 量化，添加 --torchao-config int4wo-128。它也支持其他量化策略 (INT8/FP8)。
要启用 fp8 权重量化，在 fp16 检查点上添加 --quantization fp8，或者直接加载 fp8 检查点而无需指定任何参数。
要启用 fp8 KV 缓存量化，添加 --kv-cache-dtype fp8_e5m2。
如果 Hugging Face 分词器中的模型没有聊天模板，您可以指定一个自定义聊天模板。

要在多个节点上运行张量并行，添加 --nnodes 2。如果您有两个节点，每个节点有两个 GPU，并想运行 TP=4，假设 sgl-dev-0 是第一个节点的主机名，50000 是一个可用端口，您可以使用以下命令。如果遇到死锁，请尝试添加 --disable-cuda-graph。

# Node 0
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --tp 4 --dist-init-addr sgl-dev-0:50000 --nnodes 2 --node-rank 0

# Node 1
python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --tp 4 --dist-init-addr sgl-dev-0:50000 --nnodes 2 --node-rank 1

请查阅下面的文档和 server_args.py，以了解更多关于启动服务器时可以提供的参数的信息。

模型、处理器和分词器#

参数	描述	默认值
`model_path`	模型权重的路径。可以是本地文件夹或 Hugging Face 仓库 ID。	None
`tokenizer_path`	分词器的路径。默认为 `model_path`。	None
`tokenizer_mode`	参见不同模式。	`auto`
`load_format`	要加载的模型权重的格式。	`auto`
`trust_remote_code`	是否允许 Hub 上自定义的模型在自己的建模文件中定义。	`False`
`dtype`	模型使用的数据类型 (Dtype)。	`auto`
`kv_cache_dtype`	KV 缓存的数据类型 (Dtype)。	`auto`
`context_length`	模型的最大上下文长度。默认为 None（将使用模型 config.json 中的值）。请注意，延长默认值可能会导致异常行为。	None
`device`	放置模型的设备。	None
`served_model_name`	覆盖 OpenAI API 服务器中 v1/models 端点返回的模型名称。	None
`is_embedding`	设置为 `true` 以执行嵌入 / 编码和奖励任务。	`False`
`revision`	调整以使用模型的特定版本。	None
`skip_tokenizer_init`	设置为 `true` 以直接向引擎提供输入 token 并获取输出 token，通常用于 RLHF。参见示例。	`False`
`json_model_override_args`	一个 JSON 字符串格式的字典，用于覆盖默认的模型配置。	`"{}"`
`disable_fast_image_processor`	采用基础图像处理器而不是快速图像处理器（默认）。参见详情。	`False`

服务：HTTP 和 API#

HTTP 服务器配置#

参数	描述	默认值
`host`	HTTP 服务器的主机。	`"127.0.0.1"`
`port`	HTTP 服务器的端口。	`30000`

API 配置#

参数	描述	默认值
`api_key`	为服务器和兼容 OpenAI 的 API 设置 API 密钥。	None
`file_storage_path`	存储 API 调用上传或生成文件的目录。	`"sglang_storage"`
`enable_cache_report`	如果设置，在响应使用情况中包含缓存 token 的详细使用情况。	`False`

并行性#

张量并行#

参数	描述	默认值
`tp_size`	模型权重分片的 GPU 数量。主要用于节省内存而非提高吞吐量，参见此教程：张量并行如何工作？。	`1`

数据并行#

参数	描述	默认值
`dp_size`	对于非 DeepSeek 模型，这是模型的数据并行副本数量。对于 DeepSeek 模型，这是 DeepSeek 模型上数据并行 Attention 的组大小。	`1`
`load_balance_method`	即将弃用。数据并行请求的负载均衡策略。	`"round_robin"`

专家并行#

参数	描述	默认值
`enable_ep_moe`	启用专家并行，将专家分布到多个 GPU 上用于 MoE 模型。	`False`
`ep_size`	EP 的大小。请使用 `tp_size=ep_size` 对模型权重进行分片。有关基准测试，请参考此 PR。	`1`
`enable_deepep_moe`	基于 `deepseek-ai/DeepEP` 启用专家并行，将专家分布到多个 GPU 上用于 DeepSeek-V3 模型。	`False`
`deepep_mode`	使用 DeepEP MoE 时选择模式：可以是 `normal`、`low_latency` 或 `auto`。`auto` 表示解码批次的 `low_latency`，预填充批次的 `normal`。	`auto`

内存和调度#

参数	描述	默认值
`mem_fraction_static`	用于模型权重和 KV 缓存等静态内存的空闲 GPU 内存比例。如果 KV 缓存构建失败，则增加它；如果 CUDA 内存不足，则减少它。	None
`max_running_requests`	同时运行的最大请求数。	None
`max_total_tokens`	可以在 KV 缓存中存储的最大 token 数量。主要用于调试。	None
`chunked_prefill_size`	以指定大小的块执行预填充。较大的块大小会加快预填充速度，但会增加 VRAM 使用量。如果 CUDA 内存不足，则减少它。	None
`max_prefill_tokens`	一个预填充批次中可以接受的 token 数量的预算。实际限制是此值与 `context_length` 中的最大值。	`16384`
`schedule_policy`	调度策略，控制单个引擎如何处理等待的预填充请求。	`"fcfs"`
`schedule_conservativeness`	控制服务器在接受新的预填充请求时的保守程度。高保守性可能导致饥饿，低保守性可能减慢解码速度。	`1.0`
`cpu_offload_gb`	为将模型参数卸载到 CPU 而保留的 RAM 量（以 GB 为单位）。	`0`

其他运行时选项#

参数	描述	默认值
`stream_interval`	流式响应的间隔（以 token 为单位）。较小的值导致更流畅的流式传输；较大的值提高吞吐量。	`1`
`random_seed`	可用于强制更确定的行为。	None
`watchdog_timeout`	看门狗线程的超时设置，如果在批量生成花费时间过长时，它会杀死服务器。	`300`
`download_dir`	覆盖 Hugging Face 模型权重的默认缓存目录。	None
`base_gpu_id`	设置在多个 GPU 上分发模型时使用的第一个 GPU。	`0`
`allow_auto_truncate`	自动截断超出最大输入长度的请求。	`False`

日志记录#

参数	描述	默认值
`log_level`	全局日志详细程度。	`"info"`
`log_level_http`	HTTP 服务器日志的单独详细程度。	None
`log_requests`	记录所有请求的输入和输出以进行调试。	`False`
`log_requests_level`	范围从 0 到 2：级别 0 只显示请求中的一些基本元数据，级别 1 和 2 显示请求详细信息（例如，文本、图像），级别 1 将输出限制为 2048 个字符。	`0`
`show_time_cost`	打印或记录内部操作的详细计时信息（有助于性能调优）。	`False`
`enable_metrics`	导出类似 Prometheus 的指标，用于请求使用和性能。	`False`
`decode_log_interval`	记录解码进度的频率（以 token 为单位）。	`40`

多节点分布式服务#

参数	描述	默认值
`dist_init_addr`	用于初始化 PyTorch 分布式后端的 TCP 地址（例如 `192.168.0.2:25000`）。	None
`nnodes`	集群中的节点总数。参见Llama 405B 指南。	`1`
`node_rank`	在分布式设置中，此节点在 `nnodes` 中的排名 (ID)。	`0`

LoRA#

参数	描述	默认值
`lora_paths`	要应用于模型的适配器列表。每个批次元素使用适当的 LoRA 适配器。此功能不支持 `radix_attention`，因此必须手动禁用。参见相关问题。	None
`max_loras_per_batch`	运行中的批次允许的最大 LoRA 数量，包括基础模型。	`8`
`lora_backend`	用于运行 LoRA 模块的 GEMM 内核的后端。可以是 `triton` 或 `flashinfer`。	`triton`

内核后端#

参数	描述	默认值
`attention_backend`	此参数指定用于 Attention 计算和 KV 缓存管理的后端，可以是 `fa3`、`flashinfer`、`triton`、`cutlass_mla` 或 `torch_native`。部署 DeepSeek 模型时，使用此参数指定 MLA 后端。	None
`sampling_backend`	指定用于采样的后端。	None
`mm_attention_backend`	设置多模态 Attention 后端。

约束解码#

参数	描述	默认值
`grammar_backend`	约束解码的语法后端。参见详细用法。	None
`constrained_json_whitespace_pattern`	与 `Outlines` 语法后端一起使用，以允许带有语法换行符、制表符或多个空格的 JSON。参见详情。

推测解码#

参数	描述	默认值
`speculative_draft_model_path`	推测解码的草稿模型路径。	None
`speculative_algorithm`	推测解码算法。目前支持 EAGLE 和 EAGLE3。请注意，使用 Eagle 推测解码时，禁用 Radix 缓存、分块预填充和重叠调度器。	None
`speculative_num_steps`	在验证之前运行多少次草稿 passes。	None
`speculative_num_draft_tokens`	草稿中提出的 token 数量。	None
`speculative_eagle_topk`	对于 Eagle，每一步保留用于验证的 top 候选数量。	None
`speculative_token_map`	可选，FR-Spec 高频 token 列表的路径，用于加速 Eagle。	None

调试选项#

注意：我们建议保持默认设置，仅在调试时使用这些选项以获得最佳性能。

参数	描述	默认值
`disable_radix_cache`	禁用用于前缀缓存的 Radix 后端。	`False`
`disable_cuda_graph`	禁用用于模型前向计算的 CUDA Graph。在遇到无法更正的 CUDA ECC 错误时使用。	`False`
`disable_cuda_graph_padding`	在需要填充时禁用 CUDA Graph；否则，仍然使用 CUDA Graph。	`False`
`disable_outlines_disk_cache`	禁用 outlines 语法后端的磁盘缓存。	`False`
`disable_custom_all_reduce`	禁用自定义 all-reduce 内核的使用。	`False`
`disable_overlap_schedule`	禁用 Overhead-Scheduler。	`False`
`enable_nan_detection`	如果 logits 包含 `NaN`，则启用警告。	`False`
`enable_p2p_check`	关闭默认始终允许访问 GPU 时进行 P2P 检查的设置。	`False`
`triton_attention_reduce_in_fp32`	在 Triton 内核中，将中间 Attention 结果转换为 `float32`。	`False`

优化#

注意：其中一些选项仍在实验阶段。

参数	描述	默认值
`enable_mixed_chunk`	启用预填充和解码混合，参见此讨论。	`False`
`enable_dp_attention`	为 Deepseek 模型启用数据并行 Attention。	`False`
`enable_torch_compile`	使用 Torch 编译模型。请注意，编译模型需要很长时间，但能极大地提升性能。编译后的模型也可以缓存以供将来使用。	`False`
`torch_compile_max_bs`	使用 `torch_compile` 时的最大批量大小。	`32`
`cuda_graph_max_bs`	调整使用 CUDA Graph 时的最大批量大小。默认情况下，这将根据 GPU 特定信息为您选择。	None
`cuda_graph_bs`	由 `CudaGraphRunner` 捕获的批量大小。默认情况下，这将为您完成。	None
`torchao_config`	使用 torchao 优化模型的实验性功能。可能的选择有：int8dq, int8wo, int4wo-<group_size>, fp8wo, fp8dq-per_tensor, fp8dq-per_row。	`int8dq`
`triton_attention_num_kv_splits`	用于调整 triton 内核中 KV 分割的数量。	`8`
`flashinfer_mla_disable_ragged`	对于 FlashInfer MLA Attention 后端，禁用 ragged prefill 包装器的使用。当没有前缀匹配时，ragged prefill 通过计算 MHA 而不是分页 MLA 来提高吞吐量。仅在 FlashInfer 用作 MLA 后端时使用此选项。	`False`
`disable_chunked_prefix_cache`	禁用 DeepSeek 模型的分块前缀缓存使用。仅在 FA3 用作 Attention 后端时使用此选项。	`False`
`enable_dp_lm_head`	在 Attention TP 组中启用词汇并行，以避免跨 DP 组进行 all-gather，优化 DP Attention 下的性能。	`False`

服务器参数

目录