通义千问 API Key 获取教程：阿里云百炼平台注册与接入全流程

通义千问（Qwen）的 API 通过阿里云百炼（Model Studio）平台提供，开发者只需开通百炼服务、创建 API Key，即可通过 OpenAI 兼容接口调用 Qwen-Max、Qwen-Plus、Qwen-Turbo 等全系列模型。本文逐步说明获取流程，适合从未用过阿里云的开发者。

我见过不少人第一次接入 Qwen 会踩两个坑：一是把百炼的 API Key 和阿里云主账号的 AccessKey 搞混，拿着 AccessKey 去调模型接口，结果收到一堆权限报错；二是不知道百炼其实兼容 OpenAI SDK，绕了一圈去啃 DashScope 原生 SDK 的文档，光是理解请求体结构就多花了一两个小时。这篇教程按你实际会遇到的顺序走一遍：先把账号和密钥搞定，再讲接入代码怎么写、遇到报错怎么排查，最后附上流式、并发、重试这些进阶写法，照着做基本不会绕弯路。

第一步：注册/登录阿里云账号

1. 访问 www.aliyun.com，注册或登录阿里云账号；
2. 完成手机号实名认证（个人认证即可，企业认证可获更高配额）；
3. 如你已有淘宝/支付宝账号，可直接扫码登录。

个人认证和企业认证的区别不只是「多填几个字段」这么简单。个人认证走的是身份证信息核验，通过速度快，一般几分钟到几小时；企业认证需要上传营业执照并做对公打款验证（或法人扫脸），通常要 1-2 个工作日。如果你只是自己写代码测试、跑个 Demo，个人认证完全够用；只有当你要申请更高的调用频率限额、或者后续要开发票走公司报销，才有必要折腾企业认证。建议先用个人认证把流程跑通，等真的遇到限流再升级，不要一上来就卡在资质审核这一步。

第二步：开通阿里云百炼（Model Studio）

1. 登录阿里云后，搜索「百炼」或直接访问 bailian.aliyun.com；
2. 点击「立即开通」，阅读服务协议后确认；
3. 开通成功后进入百炼控制台，左侧菜单可见「API Key 管理」。

首次开通百炼会自动为新用户发放各模型免费额度，可在「费用中心」查看。

这里有个容易忽略的点：百炼控制台会让你选择「地域」（比如华东、新加坡等节点），不同地域对应的服务端点不完全一样，如果你是国内业务，选默认的华东地域就行，不要为了「感觉离用户近」瞎切。切错地域最常见的后果是：控制台显示已开通，代码里却调不通，报错信息还不明显——因为你创建的 Key 归属在 A 地域，请求打到了 B 地域的端点上。如果你后面真的遇到「Key 明明有效但一直 401」，先回头检查一下地域和端点是不是对得上。

第三步：创建 API Key

1. 在百炼控制台左侧点击 「API Key 管理」；
2. 点击「创建 API Key」；
3. 选择归属业务空间（默认即可），填写备注名称；
4. 点击「确定」后，密钥以 sk- 开头展示；
5. 立即复制并保存——关闭弹窗后无法再次查看明文。

「业务空间」这个概念第一次见容易懵，其实理解成「项目分组」就行：不同业务空间下创建的 Key 是相互隔离的，各自的调用记录、费用统计都分开算。如果你只是自己用，默认空间足够；但如果你同时给几个项目接 Qwen（比如一个客服机器人 + 一个内容生成脚本），建议为每个项目单独建一个业务空间、单独创建 Key，好处很实在：某个项目的 Key 泄露了，你只需要吊销那一个，不影响其他项目；出账单的时候也能一眼看出哪个项目花了多少钱，不用再去翻调用日志反推。

密钥管理上还有两条我踩过坑才总结出来的经验：一是不要把 Key 直接写死在给同事看的截图或者 issue 里，哪怕打了几个星号遮挡，字体渲染下依然可能被人拼出来；二是定期去「API Key 管理」页面清理不再使用的旧 Key，一个团队用久了很容易攒下十几个「不知道是谁建的、还在不在用」的 Key，全部留着只会增加泄露面。

第四步：接入代码（OpenAI 兼容写法）

通义千问支持 OpenAI 兼容端点，替换 base_url 和 api_key 即可：

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxxxxxxxx",      # 替换为你的百炼 API Key
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

response = client.chat.completions.create(
    model="qwen-max",    # 可选：qwen-max / qwen-plus / qwen-turbo / qwen-long
    messages=[
        {"role": "system", "content": "你是一位专业的技术助手，请简洁准确地回答问题。"},
        {"role": "user", "content": "解释一下什么是 RAG（检索增强生成）？"}
    ],
)
print(response.choices[0].message.content)

这段代码看着和调 OpenAI 官方接口几乎一模一样，这不是巧合。阿里云百炼专门做了一层「兼容模式」（compatible-mode），把 DashScope 原生的请求/响应格式转换成了 OpenAI Chat Completions 的标准格式，所以你直接用 openai 这个 SDK、只改两个参数就能跑通。好处很实在：如果你的项目本来就是基于 OpenAI SDK 写的（不管是接 GPT 还是接别的兼容模型），迁移到 Qwen 基本零改动成本，甚至可以做成「多模型热切换」——把 base_url、api_key、model 三个参数抽到配置文件里，业务代码完全不用动。

如果你之后看到阿里云官方文档里用的是 dashscope 这个原生 SDK（import dashscope），不用纠结选哪个：原生 SDK 能拿到一些 Qwen 特有的扩展参数（比如更细粒度的 top_k、多轮对话的 plugins 调用），但学习成本更高、生态兼容性差；OpenAI 兼容模式覆盖了日常 90% 以上的场景，没有特殊需求就优先用兼容模式，这也是本文只讲这条路径的原因。

常用模型名速查：

模型	model 参数	特点
旗舰推理	qwen-max	最强效果，适合复杂任务
均衡性价比	qwen-plus	效果与成本平衡
高性价比轻量	qwen-turbo	速度快，适合批量简单任务
超长上下文	qwen-long	支持 1M tokens
代码专项	qwen2.5-coder-32b-instruct	代码生成与调试
多模态图文	qwen-vl-max	图像理解

Node.js 示例：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxxxxxxxxxxxxx",
  baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
});

const resp = await client.chat.completions.create({
  model: "qwen-turbo",
  messages: [{ role: "user", content: "用 JavaScript 实现一个防抖函数" }],
});
console.log(resp.choices[0].message.content);

流式输出（stream）怎么加：

如果你在做的是一个聊天界面，一定要用流式返回，不然用户盯着空白屏幕等好几秒体验会很差。只需要加一个 stream=True，然后逐块（chunk）读取：

response = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "写一段 300 字的产品介绍"}],
    stream=True,
)
for chunk in response:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

跑起来你应该能看到文字像打字机一样一个词一个词往外蹦，而不是等全部生成完才一次性输出。这里有个常见的低级错误：不少人直接 print(chunk.choices[0].delta.content) 不做非空判断，一旦某个 chunk 的 delta.content 是 None（比如流结束前的最后几个 chunk），程序会报 TypeError: can only concatenate str，加上 if delta: 这个判断就能避开。

并发调用怎么写（asyncio）：

如果你要批量处理一堆文本（比如给 1000 条评论做情感分类），同步循环调用会很慢，用异步客户端配合 asyncio.gather 能明显提速：

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key="sk-xxxxxxxxxxxxxxxx",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

async def ask(prompt: str) -> str:
    resp = await client.chat.completions.create(
        model="qwen-turbo",
        messages=[{"role": "user", "content": prompt}],
    )
    return resp.choices[0].message.content

async def main():
    prompts = ["总结一下：这家餐厅服务很好但上菜慢", "总结一下：产品质量不错但价格偏高"]
    results = await asyncio.gather(*(ask(p) for p in prompts))
    for r in results:
        print(r)

asyncio.run(main())

注意并发不是越高越好——账号是有 QPS（每秒请求数）限制的，具体额度和你的等级挂钩，突然把并发拉到几十几百，大概率会先撞到限流，而不是被服务器扛住。批量任务建议先用 asyncio.Semaphore 控制并发上限（比如设成 5），跑通之后再根据实际报错情况往上调，不要一上来就无限制并发。

429 限流后的重试退避写法：

批量任务里 429（Too Many Requests）几乎是必然会遇到的，正确姿势不是立刻重试，而是指数退避（exponential backoff），给服务器一点喘息时间：

import time
from openai import OpenAI, RateLimitError

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

def ask_with_retry(prompt: str, max_retries: int = 5) -> str:
    for attempt in range(max_retries):
        try:
            resp = client.chat.completions.create(
                model="qwen-turbo",
                messages=[{"role": "user", "content": prompt}],
            )
            return resp.choices[0].message.content
        except RateLimitError:
            wait = 2 ** attempt  # 1s, 2s, 4s, 8s, 16s
            print(f"触发限流，{wait}s 后重试（第 {attempt + 1} 次）")
            time.sleep(wait)
    raise RuntimeError("重试次数用尽，仍被限流")

2 ** attempt 这个写法的意思是等待时间随重试次数翻倍增长，避免所有失败请求在同一时刻再次涌向服务器造成「重试风暴」。如果你的业务对延迟不敏感（比如夜间批量跑离线任务），这套逻辑基本能扛住绝大部分限流场景；如果是线上实时接口，更合理的做法是设一个较短的超时上限，超了就降级返回，而不是让用户一直等重试。

环境变量安全管理

# .env 文件（加入 .gitignore，不要提交到版本库）
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx

import os
from openai import OpenAI

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

价格说明

截至 2026-06，以官方公示为准：

• 新用户开通百炼后各模型均有免费额度，可先测试后付费；
• Qwen-Turbo 是高性价比轻量档，大批量调用成本低；
• Qwen-Max 旗舰档定价高于 Turbo，适合效果敏感任务；
• 可用 价格对比表 与 DeepSeek 等其他厂商实时对比。

常见问题

调用报 401 或 InvalidApiKey 怎么解决？ ① 确认 API Key 是否完整复制（无空格、换行符）；② base_url 必须为 https://dashscope.aliyuncs.com/compatible-mode/v1，不要漏 /compatible-mode；③ 确认百炼服务已正常开通，控制台无欠费状态。

百炼 API Key 与阿里云 AccessKey 有什么区别？ 百炼 API Key（sk- 开头）专用于模型调用，权限范围小、更安全，推荐使用；阿里云 AccessKey 是账号级全功能密钥，泄露风险高，不建议用于模型调用。

通义千问能用 LangChain 接入吗？ 可以。将 ChatOpenAI 的 openai_api_base 设为 DashScope 兼容端点，model_name 设为对应 Qwen 模型名即可。阿里云也提供官方 langchain-community 集成（ChatTongyi），两种方式均可用。

---

相关阅读：国产大模型 API 全景指南 · DeepSeek API Key 获取教程 · DeepSeek 与通义千问对比

分类导航：国产模型专题

实用工具：价格对比表 · Token 计数器