bailian-train-deploy

Files (11)

• README.md
• README.zh.md
• SKILL.md
• evals.json · evals/
• audio.md · references/
• deploy.md · references/
• finetune.md · references/
• image.md · references/
• text.md · references/
• video.md · references/
• wait.sh · scripts/

SKILL.md (first lines)

# 百炼模型训练→部署闭环 (`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` —— 若已有引用同一 `finetuned_output` 且 RUNNING 的部署，直接复用其 `deployed_model`，**不要再建第二个计费实例**。
2. **计费确认硬闸门（mu/ptu）**：
   - `lora`（默认，按 token 计费，闲置一般不计费）—— 安全默认，可直接创建。
   - `mu` / `ptu` 是**预留/独占资源，闲置也计费**——创建前**必须**向用户显式说明计费方式并取得确认。在 agent / CI 等非交互环境**不能自动开通预留资源**。命中 mu/ptu 时，把“这会产生闲置计费”连同命令交还给真人在终端确认（`bl` 当前不提供 `--yes` 跳过确认 flag，确认行为完全由真人把控）。
3. **账号就绪检查**：`bl auth status` —— `authenticated: false` 即停，给 `bl auth login --api-key sk-...`。百炼走 API key / access token 认证，**没有独立的实名闸门**，`auth status` 即账号就绪检查。

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

| 用户意图 | 路由到 | 完整示范命令 |
|---|---|---|
| 只想试模型效果 / 一次性对话 | `bailian-cli` | `bl text chat --model qwen3-8b --message "..."` |
| 已确定模型，只要调用方式 | `bailian-cli` | `bl text chat --model <model> --message "..."` |
| 不知道选哪个基座 / 模型选型 | `bailian-model-recommend` | （让该 skill 按场景推荐）|
| 纯查模型参数 / 价格 / 上下文窗口 | `bailian-docs-llm-wiki` | （查模型数据目录）|
| 已有部署，只想生成调用示例 | `bailian-cli` | `bl text chat --model <deployed_model> --message "..."` 或 `bl speech synthesize --model <deployed_model> --voice default --text "..."` 或异步 API + 触发词（图像生成，见 [image.md](references/image.md#推理与调用)）|
| 对已有训练任务 / 部署做查删（生命周期） | `bl` 直接 | `bl finetune list` / `bl deploy list` / `bl deploy delete --deployed-model <id>` |

> 本 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 读取 `template_id`，在请求体中发送为 `deploy_spec`。
- **`--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（`DASHSCOPE_API_KEY` 或 `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 步：创建微调任务

```bash
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.job_id`、`output.finetuned_output`（输出模型名，形如 `<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 步即可，无需手动导出。

From modelstudioai/skills, Apache-2.0.

More from modelstudioai/skills