Qwen3.8-27B 是什么：一个模型仓里有哪些文件、各自负责什么

第一次面对 Qwen/Qwen3.8-27B 这个 Hugging Face 仓库，很多人会下意识按看 GitHub 项目的习惯去找 src/、找 examples/、找 requirements.txt——然后发现一个都没有。

这不是仓库不完整。它本来就不是代码工程，而是一个权重仓：里面装的是模型参数分片，加上一小撮告诉推理框架「该怎么把这堆参数装起来用」的配置文件。理解这一点，是看懂后面所有细节的前提。本文就按文件把这个仓库拆一遍：有哪些文件、各自负责什么、哪些说法能在文件里核到、哪些核不到。

下文所有事实的采集时间锚点是 2026-08-16，对应仓库快照 1d4bf0f。

先说清我们做了什么、没做什么

我们把这个仓库里的文本文件取到本地逐个读过，一共 8 个：README.md、LICENSE、config.json、generation_config.json、preprocessor_config.json、video_preprocessor_config.json、tokenizer_config.json、chat_template.jinja。

权重分片我们一个都没有下载，没有加载过模型，没有推理过一个 token。 所以这篇文章里不会出现任何关于生成质量、推理速度、显存占用的说法——那些我们没有依据。凡是涉及模型能力的表述，一律是「model card 原文这么写」的转述。

仓库身份：几个元数据字段

截至 2026-08-16，Hugging Face API 返回的这个仓库的元数据是：

项	值
仓库 ID	Qwen/Qwen3.8-27B
协议	apache-2.0
pipeline_tag	image-text-to-text
library	transformers
下载量 / 点赞	267,725 / 10,284
最后更新	2026-08-14T15:00:01Z

下载量和点赞数只是当天的一个截面，不能拿来推导质量、成熟度或者「值不值得用」——这是两回事。

pipeline_tag 是 image-text-to-text 而不是 text-generation，这一条比下载量有信息量得多：它对应 model card 在 Highlights 第 5 条（README.md:29）自述的 Native support for image and video understanding, from STEM diagrams and documents to hour-scale videos.

文件清单：18 个分片，加十来个配套

Hugging Face 仓库侧的文件清单可以分成六类：

类别	文件
权重分片	model-00001-of-00018.safetensors … model-00018-of-00018.safetensors，共 18 个
分片索引	model.safetensors.index.json
校验清单	crc32.txt
模型与生成配置	config.json、generation_config.json
输入预处理配置	preprocessor_config.json、video_preprocessor_config.json
分词器	tokenizer_config.json、tokenizer.json、merges.txt、vocab.json
对话模板	chat_template.jinja
文档与协议	README.md、LICENSE

关于那 18 个分片，我们能说的只有一句：它们存在，一共 18 个。单片多大、加起来多大、需要什么样的机器才装得下——我们没下载过，一个字都不推算。model.safetensors.index.json 和 crc32.txt 同理，我们只知道它们在清单里，没读过内容，所以也不描述它们的格式。

本地那 8 个文本文件的体积与行数，是可以逐个核的：

文件	字节数	行数
LICENSE	11,544	202
README.md	65,012	583
chat_template.jinja	8,952	170
config.json	4,312	140
generation_config.json	202	13
preprocessor_config.json	390	21
tokenizer_config.json	17,928	306
video_preprocessor_config.json	385	21

顺手记一个可核对的小细节：README.md 与 LICENSE 用的是 CRLF 换行（分别有 582 和 201 个 \r\n），其余 6 个文件是 LF，一个 \r\n 都没有。

各文件各自负责什么

config.json：模型结构的那份「装配图」

140 行，4,312 字节，模型结构的字面值基本都落在这个文件里。顶层结构很清楚：config.json:8-118 是 text_config，config.json:122-137 是 vision_config，剩下的是顶层字段。

如果只看一处，建议看 text_config.layer_types（config.json:21-86）。这是一个长度 64 的字符串数组，我们用 Python 统计过：linear_attention 出现 48 次，full_attention 出现 16 次，且 full_attention 所在的下标（0 起）是 3, 7, 11, 15, 19, 23, 27, 31, 35, 39, 43, 47, 51, 55, 59, 63——每隔 4 层出现一次。同一个文件里还有一个字段 full_attention_interval: 4（config.json:15）。

model card 的 Model Overview 在 README.md:41 用一行公式描述层的排布，原文逐字是：

16 × (3 × (Gated DeltaNet → FFN) → 1 × (Gated Attention → FFN))

这行和上面数出来的 48 / 16 / 间隔 4，是可以摆在一起看的两组事实。至于「所以就是 16 组、每组三线性一全注意力」——那是解读，不是仓库里写的字，我们把两边并列到这儿就停。

Model Overview 里其余的数字，绝大多数能在 config.json 里找到对应字段：hidden_size: 5120（config.json:18）对 Hidden Dimension 5120、num_hidden_layers: 64（config.json:98）对 Number of Layers 64、head_dim: 256（config.json:16）对 Gated Attention 的 Head Dimension 256、intermediate_size: 17408（config.json:20）对 FFN Intermediate Dimension 17,408、vocab_size: 248320（config.json:117）对 Token Embedding 与 LM Output 的 248,320 (Padded)、max_position_embeddings: 262144（config.json:93）对 Context Length 的 262,144 natively。

有一处对不上：README.md:48 写 Rotary Position Embedding Dimension: 64，而我们在 config.json 全文里没有找到值为 64 的字段；与旋转位置编码相关的是 partial_rotary_factor: 0.25（config.json:102 与 config.json:111 各一处）和 head_dim: 256。两处位置摆在这里，具体怎么解释我们不做推断，也不做乘除法去「算出 64」。

vision_config 那一段更值得留意：depth: 27（config.json:124）、hidden_size: 1152（:126）、num_heads: 16（:131）、intermediate_size: 4304（:129）、out_hidden_size: 5120（:133）、num_position_embeddings: 2304（:132）。而 Model Overview（README.md:32-53）从头到尾只在第 34 行用 Causal Language Model with Vision Encoder 提了一句视觉编码器，之后所有条目都挂在 Language Model 之下，没有一条视觉侧参数。想知道视觉编码器长什么样，只能翻 config.json。另外 vision_config.deepstack_visual_indexes 是个空数组 []（config.json:123），README 全文没有出现 deepstack 这个词——字面值就记到这儿，它意味着什么我们不知道，也不编。

generation_config.json：13 行的采样默认值

全文只有 202 字节：

{
    "bos_token_id": 248044,
    "do_sample": true,
    "eos_token_id": [
        248046,
        248044
    ],
    "pad_token_id": 248044,
    "temperature": 1.0,
    "top_k": 20,
    "top_p": 0.95
}

这是配置文件里的默认值，不是「你用起来会怎样」的保证。README 在 Best Practices 里推荐了两组采样参数（thinking 与 instruct 各一组，README.md:502-503），而落进这个文件的只有 thinking 那一组的三个值；README 提到的 min_p、presence_penalty、repetition_penalty 这三个键在文件里不存在。README 自己也在 README.md:255 补了一句 Please note that the support for sampling parameters varies according to inference frameworks.

两个预处理配置：图像走一份，视频走另一份

preprocessor_config.json 与 video_preprocessor_config.json 各 21 行，共同项包括 patch_size: 16、temporal_patch_size: 2、merge_size: 2、image_mean 与 image_std 都是 [0.5, 0.5, 0.5]。差别在尺寸：图像侧 size.longest_edge: 16777216、shortest_edge: 65536；视频侧 size.longest_edge: 25165824、shortest_edge: 4096。

视频这份有一处 README 自己点破的差异：README.md:561 原文说 the size parameter in the released video_preprocessor_config.json is conservatively configured，并在 README.md:563 建议改成 {"longest_edge": 469762048, "shortest_edge": 4096}。仓库里发布的值与 model card 建议的值不是一个数，这一点照实并列即可。

tokenizer_config.json：词表边界与特殊 token

306 行。关键字段：tokenizer_class 是 Qwen2Tokenizer，model_max_length 是 262144，eos_token 是 <|im_end|>，pad_token 是 <|endoftext|>，bos_token 与 unk_token 都是 null，add_bos_token 为 false。added_tokens_decoder 我们数过，一共 33 条，id 落在 248044–248076 这个连续区间。

其中几个 id 和 config.json 是能对上的：248056 = <|image_pad|> 对应 image_token_id: 248056（config.json:5），248057 = <|video_pad|> 对应 video_token_id: 248057（config.json:121），248053 = <|vision_start|>、248054 = <|vision_end|> 分别对应 vision_start_token_id、vision_end_token_id（config.json:139、config.json:138）。model_max_length 的 262144 也与 config.json 的 max_position_embeddings 和 README.md:53 的 262,144 natively 三方一致。

tokenizer.json、merges.txt、vocab.json 这三个真正装词表的文件我们没有取到本地，所以词表细节这篇不谈。

chat_template.jinja：文档说法能核到实现的地方

170 行、8,952 字节。这个文件负责把消息列表拼成模型实际吃到的字符串，也是本仓少数「README 的说法能在文件里逐字核到」的位置。

• chat_template.jinja:47：{%- set resolved_reasoning_effort = reasoning_effort|default('xhigh') %}
• chat_template.jinja:48-49：枚举校验，不在 ('xhigh', 'medium', 'low') 里就抛异常，异常文案原文写 Supported types are xhigh (default), medium, and low.
• chat_template.jinja:46：{%- if enable_thinking is undefined or enable_thinking is true %}
• chat_template.jinja:116：{%- if preserve_thinking is undefined or preserve_thinking is true or loop.index0 > ns.last_query_index %}

对照 README：README.md:259-261 写 reasoning_effort 的三档是 xhigh（默认）/ medium / low，README.md:264 写 preserve_thinking 默认开启。这两处 README 说法与模板里的枚举和默认值是一致的——在这个仓库里，这属于难得的正面样本。

README.md 与 LICENSE

README.md 65,012 字节、583 行，全文是英文（我们统计过，中日韩汉字 0 个）；有 12 个代码块、2 张 HTML 表格、15 处 http(s) 链接。顶部两个 callout 值得注意：README.md:10 写这个仓库放的是 post-trained 模型的权重与配置文件、格式是 Hugging Face Transformers 格式；README.md:12 自述兼容性清单是 Transformers / vLLM / SGLang / TokenSpeed 加一个 etc.——这是 model card 自述的兼容性，我们没有在任何框架上验证过。

README.md:15-16 的第二个 callout 提到官方有一个名为 Qwen Cloud 的 API 服务，并写明 27B 的托管版本会带 1M context length by default, official built-in tools，同时原文写着 The service is coming soon. Stay tuned for updates.。注意两件事：这些是托管服务的特性描述，不是这个开源权重仓的能力；而且原文明说服务尚未提供。

LICENSE 11,544 字节、202 行，文件结构就是 Apache License 2.0 的标准正文（LICENSE:2-4 的标题行、LICENSE:6 的 TERMS AND CONDITIONS、直到 LICENSE:179 的 APPENDIX），版权行在 LICENSE:190：Copyright 2026 Alibaba Cloud。我们在整个文件里检索过 Qwen、Acceptable Use、restriction、Tongyi、Supplement，一处都没有。model card frontmatter 的 license: apache-2.0（README.md:3）、HF API 元数据的 apache-2.0 与这份文件三方一致。具体授权范围以官方协议原文为准。

三处名字对不上的地方

翻这几个配置文件时，会撞见几个世代名并存的字面值，照实列在这里，只陈述、不推断：

• config.json:7 的 model_type 是 qwen3_5，config.json:2-4 的 architectures 是 ["Qwen3_5ForConditionalGeneration"]，config.json:94 的 text_config.model_type 是 qwen3_5_text，config.json:130 的 vision_config.model_type 也是 qwen3_5；而 README 的一级标题是 # Qwen3.8-27B（README.md:7），README.md:20 写 Built on the architectural foundation of Qwen3.5。
• preprocessor_config.json 里 processor_class 是 Qwen3VLProcessor，同一个文件里 image_processor_type 是 Qwen2VLImageProcessorFast；video_preprocessor_config.json 的 video_processor_type 是 Qwen3VLVideoProcessor；tokenizer_config.json 的 tokenizer_class 是 Qwen2Tokenizer。
• README.md:575-581 的 bibtex 条目里，title 写的是 {Qwen3.8-Max}: A New Bar for Coding and Cowork，而本仓是 Qwen3.8-27B。

再补一条位置差异：config.json:120 的 transformers_version 值是 "5.8.0.dev0"，字面上是个 dev 版号；而 README 全文没有写最低 transformers 版本要求（transformers 这个词在 README 里只出现在 frontmatter 第 2 行与第 10、12 行的兼容性表述中）。

以上都只是并列陈述两处位置的字面值。谁对谁错、为什么这样，我们不推断，也不拿它去评价这个项目。

关于上下文长度，别只看那个「1M」

README.md:53 写的是 262,144 natively and extensible up to 1,000,000 tokens.。落到配置里：max_position_embeddings 是 262144（config.json:93），tokenizer_config.json 的 model_max_length 也是 262144，而 rope_parameters.rope_type 是 "default"（config.json:113），没有 rope_scaling、没有 factor、没有 original_max_position_embeddings，config.json 全文也不出现 1000000（rope_theta 是 10000000，那是另一个数）。

model card 在 Best Practices 第 3 节（README.md:514-558）给的做法是用户自己改 config.json 或用启动参数覆盖才能启用 YaRN，示例里写的是 "rope_type": "yarn"、"factor": 4.0、"original_max_position_embeddings": 262144。同一小节的 NOTE（README.md:555-558）还写了 All the notable open-source frameworks implement static YaRN ... potentially impacting performance on shorter texts.，并建议只在确实需要处理长上下文时才改 rope_parameters。

所以准确的说法是：开箱配置是 262,144；1M 需要自行改配置或加启动参数，且 model card 自己给了告诫。 另外 README.md:516 写明 YaRN 目前由几个推理框架支持（原文点名 vLLM、SGLang、TokenSpeed）。

最后一个反直觉的地方：README 里没有下载命令

我们在整个 README.md 里检索 download，只有 1 处命中（README.md:178），而那处是 Benchmark 的脚注，讲的是评测时禁用了某些命令，与「怎么下载这个模型」无关。检索 modelscope / huggingface / safetensors / crc32 全部 0 命中。

也就是说，model card 通篇没有给出权重下载命令。## Quickstart（README.md:225）第一句就是 For streamlined integration, we recommend using Qwen3.8 via APIs.，随后 ### Serving Qwen3.8（README.md:229-241）列了 SGLang、vLLM、TokenSpeed 三个框架的官方文档入口（各带外链，我们一个都没访问过），#### Chat Completions API（README.md:270-280）给的准备步骤是 pip install -U openai 加两个环境变量：

export OPENAI_BASE_URL='<YOUR_BASE_URL>'
export OPENAI_API_KEY='<YOUR_API_KEY>'

这两行原样来自 model card，只是把 base url 与 key 换成了占位符。这些命令我们一条都没有执行过，实际写法以 model card 与你所用推理框架的官方文档为准。至于「密钥只写占位符、通过环境变量注入、不要落进任何会提交的文件」——这属于通用做法，不是 model card 里的内容。

这个文档结构本身就是信息：这个仓库定位成「权重与配置的存放处」，怎么把它部署运行，是各推理框架文档的事。你要动手前，先把上面这些文件各自负责什么弄清楚，比一上来就找启动命令更省事。

本专题全部 35 篇

下面这份目录与专题页一致，按主题分组；每篇都是独立的，可以只挑你现在要用的那几篇看。

认识、协议与仓库构成

• Qwen3.8-27B 的 config.json 里全是 qwen3_5：代际关系怎么读
• Qwen3.8-27B 的权重怎么组织：18 个分片、索引文件与 crc32
• Qwen3.8-27B 的许可实读：Apache-2.0 标准文本与那行版权
• Qwen3.8-27B 的 Citation：bibtex 标题写的是另一个型号
• Qwen3.8-27B 的上下文长度：256K、262144 还是 1M，四处口径

架构解剖：把 config.json 逐字段读完

• Qwen3.8-27B 的 64 层怎么排：全注意力恰好 16 个，下标全是 4k+3
• Qwen3.8-27B 的 Hidden Layout 公式怎么跟 layer_types 对上
• Qwen3.8-27B 的混合注意力：由 config 里哪几个字段承载
• Qwen3.8-27B 的线性注意力参数：卷积核宽度与 key/value 头数
• Qwen3.8-27B 的 GQA：24 个 Q 头配 4 个 KV 头、head_dim 是 256
• Qwen3.8-27B 的 RoPE 维度 64：config.json 里找不到对应字段
• Qwen3.8-27B 的 MTP：自述多步训练，配置里只有一层
• Qwen3.8-27B 的词表 248,320 与特殊 token：padded 是什么意思
• Qwen3.8-27B 的视觉塔 27 层：patch 16 与那个空的 deepstack 数组

Benchmark 原表与它的读法

• Qwen3.8-27B 的 Benchmark 原表照搬：两张表 25 行与确切出处
• Qwen3.8-27B 的 Benchmark 加粗口径：VL 表没说明却粗了 18 处
• Qwen3.8-27B 的评测表里，有一行两列同时被加粗
• Qwen3.8-27B 评测表里的 CI 是什么：model card 全文从未展开
• Qwen3.8-27B 评测表的对比列：有一列在多数行上是空的

部署与多模态输入

• Qwen3.8-27B 怎么部署：Serving 那一节一条启动命令都没有
• Qwen3.8-27B 的 vllm serve 启动命令：藏在 YaRN 那一段里
• Qwen3.8-27B 的文本调用示例逐行读：哪些参数是官方写的
• Qwen3.8-27B 的图像输入怎么传：示例字段与预处理配置的对应
• Qwen3.8-27B 的视频输入怎么传：那段被整体注释掉的抽帧示例
• Qwen3.8-27B 的视频 fps：README 说默认 2，配置里没有这个键
• Qwen3.8-27B 的 YaRN 长上下文：三处配置对不上
• Qwen3.8-27B 的两份 preprocessor 配置：尺寸上限与归一化参数

思考模式、对话模板与采样参数

• Qwen3.8-27B 官方推荐的采样参数，配置文件里一个都找不到
• Qwen3.8-27B 的 chat_template 逐段拆：四类消息分别怎么渲染
• Qwen3.8-27B 的 eos / bos / pad：三个配置文件里是三套值
• Qwen3.8-27B 的 preserve_thinking 控制什么、在哪一层生效
• Qwen3.8-27B 的 reasoning_effort 三档：模板里只有两档有分支
• Qwen3.8-27B 的 thinking 默认开着：怎么按请求关掉
• Qwen3.8-27B 的工具调用协议只写在模板里，README 全文 0 提及

---

本文依据 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 自述，我们没有复现。 模型仓库内容随上游更新而变动，请以官方最新说明为准。 许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。 安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。