Qwen API 由阿里云百炼（Model Studio，旧称 DashScope）提供。它同时提供 OpenAI 兼容接口和 DashScope 原生接口。对大多数团队来说，先用 OpenAI 兼容接口最省事：现有 SDK、Agent 框架和工具链通常只需要改三处——API Key、Base URL 和模型名。

真正的坑不在“能不能调通”，而在 Base URL 的地域、模型名是否有效、流式输出怎么解析，以及从 OpenAI 迁移时哪些参数不能照搬。本文用最小请求把链路跑通，再补充工具调用、报错排查和迁移清单。

说明：Qwen、通义千问、阿里云、百炼（Model Studio）、DashScope 是阿里巴巴集团及其关联公司的商标或产品名称，本文仅作技术说明，与阿里巴巴集团无隶属、代理或授权关系。Base URL、模型名、上下文长度与计费口径可能调整，请以阿里云百炼官方文档和站内模型价格为准。

一、接入前准备

开始前确认三样东西：

  • 一把可用的 API Key，且与目标地域匹配。
  • 正确的 Base URL，中国内地、国际站和网关地址不能混用。
  • 一个当前真实可用的模型名，不要照抄旧文章里的示例。

建议先用 curl 验证鉴权和网络，再接入 SDK。这样出错时容易判断是 Key、地址还是代码问题。

二、Base URL：先选地域，再选域名

OpenAI 兼容接口的路径固定为 /compatible-mode/v1，聊天接口再拼 /chat/completions。域名按地域区分，常见写法如下：

场景 OpenAI 兼容 Base URL 说明
中国内地（北京，旧共享域名） https://dashscope.aliyuncs.com/compatible-mode/v1 兼容旧代码，目前仍可用
新加坡（国际站） https://dashscope-intl.aliyuncs.com/compatible-mode/v1 国际站账号与 Key
美国弗吉尼亚 https://dashscope-us.aliyuncs.com/compatible-mode/v1 仅 IPv4，能力以文档为准
中国香港 https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 独立地域与 Key
业务空间专属 https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 生产推荐，吞吐与隔离更好
中商起航 AI 网关 https://ai.zhongshangqihang.com/v1 多模型统一入口

几个关键点。第一，API Key 与地域绑定，跨地域调用通常返回 401 和 invalid_api_key，这表示 Key 与地址不匹配，不代表 Key 失效。第二，中国内地账号与国际站账号是两套体系，Key、账单和模型列表都不通用。第三，业务空间专属域名只接受该业务空间自己的 Key，但吞吐和流量隔离更好，适合生产环境；旧共享域名则方便跨空间和快速测试。

如果团队同时使用多家模型，不想自己维护地域、额度和多套 Key，可以在中商起航 AI 网关创建统一 Key，再把 Base URL 换成上表最后一行的地址。

三、模型名怎么选

百炼的模型列表更新很快。以当前官方模型页为例，文本生成部分列出的 Qwen 模型包括 qwen3.8-max、qwen3.7-plus 和 qwen3.8-flash。从命名可以粗略理解为：max 偏能力上限，plus 偏均衡，flash 偏低延迟和成本；具体定位、上下文长度和计费以官方模型文档与模型价格页为准。

选型时不要只看“最强”。客服问答、批量分类、内容审核这类任务，用低延迟档位往往更划算；长文档分析、复杂 Agent 再上高配。把模型名做成配置项，而不是写死在代码里，后续切换会轻松很多。

还有两个容易踩的坑。旧教程里的 qwen-max、qwen-plus 等写法可能已经调整，接入前先在控制台模型列表确认；需要向量能力时用 embedding 系列（例如 qwen3.7-text-embedding），它和聊天接口的请求体不是一回事。Qwen-Audio 不支持 OpenAI 兼容协议，需要走 DashScope 原生接口。

四、用 curl 跑通第一次调用

先准备环境变量，避免 Key 出现在命令历史里：

export DASHSCOPE_API_KEY="your_key_here"

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [
      {"role": "system", "content": "你是一名简洁的技术助手。"},
      {"role": "user", "content": "用三句话解释什么是 API 网关。"}
    ],
    "temperature": 0.7
  }'

返回正常时，重点看三个字段：choices[0].message.content 是回答，usage 是本次用量，finish_reason 表示结束原因。如果返回 401，先查 Key 和地域；如果返回 404 和 ModelNotFound，先查模型名和该地域是否开通了这个模型。

五、用 Python SDK 调用与流式输出

OpenAI SDK 需要 1.0 以上版本。把 Base URL 指向百炼后，调用方式与 OpenAI 基本一致：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

stream = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "写一段产品介绍，不超过一百字。"}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

流式输出要注意：首个 chunk 可能只有角色信息，content 为空，不要假设每个 chunk 都有文本；加上 stream_options={"include_usage": True} 后，用量会出现在最后一个 chunk。HTTP 直连时响应是 SSE 格式，以 data: [DONE] 结束。用户关闭页面后，服务端应尽快取消上游请求，避免继续生成和计费。

六、工具调用与参数差异

工具调用沿用 OpenAI 的 tools 和 tool_choice 格式。模型返回 message.tool_calls 后，需要把每个调用的 function.arguments 按 JSON 解析，执行本地函数，再把结果以 role: "tool" 的消息回传。多轮流程中，每一轮请求都要带上 tools。生产环境要做参数校验、权限校验和超时控制，不能直接信任模型生成的参数。

官方兼容文档目前对工具有两条限制：只列出部分模型支持，且 tools 暂时不能与 stream=True 同时使用。模型列表和能力在持续更新，上线前务必用目标模型实测；如果业务必须边流式边调工具，可以考虑 DashScope 原生接口或把工具调用做成非流式步骤。

从 OpenAI 迁移时，还有这些参数差异要留意：

  • messages：只有 messages[0] 可以是 system 角色；user 和 assistant 一般要交替，最后一条必须是 user。
  • temperature：取值范围是 [0, 2)，官方不建议设为 0。
  • top_p：取值范围是 (0, 1.0)。
  • seed：使用无符号 64 位整数。
  • stop：数组元素不能混用 token ID 和字符串。
  • system_fingerprint：目前返回空字符串。
  • enable_search 等扩展参数：通常通过 extra_body 传入，且并非所有模型支持。
  • response_format、frequency_penalty 等字段：兼容文档未作保证，不要假设行为和 OpenAI 一致。

七、常见错误对照

现象 常见错误码 可能原因 处理方式
401 InvalidApiKey / invalid_api_key Key 错误、地域不匹配、套餐 Key 混用 核对 Key 与 Base URL 的地域和类型
404 ModelNotFound / model_not_found 模型名拼错、地域无此模型、未开通 查控制台模型列表
404 model_not_supported 模型不支持 OpenAI 兼容模式 改用 DashScope 原生接口
403 AccessDenied / Workspace.AccessDenied 空间或模型权限不足 检查业务空间授权
403 AllocationQuota.FreeTierOnly 免费额度已用完 充值或调整套餐
429 Throttling 系列 请求频率、Token 或并发超限 降并发、退避重试、申请配额
400 Arrearage 账号欠费 充值后重试
400 Range of input length... 输入超过上下文上限 压缩提示词或分段
400 DataInspectionFailed 输入或输出被内容安全拦截 调整内容后重试

重试只对 429、5xx 和网络超时有效。401、403、404 和参数错误重试不会变好，反而浪费时间和额度。排查时记录响应里的 Request ID，到控制台日志里查，会比盲猜快得多。

八、从 OpenAI 迁移的检查清单

  1. 备份现有提示词、模型参数和评测集。
  2. 新建与目标地域匹配的 Qwen Key，不要复用其他厂商的 Key。
  3. 把 Base URL 和模型名改为配置项。
  4. 检查 messages 角色规则，确保首条 system、末条 user。
  5. 检查流式解析和 usage 统计方式。
  6. 用真实工具做一轮工具调用回归测试。
  7. 用同一批样本比较输出质量、延迟和用量。
  8. 调整重试、超时和并发，观察一周再切全量。
  9. 在日志中记录 Request ID，保留回滚开关。

九、常见问题（FAQ）

1. Qwen API 兼容 OpenAI 吗？

大部分常用聊天接口兼容，但仍存在地域绑定、角色顺序、参数范围和工具调用限制等差异。建议按官方 OpenAI 兼容文档逐项验证，不要假设所有参数行为一致。

2. 中国内地和国际站能共用一个 Key 吗？

不能。两个站点的账号、Key、接入域名和账单相互独立。跨地域或跨站点调用通常会返回 401 和 invalid_api_key。

3. Base URL 该用旧域名还是业务空间专属域名？

快速测试可以用旧共享域名；生产环境建议用业务空间专属域名，吞吐和流量隔离更好。关键是 Key 必须与域名所属地域和业务空间匹配。

4. 模型名正确却返回 model_not_found 是什么原因？

常见原因是该地域没有这个模型、模型未开通、名称大小写不一致，或者访问的是已下线版本。以控制台当前模型列表为准。

5. tools 能和 stream 一起用吗？

官方兼容文档目前注明两者不能同时使用，且工具调用只列出部分模型支持。能力和限制会随模型更新，上线前用目标模型实测，或改用 DashScope 原生接口。

相关阅读