# Qwen 通义千问 API：模型 ID、思考模式开关、思考预算与报错

Source: https://ofox.ai/zh/docs/develop/models/qwen

阿里云通义千问的文本模型，包括 Qwen3.8、Qwen3.7、Qwen3.6 系列与 Qwen Flash、Qwen Plus。通过 OpenAI 兼容接口调用，Qwen3.x 系列同时支持 Anthropic 原生接口。生图模型见 [Qwen-Image](https://ofox.ai/zh/docs/develop/models/qwen-image)。

## 常见任务

- [控制思考](#thinking) — 关闭思考或限制思考长度，避免请求过慢。
- [图片输入](#vision) — 哪些模型支持识图。
- [在 Claude Code 中使用](#anthropic) — 通过 Anthropic 接口调用 Qwen。
- [报错排查](#errors) — 协议不支持、图片输入报错、回答为空。

## 模型
完整的模型列表与实时价格请参阅[模型页](https://ofox.ai/zh/models?provider=qwen)，也可通过 [Models API](https://ofox.ai/zh/docs/api/openai/models) 查询。模型 ID 可省略 `qwen/` 前缀。

**常用模型 ID（调用时原样复制）**

- Qwen3.8 Max: `qwen/qwen3.8-max` — 支持图片输入
- Qwen3.8 Flash: `qwen/qwen3.8-flash` — 支持图片输入
- Qwen3.7 Plus: `qwen/qwen3.7-plus` — 支持图片输入
- Qwen Flash: `qwen/qwen-flash` — 默认不思考，仅文本

| 能力 | 支持的模型 |
|---|---|
| 图片输入 | Qwen3.8 Max、3.8 Flash、3.8 27B、3.7 Plus、3.6 Flash |
| Anthropic 原生接口 | Qwen3.8、3.7、3.6 系列，Qwen Flash |
| Responses 接口 | Qwen3.8、3.7 系列，Qwen Flash 等，以 Models API 的 `supported_endpoints` 为准 |

Qwen 模型由阿里云百炼提供，包括国内站（`aliyun`）与国际站（`alicloud`）两个供应商，默认自动选择。指定方法见[供应商路由](https://ofox.ai/zh/docs/develop/advanced/provider-routing)。

## 调用示例

**Python**

```python filename="qwen_basic.py"
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])

resp = client.chat.completions.create(
    model="qwen/qwen3.8-flash",
    messages=[{"role": "user", "content": "用一句话解释什么是幂等性。"}],
    extra_body={"enable_thinking": False},
)
print(resp.choices[0].message.content)
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.ai/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.8-flash",
    "messages": [{"role": "user", "content": "用一句话解释什么是幂等性。"}],
    "enable_thinking": false
  }'
```

## 思考模式

**要点**:Qwen3.x 系列默认开启思考，复杂问题可能思考数万 token、耗时数分钟。请按需关闭，或用 thinking_budget 限制思考长度。

| 模型 | 默认 | 关闭思考 | 开启思考 |
|---|---|---|---|
| Qwen3.8、3.7、3.6 系列 | 开启 | `"enable_thinking": false` | 默认即开启 |
| Qwen Flash、Qwen Plus | 关闭 | 默认即关闭 | `"enable_thinking": true` |

实测同一道数学题：Qwen3.8 Flash 默认思考约 5800 token、耗时约 1.5 分钟，Qwen3.6 Flash 默认思考超过 3 万 token、耗时 4 分钟以上；关闭思考后均在数秒内返回。

### 限制思考长度
需要思考但希望控制耗时与费用时，传入 `thinking_budget`（思考 token 上限）：

```python filename="qwen_thinking_budget.py"
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])

resp = client.chat.completions.create(
    model="qwen/qwen3.8-flash",
    messages=[{"role": "user", "content": "找出所有小于 50 的正整数 n，使 n² + n + 41 不是质数。"}],
    extra_body={"enable_thinking": True, "thinking_budget": 1000},
)
msg = resp.choices[0].message
details = getattr(msg, "reasoning_details", None) or []
print("[思考]", "".join(d.get("text", "") for d in details)[:200], "…")
print("[回答]", msg.content)
print("思考 token:", resp.usage.completion_tokens_details.reasoning_tokens)
```

- 实测 `thinking_budget` 严格生效：设为 200 时，思考 token 恰为 200。
- `enable_thinking`、`thinking_budget` 不是 OpenAI SDK 的标准参数，请放在 `extra_body` 中；直接发送 HTTP 请求时放在请求体顶层。
- 思考 token 按输出单价计费，数量见 `usage.completion_tokens_details.reasoning_tokens`。

### 读取思考内容
- 流式响应中，思考内容位于 `delta.reasoning_content`，与阿里云百炼官方 API 一致。
- 非流式响应中，思考内容位于 `message.reasoning_details`，请将各项的 `text` 依次拼接（见上方示例）。

## 图片输入
支持图片输入的模型使用标准的 `image_url` 内容块：

```python filename="qwen_vision.py"
import base64
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])
img_b64 = base64.b64encode(open("photo.png", "rb").read()).decode()

resp = client.chat.completions.create(
    model="qwen/qwen3.8-flash",
    messages=[{"role": "user", "content": [
        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_b64}"}},
        {"type": "text", "text": "描述这张图片。"},
    ]}],
    extra_body={"enable_thinking": False},
)
print(resp.choices[0].message.content)
```

Qwen3.7 Max、Qwen Plus、Qwen Flash 仅支持文本，请改用上表中支持图片输入的模型。

## 在 Claude Code 中使用
Qwen3.x 系列与 Qwen Flash 支持 Anthropic 原生接口，地址为 `https://api.ofox.ai/anthropic`：

**Claude Code 配置值**

- ANTHROPIC_BASE_URL: `https://api.ofox.ai/anthropic`
- ANTHROPIC_AUTH_TOKEN: 粘贴你的 OfoxAI API Key
- ANTHROPIC_MODEL: `qwen/qwen3.8-max`

- 通过 Anthropic 接口调用时，思考内容以 `thinking` 块返回。
- Qwen3.8 系列思考量较大，请设置足够大的 `max_tokens`。实测 `max_tokens` 为 4000 时，响应可能只有 `thinking` 块而没有回答。
- Qwen Plus 不支持 Anthropic 接口，调用返回 `protocol_not_supported`。

Claude Code 的完整配置步骤见 [Claude Code 配置](https://ofox.ai/zh/docs/integrations/claude-code)。

## JSON 输出与工具调用
`response_format` 支持 `{"type": "json_object"}` 与 `{"type": "json_schema", ...}`；工具调用使用标准的 `tools` 参数。使用 `json_object` 时，请在提示词中写明「以 JSON 返回」及所需字段。写法见[结构化输出](https://ofox.ai/zh/docs/develop/guides/structured-output)与[函数调用](https://ofox.ai/zh/docs/develop/guides/function-calling)。

## 提示缓存
Qwen 自动缓存重复的请求前缀，无需修改请求。命中量见 `usage.prompt_tokens_details.cached_tokens`，命中部分按缓存读取单价计费。缓存为尽力而为，前缀相同的请求也可能未命中。

## 常见报错

**要点**:请求很慢或回答为空，多半与默认开启的思考有关；不需要思考时请关闭。

| HTTP · type | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 400 `invalid_request_error` | 包含 `The provided messages input is invalid. The error info is [Unexpected item type in content.]` | 向仅支持文本的模型（如 Qwen3.7 Max）传入了图片 | 改用支持图片输入的模型，见[图片输入](#vision) |
| 400 `protocol_not_supported` | `Model 'qwen/qwen-plus' does not support the 'anthropic' protocol on this platform.` | 该模型不支持 Anthropic 接口 | 改用 OpenAI 兼容接口，或改用 Qwen3.x 系列 |
| 404 `model_not_found` | `Model 'qwen/qwen9-max' not found` | 模型 ID 拼写错误 | 从本页复制模型 ID |
| 200，回答为空或只有思考内容 | — | 思考用尽了输出额度 | 增大 `max_tokens`、设置 `thinking_budget`，或关闭思考 |
| 请求超时 | — | 默认开启思考，复杂问题耗时较长 | 关闭思考、设置 `thinking_budget`、使用流式输出，或将客户端超时设置为 600 秒以上 |

其他通用错误见[错误处理](https://ofox.ai/zh/docs/develop/guides/error-handling)。

## 官方文档
- [阿里云百炼 · 模型列表](https://help.aliyun.com/zh/model-studio/models)
- [阿里云百炼 · 深度思考](https://help.aliyun.com/zh/model-studio/deep-thinking)
- [阿里云百炼 · OpenAI 兼容](https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope)

官方文档描述的是直连阿里云百炼时的行为。在 OfoxAI 上调用时，模型 ID 与接口地址以本页为准。

## 常见问题

**Qwen 的模型 ID 怎么写？**

标准写法为 qwen/qwen3.8-flash，也可以省略 qwen/ 前缀。

**Qwen 怎么关闭思考？**

传 "enable_thinking": false，OpenAI SDK 中放在 extra_body 里。Qwen3.8、3.7、3.6 系列默认开启思考，Qwen Flash、Qwen Plus 默认关闭。

**Qwen 响应很慢，等了好几分钟？**

Qwen3.x 系列默认开启思考，复杂问题可能思考数万 token。请关闭思考，或用 thinking_budget 限制思考长度，例如 "thinking_budget": 1000。

**Qwen 的 thinking_budget 怎么用？**

与 "enable_thinking": true 一起传入，值为思考 token 上限，例如 1000。实测严格生效。

**Qwen 哪些模型能看图？**

Qwen3.8 Max、3.8 Flash、3.8 27B、3.7 Plus、3.6 Flash 支持图片输入。Qwen3.7 Max、Qwen Plus、Qwen Flash 仅支持文本。

**Claude Code 能用 Qwen 吗？**

能。ANTHROPIC_BASE_URL 设为 https://api.ofox.ai/anthropic，模型填 qwen/qwen3.8-max 等 Qwen3.x 系列模型。Qwen Plus 不支持 Anthropic 接口。

**Qwen 的 reasoning_content 在哪里？**

流式响应中位于 delta.reasoning_content；非流式响应中位于 message.reasoning_details，请将各项的 text 拼接。