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.ai/v1/chat/completions' \
-H 'Authorization: Bearer your-api-key' \
-H 'Content-Type: application/json' \
--data '{
"model": "MODEL_ID",
"messages": [{"role": "user", "content": "用三點說明如何排查 API 逾時"}],
"reasoning_effort": "low",
"max_completion_tokens": 4096
}'