本文按原配置的顺序解释 sglang serve 和全部 35 个不同参数。只说明现有配置，不调整参数值。末尾重复出现的 --log-requests 单独注明。
参数含义依据 SGLang 官方文档及当前 main 分支源码。原配置没有提供镜像标签、SGLang 版本和 /data/model 的模型信息，因此本文不代表这组参数已经通过该部署环境的兼容性验证。尤其是 QSA、线性注意力后端和推测解码，支持情况与模型、GPU 和软件版本有关。
一、启动方式
command:
- sglang
- serve
args:
- --model-path
- /data/model
- --tp
- "4"
- --ep
- "4"
- --mem-fraction-static
- "0.85"
- --enable-hierarchical-cache
- --hicache-size
- "64"
- --hicache-write-policy
- write_through
- --hicache-io-backend
- kernel
- --hicache-mem-layout
- page_first
- --page-size
- "64"
- --mamba-radix-cache-strategy
- extra_buffer
- --kv-cache-dtype
- fp8_e4m3
- --qsa-indexer-dtype
- fp8_e4m3
- --chunked-prefill-size
- "8192"
- --linear-attn-prefill-backend
- flashinfer
- --linear-attn-decode-backend
- flashinfer
- --linear-attn-verify-backend
- triton
- --mamba-ssm-dtype
- bfloat16
- --speculative-algorithm
- NEXTN
- --speculative-num-steps
- "3"
- --speculative-eagle-topk
- "1"
- --speculative-num-draft-tokens
- "4"
- --reasoning-parser
- auto
- --tool-call-parser
- auto
- --host
- 0.0.0.0
- --port
- "80"
- --log-level
- info
- --log-level-http
- info
- --log-requests
- --log-requests-level
- "0"
- --log-requests-format
- json
- --log-requests-target
- stdout
- --enable-metrics
- --enable-request-time-stats-logging
- --enable-cache-report
- --log-requests
sglang 是命令行程序，serve 是启动推理服务的子命令。后面的 args 列表作为参数传给它。
这里的列表不是 Shell 脚本：每一项是一个独立的命令行参数。例如 --tp 和 "4" 是两个参数，程序收到的值是 4，不包含 YAML 的引号。以 # 开头的内容是注释，不会传给 SGLang；261029、2610291 等标记不影响运行。
二、模型、并行与显存
1. --model-path /data/model
从 /data/model 加载模型。这里是运行环境内部的路径；如果服务运行在容器中，就要保证模型文件已经挂载或放入容器内的这个目录。
该参数既可以接收本地目录，也可以接收 Hugging Face 仓库 ID。本配置使用本地目录，但仅凭目录名无法判断模型架构、权重精度和上下文长度。
2. --tp "4"
设置张量并行度为 4。张量并行将模型中的张量计算拆分到多个 GPU rank 上，共同完成一次推理。
它不表示启动 4 个独立模型副本。多卡之间需要通信，实际收益与模型大小、并发量和 GPU 互连有关。
3. --ep "4"
设置专家并行度为 4，用于 MoE（混合专家）模型，将专家分布到不同 rank 上执行。
TP 和 EP 负责不同层面的切分，不能直接相乘计算 GPU 数量。常见的单机 TP=4、EP=4 部署是在同一组 4 张 GPU 上分别组织张量计算和专家计算，不是必须使用 16 张卡。具体可用组合仍受模型和 MoE 执行后端限制。[1]
4. --mem-fraction-static "0.85"
将静态显存分配比例设为 0.85。静态分配主要包括模型权重和 KV Cache 内存池；混合架构还需要考虑循环状态等内存池。
这不是“KV Cache 独占 85% 显存”，也不是进程总显存占用的硬上限。运行过程中仍需要激活、临时工作区和 CUDA Graph 等空间。减小该值通常会缩小可分配的缓存池，为运行时留出更多余量。[1]
三、HiCache 与前缀缓存
5. --enable-hierarchical-cache
开启 HiCache，将前缀缓存从 GPU 显存扩展到主机内存。已经缓存的前缀离开 GPU 后，后续请求仍有机会从主机内存恢复，减少重复的 Prefill 计算。
这里保存的是 Token 前缀对应的计算状态，不是按会话 ID 保存聊天文本。历史对话或公共提示词能否复用，取决于请求是否形成可匹配的 Token 前缀；含义相近但 Token 不同的内容不能据此命中。
当前启动参数只配置了 GPU 与主机内存两级缓存，没有指定 --hicache-storage-backend mooncake 或其他外部存储后端，因此不能把它描述为已经接入 Mooncake 的跨实例共享缓存。[2][3]
6. --hicache-size "64"
指定主机侧 HiCache 内存池的容量，单位按官方参数说明为 GB。显式设置该值时，会覆盖按 --hicache-ratio 计算容量的方式。
官方设计文档说明，这个容量按 rank 分配，不是整组 TP 共用一个 64 GB 池。按 4 个 rank 各分配 64 GB 估算，主机缓存池的容量预算约为 256 GB，此外还需要操作系统、服务进程及其他内存开销。实际分配量会受到模型缓存池组成、页对齐和版本实现影响，应查看启动日志。[3]
原注释写的是：
# 每个 TP 进程 8 GB，TP=4 合计约 32 GB
它与实际值 "64" 不一致，不能用这条注释估算当前配置的内存需求。本文保留原参数值，只指出冲突。
对于混合注意力模型，主机缓存还可能包含循环状态池，不能只看普通 KV 数据的容量。官方实践文档也提醒：循环状态池先耗尽时，即使 KV 仍在主机内存中，相应前缀也可能无法复用。[2]
7. --hicache-write-policy write_through
选择写穿策略：缓存数据进入可备份的阶段后，向主机缓存保留副本，而不是等 GPU 缓存被驱逐时才备份。
这种方式让后续请求更有机会从主机缓存恢复，但也会增加 GPU 到主机的传输量，并占用主机缓存空间。它不表示每生成一个 Token 都同步写一次磁盘，也不提供持久化保证。[2][3]
8. --hicache-io-backend kernel
使用 GPU 辅助的 I/O kernel，在 GPU 与主机内存之间搬运 KV Cache。
这里的 kernel 指 GPU 数据搬运内核，不是 Linux 内核缓存，也不是 Mooncake 的网络传输协议。[3]
9. --hicache-mem-layout page_first
将主机缓存池设置为页优先布局，按缓存页组织数据，便于按页存取和传输。
它改变的是主机内存中缓存数据的排列方式，不改变模型的注意力语义。官方实践文档将 page_first 与 kernel I/O 后端配套使用；本配置选择的正是这一组合。[2]
10. --page-size "64"
设置每个缓存页容纳 64 个 Token。这里的单位是 Token，不是字节、KB，也不是操作系统的内存页大小。
页大小影响缓存分配和前缀匹配的粒度。较大的页通常可以减少元数据和小块 I/O 开销，但前缀不足一页或只部分匹配时，可复用的范围也会受页粒度限制。它不决定模型的最大上下文长度。[3]
11. --mamba-radix-cache-strategy extra_buffer
为采用 Mamba 式状态管理的混合模型选择 extra_buffer 前缀缓存策略。SGLang 的相关管理路径也用于部分 GDN、KDA 等线性注意力模型。
该策略额外分配状态缓冲区，用于跟踪和缓存循环状态，并支持计算与调度重叠。代价是增加状态内存占用，可能影响可容纳的并发请求数。具体占用与模型以及是否启用推测解码有关，不能统一按固定倍数估算。[1]
它与普通注意力的 KV Cache 不是同一类数据，也不表示给 HiCache 额外增加了固定大小的主机缓存。
四、缓存精度与 Prefill 分块
12. --kv-cache-dtype fp8_e4m3
将 KV Cache 的存储类型设置为 FP8 E4M3。FP8 是 8 位浮点格式，E4M3 使用 4 位指数和 3 位尾数。
与 BF16 或 FP16 存储相比，KV 数据本体所需空间更小，但完整缓存池还可能包含缩放参数、对齐和其他数据，不能把整个服务的显存占用直接理解为减半。
这个参数不修改模型权重精度。是否可用、如何处理缩放，以及对输出质量的影响，需要结合模型和注意力后端判断，不能仅凭启用 FP8 就认定没有精度变化。[1][5]
13. --qsa-indexer-dtype fp8_e4m3
设置 QSA（Qwen Sparse Attention）索引器的压缩缓存和索引查询的数据类型。索引器用于对候选块评分，帮助稀疏注意力选择要访问的区域。
当前官方源码说明，fp8_e4m3 会将这部分数据存为 E4M3，并使用 FP8 矩阵乘法为块评分；该路径要求 CUDA SM90 或更新架构。[5]
它与 --kv-cache-dtype 分别控制不同的数据：前者是 QSA 索引器相关数据，后者是主 KV Cache。设置其中一个不会自动完成另一个的设置。这个参数也不会把普通注意力模型变成 QSA 模型。
14. --chunked-prefill-size "8192"
设置分块 Prefill 的单块 Token 上限为 8192。长输入可以拆成多个块处理，不必在一个 Prefill 块中处理全部输入。
减小块大小通常能降低 Prefill 阶段的峰值显存需求，但会改变调度和执行开销。这里的 8192 不是最大输入长度，也不是最大输出长度；模型的上下文限制由其他配置决定。[1]
五、线性注意力执行后端与状态精度
下面三个 linear-attn 参数分别控制不同执行阶段，不是重复设置。它们只控制适用的线性注意力运算，不表示模型中所有注意力层都统一使用该后端。[4]
15. --linear-attn-prefill-backend flashinfer
在线性注意力的 Prefill／Extend 阶段使用 FlashInfer 后端，处理新输入或扩展的上下文。
它指定的是实现后端，不保证在任意 GPU、任意状态精度和任意模型上都可用，也不能据此断言一定比其他后端快。
16. --linear-attn-decode-backend flashinfer
在线性注意力的 Decode 阶段使用 FlashInfer 后端，用于生成过程中更新循环状态。
它与 Prefill 后端独立设置，因为处理长段输入与逐步解码的计算形态不同。
17. --linear-attn-verify-backend triton
在线性注意力的推测解码目标模型验证阶段使用 Triton 后端。
推测解码先提出候选 Token，再由目标模型验证；这里控制的是验证阶段的线性注意力运算。虽然前两个阶段选择了 FlashInfer，验证阶段仍被显式指定为 Triton。这是分阶段选用不同实现，不是同一个配置被覆盖。
18. --mamba-ssm-dtype bfloat16
将 Mamba 缓存中的 SSM／循环状态设置为 BF16 存储。BF16 是 16 位浮点格式。
它不改变模型的全部计算精度，也不控制普通 KV Cache 的类型。相较 FP32，BF16 状态数据本体占用更少，但精度和后端兼容性仍需结合模型验证。
因此，本配置可以同时出现 FP8 KV Cache、FP8 QSA 索引器数据和 BF16 循环状态：三者对应不同的数据结构。[4][5]
六、推测解码
推测解码先由草稿路径提出候选，再由目标模型验证。接受的候选可以减少逐 Token 执行目标模型的轮数；不被接受的部分需要修正。收益取决于接受率、验证成本和负载，不能把候选数量直接当作加速倍数。[6]
19. --speculative-algorithm NEXTN
选择 NEXTN 推测解码入口。当前官方参数参考将 NEXTN 标为 EAGLE 的别名，支持 MTP 的模型也会使用这类草稿与验证流程。[6]
能否使用模型自带的 MTP 权重，以及是否需要另行提供草稿模型路径，取决于模型和版本。原配置没有指定独立草稿模型，不能只根据这个参数认定任意模型都能直接启用推测解码。
20. --speculative-num-steps "3"
将草稿生成的步数设为 3，控制一次推测轮次中自回归草稿展开的深度。
它不是整个请求只生成 3 个 Token，也不是目标模型最终必然接受 3 个 Token。
21. --speculative-eagle-topk "1"
将每个草稿步骤保留的候选分支数设为 1，形成单分支候选链，而不是展开多分支候选树。
这里的 topk 是推测解码的候选分支参数，不是客户端请求中用于控制采样范围的 top_k。
22. --speculative-num-draft-tokens "4"
设置一次推测验证使用的候选 Token 容量。官方文档将该参数解释为并行验证容量；当 topk=1 时，它会调整为 num_steps + 1。
本配置中 3 步、单分支、容量 4 与这条关系一致。不要将它解释为“额外做 4 步草稿生成”，也不要理解为每轮固定向客户端返回 4 个 Token。实际输出取决于验证结果。[6]
七、响应解析与监听地址
23. --reasoning-parser auto
自动选择适合模型的推理内容解析器。解析器根据模型输出格式，将思考内容与最终回答分开，通常在兼容接口中分别放入 reasoning_content 和 content 等字段。
当前源码说明，自动选择会参考聊天模板或检查点元数据。这个参数负责解析已有输出，不负责让普通模型获得推理能力，也不等于打开或关闭模型的思考模式。[1][7]
24. --tool-call-parser auto
自动选择工具调用解析器，将模型输出中的工具调用格式解析为接口中的结构化工具调用信息，例如 tool_calls。
它不负责实际执行工具。工具执行和结果回传仍由调用服务的应用完成；模型也需要具备相应的工具调用能力。[1][8]
25. --host 0.0.0.0
让 HTTP 服务监听运行环境内的所有 IPv4 网络接口，而不是只监听回环地址。
0.0.0.0 是监听地址，不是客户端应填写的目标地址。在容器中，它也不代表端口已经发布到宿主机或公网；外部访问还取决于端口映射、Service、网关和网络策略。这个参数本身不提供认证或 TLS。
26. --port "80"
设置 SGLang HTTP 服务的监听端口为 80。
这是进程实际绑定的端口，不会自动创建容器端口映射或 Kubernetes Service。端口 80 属于低端口，进程能否绑定取决于运行用户、能力配置及系统的非特权端口设置。
八、日志、指标与缓存统计
27. --log-level info
将服务通用日志级别设为 info，用于查看启动、运行状态和普通提示等信息；warning、error 等更高级别日志也会保留。
它控制日志严重程度，不控制请求正文记录多少。
28. --log-level-http info
将 HTTP 服务日志级别设为 info，与通用日志级别分开指定。
HTTP 访问日志与下面的请求内容日志不是一回事：前者主要用于查看接口访问情况，后者由 --log-requests 及其配套参数控制。
29. --log-requests
开启请求日志。实际记录的字段由 --log-requests-level 决定，格式和输出位置分别由后面的参数控制。
原配置在末尾又写了一次相同开关。按官方布尔开关定义，它不会因此变成双倍日志；重复项没有增加配置含义。
30. --log-requests-level "0"
设置请求日志的详细程度为 0，只记录请求元数据，不记录采样参数，也不记录输入和输出正文。
这里的 0 不是关闭请求日志。官方对各级别的定义如下：[1]
| 级别 | 记录内容 |
|---|---|
0 |
元数据，不含采样参数 |
1 |
元数据和采样参数 |
2 |
元数据、采样参数及部分输入输出 |
3 |
元数据、采样参数及完整输入输出 |
因此，不能把本配置描述为“记录了全部对话内容”。如果以后提高详细程度，需要同时考虑提示词、工具参数和模型输出进入日志后的访问权限与保留期限。
31. --log-requests-format json
将请求日志设置为 JSON 格式，便于日志系统按字段检索和处理。
它只指定请求日志格式，不表示启动日志、HTTP 访问日志以及其他组件日志也全部变成 JSON。
32. --log-requests-target stdout
将请求日志写到标准输出，便于容器运行时或外部日志采集程序收集。
标准输出不是持久化存储。日志是否落盘、保留多久以及如何轮转，取决于运行环境和采集系统。
33. --enable-metrics
开启服务指标暴露，供 Prometheus 等监控系统采集。SGLang 通常通过 /metrics 提供指标，具体名称和可用统计项以所用版本为准。
开启指标不等于已经配置好采集、存储、看板和告警，这些工作由外部监控系统完成。
34. --enable-request-time-stats-logging
开启逐请求的时间统计日志，用于查看请求处理耗时。
它与请求正文日志详细程度是不同的开关；--log-requests-level 0 不等于关闭时间统计。具体输出哪些时间字段，应查看当前版本的实际日志，不能仅凭参数名认定其中包含全部阶段的精确耗时。[1]
35. --enable-cache-report
在 OpenAI 兼容接口的请求响应中报告缓存 Token 数。官方参数文档将其位置标为 usage.prompt_tokens_details，用于说明输入中有多少 Token 复用了缓存。[1]
它是响应统计开关，不负责开启 HiCache，也不保证每个请求都命中缓存。仅凭这个统计项，也不能判断缓存来自 GPU、主机内存还是外部存储。
九、使用这份配置时要核对的内容
最先核对主机内存预算：原来的“8 GB × 4”注释与 --hicache-size 64 冲突。应以参数值、实际 rank 数和启动日志中的缓存池容量为准，不能按原注释预留 32 GB 就结束容量评估。
其次核对模型和运行环境是否支持 QSA、BF16 循环状态、指定的 FlashInfer／Triton 后端及 NEXTN 推测解码。这些参数分别有定义，不代表它们在任意版本和硬件上都能组合使用。
可以在实际部署镜像内查看版本和参数帮助：
python -c 'import importlib.metadata; print(importlib.metadata.version("sglang"))'
sglang serve --help
帮助信息只能确认命令行参数是否存在，不能证明模型加载、内存分配和推理路径可用。仍需通过实际启动、一次生成请求，以及携带相同长前缀的重复请求，检查服务运行和缓存报告；推测解码还应结合服务日志观察实际接受情况。
本文未修改原配置，也未将它作为部署清单执行。当前编写环境没有可用的 sglang 命令，未验证模型加载、显存与主机内存分配或推理性能。
参考资料
- SGLang Server Arguments：通用参数、并行、内存、日志和缓存报告。
- SGLang HiCache Best Practices：缓存池、布局组合、混合模型状态池及外部存储配置。
- HiCache System Design and Optimization：缓存层级、每 rank 容量、页粒度和写入策略。
- 官方源码：执行后端与 Mamba 参数：线性注意力 Prefill、Decode、Verify 后端及状态精度。
- 官方源码：模型与缓存精度参数：KV Cache 和 QSA 索引器的数据类型。
- Speculative Decoding：NEXTN、MTP、草稿步数、分支数与验证容量。
- Reasoning Parser：思考内容与回答的解析。
- Tool Parser：工具调用格式解析。