在阿里云百炼开通服务并调用兼容 OpenAI 的模型 API

阿里云百炼（Model Studio）是阿里云提供的一站式大模型服务平台，集成了通义千问系列以及主流的第三方模型，对外提供兼容 OpenAI 规范的 API，同时提供可视化智能体构建与工作流编排能力。它适合两类人：一类是希望用最少改动把已有 OpenAI 调用代码迁移到阿里云模型上的开发者；另一类是不写代码、想通过配置提示词、知识库和插件搭出一个可用 AI 助手的业务人员。如果你只是想先了解这个平台能做什么、入口在哪里，可以先看 阿里云百炼 的工具页，再回到本文按步骤动手。

本文围绕一条主线展开：开通服务 → 拿到凭证 → 确认端点 → 发起第一次 API 调用，最后再补一个知识库问答应用的完整搭建流程。文中涉及的免费额度、模型版本、地域可用性等易变信息，请以阿里云百炼控制台与官网当前显示为准。

准备工作

账号与权限

百炼依附于阿里云账号体系，因此第一步不是注册百炼，而是准备好阿里云账号。素材给出的路径是：使用阿里云主账号，或使用拥有 AliyunBailianFullAccess 权限的 RAM 账号访问百炼控制台。如果你在团队里不是主账号持有人，需要先让管理员为你的 RAM 用户授予该权限，否则控制台里很多入口会不可见或不可操作。

这里有一个容易被忽略的点：开通动作是在控制台里完成的。用具备上述权限的账号进入百炼控制台，在目标地域同意服务协议后，服务会自动开通，不需要单独提交工单或走审批流程。地域的选择会影响后续的端点地址，所以开通时就要想清楚业务主要落在哪个地域。

需要提前确认的三样东西

在写第一行调用代码之前，把下面三样信息准备好，可以省掉大量排查时间：

• API Key：在百炼控制台的 API-Key 管理页面创建，是后续所有 API 调用与应用集成的鉴权凭证。
• 业务空间 ID（WorkspaceId）：使用华北2（北京）、新加坡、日本（东京）、德国（法兰克福）或中国香港地域的模型时，需要把它填进 Base URL。业务空间 ID 可以在业务空间管理页面查看。
• 地域对应的 Base URL：不同地域的端点地址不通用，必须与业务空间所在地域匹配。

这三样东西里，业务空间 ID 是最常被漏掉的一项。很多调用失败并不是密钥错了，而是端点里少了这一段，或者端点地域与业务空间地域对不上。

运行环境

因为百炼兼容 OpenAI 接口规范，所以最省事的做法是直接复用你现有的 OpenAI SDK 与运行环境。素材没有限定语言，实际使用时按你项目已有的技术栈选择即可。需要准备的只有：一个能发起 HTTPS 请求的运行环境，以及把密钥通过环境变量注入的方式——这一点在后面的注意事项里还会展开。

操作步骤

第一步：开通服务

用主账号或具备 AliyunBailianFullAccess 权限的 RAM 账号登录百炼控制台，选择目标地域，阅读并同意服务协议。同意之后服务即自动开通，无需额外操作。

开通后可以留意控制台里显示的免费额度。新用户开通后通常可以领取专属免费额度，但具体额度、有效期与适用范围以控制台实时显示为准，不要按第三方文章里的数字做容量规划。

第二步：创建 API Key

进入百炼控制台的 API-Key 管理页面，创建一个新的密钥。创建完成后把密钥值保存到安全的位置——它通常只在创建时完整展示一次。

密钥的管理建议从一开始就做对：不要把密钥硬编码进客户端代码，也不要提交到代码仓库。推荐的做法是通过环境变量注入，或者由后端服务统一下发。这一点对浏览器端、移动端这类会被用户拿到的代码尤其重要。

第三步：确认业务空间 ID 与端点

到业务空间管理页面查看你的业务空间 ID。如果你使用的是华北2（北京）、新加坡、日本（东京）、德国（法兰克福）或中国香港这几个地域的模型，就需要把这个 ID 拼进 Base URL。

端点地址必须与业务空间所在地域一致。跨地域拼接端点是一个高频错误：密钥本身有效，但请求打到了错误的地域，结果就是鉴权失败或模型不存在。

第四步：改造现有 OpenAI 调用代码

这是百炼对开发者最友好的地方。已有的 OpenAI 调用代码通常只需要改三处：api_key、base_url 和模型名称。请求体结构、消息格式、流式返回的处理方式都保持一致，因此迁移成本主要集中在这三个参数上。

下面是一个最小可运行的调用示例，用环境变量承载密钥与端点，避免把敏感信息写进源码：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BAILIAN_API_KEY"],
    base_url=os.environ["BAILIAN_BASE_URL"],
)

resp = client.chat.completions.create(
    model=os.environ["BAILIAN_MODEL"],
    messages=[
        {"role": "system", "content": "你是一名严谨的技术文档编辑。"},
        {"role": "user", "content": "用三句话说明什么是兼容 OpenAI 规范的 API。"},
    ],
)

print(resp.choices[0].message.content)

运行前把三个环境变量设好。以 Linux 或 macOS 的 shell 为例：

export BAILIAN_API_KEY="你的 API Key"
export BAILIAN_BASE_URL="你的地域端点，必要时包含业务空间 ID"
export BAILIAN_MODEL="你要调用的模型名称"

模型名称要填控制台里实际可用的模型标识，不要凭记忆写。素材在知识库示例中提到过 qwen-max，但可用模型列表会随平台更新而变化，请以控制台模型列表为准。

第五步（可选）：使用百炼 CLI

除了 SDK，素材还提到可以安装百炼 CLI，通过自然语言指令调度平台的全模态能力。如果你的场景偏向交互式探索、批量试验不同模型，而不是把调用固化进业务代码，CLI 是一条更轻的路径。安装方式与可用命令请以控制台或官网文档当前说明为准。

一个完整示例

下面把前面的步骤串成一个从头到尾可跑通的最小例子。假设你已经完成开通、创建了 API Key、查到了业务空间 ID，并且业务空间位于某个需要拼接 WorkspaceId 的地域。

第 1 步：准备环境变量。把密钥、端点、模型名分别放进三个变量。端点里要包含业务空间 ID，且地域与业务空间一致。

export BAILIAN_API_KEY="sk-xxxxxxxx"
export BAILIAN_BASE_URL="https://你的地域端点/你的WorkspaceId/compatible-mode/v1"
export BAILIAN_MODEL="qwen-max"

上面的端点只是示意结构，实际地址请从控制台复制，不要手工拼写。

第 2 步：写调用脚本。保存为 first_call.py：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BAILIAN_API_KEY"],
    base_url=os.environ["BAILIAN_BASE_URL"],
)

messages = [
    {"role": "system", "content": "你是一名中文技术文档编辑，回答简洁、不使用夸张措辞。"},
    {"role": "user", "content": "解释一下什么是业务空间 ID，以及为什么它要出现在 Base URL 里。"},
]

resp = client.chat.completions.create(
    model=os.environ["BAILIAN_MODEL"],
    messages=messages,
)

print(resp.choices[0].message.content)

第 3 步：运行并检查结果。执行 python first_call.py。如果返回了模型输出，说明密钥、端点、模型名三者都对上了。如果报鉴权错误，优先检查密钥是否被复制完整；如果报模型不存在或路径错误，优先检查端点地域与业务空间 ID。

第 4 步：迁移到真实项目。把脚本里的三处参数替换成你项目配置中心或密钥管理服务里的值，其余调用逻辑保持不变。这就是兼容 OpenAI 规范带来的实际收益——业务代码几乎不用动。

第二个场景：搭一个知识库问答应用

如果你不想写代码，百炼的可视化能力可以覆盖另一条路径。素材给出的典型实践是知识库问答，分三步：

1. 创建知识库。进入知识库页面，上传业务文档并完成解析。解析质量直接决定后续回答的准确度，文档格式越规整越好。
2. 创建应用。在应用管理中创建一个智能体，选择模型（例如 qwen-max），设置 System Prompt 来定义角色与回答边界，然后在「技能」中绑定上一步建好的知识库。
3. 测试与发布。在右侧体验窗里验证对话效果，确认回答符合预期后点击「发布」。

发布之后，这个智能体可以通过网页链接、钉钉、微信公众号或 API 等渠道集成使用。也就是说，同一份配置既能给内部同事用，也能对外提供服务，不必为每个渠道重写一遍逻辑。

除了智能体，平台还提供工作流编排：通过可视化节点把多步骤任务串成一条稳定可控的执行链路。当你的需求从「一问一答」变成「先检索、再判断、再调用工具、最后汇总」时，工作流比单纯堆提示词更合适。

注意事项

服务开通后暂不支持关闭

这是素材里明确写到的限制：百炼服务开通后暂不支持关闭。这意味着开通是一个不可逆的动作，在正式开通前应当确认业务确实需要这个平台。如果之后不再使用，可行的做法是删除 API Key，避免产生后续调用。

密钥管理

API Key 是访问服务的唯一凭证。不要把它硬编码到客户端代码中，也不要提交到代码仓库。推荐通过环境变量注入，或由后端服务统一下发。对于会分发到用户设备上的应用，密钥应当始终留在服务端。

地域与端点必须匹配

不同地域的 Base URL 不通用。使用华北2（北京）、新加坡、日本（东京）、德国（法兰克福）或中国香港地域的模型时，Base URL 中需要包含业务空间 ID。地域、业务空间、端点三者不一致，是调用失败最常见的原因之一。

免费额度以控制台为准

新用户开通后可领取专属免费额度，但额度大小、有效期和适用模型会调整。做成本评估时请以百炼控制台实时显示的信息为准，不要引用文章里的历史数字。模型版本、可用地域、计费方式同理，均以官网当前信息为准。

模型名称要现查

平台上的模型列表会更新，示例里出现的模型标识只代表当时可用。写代码时把模型名放进配置而不是散落在各处，换模型时只改一处。