通义千问API Key申请与Python调用：OpenAI兼容模式

先说结论：通义千问（阿里云百炼）可在国内网络环境中使用。本教程不会要求你注册境外模型账号；API Key请只保存在环境变量中，不要写进源码或上传到代码仓库。

一、开始前需要准备什么

1. 在通义千问（阿里云百炼）官方开放平台注册并完成平台要求的认证。
2. 在控制台创建API Key，并确认账户具有模型调用额度。
3. 电脑安装Python 3.9或更高版本。

二、安装SDK并设置API Key

python -m pip install -U openai
# Windows PowerShell
$env:DASHSCOPE_API_KEY="替换为控制台创建的API Key"

关闭当前终端后，临时环境变量通常会失效。长期使用时可在系统环境变量或部署平台的“密钥”设置中保存，但不要公开。

三、运行第一个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",
)

response = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "你是一名严谨的中文AI开发助手。"},
        {"role": "user", "content": "请用三句话解释什么是RAG。"},
    ],
)
print(response.choices[0].message.content)

当前基础地址为 https://dashscope.aliyuncs.com/compatible-mode/v1，示例模型为 qwen-plus。API Key与地域、业务空间有关；若使用子业务空间或专属部署，请以控制台给出的地域地址和模型标识为准。

四、把OpenAI教程迁移过来

如果原教程使用的是标准对话接口，通常只需修改三项：API Key环境变量、base_url和model。消息列表、流式输出等常用结构多数可以保留。

不能直接照搬的情况：Assistants、Realtime、托管文件搜索、特定图像或音频接口、厂商专属Agent SDK等高级能力并不一定兼容。遇到这些内容时，应保留教程的架构思路，按照目标平台官方接口重新实现。

五、常见错误排查

401或API Key错误

确认Key复制完整、环境变量名正确，并检查是否把其他平台的Key与当前基础地址混用。

模型不存在或无权限

从控制台复制当前可调用的模型标识；部分模型需要先开通服务或选择正确地域。

连接超时

先访问平台状态页，再检查服务器出口、防火墙、代理和请求超时。不要在失败时无限重试。

参数不兼容

先删除平台不支持的可选参数，用最小请求验证成功后再逐项恢复。

六、官方资料与其他国内方案

阿里云百炼官方SDK说明 →