服务器参数

服务器参数#

本页提供了在命令行中使用的服务器参数列表，用于在部署期间配置语言模型服务器的行为和性能。这些参数允许用户自定义服务器的关键方面，包括模型选择、并行策略、内存管理和优化技术。您可以通过 python3 -m sglang.launch_server --help 查看所有参数。

常用启动命令#

  • 要使用配置文件，请创建一个包含服务器参数的 YAML 文件，并使用 --config 指定。CLI 参数将覆盖配置文件中的值。

    # Create config.yaml
cat > config.yaml << EOF
model-path: meta-llama/Meta-Llama-3-8B-Instruct
host: 0.0.0.0
port: 30000
tensor-parallel-size: 2
enable-metrics: true
log-requests: true
EOF

# Launch server with config file
python -m sglang.launch_server --config config.yaml

  • 要启用多 GPU 张量并行，请添加 --tp 2。如果报告错误“peer access is not supported between these two devices”，请在服务器启动命令中添加 --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 Router。

    python -m sglang_router.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --dp 2 --tp 2

  • 如果您在服务期间看到显存溢出（OOM）错误，请尝试通过设置较小的 --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 大小更新。

  • 如果您在长提示词的预填充阶段看到显存溢出错误，请尝试设置较小的分块预填充（chunked prefill）大小。

    python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --chunked-prefill-size 4096

  • 要启用 torch.compile 加速，请添加 --enable-torch-compile。它能加速小模型在小 Batch Size 下的运行。默认情况下，缓存路径位于 /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。

  • 要启用确定性推理和批次不变操作，请添加 --enable-deterministic-inference。更多细节可以在 确定性推理文档 中找到。

  • 如果模型在 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
--model

模型权重路径。可以是本地文件夹或 Hugging Face 仓库 ID。

无

类型：str

--tokenizer-path

分词器路径。

无

类型：str

--tokenizer-mode

分词器模式。“auto” 将在可用时使用快速分词器，“slow” 将始终使用慢速分词器。

auto

auto, slow

--tokenizer-worker-num

分词器管理器的进程数量。

1

类型：int

--skip-tokenizer-init

如果设置，将跳过分词器初始化并在生成请求中传递 input_ids。

False

布尔标志 (设置即启用)

--load-format

要加载的模型权重格式。“auto” 将尝试加载 safetensors 格式，如果不可用则回退到 pytorch bin 格式。“pt” 将以 pytorch bin 格式加载权重。“safetensors” 将以 safetensors 格式加载权重。“npcache” 将以 pytorch 格式加载权重并存储 numpy 缓存以加快加载速度。“dummy” 将使用随机值初始化权重，主要用于性能分析。“gguf” 将以 gguf 格式加载权重。“bitsandbytes” 将使用 bitsandbytes 量化加载权重。“layered” 逐层加载权重，以便在加载下一层之前对当前层进行量化，从而减小峰值内存占用。

auto

auto, pt, safetensors, npcache, dummy, sharded_state, gguf, bitsandbytes, layered, remote, remote_instance

--model-loader-extra-config

模型加载器的额外配置。这将传递给与所选 load_format 对应的模型加载器。

{}

类型：str

--trust-remote-code

是否允许加载在 Hub 上定义了自己建模文件的自定义模型。

False

布尔标志 (设置即启用)

--context-length

模型的最大上下文长度。默认为 None（将使用模型 config.json 中的值）。

无

类型：int

--is-embedding

是否将 CausalLM 用作嵌入（Embedding）模型。

False

布尔标志 (设置即启用)

--enable-multimodal

为所服务的模型启用多模态功能。如果所服务的模型不是多模态模型，则不会产生影响。

无

布尔标志 (设置即启用)

--limit-mm-data-per-request

限制每个请求的多模态输入数量。例如：‘{“image”: 1, “video”: 1, “audio”: 1}’

无

类型：JSON / Dict

--revision

要使用的特定模型版本。可以是分支名、标签名或提交 ID。如果不指定，将使用默认版本。

无

类型：str

--model-impl

使用哪种模型实现。* “auto” 将尝试使用 SGLang 实现（如果存在），否则回退到 Transformers 实现。* “sglang” 将使用 SGLang 模型实现。* “transformers” 将使用 Transformers 模型实现。

auto

类型：str

HTTP 服务器#

参数

描述

默认值

选项

--host

HTTP 服务器的主机地址。

127.0.0.1

类型：str

--port

HTTP 服务器的端口号。

30000

类型：int

--skip-server-warmup

如果设置，将跳过预热。

False

布尔标志 (设置即启用)

--warmups

指定在服务器启动前运行的自定义预热函数 (csv)。例如：--warmups=warmup_name1,warmup_name2 将在服务器开始监听请求前运行 warmup.py 中指定的 warmup_name1 和 warmup_name2 函数。

无

类型：str

--nccl-port

用于 NCCL 分布式环境设置的端口。默认为随机端口。

无

类型：int

量化与数据类型#

参数

描述

默认值

选项

--dtype

模型权重和激活的数据类型。* “auto” 将对 FP32 和 FP16 模型使用 FP16 精度，对 BF16 模型使用 BF16 精度。* “half” 用于 FP16。推荐用于 AWQ 量化。* “float16” 与 “half” 相同。* “bfloat16” 用于在精度和范围之间取得平衡。* “float” 是 FP32 精度的简写。* “float32” 表示 FP32 精度。

auto

auto, half, float16, bfloat16, float, float32

--quantization

量化方法。

无

awq, fp8, gptq, marlin, gptq_marlin, awq_marlin, bitsandbytes, gguf, modelopt, modelopt_fp4, petit_nvfp4, w8a8_int8, w8a8_fp8, moe_wna16, qoq, w4afp8, mxfp4

--quantization-param-path

包含 KV 缓存缩放因子的 JSON 文件路径。当 KV 缓存数据类型为 FP8 时，通常应提供此项。否则，KV 缓存缩放因子默认为 1.0，这可能会导致精度问题。

无

类型：Optional[str]

--modelopt-quant

ModelOpt 量化配置。支持的值：‘fp8’, ‘int4_awq’, ‘w4a8_awq’, ‘nvfp4’, ‘nvfp4_awq’。这需要安装 NVIDIA Model Optimizer 库：pip install nvidia-modelopt

无

类型：str

--modelopt-checkpoint-restore-path

用于恢复先前保存的 ModelOpt 量化检查点的路径。如果提供，将跳过量化过程并从该检查点加载模型。

无

类型：str

--modelopt-checkpoint-save-path

量化后保存 ModelOpt 量化检查点的路径。这允许在将来的运行中重用已量化的模型。

无

类型：str

--kv-cache-dtype

KV 缓存存储的数据类型。“auto” 将使用模型数据类型。“fp8_e5m2” 和 “fp8_e4m3” 支持 CUDA 11.8+。

auto

auto, fp8_e5m2, fp8_e4m3

--enable-fp32-lm-head

如果设置，LM head 的输出 (logits) 将采用 FP32 格式。

False

布尔标志 (设置即启用)

内存与调度#

参数

描述

默认值

选项

--mem-fraction-static

用于静态分配（模型权重和 KV 缓存内存池）的显存比例。如果您看到显存溢出错误，请使用较小的值。

无

类型：float

--max-running-requests

最大运行中的请求数。

无

类型：int

--max-queued-requests

最大排队中的请求数。使用 disaggregation-mode（分离模式）时，此选项将被忽略。

无

类型：int

--max-total-tokens

内存池中的最大 Token 数量。如果未指定，将根据内存使用比例自动计算。此选项通常用于开发和调试。

无

类型：int

--chunked-prefill-size

分块预填充中每个块的最大 Token 数量。设置为 -1 表示禁用分块预填充。

无

类型：int

--max-prefill-tokens

预填充批次中的最大 Token 数量。实际边界将取此值与模型最大上下文长度中的较大者。

16384

类型：int

--schedule-policy

请求的调度策略。

fcfs

lpm, random, fcfs, dfs-weight, lof, priority

--enable-priority-scheduling

启用优先级调度。默认情况下，具有较高优先级整数值的请求将优先调度。

False

布尔标志 (设置即启用)

--schedule-low-priority-values-first

如果与 –enable-priority-scheduling 一起指定，调度程序将优先调度优先级整数值较低的请求。

False

布尔标志 (设置即启用)

--priority-scheduling-preemption-threshold

新请求抢占正在运行请求时所需的最小优先级差值。

10

类型：int

--schedule-conservativeness

调度策略的保守程度。值越大表示调度越保守。如果您发现请求经常被撤回，请使用较大的值。

1.0

类型：float

--page-size

每个页面中的 Token 数量。

1

类型：int

--hybrid-kvcache-ratio

统一 KV 缓冲区和混合 KV 缓冲区之间的混合比例，范围 [0,1]（0.0 = 纯统一：swa_size / full_size = 1）（1.0 = 纯混合：swa_size / full_size = local_attention_size / context_length）

无

Optional[float]

--swa-full-tokens-ratio

SWA 层 KV Token / 全量层 KV Token 的比例，与 swa:full 层的比例无关。应在 0 到 1 之间。例如，0.5 意味着如果每个 SWA 层有 50 个 Token，那么每个全量层就有 100 个 Token。

0.8

类型：float

--disable-hybrid-swa-memory

禁用混合 SWA 内存。

False

布尔标志 (设置即启用)

运行时选项#

参数

描述

默认值

选项

--device

要使用的设备（‘cuda’, ‘xpu’, ‘hpu’, ‘npu’, ‘cpu’）。如果不指定，则默认为自动检测。

无

类型：str

--elastic-ep-backend

为弹性专家并行 (EP) 选择集合通信后端。目前支持 ‘mooncake’。

无

无

--mooncake-ib-device

Mooncake 后端的 InfiniBand 设备，接受多个逗号分隔的设备。默认为 None，启用 Mooncake 后端时将触发自动设备检测。

无

无

--tensor-parallel-size
--tp-size

张量并行大小。

1

类型：int

--pipeline-parallel-size
--pp-size

流水线并行大小。

1

类型：int

--pp-max-micro-batch-size

流水线并行中的最大微批次 (micro batch) 大小。

无

类型：int

--stream-interval

流式输出的间隔（或缓冲区大小），以 Token 长度为单位。较小的值使流式输出更流畅，较大的值使吞吐量更高。

1

类型：int

--stream-output

是否以不相交片段序列的形式输出。

False

布尔标志 (设置即启用)

--random-seed

随机种子。

无

类型：int

--constrained-json-whitespace-pattern

（仅限 outlines 和 llguidance 后端）JSON 约束输出中允许的语法空格正则表达式。例如，要允许模型生成连续空格，可将模式设置为 [\n\t ]*

无

类型：str

--constrained-json-disable-any-whitespace

（仅限 xgrammar 和 llguidance 后端）在 JSON 约束输出中强制执行紧凑表示。

False

布尔标志 (设置即启用)

--watchdog-timeout

设置看门狗超时时间（秒）。如果前向批次耗时超过此值，服务器将崩溃以防止挂起。

300

类型：float

--dist-timeout

设置 torch.distributed 初始化的超时时间。

无

类型：int

--download-dir

Hugging Face 的模型下载目录。

无

类型：str

--base-gpu-id

开始分配 GPU 的起始 GPU ID。在同一台机器上运行多个实例时很有用。

0

类型：int

--gpu-id-step

连续 GPU ID 之间的间隔。例如，设置为 2 将使用 GPU 0, 2, 4...

1

类型：int

--sleep-on-idle

当 sglang 空闲时减少 CPU 使用率。

False

布尔标志 (设置即启用)

--mm-process-config

多模态预处理配置的 JSON 字符串。可以包含键：image, video, audio。

{}

日志#

参数

描述

默认值

选项

--log-level

所有日志记录器的日志级别。

info

类型：str

--log-level-http

HTTP 服务器的日志级别。如果未设置，默认重用 –log-level。

无

类型：str

--log-requests

记录所有请求的元数据、输入和输出。详细程度由 –log-requests-level 决定。

False

布尔标志 (设置即启用)

--log-requests-level

0: 记录元数据（无采样参数）。1: 记录元数据和采样参数。2: 记录元数据、采样参数和部分输入/输出。3: 记录所有输入/输出。

2

0, 1, 2, 3

--crash-dump-folder

用于转储崩溃（如果有）前最后 5 分钟请求的文件夹路径。如果未指定，则禁用崩溃转储。

无

类型：str

--crash-on-nan

如果在 logprobs 中出现 NaN，则使服务器崩溃。

False

类型：str

--show-time-cost

显示自定义标记的时间消耗。

False

布尔标志 (设置即启用)

--enable-metrics

启用 Prometheus 指标记录。

False

布尔标志 (设置即启用)

--enable-metrics-for-all-schedulers

当您希望所有 TP 排名（不仅是 TP 0）上的调度器分别记录请求指标时，启用此选项。这在启用 dp_attention 时特别有用，否则所有指标看起来都来自 TP 0。

False

布尔标志 (设置即启用)

--tokenizer-metrics-custom-labels-header

指定用于传递分词器指标自定义标签的 HTTP 请求头。

x-custom-labels

类型：str

--tokenizer-metrics-allowed-custom-labels

分词器指标允许的自定义标签。这些标签通过 HTTP 请求中 ‘–tokenizer-metrics-custom-labels-header’ 字段的字典指定，例如：如果设置了 ‘–tokenizer-metrics-allowed-custom-labels label1 label2’，则允许 {‘label1’: ‘value1’, ‘label2’: ‘value2’}。

无

List[str]

--bucket-time-to-first-token

首字响应时间 (TTFT) 的分桶，指定为浮点数列表。

无

List[float]

--bucket-inter-token-latency

Token 间延迟 (ITL) 的分桶，指定为浮点数列表。

无

List[float]

--bucket-e2e-request-latency

端到端请求延迟的分桶，指定为浮点数列表。

无

List[float]

--collect-tokens-histogram

收集 Prompt/Generation Token 数量的直方图。

False

布尔标志 (设置即启用)

--prompt-tokens-buckets

Prompt Token 的分桶规则。支持 3 种规则类型：‘default’ 使用预定义的分桶；‘tse’ 生成双侧指数分布的分桶（例如，‘tse 1000 2 8’ 生成 [984.0, 992.0, 996.0, 998.0, 1000.0, 1002.0, 1004.0, 1008.0, 1016.0]）；‘custom’ 使用自定义分桶值（例如，‘custom 10 50 100 500’）。

无

List[str]

--generation-tokens-buckets

生成 Token 数量直方图的分桶规则。支持 3 种规则类型：‘default’ 使用预定义分桶；‘tse’ 生成双侧指数分布的分桶（例如，‘tse 1000 2 8’ 生成 [984.0, 992.0, 996.0, 998.0, 1000.0, 1002.0, 1004.0, 1008.0, 1016.0]）；‘custom’ 使用自定义分桶值（例如，‘custom 10 50 100 500’）。

无

List[str]

--gc-warning-threshold-secs

长 GC（垃圾回收）警告阈值。如果 GC 耗时超过此值，将记录警告。设置为 0 以禁用。

0.0

类型：float

--decode-log-interval

解码批次的日志记录间隔。

40

类型：int

--enable-request-time-stats-logging

启用单个请求的时间统计日志记录。

False

布尔标志 (设置即启用)

--kv-events-config

用于 NVIDIA dynamo KV 事件发布的 JSON 格式配置。如果使用此标志，将启用发布。

无

类型：str

--enable-trace

启用 opentelemetry 追踪。

False

布尔标志 (设置即启用)

--oltp-traces-endpoint

如果设置了 –enable-trace，配置 opentelemetry 收集器端点。格式为:

localhost:4317

类型：str

数据并行#

参数

描述

默认值

选项

--data-parallel-size
--dp-size

数据并行大小。

1

类型：int

--load-balance-method

数据并行的负载均衡策略。最小 Token 算法仅在应用 DP attention 时可用。该算法根据 DP 工作线程的实时 Token 负载执行负载均衡。

round_robin

round_robin, shortest_queue, minimum_tokens

--load-watch-interval

负载监控的时间间隔（秒）。

0.1

类型：float

--prefill-round-robin-balance

预填充采用轮询 (round robin) 均衡。这用于保证解码服务器可以获取正确的 DP 排名。

False

布尔标志 (设置即启用)

多节点分布式服务#

参数

描述

默认值

选项

--dist-init-addr
--nccl-init-addr

初始化分布式后端的主机地址（例如，192.168.0.2:25000）。

无

类型：str

--nnodes

节点数量。

1

类型：int

--node-rank

节点排名。

0

类型：int

模型覆盖参数#

参数

描述

默认值

选项

--json-model-override-args

用于覆盖默认模型配置的 JSON 字符串格式字典。

{}

类型：str

--preferred-sampling-params

JSON 格式的采样设置，将在 /get_model_info 中返回。

无

类型：str

LoRA#

参数

描述

默认值

选项

--enable-lora

为模型启用 LoRA 支持。为了向后兼容，如果提供了 --lora-paths，此参数会自动设置为 True。

False

布尔标志 (设置即启用)

--max-lora-rank

应支持的最大 LoRA 秩 (Rank)。如果未指定，将从 --lora-paths 中提供的适配器自动推断。当您期望在服务器启动后动态加载具有更大秩的适配器时，需要此参数。

无

类型：int

--lora-target-modules

应应用 LoRA 的所有目标模块的并集（例如，q_proj, k_proj, gate_proj）。如果未指定，将从 --lora-paths 中的适配器自动推断。您也可以将其设置为 all 以对所有受支持的模块启用 LoRA；请注意，这可能会引入细微的性能开销。

无

q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj, qkv_proj, gate_up_proj, all

--lora-paths

要加载的 LoRA 适配器列表。每个适配器必须指定为以下格式之一：<路径> | <名称>=<路径> | 符合 Schema {"lora_name": str, "lora_path": str, "pinned": bool} 的 JSON。

无

类型：str 列表 / JSON 对象

--max-loras-per-batch

运行批次中的最大适配器数量，包括仅基础模型的请求。

8

类型：int

--max-loaded-loras

如果指定，则限制一次加载到 CPU 内存中的最大 LoRA 适配器数量。必须 ≥ --max-loras-per-batch。

无

类型：int

--lora-eviction-policy

GPU 内存池满时的 LoRA 适配器逐出策略。

lru

lru, fifo

--lora-backend

为多 LoRA 服务选择算子后端。

triton

triton, csgmv

--max-lora-chunk-size

ChunkedSGMV LoRA 后端的最大分块大小。仅在 --lora-backend 为 csgmv 时使用。较大的值可能会提高性能。

16

16, 32, 64, 128

算子后端 (Attention, Sampling, Grammar, GEMM)#

参数

描述

默认值

选项

--attention-backend

为注意力层选择算子。

无

triton, torch_native, flex_attention, nsa, cutlass_mla, fa3, fa4, flashinfer, flashmla, trtllm_mla, trtllm_mha, dual_chunk_flash_attn, aiter, wave, intel_amx, ascend

--prefill-attention-backend

为预填充阶段的注意力层选择算子（优先级高于 –attention-backend）。

无

triton, torch_native, flex_attention, nsa, cutlass_mla, fa3, fa4, flashinfer, flashmla, trtllm_mla, trtllm_mha, dual_chunk_flash_attn, aiter, wave, intel_amx, ascend

--decode-attention-backend

为解码阶段的注意力层选择算子（优先级高于 –attention-backend）。

无

triton, torch_native, flex_attention, nsa, cutlass_mla, fa3, fa4, flashinfer, flashmla, trtllm_mla, trtllm_mha, dual_chunk_flash_attn, aiter, wave, intel_amx, ascend

--sampling-backend

为采样层选择算子。

无

flashinfer, pytorch, ascend

--grammar-backend

为语法引导的解码选择后端。

无

xgrammar, outlines, llguidance, none

--mm-attention-backend

设置多模态注意力算子后端。

无

sdpa, fa3, triton_attn, ascend_attn, aiter_attn

--nsa-prefill

为预填充阶段选择 NSA 后端（在运行 DeepSeek NSA 风格注意力时覆盖 --attention-backend）。

flashmla_sparse

flashmla_sparse, flashmla_decode, fa3, tilelang, aiter

--nsa-decode

在运行 DeepSeek NSA 风格注意力时为解码阶段选择 NSA 后端。在解码阶段覆盖 --attention-backend。

flashmla_kv

flashmla_prefill, flashmla_kv, fa3, tilelang, aiter

--fp8-gemm-backend

选择 Blockwise FP8 GEMM 操作的运行后端。选项：‘auto’（默认，根据硬件自动选择）、‘deep_gemm’（JIT 编译；在安装了 DeepGEMM 的 NVIDIA Hopper (SM90) 和 Blackwell (SM100) 上默认启用）、‘flashinfer_trtllm’（最适合 Blackwell 且低延迟）、‘cutlass’（最适合 Hopper/Blackwell GPU 且高吞吐）、‘triton’（备选方案，兼容性广）、‘aiter’（仅限 ROCm）。注意：此选项取代了已弃用的环境变量 SGLANG_ENABLE_FLASHINFER_FP8_GEMM 和 SGLANG_SUPPORT_CUTLASS_BLOCK_FP8。

auto

auto, deep_gemm, flashinfer_trtllm, cutlass, triton, aiter

--disable-flashinfer-autotune

Flashinfer 自动调优默认开启。设置此标志以禁用自动调优。

False

布尔标志 (设置即启用)

投机采样 (Speculative decoding)#

参数

描述

默认值

选项

--speculative-algorithm

投机算法。

无

EAGLE, EAGLE3, NEXTN, STANDALONE, NGRAM

--speculative-draft-model-path
--speculative-draft-model

草稿模型 (draft model) 权重路径。可以是本地文件夹或 Hugging Face 仓库 ID。

无

类型：str

--speculative-draft-model-revision

要使用的特定草稿模型版本。可以是分支名、标签名或 commit id。如果未指定，将使用默认版本。

无

类型：str

--speculative-num-steps

在投机采样中从草稿模型采样的步数。

无

类型：int

--speculative-eagle-topk

在 eagle2 中每步从草稿模型采样的 token 数量。

无

类型：int

--speculative-num-draft-tokens

在投机采样中从草稿模型采样的 token 数量。

无

类型：int

--speculative-accept-threshold-single

如果草稿 token 在目标模型中的概率大于此阈值，则接受该 token。

1.0

类型：float

--speculative-accept-threshold-acc

草稿 token 的接受概率从其目标概率 p 提高到 min(1, p / threshold_acc)。

1.0

类型：float

--speculative-token-map

草稿模型小词表 (small vocab table) 的路径。

无

类型：str

--speculative-attention-mode

用于投机采样操作（目标验证和草稿扩展）的注意力后端。可以是 ‘prefill’（默认）或 ‘decode’ 之一。

prefill

prefill, decode

--speculative-moe-runner-backend

用于 EAGLE 投机采样的 MOE 后端，选项见 –moe-runner-backend。如果未设置，则与 moe runner 后端相同。

无

--speculative-moe-a2a-backend

用于 EAGLE 投机采样的 MOE A2A 后端，选项见 –moe-a2a-backend。如果未设置，则与 moe a2a 后端相同。

无

Ngram 投机采样#

参数

描述

默认值

选项

--speculative-ngram-min-match-window-size

ngram 投机采样中模式匹配的最小窗口大小。

1

类型：int

--speculative-ngram-max-match-window-size

ngram 投机采样中模式匹配的最大窗口大小。

12

类型：int

--speculative-ngram-min-bfs-breadth

ngram 投机采样中 BFS（广度优先搜索）的最小宽度。

1

类型：int

--speculative-ngram-max-bfs-breadth

ngram 投机采样中 BFS（广度优先搜索）的最大宽度。

10

类型：int

--speculative-ngram-match-type

缓存树的匹配类型。

BFS

BFS, PROB

--speculative-ngram-branch-length

ngram 投机采样的分支长度。

18

类型：int

--speculative-ngram-capacity

ngram 投机采样的缓存容量。

10000000

类型：int

MoE#

参数

描述

默认值

选项

--expert-parallel-size
--ep-size
--ep

专家并行 (expert parallelism) 大小。

1

类型：int

--moe-a2a-backend

选择专家并行的 all-to-all 通信后端。

none

none, deepep, mooncake, ascend_fuseep

--moe-runner-backend

选择 MoE 的运行后端。

auto

auto, deep_gemm, triton, triton_kernel, flashinfer_trtllm, flashinfer_cutlass, flashinfer_mxfp4, flashinfer_cutedsl

--flashinfer-mxfp4-moe-precision

选择 flashinfer mxfp4 moe 的计算精度

default

default, bf16

--enable-flashinfer-allreduce-fusion

启用 FlashInfer allreduce 与 Residual RMSNorm 的融合。

False

布尔标志 (设置即启用)

--deepep-mode

启用 DeepEP MoE 时选择模式，可以是 normal、low_latency 或 auto。默认值为 auto，表示对 decode batch 使用 low_latency，对 prefill batch 使用 normal。

auto

normal, low_latency, auto

--ep-num-redundant-experts

在专家并行中分配此数量的冗余专家。

0

类型：int

--ep-dispatch-algorithm

在专家并行中为冗余专家选择 rank 的算法。

无

类型：str

--init-expert-location

EP 专家的初始位置。

trivial

类型：str

--enable-eplb

启用 EPLB 算法

False

布尔标志 (设置即启用)

--eplb-algorithm

所选的 EPLB 算法

auto

类型：str

--eplb-rebalance-num-iterations

自动触发 EPLB 重新平衡的迭代次数。

1000

类型：int

--eplb-rebalance-layers-per-chunk

每次前向传播要重新平衡的层数。

无

类型：int

--eplb-min-rebalancing-utilization-threshold

触发 EPLB 重新平衡的 GPU 平均利用率最小阈值。必须在 [0.0, 1.0] 范围内。

1.0

类型：float

--expert-distribution-recorder-mode

专家分布记录器的模式。

无

类型：str

--expert-distribution-recorder-buffer-size

专家分布记录器的循环缓冲区大小。设置为 -1 表示无限缓冲区。

无

类型：int

--enable-expert-distribution-metrics

启用专家平衡性指标日志记录

False

布尔标志 (设置即启用)

--deepep-config

适用于您自己集群的调优后的 DeepEP 配置。可以是 JSON 内容字符串或文件路径。

无

类型：str

--moe-dense-tp-size

MoE 密集 MLP 层的 TP 大小。当 TP 大比较大时，如果 MLP 层权重维度小于 GEMM 支持的最小维度而导致错误，此标志非常有用。

无

类型：int

Mamba 缓存#

参数

描述

默认值

选项

--max-mamba-cache-size

mamba 缓存的最大大小。

无

类型：int

--mamba-ssm-dtype

mamba 缓存中 SSM 状态的数据类型。

float32

float32, bfloat16

--mamba-full-memory-ratio

mamba 状态内存占完整 KV 缓存内存的比例。

0.2

类型：float

--mamba-scheduler-strategy

mamba 调度器使用的策略。auto 目前默认为 no_buffer。1. no_buffer 不支持重叠 (overlap) 调度，因为不分配额外的 mamba 状态缓冲区。分支点缓存支持是可行的但尚未实现。2. extra_buffer 通过分配额外的 mamba 状态缓冲区来跟踪缓存的 mamba 状态，从而支持重叠调度（对于非投机采样，每个运行请求的 mamba 状态使用量变为 2x；对于投机采样，变为 1+(1/(2+speculative_num_draft_tokens))x（例如，如果 speculative_num_draft_tokens==4，则为 1.16x））。2a. 对于非 KV 缓存受限的情况，extra_buffer 显然更好；对于 KV 缓存受限的情况，权衡取决于启用重叠是否优于减少的最大运行请求数。2b. 在基数缓存 (radix cache) 分支点的 mamba 缓存显然优于非分支缓存，但需要内核支持（目前仅限 FLA 后端），目前仅 extra_buffer 支持分支。

auto

auto, no_buffer, extra_buffer

--mamba-track-interval

decode 期间跟踪 mamba 状态的间隔（以 token 为单位）。仅当 --mamba-scheduler-strategy 为 extra_buffer 时使用。如果设置，必须能被 page_size 整除，且在使用投机采样时必须 >= speculative_num_draft_tokens。

256

类型：int

多项目评分 (multi-item scoring) 参数#

参数

描述

默认值

选项

--multi-item-scoring-delimiter

多项目评分的分隔符 token ID。用于将查询 (Query) 和项目 (Items) 合并为单个序列：QueryItem1Item2… 这实现了针对单个查询的高效多项目批处理。

无

类型：int

分层缓存 (Hierarchical cache)#

参数

描述

默认值

选项

--enable-hierarchical-cache

启用分层缓存

False

布尔标志 (设置即启用)

--hicache-ratio

主机 (host) KV 缓存内存池大小与设备 (device) 池大小的比例。

2.0

类型：float

--hicache-size

主机 KV 缓存内存池的大小（GB），如果设置，将覆盖 hicache_ratio。

0

类型：int

--hicache-write-policy

分层缓存的写入策略。

write_through

write_back, write_through, write_through_selective

--radix-eviction-policy

基数树的逐出策略。‘lru’ 代表最近最少使用，‘lfu’ 代表最不经常使用。

lru

lru, lfu

--hicache-io-backend

CPU 和 GPU 之间 KV 缓存传输的 IO 后端

kernel

direct, kernel, kernel_ascend

--hicache-mem-layout

分层缓存的主机内存池布局。

layer_first

layer_first, page_first, page_first_direct, page_first_kv_split

--hicache-storage-backend

分层 KV 缓存的存储后端。内置后端：file, mooncake, hf3fs, nixl, aibrix。对于动态 (dynamic) 后端，使用 –hicache-storage-backend-extra-config 指定：backend_name（自定义名称）、module_path（Python 模块路径）、class_name（后端类名）。

无

file, mooncake, hf3fs, nixl, aibrix, dynamic, eic

--hicache-storage-prefetch-policy

控制何时应停止从存储后端预取。

best_effort

best_effort, wait_complete, timeout

--hicache-storage-backend-extra-config

JSON 字符串格式的字典，包含存储后端的额外配置。

无

类型：str

LMCache#

参数

描述

默认值

选项

--enable-lmcache

使用 LMCache 作为替代的分层缓存解决方案

False

布尔标志 (设置即启用)

双重稀疏性 (Double Sparsity)#

参数

描述

默认值

选项

--enable-double-sparsity

启用双重稀疏注意力

False

布尔标志 (设置即启用)

--ds-channel-config-path

双重稀疏通道配置的路径

无

类型：str

--ds-heavy-channel-num

双重稀疏注意力中的重通道 (heavy channels) 数量

32

类型：int

--ds-heavy-token-num

双重稀疏注意力中的重 token (heavy tokens) 数量

256

类型：int

--ds-heavy-channel-type

双重稀疏注意力中的重通道类型

qk

类型：str

--ds-sparse-decode-threshold

在双重稀疏后端从密集回退 (dense fallback) 切换到稀疏解码内核之前所需的最小解码序列长度。

4096

类型：int

卸载 (Offloading)#

参数

描述

默认值

选项

--cpu-offload-gb

为 CPU 卸载预留多少 GB 的 RAM。

0

类型：int

--offload-group-size

卸载中每组的层数。

-1

类型：int

--offload-num-in-group

一个组内要卸载的层数。

1

类型：int

--offload-prefetch-step

卸载中预取的步数。

1

类型：int

--offload-mode

卸载模式。

cpu

类型：str

优化/调试选项#

参数

描述

默认值

选项

--disable-radix-cache

禁用用于前缀缓存的 RadixAttention。

False

布尔标志 (设置即启用)

--cuda-graph-max-bs

设置 cuda graph 的最大 batch size。它会将 cuda graph 捕获的 batch size 扩展到此值。

无

类型：int

--cuda-graph-bs

设置 cuda graph 的 batch size 列表。

无

List[int]

--disable-cuda-graph

禁用 cuda graph。

False

布尔标志 (设置即启用)

--disable-cuda-graph-padding

在需要填充 (padding) 时禁用 cuda graph。在不需要填充时仍使用 cuda graph。

False

布尔标志 (设置即启用)

--enable-profile-cuda-graph

启用 cuda graph 捕获的性能分析。

False

布尔标志 (设置即启用)

--enable-cudagraph-gc

在 CUDA graph 捕获期间启用垃圾回收。如果禁用（默认），则在捕获期间冻结 GC 以加快过程。

False

布尔标志 (设置即启用)

--enable-nccl-nvls

在可用时，为 prefill 密集型请求启用 NCCL NVLS。

False

布尔标志 (设置即启用)

--enable-symm-mem

启用 NCCL 对称内存以实现快速集合通信。

False

布尔标志 (设置即启用)

--disable-flashinfer-cutlass-moe-fp4-allgather

禁用 flashinfer cutlass moe 在 all-gather 之前的量化。

False

布尔标志 (设置即启用)

--enable-tokenizer-batch-encode

启用批处理分词，以提高处理多个文本输入时的性能。请勿与图像输入、预分词的 input_ids 或 input_embeds 一起使用。

False

布尔标志 (设置即启用)

--disable-outlines-disk-cache

禁用 outlines 的磁盘缓存，以避免与文件系统或高并发相关的潜在崩溃。

False

布尔标志 (设置即启用)

--disable-custom-all-reduce

禁用自定义 all-reduce 内核并回退到 NCCL。

False

布尔标志 (设置即启用)

--enable-mscclpp

启用对 all-reduce 内核的小消息使用 mscclpp，并回退到 NCCL。

False

布尔标志 (设置即启用)

--enable-torch-symm-mem

启用对 all-reduce 内核使用 torch symm mem，并回退到 NCCL。仅支持 CUDA 设备 SM90 及以上。SM90 支持 world size 为 4, 6, 8。SM100 支持 world size 为 6, 8。

False

布尔标志 (设置即启用)

--disable-overlap-schedule

禁用重叠调度器，该调度器将 CPU 调度器与 GPU 模型 worker 重叠运行。

False

布尔标志 (设置即启用)

--enable-mixed-chunk

在使用分块 prefill (chunked prefill) 时，允许在一个 batch 中混合 prefill 和 decode。

False

布尔标志 (设置即启用)

--enable-dp-attention

为注意力机制启用数据并行 (DP)，为 FFN 启用张量并行 (TP)。DP 大小应等于 TP 大小。目前支持 DeepSeek-V2 和 Qwen 2/3 MoE 模型。

False

布尔标志 (设置即启用)

--enable-dp-lm-head

在注意力 TP 组中启用词表并行，以避免跨 DP 组的 all-gather，从而优化 DP 注意力下的性能。

False

布尔标志 (设置即启用)

--enable-two-batch-overlap

启用两个微批次 (micro batches) 的重叠运行。

False

布尔标志 (设置即启用)

--enable-single-batch-overlap

使计算和通信在单个微批次内重叠。

False

布尔标志 (设置即启用)

--tbo-token-distribution-threshold

微批次重叠中两个批次之间的 token 分布阈值，决定是进行 two-batch-overlap 还是 two-chunk-overlap。设置为 0 表示禁用 two-chunk-overlap。

0.48

类型：float

--enable-torch-compile

使用 torch.compile 优化模型。实验性功能。

False

布尔标志 (设置即启用)

--enable-torch-compile-debug-mode

为 torch compile 启用调试模式。

False

布尔标志 (设置即启用)

--enable-piecewise-cuda-graph

仅为 extend/prefill 使用分段 cuda graph 优化模型。实验性功能。

False

布尔标志 (设置即启用)

--piecewise-cuda-graph-tokens

设置使用分段 cuda graph 时的 token 列表。

无

类型：JSON 列表

--torch-compile-max-bs

设置使用 torch compile 时的最大 batch size。

32

类型：int

--piecewise-cuda-graph-max-tokens

设置使用分段 cuda graph 时的最大 token 数量。

4096

类型：int

--torchao-config

使用 torchao 优化模型。实验性功能。当前选择有：int8dq, int8wo, int4wo-<group_size>, fp8wo, fp8dq-per_tensor, fp8dq-per_row

``

类型：str

--enable-nan-detection

启用 NaN 检测以用于调试目的。

False

布尔标志 (设置即启用)

--enable-p2p-check

启用 GPU 访问的 P2P 检查，否则默认允许 P2P 访问。

False

布尔标志 (设置即启用)

--triton-attention-reduce-in-fp32

将中间注意力结果转换为 fp32，以避免与 fp16 相关的潜在崩溃。这仅影响 Triton 注意力内核。

False

布尔标志 (设置即启用)

--triton-attention-num-kv-splits

flash decoding Triton 内核中的 KV 分割数量。在长上下文场景中，较大的值更好。默认值为 8。

8

类型：int

--triton-attention-split-tile-size

flash decoding Triton 内核中分割 KV 磁贴 (tile) 的大小。用于确定性推理。

无

类型：int

--num-continuous-decode-steps

运行多个连续解码步以减少调度开销。这可以潜在提高吞吐量，但也可能增加首个 token 的延迟 (TTFT)。默认值为 1，表示一次仅运行一个解码步。

1

类型：int

--delete-ckpt-after-loading

加载模型后删除模型检查点。

False

布尔标志 (设置即启用)

--enable-memory-saver

允许使用 release_memory_occupation 和 resume_memory_occupation 来节省内存

False

布尔标志 (设置即启用)

--enable-weights-cpu-backup

在 release_weights_occupation 和 resume_weights_occupation 期间将模型权重保存到 CPU 内存

False

布尔标志 (设置即启用)

--allow-auto-truncate

允许自动截断超过最大输入长度的请求，而不是返回错误。

False

布尔标志 (设置即启用)

--enable-custom-logit-processor

允许用户向服务器传递自定义 logit 处理器（出于安全考虑，默认禁用）

False

布尔标志 (设置即启用)

--flashinfer-mla-disable-ragged

运行 flashinfer mla 时不使用 ragged prefill 包装器

False

布尔标志 (设置即启用)

--disable-shared-experts-fusion

禁用 deepseek v3/r1 的共享专家融合优化。

False

布尔标志 (设置即启用)

--disable-chunked-prefix-cache

禁用 deepseek 的分块前缀缓存功能，这应该会减少短序列的开销。

False

布尔标志 (设置即启用)

--disable-fast-image-processor

采用基础图像处理器而非快速图像处理器。

False

布尔标志 (设置即启用)

--keep-mm-feature-on-device

处理后将多模态特征张量保留在设备上，以节省 D2H 拷贝。

False

布尔标志 (设置即启用)

--enable-return-hidden-states

允许在响应中返回隐藏状态 (hidden states)。

False

布尔标志 (设置即启用)

--scheduler-recv-interval

调度器轮询请求的间隔。可以设置为 >1 以减少开销。

1

类型：int

--numa-node

设置子进程的 numa 节点。第 i 个元素对应第 i 个子进程。

无

List[int]

--enable-layerwise-nvtx-marker

为模型启用逐层 NVTX 分析注释。这会为每一层添加 NVTX 标记，以便使用 Nsight Systems 进行详细的逐层性能分析。

False

布尔标志 (设置即启用)

--enable-attn-tp-input-scattered

当仅使用张量并行时，允许注意力的输入是分散的，以减少 qkv latent 等操作的计算负载。

False

布尔标志 (设置即启用)

--enable-nsa-prefill-context-parallel

DeepSeek v3.2 长序列预填充阶段使用的上下文并行

False

布尔标志 (设置即启用)

前向钩子 (Forward hooks)#

参数

描述

默认值

选项

--forward-hooks

JSON 格式的前向钩子规范列表。每个元素必须包含 target_modules（与 model.named_modules() 名称匹配的 glob 模式列表）和 hook_factory（指向工厂函数的 Python 导入路径，例如 my_package.hooks:make_hook）。可选字段 name 用于日志记录，可选的 config 对象作为 dict 传递给工厂函数。

无

类型：JSON 列表

调试张量转储 (Debug tensor dumps)#

参数

描述

默认值

选项

--debug-tensor-dump-output-folder

转储张量的输出文件夹。

无

类型：str

--debug-tensor-dump-input-file

转储张量的输入文件名

无

类型：str

--debug-tensor-dump-inject

将来自 jax 的输出注入作为每一层的输入。

False

类型：str

--enable-dynamic-batch-tokenizer

启用异步动态批处理分词器，以提高多个请求并发到达时的性能。

False

布尔标志 (设置即启用)

--dynamic-batch-tokenizer-batch-size

[仅当设置了 –enable-dynamic-batch-tokenizer 时使用] 动态批处理分词器的最大批次大小。

32

类型：int

--dynamic-batch-tokenizer-batch-timeout

[仅当设置了 –enable-dynamic-batch-tokenizer 时使用] 批处理分词请求的超时时间（秒）。

0.002

类型：float

PD 分离 (PD disaggregation)#

参数

描述

默认值

选项

--disaggregation-mode

仅用于 PD 分离。“prefill”用于仅 prefill 的服务器，“decode”用于仅 decode 的服务器。如果未指定，则不是 PD 分离模式

null

null, prefill, decode

--disaggregation-transfer-backend

分离传输的后端。默认为 mooncake。

mooncake

mooncake, nixl, ascend, fake

--disaggregation-bootstrap-port

prefill 服务器上的 Bootstrap 服务器端口。默认为 8998。

8998

类型：int

--disaggregation-decode-tp

decode tp 大小。如果未设置，则匹配当前引擎的 tp 大小。此参数仅在 prefill 服务器上设置。

无

类型：int

--disaggregation-decode-dp

decode dp 大小。如果未设置，则匹配当前引擎的 dp 大小。此参数仅在 prefill 服务器上设置。

无

类型：int

--disaggregation-prefill-pp

prefill pp 大小。如果未设置，默认为 1。此参数仅在 decode 服务器上设置。

1

类型：int

--disaggregation-ib-device

用于分离传输的 InfiniBand 设备，接受单个设备（例如 –disaggregation-ib-device mlx5_0）或多个以逗号分隔的设备（例如 –disaggregation-ib-device mlx5_0,mlx5_1）。默认为 None，当启用 mooncake 后端时会触发自动设备检测。

无

类型：str

--disaggregation-decode-enable-offload-kvcache

在 decode 服务器（PD 模式）上启用异步 KV 缓存卸载。

False

布尔标志 (设置即启用)

--num-reserved-decode-tokens

向运行中的 batch 添加新请求时，将为其预留内存的 decode token 数量。

512

类型：int

--disaggregation-decode-polling-interval

decode 服务器轮询请求的间隔。可以设置为 >1 以减少开销。

1

类型：int

自定义权重加载器#

参数

描述

默认值

选项

--custom-weight-loader

用于更新模型的自定义数据加载器。应设置为有效的导入路径，例如 my_package.weight_load_func

无

List[str]

--weight-loader-disable-mmap

使用 safetensors 加载权重时禁用 mmap。

False

布尔标志 (设置即启用)

--remote-instance-weight-loader-seed-instance-ip

从远程实例加载权重时的种子实例 IP。

无

类型：str

--remote-instance-weight-loader-seed-instance-service-port

从远程实例加载权重时的种子实例服务端口。

无

类型：int

--remote-instance-weight-loader-send-weights-group-ports

从远程实例加载权重时的通信组端口。

无

类型：JSON 列表

用于 PD 复用 (PD-Multiplexing)#

参数

描述

默认值

选项

--enable-pdmux

启用 PD 复用，PD 运行在 greenctx 流上。

False

布尔标志 (设置即启用)

--pdmux-config-path

PD 复用配置文件的路径。

无

类型：str

--sm-group-num

SM 分区组的数量。

8

类型：int

用于确定性推理#

参数

描述

默认值

选项

--enable-deterministic-inference

启用带有 batch 不变操作的确定性推理模式。

False

布尔标志 (设置即启用)

已弃用的参数#

参数

描述

默认值

选项

--enable-ep-moe

注意：–enable-ep-moe 已弃用。请将 --ep-size 设置为与 --tp-size 相同的值。

无

无

--enable-deepep-moe

注意：–enable-deepep-moe 已弃用。请将 --moe-a2a-backend 设置为 ‘deepep’。

无

无

--enable-flashinfer-cutlass-moe

注意：–enable-flashinfer-cutlass-moe 已弃用。请将 --moe-runner-backend 设置为 ‘flashinfer_cutlass’。

无

无

--enable-flashinfer-cutedsl-moe

注意：–enable-flashinfer-cutedsl-moe 已弃用。请将 --moe-runner-backend 设置为 ‘flashinfer_cutedsl’。

无

无

--enable-flashinfer-trtllm-moe

注意：–enable-flashinfer-trtllm-moe 已弃用。请将 --moe-runner-backend 设置为 ‘flashinfer_trtllm’。

无

无

--enable-triton-kernel-moe

注意：–enable-triton-kernel-moe 已弃用。请将 --moe-runner-backend 设置为 ‘triton_kernel’。

无

无

--enable-flashinfer-mxfp4-moe

注意：–enable-flashinfer-mxfp4-moe 已弃用。请将 --moe-runner-backend 设置为 ‘flashinfer_mxfp4’。

无

无

配置文件支持#

参数

描述

默认值

选项

--config

从配置文件读取 CLI 选项。必须是带有配置选项的 YAML 文件。

无

类型：str
目录