通义千问 API 配置指南（阿里云百炼 OpenAI 兼容模式）

一、简介与适用场景

通义千问是国内综合能力最均衡的一线模型之一，官方入口是阿里云百炼平台（原 DashScope）。它的模型矩阵很全：文本有 qwen-plus / qwen-turbo，视觉有 qwen-vl 系列，向量有 text-embedding-v3，语音也有对应模型，一个 Key 全部搞定。

额度方面，百炼给新用户的策略是按模型分别赠送免费 token，且有有效期，而不是长期免费档。所以它更适合「先用免费额度验证效果，确认可行后转按量付费」的路径，不适合当成永久白嫖的对象。这一点要提前认清，避免额度到期后线上服务突然报错。

适合看这篇的情况：需要中文能力扎实的商用模型、已在阿里云生态内、或者需要文本与向量模型来自同一家以降低运维成本。

二、注册与获取 Key

1. 用阿里云账号登录 百炼控制台，首次进入需要开通服务。
2. 完成实名认证。阿里云的实名是账号级的，如果你之前用过阿里云，这步通常已经完成。
3. 在 API-KEY 页面创建密钥，复制 sk- 开头的字符串。
4. 到「模型广场」逐个开通你要用的模型——百炼的模型需要单独开通，未开通的模型直接调用会报无权限，这是新手最常见的卡点。

三、Base URL 与鉴权

• Base URL：https://dashscope.aliyuncs.com/compatible-mode/v1
• 鉴权方式：Authorization: Bearer sk-xxxxxxxx
• 对话端点：/chat/completions

注意路径里的 compatible-mode 段不能省。百炼同时提供原生 DashScope 协议（路径为 /api/v1/services/...）和 OpenAI 兼容协议，两者请求体结构不同。除非你要用原生独有的功能，否则一律走上面这个兼容地址。

如果你的服务部署在海外，还有一个新加坡区域的地址 https://dashscope-intl.aliyuncs.com/compatible-mode/v1，注意两个区域的 Key 不通用。

四、客户端接入示例

Cherry Studio 内置了阿里云百炼：

1. 打开「设置 → 模型服务 → 阿里云百炼」。
2. API 密钥填 sk- 字符串，API 地址保持默认。
3. 点「管理」拉取模型，只有已开通的模型才能正常调用。
4. 若用自定义供应商，地址填 https://dashscope.aliyuncs.com/compatible-mode/v1。
5. 首次测试用 qwen-turbo，速度快、消耗少。

五、代码示例

curl：

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "用一句话解释什么是 API"}]
  }'

Python：

import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "用一句话解释什么是 API"}],
)
print(resp.choices[0].message.content)

emb = client.embeddings.create(model="text-embedding-v3", input="一段待向量化的文本")
print(len(emb.data[0].embedding))

Node.js：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
});

const resp = await client.chat.completions.create({
  model: 'qwen-turbo',
  messages: [{ role: 'user', content: '用一句话解释什么是 API' }],
});
console.log(resp.choices[0].message.content);

六、常见错误排查