模型微调

阿里云百炼 CLI 按文本、音频、图像、视频模态创建和管理模型微调任务的命令速查。

在终端管理模型微调全生命周期：按文本、音频、图像、视频选择创建命令，管理微调任务、Checkpoint 和模型压缩。

按模态选择命令

模态	创建命令	说明
文本	bl finetune text create	文本生成模型微调，支持 sft、sft-lora、dpo、dpo-lora、cpt
音频	bl finetune audio create	音频模型微调
图像	bl finetune image create	图像生成模型微调
视频	bl finetune video create	视频生成模型微调

文本微调

bl finetune text create

创建文本模型微调任务（sft | sft-lora | dpo | dpo-lora | cpt）。需要 API Key 鉴权。

语法

bl finetune text create

参数	类型	必填	说明
--base-model <model>	string	是	要微调的基础模型（例如 qwen3-8b；不是输出模型名称）
--datasets <ids|paths>	string	是	数据集文件 ID 或本地路径，以逗号分隔（文本使用 .jsonl，音频、图片和视频使用 .zip）。本地路径会先验证并上传，再使用对应的 file-id。
--validations <ids|paths>	string	否	验证数据集文件 ID 或本地路径，以逗号分隔（与 --datasets 一样自动上传）。
--model-name <name>	string	否	训练完成后的输出模型名称
--suffix <text>	string	否	平台追加的输出后缀（finetuned_output_suffix）
--job-name <value>	string	否	训练任务显示名称（job_name）
--priority <value>	string	否	请求的调度优先级；请核对服务端回执
--eval-steps <value>	number	否	训练验证间隔步数
--lora-alpha <value>	number	否	LoRA 缩放系数
--lora-dropout <value>	number	否	LoRA 丢弃率
--lora-rank <value>	number	否	LoRA 矩阵秩
--lr-scheduler-type <value>	string	否	所选模型支持的学习率调度策略
--save-strategy <value>	string	否	Checkpoint 保存策略
--save-total-limit <value>	number	否	最多保存的 Checkpoint 数量
--save-steps <value>	number	否	按 steps 保存时的间隔
--split <value>	number	否	未指定验证集时训练集所占比例
--max-split-val-dataset-sample <value>	number	否	自动切分验证集的样本数量上限
--data-augmentation <value>	string	否	是否混入平台训练数据（true 或 false）
--training-type <t>	string	否	训练类型：sft | sft-lora | dpo | dpo-lora | cpt（默认：sft-lora）。在接口边界转换为服务端值（例如 sft-lora -> efficient_sft、dpo -> dpo_full）。
--n-epochs <n>	number	否	训练轮数（默认：3）
--batch-size <n>	number	否	单设备 Batch Size（限制在 [8, 1024]）。小数据集（<100KB）自动设为 8
--learning-rate <str>	string	否	以字符串形式指定学习率以保留精度（例如 "1.6e-5"）
--max-length <n>	number	否	最大序列长度

示例：创建文本模型微调任务

bl finetune text create --base-model qwen3-8b --datasets file-xxx

• 训练类型遵循 <method> / <method>-lora 命名约定：sft（全量）| sft-lora（LoRA）| dpo（全量）| dpo-lora（LoRA）| cpt。这些值会在接口边界映射为服务端 training_type，因此 CLI 的其他部分不会接触服务端原始字符串。
• 提交任务前（非 dry-run），会通过 listFoundationModels 检查模型训练能力（无需登录控制台）；如果训练类型不受支持，会立即失败并列出该模型实际支持的训练类型。
• n_epochs 默认为 3。其他超参数未设置时使用平台默认值。
• 学习率以字符串形式传递，避免 JSON 数字精度损失。
• 提交前检查：如果训练数据集的样本数不大于 batch_size，会在上传或消耗额度前拒绝任务（否则平台会在数据处理约 10 分钟后才失败）。

音频微调

bl finetune audio create

创建音频 TTS 模型微调任务（sft-lora）。需要 API Key 鉴权。

语法

bl finetune audio create

参数	类型	必填	说明
--base-model <model>	string	是	要微调的基础模型（例如 qwen3-8b；不是输出模型名称）
--datasets <ids|paths>	string	是	数据集文件 ID 或本地路径，以逗号分隔（文本使用 .jsonl，音频、图片和视频使用 .zip）。本地路径会先验证并上传，再使用对应的 file-id。
--validations <ids|paths>	string	否	验证数据集文件 ID 或本地路径，以逗号分隔（与 --datasets 一样自动上传）。
--model-name <name>	string	否	训练完成后的输出模型名称
--suffix <text>	string	否	平台追加的输出后缀（finetuned_output_suffix）

示例：创建音频 TTS 模型微调任务

bl finetune audio create --base-model cosyvoice-v3-flash --datasets ./audio.zip

• 音频 TTS 训练使用 sft-lora（efficient_sft）和固定的 CosyVoice 超参数默认值；没有可设置的训练类型或超参数选项。

图像微调

bl finetune image create

创建图片生成模型微调任务（sft-lora）。需要 API Key 鉴权。

语法

bl finetune image create

参数	类型	必填	说明
--base-model <model>	string	是	要微调的基础模型（例如 qwen3-8b；不是输出模型名称）
--datasets <ids|paths>	string	是	数据集文件 ID 或本地路径，以逗号分隔（文本使用 .jsonl，音频、图片和视频使用 .zip）。本地路径会先验证并上传，再使用对应的 file-id。
--validations <ids|paths>	string	否	验证数据集文件 ID 或本地路径，以逗号分隔（与 --datasets 一样自动上传）。
--model-name <name>	string	否	训练完成后的输出模型名称
--suffix <text>	string	否	平台追加的输出后缀（finetuned_output_suffix）
--generation-type <t2i|i2i>	string	否	生成类型：t2i（默认）| i2i。用于设置 generation_type/max_pixels。通过 file-id 训练 I2I 或使用 --dry-run 时必填（本地数据会自动识别 input_img）。
--learning-rate <str>	string	否	以字符串形式指定学习率以保留精度（例如 "3e-5"）

示例：创建图片生成模型微调任务

bl finetune image create --base-model wan2.7-image-pro --datasets ./images.zip

• 图片生成训练使用 sft-lora（efficient_sft）和固定默认值；仅 --learning-rate 可覆盖。通过 --generation-type（默认 t2i）声明 T2I 或 I2I，并设置 generation_type/max_pixels。本地数据会自动识别类型（包含 input_img 的记录训练 I2I）；通过 file-id 训练 I2I 或使用 --dry-run 时，请显式传入 --generation-type。

视频微调

bl finetune video create

创建视频生成模型微调任务（Wan i2v/kf2v，efficient_sft）。需要 API Key 鉴权。

语法

bl finetune video create

参数	类型	必填	说明
--base-model <model>	string	是	要微调的基础模型（例如 qwen3-8b；不是输出模型名称）
--datasets <ids|paths>	string	是	数据集文件 ID 或本地路径，以逗号分隔（文本使用 .jsonl，音频、图片和视频使用 .zip）。本地路径会先验证并上传，再使用对应的 file-id。
--validations <ids|paths>	string	否	验证数据集文件 ID 或本地路径，以逗号分隔（与 --datasets 一样自动上传）。
--model-name <name>	string	否	训练完成后的输出模型名称
--suffix <text>	string	否	平台追加的输出后缀（finetuned_output_suffix）
--n-epochs <n>	number	否	训练轮数（默认：50）
--batch-size <n>	number	否	Batch Size（默认值因模型而异：wan2.7 为 1，wan2.5/2.2 为 4）
--learning-rate <str>	string	否	以字符串形式指定学习率以保留精度（默认："2e-5"）

示例：创建视频生成模型微调任务

bl finetune video create --base-model wan2.7-i2v --datasets file-xxx

• 视频生成训练（Wan i2v/kf2v）使用 efficient_sft 和模型专属默认值：wan2.7（batch_size=1、max_pixels=102400），wan2.5/2.2（batch_size=4，max_pixels 因模型而异）。可通过 --batch-size/--n-epochs 覆盖。
• 数据集为包含 data.jsonl、帧图片和视频的 .zip 归档。
• 建议至少准备 10 个训练样本；20–100 个样本可获得更稳定的效果。

微调任务管理

bl finetune list

列出微调任务。需要 API Key 鉴权。

语法

bl finetune list [--page <n>] [--page-size <n>] [--status <s>] [--base-model <model>]

参数	类型	必填	说明
--page <n>	number	否	页码（默认：1）
--page-size <n>	number	否	每页结果数（默认：10，最多：100）
--status <s>	string	否	按状态筛选（PENDING / RUNNING / SUCCEEDED / FAILED / CANCELED）
--base-model <model>	string	否	按基础模型 ID 筛选（服务端筛选）

示例：列出运行中的微调任务

bl finetune list --status RUNNING

bl finetune get

获取单个微调任务的详情。需要 API Key 鉴权。

语法

bl finetune get --job-id <id>

参数	类型	必填	说明
--job-id <id>	string	是	微调任务 ID

示例：获取单个微调任务详情

bl finetune get --job-id ft-xxx

bl finetune watch

查询微调任务状态（默认：单次非阻塞获取）。使用 --follow 持续轮询至终态。需要 API Key 鉴权。

语法

bl finetune watch --job-id <id> [--follow] [--interval <sec>] [--poll-timeout <sec>]

参数	类型	必填	说明
--job-id <id>	string	是	微调任务 ID
--follow	switch	否	阻塞并轮询至终态（旧版行为）。不使用时仅查询一次状态并立即返回。
--interval <sec>	number	否	使用 --follow 时的轮询间隔秒数（默认：${DEFAULT_INTERVAL_SEC}，最小：${MIN_INTERVAL_SEC}）。未使用 --follow 时忽略。
--poll-timeout <sec>	number	否	使用 --follow 时，在指定秒数后停止轮询（默认：无限制）。未使用 --follow 时忽略。

示例：查询微调任务状态

bl finetune watch --job-id ft-xxx                       # 单次查询，立即返回

• 默认不使用 --follow，执行非阻塞的单次状态查询：获取一次后立即返回。该模式适用于 Agent / 脚本，由调用方控制轮询节奏，CLI 不会持续占用终端。
• 终态 FAILED/CANCELED 会触发普通 CLI 错误（非零退出码）；SUCCEEDED 或仍在运行时返回 0。使用 --follow 时，超过 --poll-timeout 会触发超时错误。
• 需要在人工终端中阻塞跟踪时使用 --follow；自行驱动轮询（例如通过 Agent）时使用默认模式。
• 要查看逐步骤训练输出（而非状态），请使用 finetune logs。

bl finetune logs

获取微调任务的训练日志。需要 API Key 鉴权。

语法

bl finetune logs --job-id <id> [--page <n>] [--page-size <n>] [--search <keyword>] [--tail <n>]

参数	类型	必填	说明
--job-id <id>	string	是	微调任务 ID
--page <n>	number	否	页码（默认：1）
--page-size <n>	number	否	每页行数（默认：由服务端决定）
--search <keyword>	string	否	不区分大小写的子字符串筛选。设置后会获取全部日志页并在客户端筛选（忽略 --page）。
--tail <n>	number	否	仅保留最后 N 条记录。设置后会获取全部日志页并保留末尾 N 条（忽略 --page）。

示例：获取微调任务训练日志

bl finetune logs --job-id ft-xxx

bl finetune metrics

查询微调任务的训练指标。需要 API Key 鉴权。

语法

bl finetune metrics --job-id <id> [--page <n>] [--page-size <n>] [--workspace-id <id>]

参数	类型	必填	说明
--job-id <id>	string	是	微调任务 ID
--page <n>	number	否	页码，从 1 开始（默认：1）
--page-size <n>	number	否	每页记录数（默认：100）
--workspace-id <id>	string	否	作为 X-DashScope-WorkSpace 发送的工作空间 ID，使用任务所属工作空间。API Key 已绑定工作空间时可省略。

示例：查询微调任务的训练指标

bl finetune metrics --job-id ft-xxx

• 查询 GET /api/v1/fine-tunes/{job_id}/basic_metrics。每条指标记录原样返回（step 加动态指标字段）；空列表是正常结果。
• 指标不在服务端筛选，接口返回完整结果，由调用方从每条记录中选取指标字段。使用 --page/--page-size 分页。

bl finetune checkpoints

列出微调任务生成的 Checkpoint。需要 API Key 鉴权。

语法

bl finetune checkpoints --job-id <id>

参数	类型	必填	说明
--job-id <id>	string	是	微调任务 ID

示例：列出微调任务生成的 Checkpoint

bl finetune checkpoints --job-id ft-xxx

• SUCCEEDED Checkpoint 中显示的 model_name 可直接作为 deploy create --model-name 的输入。
• Checkpoint 创建后约 15 天过期，expire_time 显示截止时间。请在过期前导出或部署。

bl finetune export

将 Checkpoint 发布为可部署模型。需要 API Key 鉴权。

语法

bl finetune export --job-id <id> --checkpoint <name> --model-name <name>

参数	类型	必填	说明
--job-id <id>	string	是	微调任务 ID
--checkpoint <name>	string	是	来自 finetune checkpoints 的 Checkpoint 标识
--model-name <name>	string	是	可部署模型名称

示例：将 Checkpoint 发布为可部署模型

bl finetune export --job-id ft-xxx --checkpoint ckpt-3 --model-name my-qwen-sft

• 必须先执行此操作，deploy <modality> create 才能使用 Checkpoint。任务达到 SUCCEEDED 后，平台可能自动导出最佳 Checkpoint；对于非最佳 Checkpoint，显式导出是标准方式。

bl finetune cancel

取消正在运行的微调任务。需要 API Key 鉴权。

语法

bl finetune cancel --job-id <id>

参数	类型	必填	说明
--job-id <id>	string	是	微调任务 ID

示例：取消正在运行的微调任务

bl finetune cancel --job-id ft-xxx

• 只有 PENDING / RUNNING 状态的任务可以取消。已完成、失败或已取消的任务会返回服务端错误（原样透传）。

bl finetune delete

删除微调任务记录。需要 API Key 鉴权。

语法

bl finetune delete --job-id <id>

参数	类型	必填	说明
--job-id <id>	string	是	微调任务 ID
--yes	switch	否	确认执行此高风险操作

示例：删除微调任务记录

bl finetune delete --job-id ft-xxx

• 该操作不可撤销——任务记录将被永久删除。
• 请先通过 finetune cancel 取消 RUNNING 任务，平台拒绝删除仍在运行的任务。

bl finetune capability

查询微调训练能力：按模型查询其支持的训练类型，或按训练类型查询支持它的模型。无需鉴权。

语法

bl finetune capability --base-model <m> | --training-type <t>

参数	类型	必填	说明
--base-model <m>	string	否	列出该基础模型支持的训练类型。
--training-type <t>	string	否	列出支持该训练类型的模型：sft | sft-lora | dpo | dpo-lora | cpt。

示例：查询 qwen3-8b 模型支持的训练类型

bl finetune capability --base-model qwen3-8b

• --base-model 和 --training-type 必须且只能指定一个。
• 训练类型遵循 <method> / <method>-lora 命名约定：sft | sft-lora | dpo | dpo-lora | cpt。（服务端没有 cpt-lora 变体。）
• 查询公开 API listFoundationModels，无需登录控制台。

bl finetune params

查询基础模型的训练超参配置。需要 API Key 鉴权。

语法

bl finetune params --base-model <model> [--training-type <t>] [--param-type <hyper|resource>] [--mtu-spec-code <code>] [--modality <text|vision>] [--reasoning-mode <instruct|thinking>] [--lang <locale>] [--workspace-id <id>]

参数	类型	必填	说明
--base-model <model>	string	是	要查询训练参数的基础模型（例如 qwen3-8b）
--training-type <t>	string	否	训练类型：sft | sft-lora | dpo | dpo-lora | cpt（默认：sft-lora）。映射为服务端 training_type（例如 sft-lora -> efficient_sft）。
--mtu-spec-code <code>	string	否	MTU 规格代码，资源组查询时必填（例如 MTU2）
--param-type <hyper|resource>	string	否	参数组：hyper | resource。省略时返回全部参数组。
--modality <text|vision>	string	否	训练模态：text | vision。仅对支持动态训练选项的模型有效；作为 hyper_parameters 中的 modality 发送。
--reasoning-mode <instruct|thinking>	string	否	推理模式：instruct（非思考）| thinking。仅对支持动态训练选项的模型有效；作为 hyper_parameters 中的 reasoning_mode 发送。
--lang <locale>	string	否	服务端展示文本的语言（例如 en、zh）。省略时使用服务端默认值。
--workspace-id <id>	string	否	作为 X-DashScope-WorkSpace 发送的工作空间 ID。API Key 已绑定工作空间时可省略。

示例：查询基础模型的训练超参

bl finetune params --base-model qwen3-8b

示例：查询动态训练选项

bl finetune params --base-model qwen3.7-plus-2026-05-26 --modality vision --reasoning-mode thinking

• 查询 GET /api/v1/fine-tunes/fine-tunes-params。每个 hyper_params 条目保留服务端字段名（recommend_value、defaultValue、is_advanced_parameter 等）。
• --modality / --reasoning-mode 合并为一个 hyper_parameters JSON 查询参数。支持的值和组合因模型而异；无效组合由服务端拒绝并原样返回。不支持动态训练选项的模型会忽略这两个参数。
• 输出中的 resume_from_checkpoint 表示该训练类型是否支持恢复训练。

bl finetune price

估算微调任务的训练费用（按 Token 计费）。

语法

bl finetune price --base-model <model> --datasets <ids> [--training-type <type>] [--n-epochs <n>]

参数	类型	必填	说明
--base-model <model>	string	是	待微调的基座模型（例如 qwen3-8b；不是输出模型名称）
--datasets <ids>	string	是	训练数据集文件 ID，多个以逗号分隔
--training-type <type>	string	否	训练类型：sft | dpo | cpt（默认：sft）
--n-epochs <n>	number	否	训练轮数（默认：3）

示例：估算 qwen3-8b 使用 file-ft-xxx 数据集的微调费用

bl finetune price --base-model qwen3-8b --datasets file-ft-xxx

• 该结果仅为估算值——服务端根据数据集计算 Token 用量，最终费用以账单为准。
• 支持估算 sft / dpo / cpt 的 Token 计费；此命令不支持训练单元（MTU）计费估算。
• 除 --n-epochs 外，其他超参数会使用具有代表性的固定默认值进行估算。

模型压缩

模型压缩用于量化支持的全参微调模型。先通过 templates 查询可用模板，再创建压缩任务；任务成功后，返回的 quantized_output 可作为 deploy text create --model-name 的输入。模型压缩 API 目前仅在北京地域开放。

bl finetune compress templates

列出可量化的模型及其压缩模板。需要 API Key 鉴权。

语法

bl finetune compress templates [--model <model>]

参数	类型	必填	说明
--model <model>	string	否	按自定义模型 ID 或基础模型名称筛选

示例：查看支持压缩的模型和模板

bl finetune compress templates

• 仅返回支持的全参微调模型；LoRA 模型和已量化模型不会返回。
• 模板 ID 位于 output.custom_models[].templates[].template_id。output.base_models 只列出可量化的基础模型名称，不包含模板 ID。
• templates[].hyper_parameters 为空表示该模板没有可调超参数，创建压缩任务时省略 --hparam。

bl finetune compress create

创建模型压缩任务。需要 API Key 鉴权。

语法

bl finetune compress create --model <model> --template-id <id> [flags]

参数	类型	必填	说明
--model <model>	string	是	源自定义模型 ID
--template-id <id>	string	是	压缩模板 ID
--job-name <name>	string	否	唯一任务名称，最多 50 个字符
--description <text>	string	否	任务描述，最多 200 个字符
--hparam <key=value>	array	否	覆盖超参数（可重复）
--calibration-files <file-id,...>	string	否	校准数据集文件 ID，多个用逗号分隔
--suffix <suffix>	string	否	输出模型后缀（1–8 个小写字母或数字）

示例：使用指定模板创建压缩任务

bl finetune compress create --model qwen3.5-flash-2026-02-23-ft-xxx --template-id quant-flash-nvfp4-mlp-nomtp

bl finetune compress list

列出模型压缩任务。需要 API Key 鉴权。

语法

bl finetune compress list [filters] [--page <n>] [--page-size <n>]

参数	类型	必填	说明
--status <status>	string	否	按任务状态筛选
--model <model>	string	否	按源模型 ID 筛选
--template-id <id>	string	否	按模板 ID 筛选
--quant-spec <spec>	string	否	按量化规格筛选
--quant-method <method>	string	否	按量化方法筛选
--start-time <time>	string	否	任务开始时间不早于该时间
--end-time <time>	string	否	任务结束时间不晚于该时间
--search <keyword>	string	否	搜索任务 ID 或名称
--search-field <job_id|job_name>	string	否	将 --search 限定为任务 ID 或名称
--sort-order <asc|desc>	string	否	按创建时间排序（默认：desc）
--page <n>	number	否	页码（默认：1）
--page-size <n>	number	否	每页结果数（默认：10，最多：100）

示例：列出最近成功的压缩任务

bl finetune compress list --status SUCCEEDED --page-size 20

bl finetune compress get

获取模型压缩任务详情。需要 API Key 鉴权。

语法

bl finetune compress get --job-id <id>

参数	类型	必填	说明
--job-id <id>	string	是	压缩任务 ID

示例：查看指定压缩任务详情

bl finetune compress get --job-id quant-xxx

bl finetune compress watch

探测或持续跟踪压缩任务状态。需要 API Key 鉴权。

语法

bl finetune compress watch --job-id <id> [--follow] [--interval <sec>] [--poll-timeout <sec>]

参数	类型	必填	说明
--job-id <id>	string	是	压缩任务 ID
--follow	switch	否	轮询直到任务进入终态
--interval <sec>	number	否	使用 --follow 时的轮询间隔（默认：10，最小：1）
--poll-timeout <sec>	number	否	超过该时长后停止轮询

示例：持续跟踪压缩任务直到结束

bl finetune compress watch --job-id quant-xxx --follow

• 不传 --follow 时只执行一次非阻塞状态探测。
• 任务成功后，可将 quantized_output 传给 deploy text create --model-name。

bl finetune compress logs

获取模型压缩任务日志。需要 API Key 鉴权。

语法

bl finetune compress logs --job-id <id> [--offset <n>] [--lines <n> | --tail <n>]

参数	类型	必填	说明
--job-id <id>	string	是	压缩任务 ID
--offset <n>	number	否	跳过前 N 行（默认：0）
--lines <n>	number	否	读取行数（默认：100，最多：1000）
--tail <n>	number	否	读取最后 N 行日志

示例：读取最后 20 行压缩日志

bl finetune compress logs --job-id quant-xxx --tail 20

bl finetune compress cancel

取消模型压缩任务。需要 API Key 鉴权。

语法

bl finetune compress cancel --job-id <id>

参数	类型	必填	说明
--job-id <id>	string	是	压缩任务 ID

示例：取消指定压缩任务

bl finetune compress cancel --job-id quant-xxx

• 仅 PENDING、QUEUING 或 RUNNING 状态的任务可以取消。

bl finetune compress delete

删除模型压缩任务记录。需要 API Key 鉴权。

语法

bl finetune compress delete --job-id <id>

参数	类型	必填	说明
--job-id <id>	string	是	压缩任务 ID
--yes	switch	否	确认执行此高风险操作

示例：预览删除指定压缩任务记录

bl finetune compress delete --job-id quant-xxx --dry-run

• 仅终态任务可以删除；删除任务记录不会删除其量化输出模型。