Qwen 参数与协议差异
了解 Qwen 系列模型在兼容协议下的参数差异与使用方式。
使用 Qwen 模型时，根据本页调整所选协议的参数。完整请求和响应结构参阅 Chat Completions、Responses 和 Messages。
| 模型 | 适用范围 |
|---|
| qwen3.8-max-0902、qwen3.8-flash、qwen3.8-max | 均支持 Chat、Responses 和 Messages；共同规则合并说明，媒体入口的具体范围见下方表格 |
| 字段 | 差异说明 |
|---|
enable_thinking、reasoning_effort | 默认开启思考；有效深度为 low/medium/xhigh，默认 xhigh。minimal 映射为 low，high/max 映射为 xhigh，none 等价于关闭思考 |
thinking_budget | 不能与 reasoning_effort 同时设置，否则报错。单独指定深度时，low/medium/xhigh 分别对应 4096/16384/262144 的思考预算 |
max_tokens、max_completion_tokens | max_tokens 仅限制最终回答，官方注明即将废弃；新接入使用 max_completion_tokens，限制思考与回答的总 Token 数 |
temperature | 范围 [0,2)；思考模式下文本输入默认 1.0、视觉输入默认 0.6，低于 0.6 的值按 0.6 处理；非思考模式默认 0.7 |
top_p、top_k | top_p 范围 (0,1]，思考／非思考默认分别为 0.95/0.8。扩展字段 top_k 为非负整数，默认 20；null 或大于 100 时禁用 Top-K 策略 |
repetition_penalty | Qwen 扩展，须大于 0，默认 1.0，与 OpenAI 的两个惩罚字段不同 |
preserve_thinking | 默认开启；历史思考通过 assistant 的 reasoning_content 原字段完整回传，不要拼入 content。未回传思考内容不会因此报错 |
tool_choice | 支持 auto/none；思考模式不支持 required 或强制指定函数，非思考模式可指定函数，但 required 仍不保证调用工具 |
tool_stream | 默认 false，仅在 stream=true 时控制复杂工具参数的增量输出；Max 系列限文本场景，Flash 支持全模态场景 |
response_format | 支持 json_object/json_schema；前者要求提示词包含 JSON 关键词，后者通过 response_format.json_schema 定义结构，无需关闭思考 |
enable_search、search_options | enable_search 默认 false；search_options.forced_search 可强制搜索，本页模型使用 turbo/max 策略。include_tool_usage=true 时，实际搜索调用统计返回在 usage.x_tools |
| 字段 | 差异说明 |
|---|
reasoning.effort | 支持 none/low/medium/xhigh，默认 xhigh；minimal 映射为 low，high/max 映射为 xhigh |
enable_thinking | 兼容开关，官方建议改用 reasoning.effort，后续将停止支持；两者同时传入时，reasoning.effort 优先 |
max_output_tokens | 最小为 16，包含思考与最终回答 |
text.format | 支持 text/json_object/json_schema；JSON Schema 配置放在 text.format.json_schema 内，包含 name/schema/strict，与原版的平铺结构不同 |
tool_choice | 支持 auto/none/required 和 allowed_tools 对象；required 仅在工具列表只有一个工具时可用 |
tools | 除函数外，还支持 web_search、web_extractor、code_interpreter 等内置工具；网页抓取须搭配搜索，代码解释器须开启思考 |
store、previous_response_id、conversation | 支持服务端保存历史，store 默认 true，响应 ID 有效期为 7 天；后两个字段不能同时使用 |
background、其他扩展参数 | 不支持后台异步执行；官方 Responses Reference 未列出的 OpenAI 参数会被忽略 |
| 字段 | 差异说明 |
|---|
thinking.type | 支持 enabled/disabled，默认开启思考；不要直接套用 Claude 的 adaptive 配置 |
output_config.effort | 使用 low/medium/xhigh，默认 xhigh；high/max 映射为 xhigh，不照搬 Chat 的全部兼容映射值 |
thinking.budget_tokens | 官方注明即将废弃，新接入使用 output_config.effort；保留旧预算配置时，max_tokens 须大于该预算 |
max_tokens | 必填；Qwen3.8 中限制思考与最终回答的总 Token 数 |
temperature、messages[].role | 温度范围为 [0,2)；消息角色除 user/assistant 外，还允许 system |
tool_result.content | 使用字符串回传工具结果；对象或数组结果先序列化，不直接套用 Claude 的内容块数组结构 |
output_config.format | 支持严格 JSON Schema；使用 type: "json_schema"，Schema 放在 schema 内，additionalProperties 须为 false |
tools 中的 web_search | 搜索工具名为 web_search，类型使用 web_search_20250305 等日期后缀形式；HTTP／SDK 调用还须在 system 中加入客户端标识 x-anthropic-billing-header: cc_entrypoint=cli; |
| 字段 | 差异说明 |
|---|
| 隐式缓存 | 自动开启；相同前缀至少 1024 Token 才具备命中条件，达到长度不保证每次命中 |
| Chat／Messages 显式缓存 | 在内容块上使用 cache_control: { type: "ephemeral" }；最少 1024 Token，有效期 5 分钟，命中后重置；最多设置 4 个标记 |
| 显式缓存位置 | 系统提示词需使用内容块数组；工具定义参与前缀计算，但在工具定义上单独添加标记会被忽略。不要照搬通用 Reference 的其他 TTL 或缓存断点字段 |
| Responses Session 缓存 | Header x-dashscope-session-cache: enable 开启，默认 disable；关闭 Session 缓存不等于关闭自动隐式缓存 |
| 缓存用量 | Chat 查看 usage.prompt_tokens_details.cached_tokens；Responses 查看 usage.input_tokens_details.cached_tokens；Messages 查看 usage.cache_read_input_tokens、usage.cache_creation_input_tokens |
将 MODEL_ID 替换为平台提供的完整模型 ID，API Key 使用自己的值。
curl 'https://api.agtcloud.cn/v1/chat/completions' \
-H 'Authorization: Bearer your-api-key' \
-H 'Content-Type: application/json' \
--data '{
"model": "MODEL_ID",
"messages": [{"role": "user", "content": "用三点说明如何排查接口超时"}],
"reasoning_effort": "low",
"max_completion_tokens": 4096
}'