阿里云百炼通义千问 API 实战：OpenAI 兼容接口快速接入指南

本文详细介绍了如何通过阿里云百炼平台接入通义千问大模型API的全流程。主要内容包括：1）新用户注册和免费额度领取；2）API密钥获取方法；3）使用兼容OpenAI协议的接口实现零成本切换；4）核心代码解析及多轮对话、流式输出等高级功能实现。文章特别强调了阿里云百炼平台的关键优势——完全兼容OpenAI接口，开发者只需修改少量配置即可调用通义千问模型，无需重构代码。同时提供了常见问题解决方案和性能优

纤纡.

1044人浏览 · 2026-05-09 09:04:10

纤纡. · 2026-05-09 09:04:10 发布

随着大模型技术的普及，越来越多的开发者希望以低成本、低门槛的方式将 AI 能力集成到自己的项目中。阿里云百炼平台为个人和企业开发者提供了通义千问系列大模型的 API 服务，其核心优势之一是完全兼容 OpenAI 接口协议，这意味着开发者可以直接使用熟悉的 OpenAI SDK，仅需修改几行配置，就能无缝切换到通义千问模型，无需重构代码。

本文将从新人注册领取免费福利、获取 API 密钥，到编写可运行的 Python 代码，手把手带你完成通义千问 API 的接入全流程。同时，我们会深度解析代码原理、扩展多轮对话、流式输出等高级功能，帮助你快速上手阿里云百炼平台的开发。

一、阿里云百炼平台：新人注册与免费福利领取

1.1 平台简介与注册流程

阿里云百炼是阿里云推出的一站式大模型开发与服务平台，提供了通义千问系列大模型的 API 调用、模型微调、应用构建等服务。对于个人开发者，平台提供了非常友好的新手福利，新用户注册即可领取免费的调用额度，足以支撑学习和小规模项目开发。

注册步骤：

访问阿里云百炼官网：https://bailian.console.aliyun.com/
使用阿里云账号登录，未注册用户需先完成账号注册与实名认证。
进入「控制台」首页，新用户会自动弹出「新人福利」领取窗口，按照提示即可领取免费的 Token 额度（通常包含数十万 Tokens，有效期内可免费使用）。
领取成功后，即可进入平台开始使用。

1.2 API 密钥获取与权限说明

领取福利后，你需要创建 API 密钥才能调用模型。

在百炼控制台左侧导航栏，找到「API-KEY 管理」。
点击「创建 API-KEY」，系统会生成一对API Key和API Secret。
重要安全提示：这对密钥相当于你的账号密码，请务必妥善保存，不要泄露给他人，也不要直接提交到公开代码仓库。

1.3 模型选择与接口地址

百炼平台提供了多种通义千问模型，如qwen-turbo、qwen-plus、qwen-max等，不同模型的能力和价格不同。在你的代码中使用的qwen-plus是一个性价比很高的通用模型，适合大多数对话场景。

同时，平台提供了 OpenAI 兼容的接口地址：https://dashscope.aliyuncs.com/compatible-mode/v1通过这个地址，你可以直接使用openai SDK 来调用通义千问模型，这是整个接入流程的核心。

二、开发环境搭建与依赖安装

2.1 环境要求

Python 3.7+
openai SDK >= 1.0（注意：旧版本的 SDK 语法不同，本文基于 v1.x 版本）

2.2 安装依赖

在终端执行以下命令，安装最新版的 OpenAI SDK：

pip install --upgrade openai

三、核心代码解析：你的通义千问调用示例

下面是你截图中代码的完整版，我将逐行为你解析，并修复潜在问题，确保代码可以直接运行。

3.1 完整可运行代码

from openai import OpenAI

# -------------------------- 配置API参数 --------------------------
# 替换为你自己的API Key
API_KEY = "你的阿里云百炼API Key"
# 阿里云百炼的OpenAI兼容接口地址
BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"

# 1. 初始化OpenAI客户端
client = OpenAI(
    api_key=API_KEY,
    base_url=BASE_URL,
)

# 2. 调用通义千问模型
completion = client.chat.completions.create(
    model="qwen-plus",  # 指定模型为通义千问Plus
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "你是谁？"}
    ]
)

# 3. 输出完整的JSON响应
print("完整响应：")
print(completion.model_dump_json())
print("-" * 50)

# 4. 仅输出模型回复内容
print("模型回答：")
print(completion.choices[0].message.content)

3.2 代码逐行深度解析

（1）初始化 OpenAI 客户端

client = OpenAI(
    api_key=API_KEY,
    base_url=BASE_URL,
)

api_key: 你在阿里云百炼平台创建的 API Key。
base_url: 阿里云百炼提供的 OpenAI 兼容接口地址。通过修改这个参数，openai SDK 会将所有请求发送到阿里云的服务器，而不是 OpenAI 的官方服务器。这就是实现 “零成本切换模型” 的关键所在。

（2）核心请求参数说明

completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "你是谁？"}
    ]
)

model: 指定要调用的模型名称。这里我们使用qwen-plus，你也可以替换为其他支持的模型，如qwen-turbo或qwen-max。
messages: 对话历史列表，遵循 OpenAI 的对话格式。
- system: 系统角色，用于设定模型的行为和背景，例如 “你是一个有用的助手”、“你是一个 Python 专家” 等。
- user: 用户角色，代表用户的提问内容。

（3）结果解析与输出

# 完整响应
print(completion.model_dump_json())

# 模型回复内容
print(completion.choices[0].message.content)

completion.model_dump_json(): 将整个响应对象转换为 JSON 格式的字符串，方便你查看返回的所有信息，包括模型、使用的 Token 数、生成的文本等。
completion.choices[0].message.content: 这是最常用的方式，直接获取模型生成的回复文本。choices[0]表示获取第一个（也是唯一一个）生成结果。

四、功能扩展：从单轮到多轮对话

你的代码示例是一个单轮对话，下面我们将它扩展为更实用的多轮对话。

4.1 多轮对话实现

多轮对话的核心是维护messages列表，每次用户提问后，将用户输入和模型回复都追加到列表中，作为下一轮对话的上下文。

from openai import OpenAI

API_KEY = "你的阿里云百炼API Key"
BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
client = OpenAI(api_key=API_KEY, base_url=BASE_URL)

def chat_with_qwen(messages):
    """调用通义千问模型并返回回复"""
    completion = client.chat.completions.create(
        model="qwen-plus",
        messages=messages,
        temperature=0.7  # 控制回复的随机性，0为最确定，1为最随机
    )
    return completion.choices[0].message.content

if __name__ == "__main__":
    # 初始化对话历史
    messages = [
        {"role": "system", "content": "你是一个有用的助手，用中文回答用户的问题。"}
    ]

    print("你好！我是通义千问，有什么可以帮你的吗？输入 'exit' 退出对话。")
    while True:
        user_input = input("你: ")
        if user_input.lower() == "exit":
            print("通义千问: 再见！")
            break
        
        # 将用户输入加入对话历史
        messages.append({"role": "user", "content": user_input})
        
        # 调用模型
        response = chat_with_qwen(messages)
        
        # 将模型回复加入对话历史
        messages.append({"role": "assistant", "content": response})
        
        print(f"通义千问: {response}")

五、高级特性：流式输出体验打字机效果

当回复内容较长时，一次性输出会让用户等待很久。使用流式输出，可以让模型的回复像打字机一样逐字显示，极大提升交互体验。

5.1 流式输出代码示例

from openai import OpenAI

API_KEY = "你的阿里云百炼API Key"
BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
client = OpenAI(api_key=API_KEY, base_url=BASE_URL)

completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "你是一个诗人，写一首关于春天的诗。"},
        {"role": "user", "content": "写一首关于春天的短诗"}
    ],
    stream=True,  # 开启流式输出
)

print("通义千问: ", end="")
# 逐字打印输出
for chunk in completion:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()

六、常见问题排查与优化建议

6.1 常见报错与解决方案

报错信息	可能原因	解决方案
`Invalid API key`	API Key 配置错误或过期	检查 Key 是否复制正确，或在百炼控制台重新生成
`Insufficient quota`	免费额度用完或账户欠费	查看百炼控制台的用量统计，或充值升级套餐
`Connection refused`	Base URL 错误或网络问题	检查`BASE_URL`是否为`https://dashscope.aliyuncs.com/compatible-mode/v1`