Qwen3.8-27B 的 vllm serve 启动命令：藏在 YaRN 那一段里

2026-08-16

拿到一个新模型仓，多数人第一件事是搜「怎么起服务」。Hugging Face 上 Qwen/Qwen3.8-27B 的 model card 里恰好有一个小节就叫 ### Serving Qwen3.8，位置在 README.md:229。按常理，命令应该在那儿。

但那一节里没有命令。

这不是我们漏看了。截至 2026-08-16，我们采集的快照是 1d4bf0f，README.md 全文 583 行、65,012 字节。我们在全文检索 vllm / sglang / tokenspeed，唯一出现完整命令行的地方不在 Quickstart，而在文档末尾的 Best Practices 里。这篇就把这件事按行号摊开讲，顺带把命令周边几处配置口径不一致的地方标出来。

一、`### Serving Qwen3.8` 这一节里究竟有什么

README.md:229-240 全文只有三样东西。

第一样是一个 [!Important] 提示块（README.md:231-234），原文写的是推理效率与吞吐在不同框架之间差异显著、建议使用最新版框架，以及在生产或高吞吐场景下建议用 SGLang、vLLM、TokenSpeed 这类专用服务引擎。注意这几句是 model card 的表述，它没有给出任何数字，我们也不做任何延伸——本文全篇不涉及性能、吞吐、延迟、显存的任何结论。

第二样是一句正文（README.md:236）：Qwen3.8 can be deployed with popular inference frameworks, e.g.:。

第三样是三条外链条目（README.md:238-240），原样是：

- [SGLang](https://www.sglang.io/): [Qwen3.8 Cookbook](https://docs.sglang.io/cookbook/autoregressive/Qwen/Qwen3.8-27B)
- [vLLM](https://vllm.ai/): [Qwen3.8 Recipe](https://recipes.vllm.ai/Qwen/Qwen3.8-27B)
- [TokenSpeed](https://lightseek.org/tokenspeed/): [Qwen3.8 Recipe](https://lightseek.org/tokenspeed/recipes/models#qwen3-8)

也就是说，「具体怎么起服务」这件事，model card 把读者转交给了三个外部文档站。我们没有访问这三个站点，本文不含它们的任何内容——所以如果你要照着起服务，真正该读的是那三份文档，不是这篇文章，也不是 model card 本身。

顺便记一句 Quickstart 段首（README.md:227）：For streamlined integration, we recommend using Qwen3.8 via APIs. 加上 README.md:10-12 那段说明——本仓提供的是 Hugging Face Transformers 格式的权重与配置文件，并称这些产物与 Transformers、vLLM、SGLang、TokenSpeed 等兼容。把这几句连起来看，Quickstart 的重心确实落在「怎么用 API 调」，而不是「怎么把服务拉起来」。

二、唯一的三条 serve 命令，在 `## Best Practices` 的第 3 条

## Best Practices 起始于 README.md:496，第 3 条 “Processing Ultra-Long Texts” 覆盖 README.md:514-558。三条命令分别在：

框架	行号	段首说明句
vLLM	`README.md:540-543`	`For vLLM, you can use`
SGLang	`README.md:545-548`	`For SGLang, you can use`
TokenSpeed	`README.md:550-553`	`For TokenSpeed, you can use`

vLLM 那条原样照抄如下：

VLLM_ALLOW_LONG_MAX_MODEL_LEN=1 vllm serve ... --hf-overrides '{"text_config": {"rope_parameters": {"mrope_interleaved": true, "mrope_section": [11, 11, 10], "rope_type": "yarn", "rope_theta": 10000000, "partial_rotary_factor": 0.25, "factor": 4.0, "original_max_position_embeddings": 262144}}}' --max-model-len 1000000

SGLang 侧对应的是 SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1 python -m sglang.launch_server ... --json-model-override-args '...' --context-length 1000000，TokenSpeed 侧是 TOKENSPEED_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1 tokenspeed serve ... --hf-overrides '...' --max-model-len 1000000，三条里的 JSON 内容完全一致，差异只在环境变量名、可执行入口、以及上下文长度参数叫 --max-model-len 还是 --context-length。

这里有个很容易吃亏的细节：命令里那个 ... 是 README 原文就带着的省略号，不是我们为了排版省掉的东西。 README 没有说明 ... 处应该填什么，比如模型路径或模型名。换句话说，这三条命令不能直接复制粘贴运行。

还有一点值得先说破：这三条命令的语境是「把上下文扩到 1M」，不是「常规启动」。README.md:514 那条的主题是超长文本处理，前提是总长度（输入加输出）超出原生支持的范围。你要是只想常规起个服务，照抄这条命令等于顺手把 YaRN 一起开了，而 README 在同一节末尾明确不建议这么干（下文第四节）。

三、同一件事的另一种做法：直接改 `config.json`

Best Practices 第 3 条在给命令之前，先给了「改配置文件」这条路（README.md:519-536）。前置说明句在 README.md:521：把 config.json 里 text_config 下的 rope_parameters 字段改成：

{
    "mrope_interleaved": true,
    "mrope_section": [
        11,
        11,
        10
    ],
    "rope_type": "yarn",
    "rope_theta": 10000000,
    "partial_rotary_factor": 0.25,
    "factor": 4.0,
    "original_max_position_embeddings": 262144,
}

这里只陈述一个文本形态上的事实：README.md:534 这一行 "original_max_position_embeddings": 262144, 之后紧跟着的就是 }，也就是这段 JSON 片段带尾随逗号。我们只记录文本长什么样，不推断它会造成什么。

四、把 README 的建议值和仓库实际值放在一起看

如果你打算按上面那段改 config.json，有几处对不上的口径最好先知道，因为这直接决定你「改」的是什么。

rope_type： README.md:530 建议改成 "yarn"；仓库 config.json:113 实际发布的值是 "rope_type": "default"。两处不同。

factor 与 original_max_position_embeddings： README 建议里有 "factor": 4.0（README.md:533）和 "original_max_position_embeddings": 262144（README.md:534）这两项；而在仓库 config.json 的 rope_parameters 里（config.json:104-114），这两个键都不存在。也就是说这两项是新增而不是修改。

两处一致的部分： mrope_interleaved: true、mrope_section: [11, 11, 10]、rope_theta: 10000000、partial_rotary_factor: 0.25 这四项，README 建议值与仓库实际值相同。

按上面的规矩，我们只陈述差异并给出两处的具体位置，不推断哪一处「才是对的」，也不推断为什么会这样。你自己动手时以你拉下来的仓库当前内容为准。

五、YaRN 后面那个 `[!NOTE]` 不要跳过

README.md:555-558 的提示块原文说了三件事：所有主流开源框架实现的都是静态 YaRN，缩放因子不随输入长度变化，这可能影响较短文本上的表现（原文用了加粗）；因此建议只在确实需要处理长上下文时才改 rope_parameters；并且建议按需调整 factor——原文举的例子是，如果你的应用典型上下文长度是 524,288 tokens，把 factor 设为 2.0 会更合适。

这三句都是 model card 自述，我们没有验证过。这里能给出的唯一可操作结论是：该把 factor 调成多少取决于你的用法，README 只给了一个举例，没有给通用值。

顺带把上下文长度的三个口径也摆一下，因为它们经常被混着引用：README.md:53 写的是原生 262,144、可扩展到 1,000,000 tokens；config.json:93 的 max_position_embeddings 是 262144；tokenizer_config.json 的 model_max_length 也是 262144。而 README.md:16 说的 1M 默认上下文，说的是托管版（Qwen Cloud）的特性，同一句里还写着 The service is coming soon. Stay tuned for updates.——我们采集时那是「即将推出」状态，不能当成现有能力来规划。

六、另一处「命令不存在」：`--media-io-kwargs`

同一个 model card 的 Video Input 示例里，README.md:405 有一行注释提到 When vLLM is launched with --media-io-kwargs '{"video": {"num_frames": -1}}'，视频抽帧就可以通过 extra_body 配置。但 README 全文里那条 vllm serve 命令（也就是第二节那条 YaRN 命令）并不包含 --media-io-kwargs，别处也没有给出带这个参数的完整启动命令。另外 README.md:405-417 那一整段——包括带 mm_processor_kwargs 的那次调用——在 README 里是注释状态，每一行都以 # 开头，不是会执行的代码。README.md:407 还写着这项能力目前只在 vLLM 支持。

所以如果你要开视频抽帧配置，--media-io-kwargs 这个参数怎么拼进启动命令，得去第一节那三个框架文档站找，model card 里核不到。关于视频输入与两个预处理配置文件的字段细节，我们另有一篇专门讲。

七、想找启动命令时，一套可执行的判定动作

把上面的东西收成几步，方便你下次自己核：

先在 model card 全文搜 vllm serve、sglang.launch_server、tokenspeed serve 三个字符串。截至 2026-08-16 的快照，只会命中 README.md:542、:547、:552 三处，且全在 Best Practices 的 YaRN 段落。
命中之后，先看命令里有没有 ...。有省略号就说明它不是完整命令，别直接复制。
再看命令所在小节的标题。这三条挂在 “Processing Ultra-Long Texts” 之下，不是通用启动示例——照抄会顺带启用 YaRN。
要改 config.json 之前，把 README 建议的每个键逐个和 config.json 里 text_config.rope_parameters（config.json:104-114）对一遍，分清哪些是改、哪些是新增。
真正的启动步骤去 README.md:238-240 给的三个框架文档站找；我们没有访问过它们，不替它们背书，也不代为转述。

什么情况说明你遇到的不是这篇讲的问题： 如果你在 model card 里能搜到一条不带 ...、且不在 Best Practices 段落下的启动命令，那说明上游已经更新，这篇按 1d4bf0f 快照写的内容就不适用了；如果你的问题是「服务起来了但请求报错」，那属于 API 调用参数的范畴（chat_template_kwargs、reasoning_effort、preserve_thinking 那一串），跟启动命令在哪没关系。

最后回到开头那个反直觉的地方：这份 model card 里，标题叫 Serving 的小节（README.md:229-240）没有 serve 命令，而唯一的三条 serve 命令在讲长文本处理的 README.md:540-553，且都带省略号。我们只陈述这两处位置的差异，不推断原因；记住这处位置关系，下次按行号直奔目标，能少扑一次空。

延伸阅读

本文依据 Hugging Face 仓库 Qwen/Qwen3.8-27B 的 model card 与随仓配置文件（config.json、generation_config.json、preprocessor_config.json、chat_template.jinja 等）整理，核对日 2026-08-16，对应仓库快照 1d4bf0f。本文内容为 model card 与配置文件口径，我们没有下载权重、没有部署、也没有推理过这个模型，因此不涉及生成质量、推理速度与显存占用的任何描述；文中所有评测数字均为 model card 自述，我们没有复现。模型仓库内容随上游更新而变动，请以官方最新说明为准。安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。

Qwen3.8-27B 的 vllm serve 启动命令：藏在 YaRN 那一段里

一、### Serving Qwen3.8 这一节里究竟有什么

二、唯一的三条 serve 命令，在 ## Best Practices 的第 3 条

三、同一件事的另一种做法：直接改 config.json