将训练好的文本模型发布为在线 API 服务。
适用范围
- 适用地域:模型部署 API 的开放地域因部署方式而异——模型单元(MU)与 独占吞吐(DTU)支持华北2(北京)。如您使用的地域未开放对应部署方式,请通过该地域的百炼控制台完成模型部署操作。
- 开通账号权限:若使用阿里云子账号(RAM用户),需要为子账号授予模型调用、训练和部署权限。
- 配置环境变量:已成功获取 API Key,并配置到环境变量。
- 阅读部署文档:建议先阅读专属部署概述和使用 API 创建模型部署任务,了解模型部署的使用方法和基本步骤。
部署模型
华北2(北京)
POST https://dashscope.aliyuncs.com/api/v1/deployments
新加坡
POST https://dashscope-intl.aliyuncs.com/api/v1/deployments
请求域名因地域而异:北京地域使用
dashscope.aliyuncs.com,新加坡地域使用dashscope-intl.aliyuncs.com;业务空间专属域名({WorkspaceId}.{region}.maas.aliyuncs.com)各地域均可用。各地域完整域名信息请参见各地域接入信息。
Windows CMD 请将
$DASHSCOPE_API_KEY替换为%DASHSCOPE_API_KEY%,PowerShell请替换为$env:DASHSCOPE_API_KEY
请求参数
请求头(Headers)
参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
Content-Type | String | 是 | 固定值: |
Authorization | String | 是 | API Key 鉴权,格式为 |
请求体(Request Body)
请求体参数因部署方式(plan)而异,各计费方式的完整请求体参数与部署示例如下:
按DTU独占算力计费
独占吞吐(DTU)为预付费(按月)计费,按输入/输出 TPM 购买容量,独占 GPU 资源,是模型单元(MU)的继任方案,新购独占部署优先选择。使用前需在控制台开通 DTU 功能并申请资源额度,详见独占吞吐(DTU)。
DTU 部署的 API 请求需使用部署所在业务空间的
maas.aliyuncs.com域名(例如ws-vxxx.cn-beijing.maas.aliyuncs.com)和该业务空间的 API Key;sku_code、template_code与容量范围通过可部署模型列表接口plan=dtu查询。完整参数、扩缩容、修改限流与更新模型等接口详见模型部署 API 参考。
参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
model_name | String | 是 | |
plan | String | 是 | 部署方案,决定计费方式: |
display_name | String | 是 | 服务展示名称,最多 50 个字符(其他部署方式使用 |
suffix | String | 否 | 部署标识后缀,最多 24 个字符;生成的完整部署标识不超过 100 个字符。省略时自动生成。 |
sku_code | String | 是 | 当前模型可用的预付费 SKU,通过可部署模型列表接口 |
template_code | String | 是 | 与模型和 SKU 匹配的部署模板,与 |
charge_type | String | 是 | 付费方式,DTU 固定传 |
dtu_capacity | Object | 是 | DTU 购买容量,须同时提供 |
dtu_capacity.input_tpm | Integer | 是 | 购买的输入 TPM(tokens/min),非负整数,最大值为 2147483647,须为查询所得步长的整数倍。 |
dtu_capacity.output_tpm | Integer | 是 | 购买的输出 TPM(tokens/min),非负整数,最大值为 2147483647,与输入 TPM 同倍数。 |
pre_paid_info | Object | 是 | 预付费购买及自动续费设置。包含字段: |
curl "https://ws-vxxx.cn-beijing.maas.aliyuncs.com/api/v1/deployments" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model_name": "your-supported-model",
"display_name": "业务模型服务",
"suffix": "production",
"plan": "dtu",
"sku_code": "your-prepaid-sku",
"template_code": "your-template",
"charge_type": "pre_paid",
"pre_paid_info": {
"pricing_cycle": "Month",
"duration": 1,
"auto_renewal": false
},
"dtu_capacity": {"input_tpm": 10000, "output_tpm": 10000}
}'
按模型单元计费
选择按模型单元计费,计费模式为按模型单元的使用时长收费,适用于模型调优后的大规模推理业务,资源专属,性能和成本灵活可调。
执行以下部署命令后,即便您还没有调用模型,模型部署服务仍将在部署成功后开始计费。建议您先确认服务计费规则,再执行部署命令。
参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
model_name | String | 是 | |
plan | String | 是 | 部署方案,决定计费方式: |
name | String | 否 | 模型的控制台显示名称。如果不传该参数,将自动使用 |
suffix | String | 否 | 模型部署后将生成新的模型名称,suffix 用于指定新模型名称的后缀,最大长度为 8 个字符且需全局唯一。每个模型在首次部署时可以不指定后缀,多次部署同一模型时必须设置。 |
template_id | String | 条件必填 | 部署模板 ID,对应可部署模型列表接口返回的 |
deploy_spec(旧) | String | 否 | 模型单元规格,已废弃,请改用 |
capacity | Integer | 条件必填 | 部署使用的资源单元数量,需为 |
charge_type | String | 否 | 付费方式: |
enable_thinking | Boolean | 否 | 是否启用思考模式。部分模型支持,可设置为 |
max_context_length | Number | 否 | 最大上下文长度。部分模型支持。样例: |
rpm_limit | Number | 否 | 每分钟请求数(requests per minute)限流。部分模型支持。 |
tpm_limit | Number | 否 | 每分钟 Token 使用量(tokens per minute)限流。部分模型支持。 |
curl "https://dashscope.aliyuncs.com/api/v1/deployments" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"name": "my_qwen_plus",
"model_name": "qwen-plus-2025-12-01",
"plan": "mu",
"template_id": "MU1",
"enable_thinking": true,
"capacity": 4,
"charge_type": "post_paid",
"max_context_length": 10000,
"rpm_limit": 500,
"tpm_limit": 1000
}'
按Token用量计费
选择按 Token 用量计费,适用于高性价比诉求且对并发和延迟要求不高的场景。该模式价格优势最高,吞吐/并发和生成速度均由平台预置,用户不可调。
参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
model_name | String | 是 | |
plan | String | 是 | 部署方案,决定计费方式: |
name | String | 否 | 模型的控制台显示名称。如果不传该参数,将自动使用 |
suffix | String | 否 | 模型部署后将生成新的模型名称,suffix 用于指定新模型名称的后缀,最大长度为 8 个字符且需全局唯一。 |
capacity | Integer | 条件必填 | 按 Token 用量计费时该参数设置无效但必须填写,固定传 1。 |
curl "https://dashscope.aliyuncs.com/api/v1/deployments" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model_name": "qwen3-8b-ft-202511132025-0260",
"plan": "lora",
"capacity": 1,
"name": "qwen3-8b-ft"
}'
部署排障与性能调优
max-num-seqs 参数不可配置
百炼模型部署在吞吐预留(独立产品,另见其 API 文档)和按模型单元计费两种计费方式下,吞吐、并发和生成速度均为平台预置,不支持直接调整 vLLM 内部的 max-num-seqs 等推理引擎参数,本接口的请求参数中也不存在该参数。
按模型单元计费方式下,可通过选择模型单元类型(对应请求参数 template_id)和调整部署副本数(对应请求参数 capacity)间接控制吞吐能力。
部署模板与资源隔离
当前部署模板仅支持单机部署(单机部署-增强型通用推理),不支持多卡实例隔离。如需资源隔离,请使用按模型单元计费方式,该方式下算力资源为业务专属。
限流错误处理
当并发请求超出限流阈值时,接口返回 HTTP 429,错误码为 Throttling.RateQuota,错误信息为 Requests rate limit exceeded, please try again later。处理方式:
- 吞吐预留(独立产品,另见其 API 文档):调整
ptu_capacity中的input_tpm和output_tpm(控制台对应 Input kTPM 和 Output kTPM),或降低请求频率。该方式下溢出策略可选自动溢出(切换为按量付费)或仅使用预留容量(超出容量的请求直接返回429)。 - 按模型单元计费:调整
rpm_limit和tpm_limit,或降低请求频率。
上下文长度调优
按模型单元计费方式下可通过请求参数 max_context_length 配置最长上下文,取值范围 1~262144(实际上限取决于所部署模型的能力)。该参数限制单次请求的上下文规模,从而限制单请求的内存占用,可降低 OOM 风险。
处理大量图片任务时,请结合图片尺寸和单请求图片数量设置该参数。
响应参数
参数 | 类型 | 说明 |
|---|---|---|
request_id | String | 请求的唯一标识符。 |
output | Object | 任务详情。 |
output.deployed_model | String | 部署模型的唯一标识。用于查询模型部署状态和调用模型。 |
output.name | String | 部署的显示名称。 |
output.model_name | String | 模型标识名。 |
output.base_model | String | 使用的基准模型。 |
output.status | String | 部署状态: |
output.workspace_id | String | API Key 所属业务空间 ID。请参见获取 Workspace ID。 |
output.charge_type | String | 付费模式: |
output.creator | String | 创建人的阿里云账号 ID。 |
output.modifier | String | 修改人的阿里云账号 ID。 |
output.plan | String | 部署方式。 |
output.gmt_create | String | 部署任务创建时间。 |
output.gmt_modified | String | 部署任务更新时间。 |
仅模型单元(mu)部署方式返回 | ||
output.base_capacity | Number | 基础模型运行所需的最小资源单元数量。 |
output.ready_capacity | Number | 已就绪并可立即处理请求的资源单元数量。 |
output.capacity | Number | 部署使用的资源单元数量。 |
output.model_unit_spec | String | 模型单元规格。 |
output.enable_thinking | Boolean | 是否开启思考模式。 |
output.max_context_length | Number | 最大上下文长度限制。 |
output.rpm_limit | Number | 每分钟请求数。 |
output.tpm_limit | Number | 每分钟 Token 使用量。 |
仅预置吞吐(ptu_v2)部署方式返回 | ||
output.ptu_capacity | Object | 预置吞吐量配置,包含 |
仅 DTU(dtu)部署方式返回 | ||
output.dtu_capacity | Object | 购买的输入/输出 TPM 容量,包含 |
output.pre_paid_info | Object | 预付费及自动续费信息。 |
DTU 完整响应字段说明见模型部署 API 参考 | ||
调用失败时返回 | ||
code | String | 错误码。调用失败时返回。 |
message | String | 错误详情描述。调用失败时返回。 |
成功响应示例
重点关注:output.deployed_model(部署模型的唯一标识)、output.status(部署状态)。
{
"request_id": "f2ae64f7-83cc-410c-bc0b-840443f7eb86",
"output": {
"deployed_model": "qwen-plus-2025-12-01-mu-xxxx",
"gmt_create": "2025-06-17T11:00:38.68",
"gmt_modified": "2025-06-17T11:00:38.68",
"status": "PENDING",
"model_name": "qwen-plus-2025-12-01",
"base_model": "qwen-plus",
"model_unit_spec": "MU1",
"enable_thinking": true,
"max_context_length": 10000,
"rpm_limit": 500,
"tpm_limit": 1000,
"base_capacity": 1,
"ready_capacity": 0,
"workspace_id": "llm-v71tlv3d***",
"charge_type": "post_paid",
"creator": "175805416***",
"modifier": "175805416***",
"plan": "mu"
}
}
错误响应示例
{
"code": "InvalidParameter",
"request_id": "BE213CDD-8A5C-59EE-9A67-055EAB0CB59B",
"message": "The model xxx does not exist or is not deployable"
}
下一步
部署为异步操作,调用本接口后可通过查询和管理部署接口查询部署状态。