Skip to content
AI Blog

通义千问 API 与阿里云百炼入门

最后更新：2026-09-17· 17 分钟阅读

🚀 快速通道

  • Qwen Max：点击直达↗
  • 多模型对话工作台：打开镜像↗
  • 官方 Qwen：chat.qwen.ai ↗

通义千问 API 与阿里云百炼入门

更新时间：2026-09-17。端点、模型名、价格与限流以 阿里云百炼文档 与 百炼控制台 当天页面为准；下文用占位符，避免写入易过期的具体型号与单价。

导读

「通义千问 API」「阿里云百炼」「Qwen API 入门」对应的是把 Qwen 模型接到网站、脚本、客服机器人或内部工具——入口在 阿里云百炼（Model Studio），而不是通义千问 App 的聊天账号。可上线的接入不只是「请求 200」，还要管：密钥不进浏览器、超时与重试、结构化校验、用量与预算、日志脱敏。 网页聊天与 API 的配额、模型列表、账单不要默认当成同一套。

这篇解决什么问题？

  • 分清百炼 API 与通义千问聊天产品的账号/计费边界
  • 完成阿里云账号、百炼开通与 API Key 准备
  • 用环境变量安全发起第一次请求（含 OpenAI 兼容思路）
  • 设计超时、重试、错误分类与成本控制
  • 上线前过一遍安全清单

百炼 vs 聊天产品：先搞清边界

维度通义千问聊天产品阿里云百炼 API
典型入口通义 App、官网对话页百炼控制台
主要用途人工试用、轻量对话服务端集成、自动化、批量任务
鉴权方式登录态 / 产品账号API Key（DashScope 等，以文档为准）
计费产品套餐或免费额度按调用量 / 资源包，独立账单
模型列表以聊天界面可选为准以控制台与 API 文档列表为准

日常试用可走 Qwen Max 对话 或 多模型对话工作台；产品集成必须走服务端 API，并在百炼控制台单独开通与充值。

开通前准备：账户、Key、计费

  1. 登录 阿里云账号，进入 百炼控制台。
  2. 按控制台引导完成 百炼服务开通 与 计费 / 资源包 配置；设置预算或用量告警（若提供）。
  3. 在「API-KEY 管理」或文档所示入口创建 Key：立即复制到密码管理器或密钥服务；页面可能不再完整显示。
  4. 给 Key 打用途标签（如 dev-chat / prod-summarizer），便于泄露后定向吊销。
  5. 在 Model Studio 文档 确认当前 base URL、鉴权头、模型 ID 列表——不要从过期博客抄。

若你已有通义千问 App 账号，不代表 API Key 已就绪；两者权限与账单独立，需分别在控制台核对。

环境变量：密钥只放服务端

# Linux / macOS 示例（本地开发）
export DASHSCOPE_API_KEY="your-secret-here"
# Windows PowerShell（仅当前会话；生产请用平台 Secret）
$env:DASHSCOPE_API_KEY = "your-secret-here"

环境变量名以官方文档为准（常见为 DASHSCOPE_API_KEY）；此处仅为示例占位。

硬性规则：

  • Key 永远不要写进前端、移动 App、公开仓库、截图、ISSUE
  • 用 process.env / 部署平台 Secret / 云厂商密钥管理器
  • 不同环境（dev / staging / prod）使用不同 Key
  • 怀疑泄露 → 控制台立刻吊销并轮换

第一个请求（占位符，请对照文档替换）

阿里云百炼提供 OpenAI 兼容 调用方式（具体路径与字段以文档「OpenAI 兼容」章节为准）。以下示例展示请求形状；请将 OFFICIAL_API_ENDPOINT 与 MODEL_ID_FROM_DOCS 替换为文档中的当前值。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="OFFICIAL_API_ENDPOINT",  # 从官方文档复制，如兼容模式 base URL
)

resp = client.chat.completions.create(
    model="MODEL_ID_FROM_DOCS",  # 如 qwen-max、qwen-plus 等，以控制台为准
    messages=[
        {"role": "user", "content": "用三点解释什么是幂等性"}
    ],
    timeout=60,
)
print(resp.choices[0].message.content)

若不用 OpenAI SDK，也可用 requests 按文档 REST 格式 POST；鉴权头名称（如 Authorization: Bearer 或 X-DashScope-Api-Key）以当日文档为准。

跑通后立刻检查：响应里的用量字段（若有）、延迟、以及你是否误把 Key 打进了日志。

模型 ID 与版本注意

  • 控制台显示的模型名（如 Qwen Max、Qwen Plus、Qwen Turbo）与 API 的 model 字符串可能不同，每次集成前回查文档。
  • 新模型或预览版可能需单独开通；未开通时常见 403 或「模型不存在」类错误。
  • 禁止把内测、限时或带日期的临时 ID 写死进生产配置；应配回退到稳定型号。
  • 多模态、工具调用、JSON 模式等能力因模型而异，以文档能力矩阵为准。

可复制业务提示（放在 messages 里）

你是内部知识助手。只根据提供的 context 回答。
若 context 不足，回答「资料中未提及」并列出缺失信息。
不得编造链接、法规条文或数据。
context:
"""
[脱敏段落]
"""
问题：[用户问题]

流式输出说明

交互式 UI 通常需要 streaming，让用户先看到部分 token。百炼文档中有流式（SSE）说明；事件格式与客户端解析以官方章节为准。注意：

  • 流式同样要设总体超时与空闲超时
  • 中途断开要可恢复或明确失败，避免前端无限转圈
  • 不要在浏览器持有 Key 去做「直连流式」；由后端代发

可靠性设计（上线必做）

  1. 超时：连接超时 + 读超时；避免请求挂死占满线程
  2. 重试：仅对 429 / 5xx / 网络闪断 做有限次指数退避；401/403/400 不要盲重试
  3. 幂等：写操作带业务幂等键，防止重试重复下单类副作用
  4. 校验：要求 JSON 时做 schema 校验；失败则安全降级或有限次「修复请求」
  5. 隔离：单用户 QPS 限额、全局限流、熔断
  6. 可观测：记录 request_id（若返回）、模型名、耗时、token、错误码；不记录原始身份证/银行卡/完整对话隐私
  7. 版本：system prompt、模型名、温度类参数纳入配置版本管理

错误处理对照表

情况典型表现处理
认证失败401 / 密钥无效检查环境变量与 Key 状态；不重试
权限/未开通403 / 模型未授权查控制台开通状态与账户余额
参数错误400 / 模型名无效对照文档修正 model 与字段
限流429退避、排队、降并发、申请提额
服务端错误5xx有上限重试 + 告警
超时client timeout缩短上下文、降 max tokens、异步化
输出不合格JSON 坏掉校验失败路径 + 有限次重试

成本控制

  • 限制输入长度与最大输出；长历史做摘要或截断
  • 对相同请求做缓存（注意个性化与隐私边界）
  • 按路由选模型：简单分类用轻量档，复杂推理再升 Max 档（名称以文档为准）
  • 记录每日 token 与费用；设置预算告警
  • 批处理尽量非高峰；避免无意义的多轮「再想想」循环

不要在教程或代码注释里写死「某模型每百万 token 价格」——以 百炼定价页 实时数据为准。

安全清单（上线前必查）

  • Key 仅存在于服务端环境变量或密钥管理器
  • 仓库、CI 日志、前端 bundle 无密钥
  • 用户输入有长度限制与基础过滤（按合规要求）
  • 日志脱敏；保留期限明确
  • 定期轮换 Key；离职流程含吊销
  • dev / staging / prod Key 分离
  • 浏览器与 App 从不直持 Key

访问与入口

网页入口用于人工试用；API 用于服务端集成。两者模型列表与计费可能不同。

常见问题

通义千问 App 账号能直接调 API 吗？

不能默认等同。API 需在百炼控制台单独创建 Key 并开通计费；聊天产品的额度与 API 账单分开管理。

API Key 可以放浏览器吗？

不可以。任何下发到浏览器的字符串都可能被用户取出。应由后端代为调用百炼 API。

OpenAI 兼容模式和原生 API 怎么选？

若已有 OpenAI SDK 封装，兼容模式迁移成本低；新项目可先读文档对比功能差异（工具调用、多模态、结构化输出）。endpoint 与 model 名以当日文档为准，不要混用过期示例。

模型名报错怎么办？

以控制台与 官方文档 的当前列表为准：可能已更名、未开通或拼写错误。用 MODEL_ID_FROM_DOCS 占位提醒自己每次回查。

如何控制成本？

限制上下文与输出、缓存可复用结果、分档路由（Turbo/Plus/Max）、设预算告警，并监控异常流量（被刷接口）。

Key 泄露了怎么办？

立即在百炼控制台吊销 → 创建新 Key → 排查 Git 历史、CI 日志、容器环境变量与前端产物 → 检查账单异常调用。

官方资源

下一步阅读

行动路径

今天：在百炼控制台创建 Key，用环境变量跑通一条占位请求，打印用量与耗时。
明天：加上超时、429 退避与 schema 校验，删除代码里任何明文 Key。
本周：设预算告警，用 10 条真实输入做基准，再决定默认模型档位；提示词侧见 提示词指南。

相关内容