Qwen3.8-27B 的 YaRN 长上下文：三处配置对不上

先说清楚这篇文章的边界：Hugging Face 上的 Qwen/Qwen3.8-27B 是一个模型权重仓，里面没有建模源码可读。我们采集的时间锚点是 2026-08-16，对应快照 1d4bf0f，本地只保留了 model card 与几个文本配置文件。我们没有下载权重、没有装任何推理框架、没有推理过一个 token，所以下面全部内容都只是「这个文件里写了什么、那个文件里写了什么」的文本核对，不涉及任何运行效果。

现象：照着 Best Practices 改第一步就对不上

README.md 的 ## Best Practices 第 3 条叫 “Processing Ultra-Long Texts”（README.md:514 起）。这一条里 model card 给了两条启用 YaRN 的路径：改配置文件，或者传命令行参数。改配置文件那条的前置说明句在 README.md:521，原文是：

In the config.json file, change the rope_parameters fields in text_config to:

紧接着是这样一段 JSON（这段替换片段位于 README.md:521-536，原样照抄）：

{
    "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,
}

一句「change … to」听起来像是「把某几个字段改一改」。但你真打开仓库里那份 config.json，会发现要改的东西和要新增的东西是混在一起的，而且这段示例本身还有一个书写上的细节值得先看一眼。

两处原文摆在一起

仓库发布的 config.json 里，text_config.rope_parameters 位于 config.json:104-114，一共只有 5 个键：

字段	发布值	行号
mrope_interleaved	true	config.json:105
mrope_section	[11, 11, 10]	config.json:106-110
partial_rotary_factor	0.25	config.json:111
rope_theta	10000000	config.json:112
rope_type	"default"	config.json:113

把它跟 README.md:521-536 那段并排看，差异可以拆成三条，一条一条说，说完就停：

第一条：rope_type 两处不同。 config.json:113 写的是 "default"，README.md:530 建议改成 "yarn"。也就是说，开箱即用的那份配置不是 YaRN 配置。

第二条：README 建议的 JSON 里有两个键在发布配置里不存在。 "factor": 4.0 与 "original_max_position_embeddings": 262144（后者在 README.md:534），在 config.json:104-114 的这 5 个键里都找不到。所以这一步对你来说不是「改值」，是「加键」。

第三条：四项是一致的。 mrope_interleaved 为 true、mrope_section 为 [11, 11, 10]、rope_theta 为 10000000、partial_rotary_factor 为 0.25，两处逐字相同。

按照写「不一致」的纪律，我们只陈述这两处文本各自写了什么、位置在哪，不推断哪一处「是对的」，也不去解释为什么会这样。

那个尾随逗号

README.md:534 这一行的行尾是：

    "original_max_position_embeddings": 262144,

而 README.md:535 紧跟着就是 }。也就是说，这段示例 JSON 的最后一个成员后面带着一个逗号。按 JSON 规范，对象的最后一个成员后不允许有逗号——这一点我们只陈述这个书写事实，不推断会造成什么后果，因为那取决于你用什么工具去解析它，而这一点在本仓库里核不到。

顺带记一个对照：同一节 README.md:542、:547、:552 那三条命令行里，塞进 --hf-overrides / --json-model-override-args 的是同一份 JSON，但写成了一行，没有这个尾随逗号。两种写法都在同一节里，形态不同。

判定动作：怎么确认你遇到的就是这件事

排查这类问题不需要跑模型，全是文本比对，Windows 与 Linux/macOS 上做法一样：

1. 先看 rope_parameters 里到底有几个键。 打开仓库根目录的 config.json，定位到 text_config 下的 rope_parameters。如果你数出来是 5 个键、rope_type 是 "default"，那你手上就是我们采集时的那份发布配置，README 那段 JSON 对你来说是「改 1 个值 + 加 2 个键」。

2. 确认自己改完的文件还是合法 JSON。 如果你是把 model card 那段直接复制粘贴进去的，那个尾随逗号也会被一起带进去。用一条通用的 Python 检查就能看出来：

   python -c "import json,io; json.load(io.open('config.json',encoding='utf-8')); print('ok')"
   

   这是一条通用的 JSON 合法性检查，不是该项目官方文档给的步骤；我们也没有在改过的文件上跑过它。

3. 改完再回读一遍这 5 个键 + 2 个新键。 确认 rope_type 已经是 "yarn"、factor 与 original_max_position_embeddings 确实加进了 rope_parameters 这一层（而不是被放到了 text_config 直属层）。注意 partial_rotary_factor 在 text_config 里本来就出现了两次——一次在直属层（config.json:102），一次在 rope_parameters 子对象里（config.json:111），两处值都是 0.25，别改错层。

另一条路径：命令行参数，但命令是不完整的

如果你不想动配置文件，model card 在同一节里还给了另一条做法「Passing command line arguments」，即把这份 JSON 通过启动参数传进去。三条命令分别在 README.md:542（vLLM）、:547（SGLang）、:552（TokenSpeed），段首说明句分别是 For vLLM, you can use / For SGLang, you can use / For TokenSpeed, you can use。这里要提醒两件事：

• 三条命令里都有一个 ...，那是 README 原文就写着的省略号，不是我们省略的。README 没有说明 ... 处该填什么（比如模型路径），所以这三条命令不能直接复制运行。
• 这三条命令在本文里只是从 model card 原文照录的文本，我们没有运行过其中任何一条，具体参数以官方文档与你所用框架的 --help 实际输出为准。
• 这三条也是全篇 README 里仅有的 serve 启动命令。标题叫 ### Serving Qwen3.8 的那一小节（README.md:229-240）里其实一条启动命令都没有，只有一个提示块和三条指向外部框架文档站的链接（SGLang、vLLM、TokenSpeed）。我们没有访问这三个外链，它们的内容不在本文范围内。

model card 自己给的限定，别漏掉

YaRN 那段后面跟着一个 [!NOTE]（README.md:555-558），有三句话必须原样带上：

• 所有主流开源框架实现的都是 static YaRN，scaling factor 不随输入长度变化，原文写 potentially impacting performance on shorter texts.
• 建议仅在需要处理长上下文时才修改 rope_parameters。
• 建议按需修改 factor。原文举的例子是：如果你的应用典型上下文长度是 524,288 tokens，把 factor 设成 2.0 会更好。

这三句都是 model card 自述的说明，我们没有验证过。特别是第三条——README 只给了一个举例，没有给通用值。所以「我该把 factor 设成几」这个问题，本文不给建议：该设多少取决于你的用法，项目没有给出通用值，我们也不做任何推算。

顺带核一下上下文长度的几个口径

既然这一节是冲着长上下文去的，把相关的几个数字并排放一下（都是实读值，不做推导）：

• README.md:53 写 Context Length: 262,144 natively and extensible up to 1,000,000 tokens.
• config.json:93 的 max_position_embeddings 是 262144；tokenizer_config.json 的 model_max_length 也是 262144。
• 发布的配置文件里没有任何字段写着 1,000,000。 README.md:16 说的是托管版本会默认带 1M 上下文，而同一句里该托管服务的状态原文标注为 The service is coming soon. Stay tuned for updates.——即我们采集时它还是「即将推出」，不能当成现有能力来用。

什么情况说明不是这个原因

最后这一步不能省。以下几种情况，说明你碰到的不是本文讲的这件事：

• 你手上的 config.json 里 rope_type 已经不是 "default"，或者 rope_parameters 的键数不是 5 个——那你拿到的不是我们采集时（2026-08-16，快照 1d4bf0f）的那份配置，模型仓内容随上游更新变动，请以官方最新说明为准。
• 你的场景根本没超过 262,144 tokens——README 自己写了，建议仅在需要长上下文时才改 rope_parameters，那这一节整段都不该动。
• 你走的是命令行参数那条路径而不是改文件——尾随逗号只出现在 README.md:534 那段多行 JSON 里，三条命令行里的同一份 JSON 没有它。
• 你的问题出在这些字段运行时怎么被消费上——这是权重仓，Qwen3_5ForConditionalGeneration 的实现不在本仓，rope_type、partial_rotary_factor、mrope_section 这些字段具体如何被推理代码使用，我们一个字都核不到，也不推断。

这篇能给你的只有一件事：把 model card 里让你改的那段，和仓库里实际发布的那段，逐键摆在一起看清楚。剩下的以官方文档和你所用推理框架的实际行为为准。

延伸阅读

• 从头读起：Qwen3.8-27B 是什么：一个模型仓里有哪些文件、各自负责什么
• 本专题共 35 篇，完整分组目录见专题页
• Qwen3.8-27B 的视频 fps：README 说默认 2，配置里没有这个键
• Qwen3.8-27B 的两份 preprocessor 配置：尺寸上限与归一化参数

---

本文依据 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 自述，我们没有复现。 模型仓库内容随上游更新而变动，请以官方最新说明为准。