阿里云百炼大模型服务平台对接使用完全指南

引言：一站式大模型服务平台百炼

阿里云百炼大模型服务平台（Model Studio）是面向企业与开发者的一站式AI服务底座，整合了通义千问（Qwen）全系列模型以及DeepSeek、Kimi、GLM等第三方优质模型，提供从模型调用、定制调优到应用构建的全链路能力。平台核心价值在于开箱即用、灵活扩展与安全可控，用户无需从零搭建模型服务即可快速获取高性能推理能力，同时支持模型定制与应用开发，适配不同业务需求。2026年平台全面升级后，以多模型生态、灵活计费与极简接入为核心优势，大幅降低了大模型的落地门槛。

百炼平台集成的通义千问全系列模型覆盖了多种能力层级：旗舰级Qwen3.7-Max面向智能体时代的复杂推理与工具调用场景；通用型Qwen3.7-Plus兼顾性能与成本的平衡；高效型Qwen-Turbo适合高频轻量级调用。此外，DeepSeek-V4-Pro作为旗舰级混合专家（MoE）大模型，具备顶尖的数学逻辑、复杂推理与百万级超长上下文能力，也已全面接入百炼平台。

本文将从零开始，完整讲解阿里云百炼的对接使用流程，涵盖账号开通、API密钥管理、模型调用、应用构建、知识库（RAG）配置、工具接入、模型部署与计费优化等核心环节，并提供完整的代码示例，帮助开发者快速上手并高效使用百炼平台。

需要先登录阿里云控制台，点击：阿里云控制台

一、开通百炼服务与前置准备

1.1 账号注册与实名认证

使用阿里云百炼服务的第一步是拥有一个阿里云账号并完成实名认证。个人用户可通过支付宝刷脸快速完成认证，全程仅需10秒左右；企业用户需上传营业执照及法人信息，审核周期通常为1-3个工作日。未完成实名认证的账号无法开通百炼服务，也无法创建API Key。实名认证入口位于阿里云控制台右上角的账号下拉菜单中，按指引提交身份信息即可完成，通常实时生效。

1.2 开通百炼平台服务

完成实名认证后，在阿里云控制台搜索“百炼”或“大模型服务平台百炼”，进入百炼控制台。首次访问时会弹出服务开通提示，勾选服务协议后点击“确认开通”，即可完成百炼平台基础服务的激活。部分用户开通后可以领取免费试用额度，用于初期的模型调用测试。

2026年新用户开通百炼平台后，可领取超7000万Tokens的免费额度，有效期90天，覆盖通义千问全系列及部分第三方模型，支持免费体验模型调用与基础应用开发。免费额度仅在华北2（北京）地域生效，因此地域选择是一个关键点。

1.3 地域选择

百炼的API Key与调用接口绑定地域。目前主流可用地域包括：

• 华北2（北京）：模型服务最全、稳定性最优，免费额度仅在此地域可用，推荐优先选择
• 新加坡：国际地域，适合海外业务部署
• 美国（弗吉尼亚）：国际地域
• 德国（法兰克福）：国际地域

创建API Key前，必须在控制台右上角切换至目标地域。若调用时地域不匹配，会直接返回403无权限错误。DeepSeek系列模型目前仅在华北2（北京）地域可用。

二、API Key的创建与管理

2.1 API Key的作用

API Key是接入阿里云百炼大模型服务的核心凭证，所有模型调用、SDK开发、智能体部署、第三方工具集成都必须通过它完成身份鉴权与权限校验。API Key的格式通常以sk-或sk-ws-开头，创建后仅显示一次，需妥善保存。

2.2 创建API Key

在百炼控制台左侧导航栏找到“API Key管理”选项，点击进入密钥管理页面。点击“创建API Key”按钮，需配置以下核心参数：

• 归属业务空间：默认选择“默认业务空间”即可。业务空间用于隔离不同项目的密钥与调用记录，单个主账号最多创建20个业务空间，每个空间最多创建20个API Key
• 描述（可选）：填写密钥用途，如“个人开发测试”“企业生产调用”等，方便后续管理与排查
• 权限配置：提供“全部”和“自定义”两种选项。选择“全部”可调用百炼所有模型与应用，适合开发测试；选择“自定义”需配置IP白名单，仅允许指定IP段调用，适合生产环境提升安全性

确认后生成的API Key应立即复制并保存到安全位置，如密码管理器或本地加密存储。

2.3 API Key的安全管理

建议将API Key配置为系统环境变量，避免在代码中硬编码导致泄露：

• Windows：此电脑 → 属性 → 高级系统设置 → 环境变量，新建系统变量DASHSCOPE_API_KEY，粘贴密钥
• macOS/Linux：终端执行export DASHSCOPE_API_KEY=你的密钥（临时生效），永久生效需修改~/.bashrc或~/.zshrc文件

同时需注意，中国内地地域与国际地域的API Key不通用，需根据部署区域选择对应Key。子账号需通过主账号完成授权后，方可进行API Key的创建与模型调用操作。

三、模型调用：三种接入方式详解

阿里云百炼提供三种主要的模型接入方式，分别适配不同的使用场景。

3.1 方式一：按量计费API调用

按量计费是百炼的默认计费方式，适合临时测试、低频调用场景，按实际Token消耗付费。调用时需使用DashScope API接口，不同地域的Base URL不同：

• 华北2（北京）：https://dashscope.aliyuncs.com/compatible-mode/v1
• 新加坡：https://[workspace-id].ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
• 美国（弗吉尼亚）：https://dashscope-us.aliyuncs.com/compatible-mode/v1

Python SDK调用示例（兼容OpenAI）

百炼的API兼容OpenAI接口协议，使用OpenAI Python SDK即可完成调用：

import os
from openai import OpenAI
# 初始化客户端
client = OpenAI(
    api_key=os.environ.get("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)
# 调用模型
completion = client.chat.completions.create(
    model="qwen-max",
    messages=[
        {"role": "system", "content": "你是一个专业的AI助手"},
        {"role": "user", "content": "请简要介绍阿里云百炼平台"}
    ],
    temperature=0.7,
    max_tokens=1024
)
print(completion.choices[0].message.content)

对于DeepSeek-V4-Pro模型，模型名称需指定为deepseek-v4-pro，若需解锁百万上下文能力，可在模型名后添加[1m]，即选择deepseek-v4-pro[1m]，可处理约75万字的长文本内容。

HTTP请求调用示例

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "qwen-max",
    "messages": [
      {"role": "system", "content": "你是一个专业的AI助手"},
      {"role": "user", "content": "请简要介绍阿里云百炼平台"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

批量调用（Batch API）

百炼提供与OpenAI兼容的Batch File API，支持通过文件批量提交请求。系统异步处理所有请求，在全部完成或达到最长等待时间后返回结果，费用仅为实时调用的50%。适用于数据分析、批量文本处理等对实时性要求不高的场景。

3.2 方式二：Token Plan团队版订阅

Token Plan是阿里云百炼推出的预付费套餐模式，适用于团队协作、高频调用场景，提供固定额度的Credits，并支持多模型统一管理。按“坐席”（即团队成员名额）订阅，提供三档套餐，按月或按年付费：

Token Plan团队版的API接入配置如下：

• Base URL：https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
• API Key：Token Plan团队版专属API Key（在百炼控制台Token Plan管理页面获取）

目前Qwen3.7-Max模型的Credits消耗减半（即实际消耗=原值×0.5）。Token Plan团队版支持多模型统一管理，可在Qwen全系列及部分第三方模型间灵活切换。

3.3 方式三：Coding Plan（AI编程专属套餐）

Coding Plan是阿里云百炼专为个人开发者与小型团队打造的AI编码专属套餐，以固定月费提供定额调用额度，聚合多模型能力并兼容主流开发工具。Coding Plan的API配置如下：

• Base URL：https://coding.dashscope.aliyuncs.com/v1
• API Key：Coding Plan专属API Key

Coding Plan仅限在AI编程工具和OpenClaw类型Agent中使用，不支持在Dify、n8n、Coze等工作流/自动化平台，以及Postman等API测试工具中使用。

四、应用构建：智能体、工作流与高代码应用

百炼平台提供三种应用构建模式，覆盖从零代码到高代码的完整开发链路。

4.1 智能体应用（Agent）

智能体由提示词驱动，通过协调外部能力完成复杂任务。百炼智能体支持以零代码方式将大模型与外部工具和知识库连接，突破模型内置能力的边界。

创建基础智能体

访问阿里云百炼控制台应用管理页面，单击“+创建应用”，在智能体应用页签单击“立即创建”。在应用配置界面中：

• 模型选择：下拉菜单中选择模型，如千问-Plus或千问-Max
• 最长回复长度：模型生成内容的长度上限
• 携带的上下文轮数：输入模型的最大历史对话轮数
• temperature：控制生成内容的随机性，取值范围[0, 2)
• enable_thinking：是否开启推理模式。开启后模型在生成回复前会进行更深入的推理，Token消耗会增加

智能体的核心能力包括：

• 知识库（RAG）：连接外部知识库，基于私有数据回答问题
• 插件：调用平台预置工具，如代码执行、图像生成、天气查询等

4.2 工作流应用（Workflow）

工作流应用通过可视化节点编排，串联多步骤任务，实现固定流程自动化。适合报告生成、订单处理等流程固定的业务场景。

4.3 高代码应用

面向专业开发者，支持Python代码开发，一键部署上云，集成企业级服务。高代码应用通过MCP（Model Context Protocol）协议接入各类工具，为AI Agent扩展知识检索、外部服务调用、应用编排和数据访问能力。

高代码应用支持四种工具类型：

• 知识库：配置好的知识库可发布为MCP服务接入，为智能体提供补充知识
• MCP服务：通过插件转换或开通广场中的MCP服务，提供联网搜索、天气查询等外部服务调用
• 应用组件：将已创建的智能体或工作流作为组件接入，实现多Agent协作
• 数据连接器：访问外部数据的桥梁，提供企业级数据服务

一个规范的高代码应用项目推荐使用以下目录结构：

my-agent-app/
├── main.py              # 入口文件（必须）
├── requirements.txt     # Python依赖声明
├── tools/               # 工具函数模块
│   ├── search.py        # 搜索工具
│   ├── knowledge.py     # 知识库工具
│   └── data.py          # 数据连接工具
├── prompts/             # 系统提示词模板
│   └── system.txt
└── utils/               # 通用工具类
    └── helpers.py

工具接入的代码示例（通过fastmcp.Client连接MCP服务）：

import os
from agentscope.message import TextBlock
from agentscope.tool import ToolResponse
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport
async def web_search(query: str) -> ToolResponse:
    """通过MCP服务调用联网搜索工具"""
    api_key = os.environ.get("DASHSCOPE_API_KEY")
    transport = StreamableHttpTransport(
        mcp_url="https://dashscope.aliyuncs.com/api/v1/mcps/{mcpCode}/mcp",
        headers={"Authorization": f"Bearer {api_key}"},
    )
    async with Client(transport=transport) as client:
        result = await client.call_tool("{toolName}", {"query": query})
        if result and result.content:
            text = "\n".join(block.text for block in result.content if hasattr(block, "text"))
        else:
            text = "No results found."
        return ToolResponse(content=[TextBlock(type="text", text=text)])

五、知识库与RAG（检索增强生成）

5.1 知识库概述

百炼平台内置原生RAG知识库能力，配套向量存储、文档解析、检索重排序、长期记忆插件等一体化工具。知识库为Agent提供补充知识以增强回复准确性，适用于产品文档问答、企业知识检索、FAQ自动回复等需要特定领域知识的场景。

5.2 创建知识库（可视化方式）

在百炼控制台进入“数据管理-知识索引”，点击“创建知识库”。填写知识库名称和描述，选择“文档搜索”类型，配置分片大小、相似度阈值等参数。上传企业私有文档，支持PDF、Word、Excel、TXT、Markdown等格式，平台自动完成解析、切片、向量化存储。记录知识库索引名称，作为后续API调用的唯一标识。

5.3 知识库API方式创建与文档导入

适合批量数据导入与自动化流程，Java示例代码如下：

// 初始化百炼API客户端
DashScopeApi dashscopeApi = new DashScopeApi(apiKey, workspaceId);
// 文档读取与切片
DashScopeDocumentCloudReader reader = new DashScopeDocumentCloudReader(
    "企业文档.pdf", dashscopeApi, null
);
List<Document> docs = reader.get();
DashScopeDocumentTransformer transformer = new DashScopeDocumentTransformer(dashscopeApi);
List<Document> splitDocs = transformer.apply(docs);
// 向量化并存储到百炼知识库
DashScopeCloudStore cloudStore = new DashScopeCloudStore(
    dashscopeApi,
    new DashScopeStoreOptions("企业知识库索引")
);
cloudStore.add(splitDocs);

5.4 Spring AI集成百炼RAG

对于Java生态开发者，可通过Spring AI Alibaba框架快速集成百炼RAG能力。核心依赖如下：

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.0.0</version>
</dependency>

配置文件（application.yml）示例：

spring:
  application:
    name: enterprise-rag-demo
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}
      workspace-id: ${AI_DASHSCOPE_WORKSPACE_ID:}
    chat:
      options:
        model: qwen-max

六、模型部署与自定义

6.1 模型部署

百炼支持将模型部署为可调用的服务端点。部署前需阅读模型部署和使用API进行模型部署的相关内容，掌握基本步骤。执行部署命令后，即便还没有调用模型，模型部署服务仍将在部署成功后开始计费，建议先确认服务计费规则再执行部署命令。

6.2 列举可部署模型

通过以下API可以查询支持部署的模型列表：

GET https://dashscope.aliyuncs.com/api/v1/deployments/models

推荐使用version=v1.0获取包含部署方案和模板信息的完整响应。

6.3 模型定制与调优

百炼支持有监督微调（SFT）、继续预训练（CPT）等多种调优方式，企业可基于私有数据定制专属模型。平台提供全链路调优工具，包括数据标注、效果评测、模型部署，无需专业AI团队即可完成模型定制。

七、计费规则与成本优化

7.1 计费模式总览

阿里云百炼采用“开通免费、按需付费”的基础计费模式：

• 开通服务无需费用，可免费开通百炼平台账户
• 仅在调用模型（推理）、微调模型或部署模型时产生费用
• 文本类模型按输入Token和输出Token分别计费
• 图像生成类按成功生成的图像张数计费
• 视频生成/编辑类按成功输出的视频秒数计费
• 账单按分钟级出账，按自然月结算

7.2 主流模型按量付费价格（华北2/北京）

7.3 成本优化策略

• 利用免费额度：新用户可领取超7000万Tokens免费额度，有效期90天
• 批量调用：使用Batch API可享实时推理价格50%的优惠
• 上下文缓存：对于重复输入的场景，上下文缓存可降低输入Token成本
• 思考模式按需开启：enable_thinking参数开启后Token消耗会增加，非必要场景可不开启
• 订阅制套餐：高频调用场景可选择Token Plan团队版或Coding Plan，成本更可控
• AI通用型节省计划：1000元起购，全预付享最高折扣

7.4 费用控制提醒

未完成实名认证的用户在免费额度用尽后将无法继续使用服务；已认证用户默认自动转为按量付费，可开启“免费额度用完即停”功能避免意外扣费。

八、常见问题与解答

问1：百炼平台和DashScope是什么关系？

百炼（Model Studio）是阿里云的大模型服务平台，提供从模型调用到应用构建的全链路能力；DashScope是百炼的模型API调用接口域名和服务名称。开发者通过DashScope API调用百炼平台上的各类模型。

问2：API调用返回403错误是什么原因？

403错误通常由以下原因引起：API Key与调用地域不匹配（如在北京地域创建的Key却在其他地域调用）；API Key已过期或被删除；子账号权限不足。建议检查控制台右上角的地域设置，确保与API Key创建时一致。

问3：Token Plan和按量计费可以同时使用吗？

可以。Token Plan是预付费订阅模式，按量计费是后付费模式，两者可以并存。用户可根据不同场景选择使用Token Plan的专属API Key或按量计费的API Key进行调用。

问4：如何将私有文档接入大模型进行问答？

通过百炼的知识库（RAG）功能实现。在控制台创建知识库，上传PDF、Word等格式的文档，平台自动完成解析、向量化存储。然后在智能体应用中关联该知识库，即可实现基于私有文档的问答。

问5：百炼支持哪些第三方模型？

百炼已接入DeepSeek-V4-Pro、Kimi、GLM-5.2等第三方优质模型。用户可在模型广场中搜索并开通所需模型，开通后在调用时指定对应的模型ID即可。

问6：模型调用的Token消耗如何计算？

Token是模型处理文本的基本单位。输入Token指用户发送给模型的提示词（含系统提示、历史对话等）的总Token数；输出Token指模型生成的回复内容的Token数。计费时分别按输入和输出的单价计算。不同模型的Token单价不同，可在百炼控制台的计费说明页面查看具体价格。