Qwen3.8-27B 的文本调用示例逐行读：哪些参数是官方写的

2026-08-16

抄示例代码最容易出的岔子，不是抄错，而是抄完之后分不清哪一行是官方写的、哪一行是自己顺手补的。等某个参数不生效，回头翻文档才发现原文根本没提过它。

这篇就干一件事：把 Hugging Face Qwen/Qwen3.8-27B 的 model card 里那段纯文本调用示例逐行摊开，标明每个参数在 README 里的确切行号，以及 README 对它说了什么、没说什么。我们没有下载权重、没有部署、也没有调用过任何接口，下文所有代码都是从 README.md 原样照抄的文本。

这段示例在 model card 的什么位置

README.md 全文 583 行（截至 2026-08-16 的快照 1d4bf0f，Python 按 read().split('\n') 计数）。## Quickstart 在第 225 行，## Best Practices 在第 496 行，这两者之间一共 6 个代码围栏块：1 个 shell 加 5 个 python。

我们要读的这一段是 ##### Text-Only Input，小节标题在 README.md:282，代码块占 README.md:284-340。它上面还有一层结构：### API Usage（README.md:243）→ #### Chat Completions API（README.md:270）→ 才是 Text-Only。

顺带说清一件事：Quickstart 段首那句原文是 For streamlined integration, we recommend using Qwen3.8 via APIs.（README.md:227）。也就是说，这段示例默认你面前已经有一个 OpenAI 兼容的服务端点，它并不负责告诉你这个端点怎么起来。

前置的两行环境变量：占位符是原文自带的

#### Chat Completions API 小节里先给了一个 shell 块（README.md:274-280），原样照抄：

pip install -U openai

# Set the following accordingly
export OPENAI_BASE_URL='your-base-url'
export OPENAI_API_KEY='your-api-key'

your-base-url 和 your-api-key 是 README 原文的占位符，不是我们替换过的。真正要填什么，README 在这一处没有说；它前面一句写的是这套 Chat Completions 接口可以配合大多数推理框架使用，也可以配合官方的托管服务（README.md:272）。我们只中立转述这一句的存在，托管服务本身在 model card 里的状态是 The service is coming soon. Stay tuned for updates.（README.md:16），也就是我们采集时它还是「即将推出」，不能当成现成能力来规划。

这两行落到实操上还有个平台差异：上面是 Linux 与 macOS 的写法。Windows 下 export 不可用，PowerShell 与 CMD 各有各的设置方式，README 没有给对应写法，这属于你自己环境里的事。示例里 client = OpenAI() 上方那行注释 # Configured by environment variables（README.md:286）说明凭据是从环境变量读的，代码里不出现具体值。至于密钥该怎么保管，那属于通用运维做法、不是 model card 的内容，本文不展开。

逐行读那段调用

示例的请求构造部分是这样的（照抄 README.md:284-340 的前半段）：

from openai import OpenAI
# Configured by environment variables
client = OpenAI()

messages = [{"role": "user", "content": "Write a Python function to merge two sorted linked lists."}]

completion = client.chat.completions.create(
    model="Qwen/Qwen3.8-27B",
    messages=messages,
    extra_body={
        "chat_template_kwargs": {
            "enable_thinking": True,  # on by default
            "preserve_thinking": True, # on by default
        },
    },
    reasoning_effort="xhigh",  # xhigh by default; supported levels are xhigh, medium, and low
    stream=True,
    stream_options={"include_usage": True},
)

这里有一条容易被忽略的分层：model、messages、reasoning_effort、stream、stream_options 是顶层参数，而 enable_thinking 与 preserve_thinking 被包了两层，先进 chat_template_kwargs，再进 extra_body。名字带 chat_template 不是随手起的，这两个键最终是给聊天模板用的。

三行行尾的注释都是 README 自带的，不是我们加的：

"enable_thinking": True, # on by default（README.md:296）
"preserve_thinking": True, # on by default（README.md:297）
reasoning_effort="xhigh", # xhigh by default; supported levels are xhigh, medium, and low（README.md:300）

三个都标了「默认就是这个值」。换句话说，这段示例把默认值显式写了一遍，属于把行为写明白，而不是在改行为。reasoning_effort 的三档在 README.md:258-261 有单独说明：xhigh 是默认，对应需要充分分析的复杂任务；medium 是准确度与速度之间的平衡；low 面向速度与成本。这是 model card 的自述，档位之间的实际差别我们没有依据评价。

preserve_thinking 在 README.md:264 另有一句：preserve_thinking is enabled by default for all workloads。要关掉它得显式传 False，那是另一个小节的事（README.md:469 起）。

至于 stream=True 和 stream_options={"include_usage": True}（README.md:301-302）——README 全文没有对这两个参数作任何说明，它们只是在示例里出现。它们属于 OpenAI Python SDK 自己的参数，是否被你那一侧的推理框架支持，得看框架文档。同样地，extra_body 本身 README 也没解释过，全文只出现 5 次，都在示例里。

流式回读为什么要判两个字段名

示例的后半段是把流式分片拼回去，其中这一段值得单独看（README.md:318-325）：

    if hasattr(delta, "reasoning_content") and delta.reasoning_content is not None:
        if not is_answering:
            print(delta.reasoning_content, end="", flush=True)
        reasoning_content += delta.reasoning_content
    elif hasattr(delta, "reasoning") and delta.reasoning is not None:
        if not is_answering:
            print(delta.reasoning, end="", flush=True)
        reasoning_content += delta.reasoning

同一份思考内容，示例准备了两个字段名去接：先试 reasoning_content，拿不到再试 reasoning。README 没有说明哪个框架返回哪一个。所以这不是可以精简掉的冗余分支——如果你只留一支，就得先确认自己那套服务端返回的是哪个字段名。

对话拼接的收尾也照抄一下（README.md:334-339）：

messages.append({
    "role": "assistant",
    "content": answer_content,
    "reasoning_content": reasoning_content,
    "reasoning": reasoning_content,
})

写回历史时两个键也都写了。这里有一处可以照实记录的差异：仓库里的 chat_template.jinja 在 :112-114 只判断 message.reasoning_content is string；我们在 chat_template.jinja 全文检索 reasoning，除 reasoning_content、reasoning_instructions、reasoning_effort 之外，没有出现单独的 message.reasoning。也就是说，示例代码写入的是两个键（README.md:334-339），模板读取条件里出现的是其中一个（chat_template.jinja:112-114）。我们只陈述这两处文本的差异，不推断运行时会怎样，也不推断原因——请求在到达模板之前是否被推理框架改写过，从这个仓库里核不出来。

同一个开关，两种写法

chat_template_kwargs 这一层包装还有个不能照抄了事的地方。model card 在两处 [!Note] 里写了同一件事：如果用的是官方托管服务的 API，除了改 model 之外，要直接写 "enable_thinking": False、"preserve_thinking": False，而不是把它们包在 chat_template_kwargs 里（README.md:466 与 README.md:493）。

这两句分别挂在 Instruct 模式与关闭 preserved thinking 的小节下，而 Text-Only 这段示例所在的位置没有重复这条提醒。所以「参数怎么写」这件事在这份 model card 里是分调用侧的：对着推理框架是一种包法，对着托管服务是另一种。抄示例之前先确认自己连的是哪一侧，否则传过去的键可能根本不会被读到。前面提过，托管服务在我们采集时标着即将推出。

采样参数：示例里没传，Tip 里有，配置文件只有一部分

这段文本示例里没有 temperature、top_p 之类的采样参数。推荐值在上一层的 [!Tip] 里（README.md:250-255），原文给了两组：思考模式 temperature=1.0、top_p=0.95、top_k=20、min_p=0.0、presence_penalty=0.0、repetition_penalty=1.0；Instruct（非思考）模式 temperature=0.7、top_p=0.80、top_k=20、min_p=0.0、presence_penalty=1.5、repetition_penalty=1.0。同一个提示块结尾还有一句 Please note that the support for sampling parameters varies according to inference frameworks.（README.md:255）。

再往下一层，仓库里的 generation_config.json 只有 12 行，其中与采样相关的是 do_sample: true（:3）、temperature: 1.0（:9）、top_k: 20（:10）、top_p: 0.95（:11）。这三个值与 README 推荐的思考模式一组一致；而 min_p、presence_penalty、repetition_penalty 三个键在这个文件里不存在。

所以「参数出自哪一层」在这里有三种答案：写在示例代码里的、写在文档提示块里的、落在 generation_config.json 里的。这三层不是同一件东西，该设成多少也取决于你的用法与所用框架，项目没有给一个通用值。

回到开头那个问题

对着 README.md:284-340 这一段，能明确归类的是：

出现在示例里的东西	出处与 README 的说明
`model="Qwen/Qwen3.8-27B"`	示例的第一个参数，`Qwen/Qwen3.8-27B` 这个字符串全文出现 8 次
`enable_thinking` / `preserve_thinking`	`README.md:296-297`，均带 `# on by default` 注释
`reasoning_effort`	`README.md:300`，三档说明在 `:258-261`
`stream` / `stream_options`	`README.md:301-302`，README 未作说明
`extra_body` / `chat_template_kwargs`	示例中使用，README 未对 `extra_body` 本身作解释
采样参数	示例未传，推荐值在 `README.md:250-255`

另外还有一层对照可以顺手做：同一份 Quickstart 里的图像示例（README.md:345-373）与视频示例（README.md:377-420）里，那次真正会执行的请求都没有传 extra_body、没有传采样参数、也没有传 reasoning_effort——只有 model 与 messages。同一篇文档里两种写法并存，你要抄哪一版，得先想清楚自己是不是需要那些参数。

最后提一句 model card 自述但我们没有验证过的说法：README.md:267 的 [!Tip] 写的是，在多轮 agent 任务里，把 reasoning effort 调低并不总能缩短整体完成时间——单轮响应可能更快，但也可能因为分析不足而出现更多失败与重试。这是文档里的表述，不是我们的结论。

延伸阅读

从头读起：Qwen3.8-27B 是什么：一个模型仓里有哪些文件、各自负责什么
本专题共 35 篇，完整分组目录见专题页
Qwen3.8-27B 的 vllm serve 启动命令：藏在 YaRN 那一段里
Qwen3.8-27B 的图像输入怎么传：示例字段与预处理配置的对应

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