百炼模型训练→部署闭环 (bl)

用百炼 CLI bl 把模型部署成可调用的专属推理服务——可以先微调再部署，也可以跳过训练直接部署基座。支持文本、音频 TTS、图像生成和视频生成四种模态，两处"等待"用 Monitor 异步轮询，不阻塞主流程。

链路 A（先训练后部署）：
数据集 → finetune <模态> create → 等 SUCCEEDED → 导出模型(通常自动) → deploy <模态> create → 等 RUNNING → 调用

链路 B（直接部署基座，跳过训练）：
选基座 → deploy <模态> create → 等 RUNNING → 调用

链路 B 适用于"只想把某个基座跑成自己的部署服务"——和直接调用 API 在推理上没本质区别，但能拿到独立部署实例、可调速率/计费方式、纳入自己的运维。仅当用户明确表示不训练 / 跳过训练 / 直接部署基座时才走这条；用户只是没提训练细节时，默认按链路 A 引导，不要擅自跳过训练。

模态分发：本技能的通用流程适用于所有模态，但数据格式、超参、推理命令因模态而异。确定用户意图后，按模态查阅对应参考文件：

• 文本模型（对话/推理）→ [references/text.md](references/text.md)
• 音频 TTS 模型（语音合成/CosyVoice）→ [references/audio.md](references/audio.md)
• 图像生成模型（文生图/图生图/Wan2.7）→ [references/image.md](references/image.md)
• 视频生成模型（图生视频/首尾帧/Wan i2v/kf2v）→ [references/video.md](references/video.md)
• 未来新增模态 = 新增对应 reference 文件，本流程骨架不变

本技能假设 bl（bailian-cli）已安装。命令/flag 细节以 bl <cmd> --help 为准；本技能聚焦流程编排与避坑。

写操作护栏（创建前必读）

bl finetune <模态> create 与 bl deploy <模态> create 都是真实写操作，会产生计费资源（微调训练 + 推理部署）。bl 没有 --dry-run，所以用预检命令代替预演、用计费确认把关预留资源。任何写操作前必须先过这三道闸：

1. 预检代替 dry-run（创建前必跑，确认可行再写）。这些预检命令本身都需先通过下方[前置检查](#前置检查动作流起点)的认证——未认证先 bl auth login 再预检：

- 训练前：bl finetune capability --base-model <base> —— 确认基座支持你选的 training-type（不支持会快速失败且不耗配额；create 提交时也会再校验一次）。 - 部署前：bl deploy models --source custom（链路 A 微调输出）或 --source base（链路 B 基座）—— 确认目标模型可部署、看清可用 plan，再决定 --plan。 - 复用检测：bl deploy list --status RUNNING —— 若已有引用同一 finetunedoutput 且 RUNNING 的部署，直接复用其 deployedmodel，不要再建第二个计费实例。

1. 计费确认硬闸门（mu/ptu）：

- lora（默认，按 token 计费，闲置一般不计费）—— 安全默认，可直接创建。 - mu / ptu 是预留/独占资源，闲置也计费——创建前必须向用户显式说明计费方式并取得确认。在 agent / CI 等非交互环境不能自动开通预留资源。命中 mu/ptu 时，把“这会产生闲置计费”连同命令交还给真人在终端确认（bl 当前不提供 --yes 跳过确认 flag，确认行为完全由真人把控）。

1. 账号就绪检查：bl auth status —— authenticated: false 即停，给 bl auth login --api-key sk-...。百炼走 API key / access token 认证，没有独立的实名闸门，auth status 即账号就绪检查。

反触发表（不归本 skill 的意图，附完整命令）

本 skill 只负责"新建训练任务 + 新建部署 + 调用交付"这一条闭环。训练任务与部署的全生命周期管理（list / stop / delete 历史任务、删除部署等）不在本 skill 流程内，用 bl finetune list / bl deploy list / bl deploy delete 直接操作。

反幻觉清单

• --base-model / --model-name / --model 分属不同命令，切勿复用：

- bl finetune <模态> create --base-model → 基座模型名（文本 qwen3-8b，音频 cosyvoice-v3-flash，图像 wan2.7-image-pro）。 - bl deploy <模态> create --model-name → 导出模型名（链路 A：qwen3-8b-ft-... / cosyvoice-v3-flash-ft-... / wan2.7-image-pro-ft-...；链路 B：基座名）。 - 推理命令 --model → 必须用 deploy <模态> create 响应里的 deployed_model，不是你传给 deploy <模态> create 的名字。

• --training-type 取值穷举：sft / sft-lora（默认）/ dpo / dpo-lora / cpt。映射在 CLI 边界完成（sft-lora→efficient_sft），永远传 CLI 值，不要传服务端字符串。cpt 无 -lora 变体。音频 TTS 和图像生成都只用 sft-lora——finetune audio create / finetune image create 不暴露此 flag，仅 finetune text create 接受。
• --plan 取值穷举：lora（默认，token 计费）/ ptu（需 --input-tpm/--output-tpm）/ mu（需 --deploy-spec/--capacity）。链路 B 基座通常不支持 lora。音频 TTS 微调模型只支持 mu。图像生成微调模型只支持 lora。
• --deploy-spec（非 template-id）：mu plan 的部署规格 flag。CLI 从 catalog 读取 templateid，在请求体中发送为 deployspec。
• --source 取值穷举（bl deploy models）：custom（微调输出）/ base（基座）/ public。
• --learning-rate 必须字符串：传 "3e-4"，不要传数字 3e-4，避免 JSON 精度丢失（文本适用，音频/图像不需要传此参数）。
• 推理命令因模态不同：文本模型用 bl text chat，音频 TTS 用 bl speech synthesize --voice default，图像生成用异步 API + 触发词（详见 [references/image.md](references/image.md#推理与调用)）。
• 没有这些 flag/子命令：bl 无 --dry-run、无裸 finetune create/deploy create（必须带模态段：finetune text|audio|image create、deploy text|audio|image create）、无 finetune start、无 deploy stop（停用/恢复用 bl deploy pause / bl deploy resume；pause 对 mu/ptu 停止计费）。
• 必填：finetune <模态> create 的 --base-model / --datasets；deploy <模态> create 的 --model-name / --display-name。

前置检查（动作流起点）

• 认证：bl auth status，确认已配置 API key（DASHSCOPEAPIKEY 或 bl auth login --api-key sk-...）。
• 基座选型：查询训练能力用 bl finetune capability（查 listFoundationModels，走 API key、无需 console 登录）：

- bl finetune capability --base-model <base> —— 该模型支持哪些训练类型。 - bl finetune capability --training-type sft-lora —— 反向查：哪些模型支持该训练类型（返回 models 列表，含中文名）。 - 选定基座后可直接进入第 2 步；bl finetune <模态> create 提交前也会再用 listFoundationModels 校验，不支持会快速失败。 - 文本推理推荐 Qwen3 系列（qwen3-8b / qwen3-14b / qwen3.6-flash）；音频 TTS 用 cosyvoice-v3-flash；图像生成用 wan2.7-image-pro / wan2.7-image。

第 1 步：准备数据集

支持三种数据来源，由你（Agent）根据用户意图灵活选用，不必写死交互流程——你本身具备主动提问能力，知道有哪些选项后自然向用户确认即可：

1. 本地数据集 —— 用户提供本地文件路径，直接使用。
2. 已上传数据集 —— 从百炼上已有的数据集中选取（bl dataset list）。
3. 生成示例数据 —— 征得用户同意后，由你生成一份小规模示例数据，仅用于跑通流程（效果有限，需如实告知用户）。

数据格式因模态不同，详见对应参考文件：

• 文本模型：.jsonl 文件（ChatML/DPO/CPT schema），详见 [references/text.md](references/text.md#数据格式)。
• 音频 TTS：.zip 包（内含 data.jsonl + train/*.wav），详见 [references/audio.md](references/audio.md#数据格式)。
• 图像生成：.zip 包（内含 data.jsonl + 图像文件平铺），详见 [references/image.md](references/image.md#数据格式)。

提交训练前用 bl dataset validate --file <path> 校验通过再继续（CLI 自动探测 schema，也可 --schema tts / --schema image / --schema chatml 显式指定）。

第 2 步：创建微调任务

bl finetune <模态> create \
  --base-model <base-model> \
  --datasets <path-or-file-id> \
  --output json

training-type 取值与映射详见 [references/finetune.md](references/finetune.md)。模态特异性超参见对应参考文件：

• 文本模型（finetune text create）：接受 --training-type / --n-epochs / --learning-rate 等，详见 [references/text.md](references/text.md#创建训练任务)。
• 音频 TTS（finetune audio create）：不暴露 --training-type（内部固定 sft-lora），超参由 CLI 自动注入，详见 [references/audio.md](references/audio.md#创建训练任务)。
• 图像生成（finetune image create）：不暴露 --training-type（内部固定 sft-lora），超参由 CLI 自动注入，详见 [references/image.md](references/image.md#创建训练任务)。

从响应记下：output.jobid、output.finetunedoutput（输出模型名，形如 <base>-ft-<ts>-<id>）。

第 3 步：等待训练完成（异步）

用 Monitor 工具运行本技能自带的等待脚本——它会在状态变化时通知，到终态退出：

Monitor command: bash <本技能目录>/scripts/wait.sh finetune <JOB_ID>

<本技能目录> 即本技能的 base 目录（技能加载时会给出，含 scripts/wait.sh），用实际路径替换。脚本每 30s 轮询，终态为 SUCCEEDED/FAILED/CANCELED/PARTIALLY_SUCCEEDED。

⚠️ 避坑：不要在 zsh 里手写 status=... 轮询循环。 status 是 zsh 的只读内置变量，赋值会报 read-only variable 并让脚本 exit 1。用本技能的 bash 脚本（#!/usr/bin/env bash）规避，或自写时改用 st 等变量名。

第 4 步：导出最佳模型（通常可跳过）

任务 SUCCEEDED 后，平台会自动导出 best checkpoint 为可部署模型——直接进第 5 步即可，无需手动导出。

只有要部署非 best 的某个 checkpoint 时才显式导出：

bl finetune checkpoints --job-id <JOB_ID>          # 列出可用 checkpoint
bl finetune export --job-id <JOB_ID> --checkpoint <name> --model-name <自定义名>

第 5 步：创建部署

创建前先过[写操作护栏](#写操作护栏创建前必读)：bl deploy list --status RUNNING 查是否已有同模型部署可复用；bl deploy models --source custom|base 确认可用 plan；mu/ptu 必须先取得用户计费确认。

⚠️ 关键避坑：微调后的模型不能直接用微调输出名调用，会 404 Model not exist。必须先创建部署。（链路 B 部署基座同理——直接调用走的是公共推理，不经过你的部署实例。）

bl deploy <模态> create \
  --model-name <finetuned-output> \   # 微调输出名(链路A) 或基座名(链路B)
  --display-name <display-name> \
  --plan <lora|ptu|mu> \              # 见下方说明
  --output json

• 模态段（text / audio / image）须与部署模型模态匹配；三个模态子命令 flag 完全相同。
• --model-name：链路 A 传第 2 步的 finetuned_output；链路 B 直接传基座模型名。
• --plan：

- 文本微调模型默认 lora（token 计费），也可用 mu。 - 音频 TTS 微调模型只支持 mu（不支持 lora / ptu），需 --deploy-spec + --capacity。 - 图像生成微调模型只支持 lora（不支持 mu / ptu）。 - 链路 B 基座通常只支持 ptu/mu，不支持 lora。 - 各 plan 必填参数与计费细则见 [references/deploy.md](references/deploy.md)。

• --deploy-spec：mu plan 的部署规格（如 dps-20260521172224-1vabse），省略时自动从 catalog 匹配。
• 不确定支持哪些 plan：链路 A 用 bl deploy models --source custom，链路 B 用 bl deploy models --source base，按返回的 plans 选。

⚠️ 避坑（最高频错误）：--model-name 与推理命令的 --model 含义不同——deploy <模态> create --model-name 传导出模型名，响应返回的 output.deployedmodel 才是部署实例 id，推理命令 --model 必须用 deployedmodel，不要复用。详见 [references/deploy.md](references/deploy.md)。

从响应记下：output.deployed_model。

第 6 步：等待部署就绪（异步）

Monitor command: bash <本技能目录>/scripts/wait.sh deploy <DEPLOYED_MODEL>

<本技能目录> 同第 3 步。每 15s 轮询，RUNNING 即就绪（FAILED/STOPPED 终止）。

⚠️ 避坑：状态传播延迟。 部署刚到 RUNNING 时立即调用，可能短暂返回 404 Model not exist——这是服务端状态传播延迟，不是用错模型名。bl deploy get 也可能还显示 PENDING。约 1 分钟内会稳定，遇 404 等十几秒重试即可；若持续 404，先核对用的是 deployed_model 而非微调输出名。

第 7 步：调用与交付

推理命令因模态不同：

文本模型：

bl text chat --model <DEPLOYED_MODEL> --message "你的问题"

音频 TTS 模型：

bl speech synthesize --model <DEPLOYED_MODEL> --voice default --text "你要合成的文本" --out result.mp3

图像生成模型（异步 API，需触发词）：

# 详见 references/image.md —— 需 X-DashScope-Async 头 + prompt 含触发词

--model 必须用 deploy <模态> create 响应中的 deployed_model，不是微调输出名。音频 TTS 的 --voice 固定为 default。图像生成需异步调用且 prompt 包含触发词。详见对应模态参考文件。

向用户交付时给出：

• 部署实例 id（deployed_model）——调用用它，不是微调输出名
• 一条可直接运行的推理示例命令
• 常用运维命令：bl deploy get --deployed-model <id> 查状态；bl deploy delete --deployed-model <id> 删除部署；bl finetune list 查历史任务。

收尾提示

• 闲置计费与删除：lora 闲置一般不计费；mu/ptu 闲置也计费，不用要清理；bl deploy delete 只能删 STOPPED/FAILED 的部署，RUNNING 的 mu/ptu 可先 bl deploy pause（停止计费）再删。细则见 [references/deploy.md](references/deploy.md#计费与运维细则)。
• 复用数据集：多次训练同一数据时，先 bl dataset upload 拿 file-id，再用 --datasets <file-id> 避免重复上传。
• 效果不好：优先加数据（量与质量），其次调 n-epochs/learning-rate，最后才考虑全参 sft。小数据集（<100 条）效果上限有限，要管理预期。