reference/dataset.md
# `bl dataset` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| --------------------- | -------------- | ------------------------------------------------------------------ |
| `bl dataset delete` | API Key | Delete a dataset file by ID |
| `bl dataset get` | API Key | Get details of a single dataset file |
| `bl dataset list` | API Key | List uploaded dataset files |
| `bl dataset upload` | API Key | Upload a dataset file (.jsonl or .zip) to Bailian |
| `bl dataset validate` | No Auth | Locally validate a dataset file (.jsonl or .zip) without uploading |
## Command details
### `bl dataset delete`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------- |
| **Name** | `dataset delete` |
| **Description** | Delete a dataset file by ID |
| **Authentication** | API Key |
| **Usage** | `bl dataset delete --file-id <id>` |
| **Risk** | `high` |
| **Risk message** | This permanently deletes the specified dataset file and cannot be undone. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------------------- |
| `--file-id <id>` | string | yes | Dataset file ID (required) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl dataset delete --file-id file-id-xxx
```
```bash
bl dataset delete --file-id file-id-xxx --dry-run
```
```bash
# Only after explicit user confirmation:
bl dataset delete --file-id file-id-xxx --yes
```
### `bl dataset get`
| Field | Value |
| ------------------ | ------------------------------------ |
| **Name** | `dataset get` |
| **Description** | Get details of a single dataset file |
| **Authentication** | API Key |
| **Usage** | `bl dataset get --file-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------------- |
| `--file-id <id>` | string | yes | Dataset file ID (required) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl dataset get --file-id file-xxx
```
```bash
bl dataset get --file-id file-xxx --output json
```
### `bl dataset list`
| Field | Value |
| ------------------ | ------------------------------------------------------------------- |
| **Name** | `dataset list` |
| **Description** | List uploaded dataset files |
| **Authentication** | API Key |
| **Usage** | `bl dataset list [--page <n>] [--page-size <n>] [--purpose <name>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | --------------------------------------------------------------------- |
| `--page <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Results per page (default: 10, max 100) |
| `--purpose <name>` | string | no | Filter by purpose (e.g. "fine-tune", "evaluation"). Omit to list all. |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl dataset list
```
```bash
bl dataset list --purpose fine-tune
```
```bash
bl dataset list --purpose evaluation --page-size 20
```
```bash
bl dataset list --output json
```
### `bl dataset upload`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `dataset upload` |
| **Description** | Upload a dataset file (.jsonl or .zip) to Bailian |
| **Authentication** | API Key |
| **Usage** | `bl dataset upload --file <path> [--purpose <name>] [--schema <chatml\|dpo\|cpt\|tts\|image\|video>] [--no-validate] [--full-validate]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--file <path>` | string | yes | Local dataset file (.jsonl or .zip; ≤200MB SFT/DPO, ≤300MB CPT, ≤2GB media zip) |
| `--purpose <name>` | string | no | Dataset purpose tag (default: "fine-tune"; e.g. "evaluation") |
| `--schema <s>` | string | no | Record schema: "chatml" (SFT), "dpo" (chosen/rejected), "cpt" (raw text), "tts" (audio), "image" (image generation), or "video" (video generation). Default auto-detects per record. |
| `--no-validate` | switch | no | Skip the local JSONL pre-flight check (not recommended) |
| `--full-validate` | switch | no | JSON.parse every line instead of sampling (slower) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Supports .jsonl (text) and .zip (audio/image/video archives with a data.jsonl manifest). Six record schemas are recognized: chatml = {messages:[...]} (SFT); dpo = {messages:[...], chosen, rejected}; cpt = {text:"..."} (continual pre-training, raw text); tts = {wav_fn:"train/xxx.wav", text:"..."} (audio fine-tuning); image = {img_path:"..."} (image generation); video = {first_frame_path:...} (video generation).
- With no --schema, a record carrying wav_fn is validated as TTS, img_path as image, chosen/rejected as DPO, text (no messages) as CPT, otherwise ChatML.
- Upload cap: 200MB SFT/DPO text, 300MB CPT, 2GB media zip. Upload uses the OpenAI-compatible /compatible-mode/v1/files endpoint so the purpose tag is persisted (the DashScope-native /api/v1/files drops it).
#### Examples
```bash
bl dataset upload --file train.jsonl
```
```bash
bl dataset upload --file dpo.jsonl --schema dpo
```
```bash
bl dataset upload --file cpt.jsonl --schema cpt
```
```bash
bl dataset upload --file audio.zip --schema tts
```
```bash
bl dataset upload --file eval.jsonl --purpose evaluation
```
```bash
bl dataset upload --file train.jsonl --full-validate
```
```bash
bl dataset upload --file train.jsonl --no-validate
```
### `bl dataset validate`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| **Name** | `dataset validate` |
| **Description** | Locally validate a dataset file (.jsonl or .zip) without uploading |
| **Authentication** | No Auth |
| **Usage** | `bl dataset validate --file <path> [--full-validate] [--schema <chatml\|dpo\|cpt\|tts\|image\|video>]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--file <path>` | string | yes | Local dataset file (.jsonl or .zip) |
| `--full-validate` | switch | no | JSON.parse every line instead of sampling (slower) |
| `--schema <s>` | string | no | Record schema: "chatml" (SFT), "dpo" (chosen/rejected), "cpt" (raw text), "tts" (audio), "image" (image generation), or "video" (video generation). Default auto-detects per record. |
#### Notes
- Default scan: every line gets a structural check, then ~160 lines (front 50, evenly spaced 100, last 10) are JSON.parsed against the active schema.
- Schemas: chatml = {messages:[...]} (SFT); dpo = {messages:[...], chosen, rejected}; cpt = {text:"..."} (continual pre-training, raw text); tts = {wav_fn:"train/xxx.wav", text:"..."} (audio fine-tuning); image = {img_path:"..."} (image generation); video = {first_frame_path:"...", video_path:"..."} (video generation, i2v first-frame or kf2v first+last-frame with last_frame_path).
- With no --schema, a record carrying wav_fn is validated as TTS, img_path as image, first_frame_path/video_path as video, chosen/rejected as DPO, text (no messages) as CPT, otherwise ChatML. Pass --schema to require a specific shape on every record.
- ZIP archives (.zip) are validated structurally (data.jsonl present, media references resolve) in addition to per-record content checks. Use --full-validate to JSON.parse every line.
#### Examples
```bash
bl dataset validate --file train.jsonl
```
```bash
bl dataset validate --file dpo.jsonl --schema dpo
```
```bash
bl dataset validate --file cpt.jsonl --schema cpt
```
```bash
bl dataset validate --file audio.zip --schema tts
```
```bash
bl dataset validate --file wan-i2v-training-dataset.zip --schema video
```
```bash
bl dataset validate --file eval.jsonl --full-validate
```
```bash
bl dataset validate --file train.jsonl --output json
```
reference/deploy.md
# `bl deploy` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ------------------------ | -------------- | ------------------------------------------------------------- |
| `bl deploy audio create` | API Key | Create an audio (TTS) model deployment |
| `bl deploy delete` | API Key | Delete a model deployment (must be STOPPED or FAILED) |
| `bl deploy get` | API Key | Get details of a single model deployment |
| `bl deploy image create` | API Key | Create an image generation model deployment |
| `bl deploy list` | API Key | List model deployments |
| `bl deploy models` | API Key | List models available for deployment |
| `bl deploy pause` | Console | Pause a running model deployment (stops billing for mu/ptu) |
| `bl deploy resume` | Console | Resume a paused model deployment (brings service back online) |
| `bl deploy scale` | API Key | Scale a deployment's capacity |
| `bl deploy text create` | API Key | Create a text model deployment |
| `bl deploy update` | API Key | Update a deployment's rate limits (rpm_limit / tpm_limit) |
## Command details
### `bl deploy audio create`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name** | `deploy audio create` |
| **Description** | Create an audio (TTS) model deployment |
| **Authentication** | API Key |
| **Usage** | `bl deploy audio create --model-name <model_name> --display-name <display_name> [--plan <plan>] [--deploy-spec <id>] [--capacity <n>] [--billing-method <m>] [--input-tpm <n>] [--output-tpm <n>] [--thinking-output-tpm <n>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `--model-name <model_name>` | string | yes | Model to deploy — fine-tuned output name or catalog model (required) |
| `--display-name <display_name>` | string | yes | Console display name for the deployment (required) |
| `--plan <plan>` | string | no | Billing plan: lora (default, Token-billed) \| ptu (Token-billed) \| mu |
| `--deploy-spec <id>` | string | no | Deploy spec (only used by plan=mu; auto-picked if omitted) |
| `--capacity <n>` | number | no | Resource units (plan=mu only; required by API; defaults to the template's unit) |
| `--billing-method <m>` | string | no | Billing method (plan=mu only; default "POST_PAY", the only supported value) |
| `--input-tpm <n>` | number | no | PTU max input tokens/min (required for plan=ptu) |
| `--output-tpm <n>` | number | no | PTU max output tokens/min (required for plan=ptu) |
| `--thinking-output-tpm <n>` | number | no | PTU max thinking-output tokens/min (optional, some models) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Plan defaults to `lora` (Token-billed) for text/image and `mu` (model-unit-billed) for audio (CosyVoice TTS). Pass --plan to override.
- For plan=ptu (Token-billed, provisioned throughput), --input-tpm and --output-tpm are required (the platform rejects creation without an explicit ptu_capacity despite the doc listing defaults).
- For plan=mu, `capacity`, `billing_method` and `deploy_spec` are required. billing_method defaults to POST_PAY (only supported value); deploy_spec and capacity are auto-picked from GET /deployments/models when omitted.
- Use `bl deploy models --source base` to inspect available templates.
- After creation, status starts at PENDING and transitions to RUNNING. Invoke the deployed model with: bl text chat --model <deployed_model>
- NOTE: --model-name is the model being deployed (e.g. `qwen3-8b-ft-...`). The create response also returns a `deployed_model` field — the deployment instance id (e.g. `qwen3-8b-5ecb5f068d79`). Use that id for inference (`bl text chat --model <deployed_model>`) and lifecycle commands (`deploy get/scale/pause/resume/delete --deployed-model <id>`).
#### Examples
```bash
bl deploy audio create --model-name my-cosyvoice-ft --display-name my-tts
```
```bash
bl deploy audio create --model-name my-cosyvoice-ft --display-name my-tts --deploy-spec dps-xxxx --capacity 1
```
```bash
bl deploy audio create --model-name my-cosyvoice-ft --display-name my-tts --dry-run
```
### `bl deploy delete`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------- |
| **Name** | `deploy delete` |
| **Description** | Delete a model deployment (must be STOPPED or FAILED) |
| **Authentication** | API Key |
| **Usage** | `bl deploy delete --deployed-model <id> [--skip-precheck]` |
| **Risk** | `high` |
| **Risk message** | This permanently deletes the specified model deployment and cannot be undone. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | --------------------------------------------- |
| `--deployed-model <id>` | string | yes | Deployed model identifier (required) |
| `--skip-precheck` | switch | no | Skip the local STOPPED/FAILED status precheck |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl deploy delete --deployed-model dep-...
```
```bash
bl deploy delete --deployed-model dep-... --dry-run
```
```bash
# Only after explicit user confirmation:
bl deploy delete --deployed-model dep-... --yes
```
### `bl deploy get`
| Field | Value |
| ------------------ | ---------------------------------------- |
| **Name** | `deploy get` |
| **Description** | Get details of a single model deployment |
| **Authentication** | API Key |
| **Usage** | `bl deploy get --deployed-model <id>` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | ------------------------------------ |
| `--deployed-model <id>` | string | yes | Deployed model identifier (required) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl deploy get --deployed-model qwen-plus-2025-12-01-b6d61c71
```
```bash
bl deploy get --deployed-model qwen-plus-2025-12-01-b6d61c71 --output json
```
### `bl deploy image create`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name** | `deploy image create` |
| **Description** | Create an image generation model deployment |
| **Authentication** | API Key |
| **Usage** | `bl deploy image create --model-name <model_name> --display-name <display_name> [--plan <plan>] [--deploy-spec <id>] [--capacity <n>] [--billing-method <m>] [--input-tpm <n>] [--output-tpm <n>] [--thinking-output-tpm <n>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `--model-name <model_name>` | string | yes | Model to deploy — fine-tuned output name or catalog model (required) |
| `--display-name <display_name>` | string | yes | Console display name for the deployment (required) |
| `--plan <plan>` | string | no | Billing plan: lora (default, Token-billed) \| ptu (Token-billed) \| mu |
| `--deploy-spec <id>` | string | no | Deploy spec (only used by plan=mu; auto-picked if omitted) |
| `--capacity <n>` | number | no | Resource units (plan=mu only; required by API; defaults to the template's unit) |
| `--billing-method <m>` | string | no | Billing method (plan=mu only; default "POST_PAY", the only supported value) |
| `--input-tpm <n>` | number | no | PTU max input tokens/min (required for plan=ptu) |
| `--output-tpm <n>` | number | no | PTU max output tokens/min (required for plan=ptu) |
| `--thinking-output-tpm <n>` | number | no | PTU max thinking-output tokens/min (optional, some models) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Plan defaults to `lora` (Token-billed) for text/image and `mu` (model-unit-billed) for audio (CosyVoice TTS). Pass --plan to override.
- For plan=ptu (Token-billed, provisioned throughput), --input-tpm and --output-tpm are required (the platform rejects creation without an explicit ptu_capacity despite the doc listing defaults).
- For plan=mu, `capacity`, `billing_method` and `deploy_spec` are required. billing_method defaults to POST_PAY (only supported value); deploy_spec and capacity are auto-picked from GET /deployments/models when omitted.
- Use `bl deploy models --source base` to inspect available templates.
- After creation, status starts at PENDING and transitions to RUNNING. Invoke the deployed model with: bl text chat --model <deployed_model>
- NOTE: --model-name is the model being deployed (e.g. `qwen3-8b-ft-...`). The create response also returns a `deployed_model` field — the deployment instance id (e.g. `qwen3-8b-5ecb5f068d79`). Use that id for inference (`bl text chat --model <deployed_model>`) and lifecycle commands (`deploy get/scale/pause/resume/delete --deployed-model <id>`).
#### Examples
```bash
bl deploy image create --model-name my-wan-ft --display-name my-wan
```
```bash
bl deploy image create --model-name my-wan-ft --display-name my-wan-mu --plan mu
```
```bash
bl deploy image create --model-name my-wan-ft --display-name my-wan --dry-run
```
### `bl deploy list`
| Field | Value |
| ------------------ | -------------------------------------------------------------- |
| **Name** | `deploy list` |
| **Description** | List model deployments |
| **Authentication** | API Key |
| **Usage** | `bl deploy list [--page <n>] [--page-size <n>] [--status <s>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | ------------------------------------------------------- |
| `--page <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Results per page (default: 10, max 100) |
| `--status <s>` | string | no | Filter by status (PENDING / RUNNING / STOPPED / FAILED) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl deploy list
```
```bash
bl deploy list --status RUNNING
```
```bash
bl deploy list --page-size 20 --output json
```
### `bl deploy models`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| **Name** | `deploy models` |
| **Description** | List models available for deployment |
| **Authentication** | API Key |
| **Usage** | `bl deploy models [--page <n>] [--page-size <n>] [--catalog-version <v>] [--source <custom\|public>]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | ----------------------------------------------------------------------- |
| `--page <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Results per page (default: 100) |
| `--catalog-version <v>` | string | no | Catalog version filter (default: v1.0; required for new catalog models) |
| `--source <s>` | string | no | Model source filter: custom (fine-tuned) \| base (catalog) \| public |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl deploy models
```
```bash
bl deploy models --source base
```
```bash
bl deploy models --source custom --page-size 50
```
```bash
bl deploy models --catalog-version v1.0 --output json
```
### `bl deploy pause`
| Field | Value |
| ------------------ | ----------------------------------------------------------- |
| **Name** | `deploy pause` |
| **Description** | Pause a running model deployment (stops billing for mu/ptu) |
| **Authentication** | Console |
| **Usage** | `bl deploy pause --deployed-model <id> [--skip-precheck]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--deployed-model <id>` | string | yes | Deployed model identifier (required) |
| `--skip-precheck` | switch | no | Skip the local RUNNING/PENDING status precheck |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Notes
- While paused, billing ceases for mu/ptu plans. Use `deploy resume` to bring it back online or `deploy delete` to remove.
- Precheck verifies status is RUNNING/PENDING before issuing the pause; pass --skip-precheck to bypass.
#### Examples
```bash
bl deploy pause --deployed-model dep-...
```
```bash
bl deploy pause --deployed-model dep-... --skip-precheck
```
```bash
bl deploy pause --deployed-model dep-... --dry-run
```
### `bl deploy resume`
| Field | Value |
| ------------------ | ------------------------------------------------------------- |
| **Name** | `deploy resume` |
| **Description** | Resume a paused model deployment (brings service back online) |
| **Authentication** | Console |
| **Usage** | `bl deploy resume --deployed-model <id> [--skip-precheck]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--deployed-model <id>` | string | yes | Deployed model identifier (required) |
| `--skip-precheck` | switch | no | Skip the local STOPPED status precheck |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Notes
- Precheck verifies status is STOPPED before issuing the resume; pass --skip-precheck to bypass.
- For mu/ptu plans, billing resumes once the service is back online.
#### Examples
```bash
bl deploy resume --deployed-model dep-...
```
```bash
bl deploy resume --deployed-model dep-... --skip-precheck
```
```bash
bl deploy resume --deployed-model dep-... --dry-run
```
### `bl deploy scale`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------- |
| **Name** | `deploy scale` |
| **Description** | Scale a deployment's capacity |
| **Authentication** | API Key |
| **Usage** | `bl deploy scale --deployed-model <id> --capacity <n> [--input-tpm <n>] [--output-tpm <n>]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | ---------------------------------------------------------------- |
| `--deployed-model <id>` | string | yes | Deployed model identifier (required) |
| `--capacity <n>` | number | no | New capacity in plan units (must be a multiple of base_capacity) |
| `--input-tpm <n>` | number | no | PTU only — input tokens per minute |
| `--output-tpm <n>` | number | no | PTU only — output tokens per minute |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl deploy scale --deployed-model qwen-plus-...-b6d61c71 --capacity 8
```
```bash
bl deploy scale --deployed-model dep-... --capacity 2
```
### `bl deploy text create`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `deploy text create` |
| **Description** | Create a text model deployment |
| **Authentication** | API Key |
| **Usage** | `bl deploy text create --model-name <model_name> --display-name <display_name> [--plan <plan>] [--deploy-spec <id>] [--capacity <n>] [--billing-method <m>] [--input-tpm <n>] [--output-tpm <n>] [--thinking-output-tpm <n>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `--model-name <model_name>` | string | yes | Model to deploy — fine-tuned output name or catalog model (required) |
| `--display-name <display_name>` | string | yes | Console display name for the deployment (required) |
| `--plan <plan>` | string | no | Billing plan: lora (default, Token-billed) \| ptu (Token-billed) \| mu |
| `--deploy-spec <id>` | string | no | Deploy spec (only used by plan=mu; auto-picked if omitted) |
| `--capacity <n>` | number | no | Resource units (plan=mu only; required by API; defaults to the template's unit) |
| `--billing-method <m>` | string | no | Billing method (plan=mu only; default "POST_PAY", the only supported value) |
| `--input-tpm <n>` | number | no | PTU max input tokens/min (required for plan=ptu) |
| `--output-tpm <n>` | number | no | PTU max output tokens/min (required for plan=ptu) |
| `--thinking-output-tpm <n>` | number | no | PTU max thinking-output tokens/min (optional, some models) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Plan defaults to `lora` (Token-billed) for text/image and `mu` (model-unit-billed) for audio (CosyVoice TTS). Pass --plan to override.
- For plan=ptu (Token-billed, provisioned throughput), --input-tpm and --output-tpm are required (the platform rejects creation without an explicit ptu_capacity despite the doc listing defaults).
- For plan=mu, `capacity`, `billing_method` and `deploy_spec` are required. billing_method defaults to POST_PAY (only supported value); deploy_spec and capacity are auto-picked from GET /deployments/models when omitted.
- Use `bl deploy models --source base` to inspect available templates.
- After creation, status starts at PENDING and transitions to RUNNING. Invoke the deployed model with: bl text chat --model <deployed_model>
- NOTE: --model-name is the model being deployed (e.g. `qwen3-8b-ft-...`). The create response also returns a `deployed_model` field — the deployment instance id (e.g. `qwen3-8b-5ecb5f068d79`). Use that id for inference (`bl text chat --model <deployed_model>`) and lifecycle commands (`deploy get/scale/pause/resume/delete --deployed-model <id>`).
#### Examples
```bash
bl deploy text create --model-name my-qwen-sft --display-name my-sft-test
```
```bash
bl deploy text create --model-name qwen3.6-flash-2026-04-16 --display-name my-flash --plan ptu --input-tpm 10000 --output-tpm 1000
```
```bash
bl deploy text create --model-name qwen3-8b --display-name my-qwen3-mu --plan mu
```
```bash
bl deploy text create --model-name qwen3-8b --display-name my-qwen3 --plan mu --deploy-spec MU1 --capacity 2
```
### `bl deploy update`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------- |
| **Name** | `deploy update` |
| **Description** | Update a deployment's rate limits (rpm_limit / tpm_limit) |
| **Authentication** | API Key |
| **Usage** | `bl deploy update --deployed-model <id> [--rpm-limit <n>] [--tpm-limit <n>]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | ------------------------------------ |
| `--deployed-model <id>` | string | yes | Deployed model identifier (required) |
| `--rpm-limit <n>` | number | no | Requests per minute |
| `--tpm-limit <n>` | number | no | Tokens per minute |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- At least one of --rpm-limit / --tpm-limit must be provided.
#### Examples
```bash
bl deploy update --deployed-model dep-... --rpm-limit 1000
```
```bash
bl deploy update --deployed-model dep-... --rpm-limit 1000 --tpm-limit 200000
```
reference/finetune.md
# `bl finetune` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| -------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `bl finetune audio create` | API Key | Create an audio TTS model fine-tune job (sft-lora) |
| `bl finetune cancel` | API Key | Cancel a running fine-tune job |
| `bl finetune capability` | No Auth | Query fine-tune training capability — by model (which training types it supports) or by training type (which models support it) |
| `bl finetune checkpoints` | API Key | List checkpoints produced by a fine-tune job |
| `bl finetune delete` | API Key | Delete a fine-tune job record |
| `bl finetune export` | API Key | Publish a checkpoint as a deployable model |
| `bl finetune get` | API Key | Get details of a single fine-tune job |
| `bl finetune image create` | API Key | Create an image generation model fine-tune job (sft-lora) |
| `bl finetune list` | API Key | List fine-tune jobs |
| `bl finetune logs` | API Key | Fetch training logs for a fine-tune job |
| `bl finetune price` | Console | Estimate the training cost for a fine-tune job (token billing) |
| `bl finetune text create` | API Key | Create a text model fine-tune job (sft \| sft-lora \| dpo \| dpo-lora \| cpt) |
| `bl finetune video create` | API Key | Create a video generation model fine-tune job (Wan i2v/kf2v, efficient_sft) |
| `bl finetune watch` | API Key | Probe a fine-tune job's status (default: single non-blocking fetch). Pass --follow to poll until terminal. |
## Command details
### `bl finetune audio create`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `finetune audio create` |
| **Description** | Create an audio TTS model fine-tune job (sft-lora) |
| **Authentication** | API Key |
| **Usage** | `bl finetune audio create --base-model <model> --datasets <id\|path> [--validations <id\|path>] [--model-name <name>] [--suffix <text>]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--base-model <model>` | string | yes | Base model to fine-tune (e.g. qwen3-8b; not the output model name) |
| `--datasets <ids\|paths>` | string | yes | Comma-separated dataset file IDs or local paths (.jsonl for text, .zip for audio/image/video). Local paths are uploaded (validated) first, then their file-ids are used. |
| `--validations <ids\|paths>` | string | no | Comma-separated validation dataset file IDs or local paths (auto-uploaded like --datasets). |
| `--model-name <name>` | string | no | Output model name (after training) |
| `--suffix <text>` | string | no | Output suffix appended by the platform (finetuned_output_suffix) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Creating a job uploads any local datasets and consumes training quota.
- Use --dry-run to preview the request body without submitting.
- --datasets / --validations accept either file-ids (from `dataset upload`) or local paths. Local paths are validated and uploaded first, then their file-ids are submitted — a one-step upload-and-train.
- Audio TTS training runs sft-lora (efficient_sft) with fixed CosyVoice hyper-parameter defaults; there are no training-type or hyper-parameter knobs to set.
#### Examples
```bash
bl finetune audio create --base-model cosyvoice-v3-flash --datasets ./audio.zip
```
```bash
bl finetune audio create --base-model cosyvoice-v3-flash --datasets file-xxx
```
```bash
bl finetune audio create --base-model cosyvoice-v3-flash --datasets ./audio.zip --model-name my-tts
```
```bash
bl finetune audio create --base-model cosyvoice-v3-flash --datasets file-xxx --output json
```
```bash
bl finetune audio create --base-model cosyvoice-v3-flash --datasets ./audio.zip --dry-run
```
### `bl finetune cancel`
| Field | Value |
| ------------------ | ---------------------------------- |
| **Name** | `finetune cancel` |
| **Description** | Cancel a running fine-tune job |
| **Authentication** | API Key |
| **Usage** | `bl finetune cancel --job-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | --------------------------- |
| `--job-id <id>` | string | yes | Fine-tune job ID (required) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Only PENDING / RUNNING jobs can be cancelled. Completed / failed / already-cancelled jobs return a server-side error (passed through verbatim).
#### Examples
```bash
bl finetune cancel --job-id ft-xxx
```
```bash
bl finetune cancel --job-id ft-xxx --dry-run
```
### `bl finetune capability`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `finetune capability` |
| **Description** | Query fine-tune training capability — by model (which training types it supports) or by training type (which models support it) |
| **Authentication** | No Auth |
| **Usage** | `bl finetune capability --base-model <m> \| --training-type <t>` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `--base-model <m>` | string | no | List training types supported by this base model. |
| `--training-type <t>` | string | no | List models supporting this training type: sft \| sft-lora \| dpo \| dpo-lora \| cpt. |
#### Notes
- Exactly one of --base-model / --training-type is required.
- Training-type values use the `<method>` / `<method>-lora` convention: sft | sft-lora | dpo | dpo-lora | cpt. (cpt has no -lora variant server-side.)
- Queries listFoundationModels, a public API — no console login needed.
#### Examples
```bash
bl finetune capability --base-model qwen3-8b
```
```bash
bl finetune capability --training-type sft-lora
```
```bash
bl finetune capability --training-type cpt --output json
```
```bash
bl finetune capability --training-type sft --quiet
```
### `bl finetune checkpoints`
| Field | Value |
| ------------------ | -------------------------------------------- |
| **Name** | `finetune checkpoints` |
| **Description** | List checkpoints produced by a fine-tune job |
| **Authentication** | API Key |
| **Usage** | `bl finetune checkpoints --job-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | --------------------------- |
| `--job-id <id>` | string | yes | Fine-tune job ID (required) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- `model_name` (shown for SUCCEEDED checkpoints) is the direct input for `deploy create --model-name`.
- Checkpoints expire ~15 days after creation; `expire_time` shows the deadline. Export or deploy before expiry.
#### Examples
```bash
bl finetune checkpoints --job-id ft-xxx
```
```bash
bl finetune checkpoints --job-id ft-xxx --output json
```
### `bl finetune delete`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------------- |
| **Name** | `finetune delete` |
| **Description** | Delete a fine-tune job record |
| **Authentication** | API Key |
| **Usage** | `bl finetune delete --job-id <id>` |
| **Risk** | `high` |
| **Risk message** | This permanently deletes the specified fine-tune job record and cannot be undone. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------------------- |
| `--job-id <id>` | string | yes | Fine-tune job ID (required) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Cancel a RUNNING job first via `finetune cancel` — the platform refuses to delete jobs that are still in flight.
#### Examples
```bash
bl finetune delete --job-id ft-xxx
```
```bash
bl finetune delete --job-id ft-xxx --dry-run
```
```bash
# Only after explicit user confirmation:
bl finetune delete --job-id ft-xxx --yes
```
### `bl finetune export`
| Field | Value |
| ------------------ | -------------------------------------------------------------------------- |
| **Name** | `finetune export` |
| **Description** | Publish a checkpoint as a deployable model |
| **Authentication** | API Key |
| **Usage** | `bl finetune export --job-id <id> --checkpoint <name> --model-name <name>` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | ------------------------------------------------------------ |
| `--job-id <id>` | string | yes | Fine-tune job ID (required) |
| `--checkpoint <name>` | string | yes | Checkpoint identifier from `finetune checkpoints` (required) |
| `--model-name <name>` | string | yes | Deployable model name (required) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Required before `deploy <modality> create` can target a checkpoint. The platform may auto-export the best checkpoint when a job reaches SUCCEEDED — explicit export is the canonical path for non-best checkpoints.
#### Examples
```bash
bl finetune export --job-id ft-xxx --checkpoint ckpt-3 --model-name my-qwen-sft
```
### `bl finetune get`
| Field | Value |
| ------------------ | ------------------------------------- |
| **Name** | `finetune get` |
| **Description** | Get details of a single fine-tune job |
| **Authentication** | API Key |
| **Usage** | `bl finetune get --job-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | --------------------------- |
| `--job-id <id>` | string | yes | Fine-tune job ID (required) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl finetune get --job-id ft-xxx
```
```bash
bl finetune get --job-id ft-xxx --output json
```
### `bl finetune image create`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `finetune image create` |
| **Description** | Create an image generation model fine-tune job (sft-lora) |
| **Authentication** | API Key |
| **Usage** | `bl finetune image create --base-model <model> --datasets <id\|path> [--validations <id\|path>] [--model-name <name>] [--suffix <text>] [--generation-type <t2i\|i2i>] [--learning-rate <str>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--base-model <model>` | string | yes | Base model to fine-tune (e.g. qwen3-8b; not the output model name) |
| `--datasets <ids\|paths>` | string | yes | Comma-separated dataset file IDs or local paths (.jsonl for text, .zip for audio/image/video). Local paths are uploaded (validated) first, then their file-ids are used. |
| `--validations <ids\|paths>` | string | no | Comma-separated validation dataset file IDs or local paths (auto-uploaded like --datasets). |
| `--model-name <name>` | string | no | Output model name (after training) |
| `--suffix <text>` | string | no | Output suffix appended by the platform (finetuned_output_suffix) |
| `--generation-type <t2i\|i2i>` | string | no | Generation type: t2i (default) \| i2i. Sets generation_type/max_pixels. Required to train I2I from a file-id or with --dry-run (local data auto-detects input_img). |
| `--learning-rate <str>` | string | no | Learning rate as a string to preserve precision (e.g. "3e-5") |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Creating a job uploads any local datasets and consumes training quota.
- Use --dry-run to preview the request body without submitting.
- --datasets / --validations accept either file-ids (from `dataset upload`) or local paths. Local paths are validated and uploaded first, then their file-ids are submitted — a one-step upload-and-train.
- Image generation training runs sft-lora (efficient_sft) with fixed defaults; only --learning-rate is overridable. T2I vs I2I is declared with --generation-type (default t2i), which sets generation_type/max_pixels. For local data the type is auto-detected (records with input_img train I2I); pass --generation-type explicitly to train I2I from a file-id or in --dry-run.
#### Examples
```bash
bl finetune image create --base-model wan2.7-image-pro --datasets ./images.zip
```
```bash
bl finetune image create --base-model wan2.7-image-pro --datasets file-xxx
```
```bash
bl finetune image create --base-model wan2.7-image-pro --datasets file-xxx --generation-type i2i
```
```bash
bl finetune image create --base-model wan2.7-image-pro --datasets ./images.zip --model-name my-wan
```
```bash
bl finetune image create --base-model wan2.7-image-pro --datasets file-xxx --output json
```
```bash
bl finetune image create --base-model wan2.7-image-pro --datasets ./images.zip --dry-run
```
### `bl finetune list`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------------------- |
| **Name** | `finetune list` |
| **Description** | List fine-tune jobs |
| **Authentication** | API Key |
| **Usage** | `bl finetune list [--page <n>] [--page-size <n>] [--status <s>] [--base-model <model>]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | -------------------------------------------------------------------- |
| `--page <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Results per page (default: 10, max 100) |
| `--status <s>` | string | no | Filter by status (PENDING / RUNNING / SUCCEEDED / FAILED / CANCELED) |
| `--base-model <model>` | string | no | Filter by base model ID (server-side) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl finetune list
```
```bash
bl finetune list --status RUNNING
```
```bash
bl finetune list --base-model qwen3-8b
```
```bash
bl finetune list --page-size 20
```
### `bl finetune logs`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| **Name** | `finetune logs` |
| **Description** | Fetch training logs for a fine-tune job |
| **Authentication** | API Key |
| **Usage** | `bl finetune logs --job-id <id> [--page <n>] [--page-size <n>] [--search <keyword>] [--tail <n>]` |
#### Flags
| Flag | Type | Required | Description |
| -------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `--job-id <id>` | string | yes | Fine-tune job ID (required) |
| `--page <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Lines per page (default: server-defined) |
| `--search <keyword>` | string | no | Case-insensitive substring filter. When set, all log pages are fetched and filtered client-side (--page is ignored). |
| `--tail <n>` | number | no | Keep only the last N entries. When set, all log pages are fetched and the trailing N are kept (--page is ignored). |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl finetune logs --job-id ft-xxx
```
```bash
bl finetune logs --job-id ft-xxx --page-size 100 --output json
```
```bash
bl finetune logs --job-id ft-xxx --search checkpoint
```
```bash
bl finetune logs --job-id ft-xxx --search error --output json
```
```bash
bl finetune logs --job-id ft-xxx --tail 20
```
```bash
bl finetune logs --job-id ft-xxx --search checkpoint --tail 5
```
### `bl finetune price`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| **Name** | `finetune price` |
| **Description** | Estimate the training cost for a fine-tune job (token billing) |
| **Authentication** | Console |
| **Usage** | `bl finetune price --base-model <model> --datasets <ids> [--training-type <type>] [--n-epochs <n>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ------------------------------------------------------------------ |
| `--base-model <model>` | string | yes | Base model to fine-tune (e.g. qwen3-8b; not the output model name) |
| `--datasets <ids>` | string | yes | Training dataset file IDs, comma-separated (required) |
| `--training-type <type>` | string | no | Training type: sft \| dpo \| cpt (default: sft) |
| `--n-epochs <n>` | number | no | Number of training epochs (default: 3) |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Notes
- Estimate only — the server computes token usage from the datasets; final cost is subject to the bill.
- Covers token billing for sft / dpo / cpt. Training-unit (MTU) billing is not supported by this command.
- Hyper-parameters other than --n-epochs are fixed at representative defaults for estimation.
#### Examples
```bash
bl finetune price --base-model qwen3-8b --datasets file-ft-xxx
```
```bash
bl finetune price --base-model qwen3-8b --datasets file-ft-xxx,file-ft-yyy --n-epochs 2
```
```bash
bl finetune price --base-model qwen3-8b --datasets file-ft-xxx --training-type cpt
```
### `bl finetune text create`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name** | `finetune text create` |
| **Description** | Create a text model fine-tune job (sft \| sft-lora \| dpo \| dpo-lora \| cpt) |
| **Authentication** | API Key |
| **Usage** | `bl finetune text create --base-model <model> --datasets <id\|path,...> [--validations <id\|path,...>] [--model-name <name>] [--suffix <text>] [--n-epochs <n>] [--batch-size <n>] [--learning-rate <str>] [--max-length <n>] [--training-type <sft\|sft-lora\|dpo\|dpo-lora\|cpt>]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--base-model <model>` | string | yes | Base model to fine-tune (e.g. qwen3-8b; not the output model name) |
| `--datasets <ids\|paths>` | string | yes | Comma-separated dataset file IDs or local paths (.jsonl for text, .zip for audio/image/video). Local paths are uploaded (validated) first, then their file-ids are used. |
| `--validations <ids\|paths>` | string | no | Comma-separated validation dataset file IDs or local paths (auto-uploaded like --datasets). |
| `--model-name <name>` | string | no | Output model name (after training) |
| `--suffix <text>` | string | no | Output suffix appended by the platform (finetuned_output_suffix) |
| `--training-type <t>` | string | no | Training type: sft \| sft-lora \| dpo \| dpo-lora \| cpt (default: sft-lora). Mapping to the server happens at the interface boundary (e.g. sft-lora -> efficient_sft, dpo -> dpo_full). |
| `--n-epochs <n>` | number | no | Number of epochs (default: 3) |
| `--batch-size <n>` | number | no | Per-device batch size (clamped to [8, 1024]). Auto-set to 8 for small datasets (<100KB) |
| `--learning-rate <str>` | string | no | Learning rate as a string to preserve precision (e.g. "1.6e-5") |
| `--max-length <n>` | number | no | Max sequence length |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Creating a job uploads any local datasets and consumes training quota.
- Use --dry-run to preview the request body without submitting.
- --datasets / --validations accept either file-ids (from `dataset upload`) or local paths. Local paths are validated and uploaded first, then their file-ids are submitted — a one-step upload-and-train.
- Training-type values use the `<method>` / `<method>-lora` convention: sft (full) | sft-lora (LoRA) | dpo (full) | dpo-lora (LoRA) | cpt. These map to the server's training_type at the interface boundary, so the rest of the CLI never sees the raw server strings.
- Before submitting (non dry-run) the job, the model's training capability is checked via listFoundationModels (no console login required); an unsupported training type fails fast with the list the model actually supports.
- n_epochs defaults to 3. Other hyper-parameters are platform defaults unless set.
- Learning rate is forwarded as a string to avoid JSON-number precision loss.
- Pre-submit gate: if the training dataset's sample count is not greater than batch_size, the job is rejected before upload or quota consumption (the platform would otherwise fail ~10 min in, after data processing).
#### Examples
```bash
bl finetune text create --base-model qwen3-8b --datasets file-xxx
```
```bash
bl finetune text create --base-model qwen3-8b --datasets ./train.jsonl
```
```bash
bl finetune text create --base-model qwen3-8b --datasets ./train.jsonl --validations ./eval.jsonl
```
```bash
bl finetune text create --base-model qwen3-8b --datasets file-aaa,./extra.jsonl
```
```bash
bl finetune text create --base-model qwen3-8b --datasets ./train.jsonl --training-type sft
```
```bash
bl finetune text create --base-model qwen3-8b --datasets file-xxx --learning-rate "1.6e-5" --n-epochs 4
```
```bash
bl finetune text create --base-model qwen3-8b --datasets file-xxx --output json
```
```bash
bl finetune text create --base-model qwen3-8b --datasets file-xxx --dry-run
```
### `bl finetune video create`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `finetune video create` |
| **Description** | Create a video generation model fine-tune job (Wan i2v/kf2v, efficient_sft) |
| **Authentication** | API Key |
| **Usage** | `bl finetune video create --base-model <model> --datasets <id\|path> [--validations <id\|path>] [--model-name <name>] [--suffix <text>] [--n-epochs <n>] [--batch-size <n>] [--learning-rate <str>]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--base-model <model>` | string | yes | Base model to fine-tune (e.g. qwen3-8b; not the output model name) |
| `--datasets <ids\|paths>` | string | yes | Comma-separated dataset file IDs or local paths (.jsonl for text, .zip for audio/image/video). Local paths are uploaded (validated) first, then their file-ids are used. |
| `--validations <ids\|paths>` | string | no | Comma-separated validation dataset file IDs or local paths (auto-uploaded like --datasets). |
| `--model-name <name>` | string | no | Output model name (after training) |
| `--suffix <text>` | string | no | Output suffix appended by the platform (finetuned_output_suffix) |
| `--n-epochs <n>` | number | no | Training epochs (default: 50) |
| `--batch-size <n>` | number | no | Batch size (default: model-specific, 1 for wan2.7, 4 for wan2.5/2.2) |
| `--learning-rate <str>` | string | no | Learning rate as a string to preserve precision (default: "2e-5") |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Creating a job uploads any local datasets and consumes training quota.
- Use --dry-run to preview the request body without submitting.
- --datasets / --validations accept either file-ids (from `dataset upload`) or local paths. Local paths are validated and uploaded first, then their file-ids are submitted — a one-step upload-and-train.
- Video generation training (Wan i2v/kf2v) runs efficient_sft with model-specific defaults: wan2.7 (batch_size=1, max_pixels=102400), wan2.5/2.2 (batch_size=4, max_pixels per model). Override with --batch-size/--n-epochs.
- Datasets are .zip archives with data.jsonl + frame images + videos.
- Recommended: ≥10 training samples, 20-100 for stable results.
#### Examples
```bash
bl finetune video create --base-model wan2.7-i2v --datasets file-xxx
```
```bash
bl finetune video create --base-model wan2.7-i2v --datasets ./i2v-data.zip
```
```bash
bl finetune video create --base-model wan2.2-kf2v-flash --datasets file-xxx --n-epochs 100
```
```bash
bl finetune video create --base-model wan2.7-i2v --datasets file-xxx --dry-run
```
### `bl finetune watch`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Name** | `finetune watch` |
| **Description** | Probe a fine-tune job's status (default: single non-blocking fetch). Pass --follow to poll until terminal. |
| **Authentication** | API Key |
| **Usage** | `bl finetune watch --job-id <id> [--follow] [--interval <sec>] [--poll-timeout <sec>]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--job-id <id>` | string | yes | Fine-tune job ID (required) |
| `--follow` | switch | no | Block and poll until a terminal state (the legacy behavior). Without it, a single status probe is performed and the command returns immediately. |
| `--interval <sec>` | number | no | Seconds between polls with --follow (default: 10, min: 1). Ignored without --follow. |
| `--poll-timeout <sec>` | number | no | With --follow, stop polling after this many seconds (default: no limit). Ignored without --follow. |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Default (no --follow) is a NON-BLOCKING single status probe: one fetch, then return immediately. This is the mode meant for agents / scripts — the caller owns the polling cadence, so the CLI never holds the terminal.
- A terminal FAILED/CANCELED status raises a normal CLI error (non-zero exit); a SUCCEEDED or still-running status returns 0. With --follow, exceeding --poll-timeout raises a timeout error.
- Use --follow for the blocking, human-terminal-follow experience; use the default mode when driving the loop yourself (e.g. from an agent).
- For per-step training output (not status), use `finetune logs`.
#### Examples
```bash
bl finetune watch --job-id ft-xxx # single probe, returns immediately
```
```bash
bl finetune watch --job-id ft-xxx --output json # status probe for agents
```
```bash
bl finetune watch --job-id ft-xxx --follow # block until terminal
```
```bash
bl finetune watch --job-id ft-xxx --follow --interval 5
```
```bash
bl finetune watch --job-id ft-xxx --follow --poll-timeout 3600
```
reference/index.md
# `bailian-finetune` command reference
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Command **details** are in sibling `<group>.md` files in this directory.
This index only covers groups owned by this skill. Other `bl` groups live in sibling bailian-\* skills.
Use this index for the skill-scoped quick index and global flags.
## Quick index
| Command | Authentication | Description | Detail |
| -------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `bl dataset delete` | API Key | Delete a dataset file by ID | [dataset.md](dataset.md) |
| `bl dataset get` | API Key | Get details of a single dataset file | [dataset.md](dataset.md) |
| `bl dataset list` | API Key | List uploaded dataset files | [dataset.md](dataset.md) |
| `bl dataset upload` | API Key | Upload a dataset file (.jsonl or .zip) to Bailian | [dataset.md](dataset.md) |
| `bl dataset validate` | No Auth | Locally validate a dataset file (.jsonl or .zip) without uploading | [dataset.md](dataset.md) |
| `bl deploy audio create` | API Key | Create an audio (TTS) model deployment | [deploy.md](deploy.md) |
| `bl deploy delete` | API Key | Delete a model deployment (must be STOPPED or FAILED) | [deploy.md](deploy.md) |
| `bl deploy get` | API Key | Get details of a single model deployment | [deploy.md](deploy.md) |
| `bl deploy image create` | API Key | Create an image generation model deployment | [deploy.md](deploy.md) |
| `bl deploy list` | API Key | List model deployments | [deploy.md](deploy.md) |
| `bl deploy models` | API Key | List models available for deployment | [deploy.md](deploy.md) |
| `bl deploy pause` | Console | Pause a running model deployment (stops billing for mu/ptu) | [deploy.md](deploy.md) |
| `bl deploy resume` | Console | Resume a paused model deployment (brings service back online) | [deploy.md](deploy.md) |
| `bl deploy scale` | API Key | Scale a deployment's capacity | [deploy.md](deploy.md) |
| `bl deploy text create` | API Key | Create a text model deployment | [deploy.md](deploy.md) |
| `bl deploy update` | API Key | Update a deployment's rate limits (rpm_limit / tpm_limit) | [deploy.md](deploy.md) |
| `bl finetune audio create` | API Key | Create an audio TTS model fine-tune job (sft-lora) | [finetune.md](finetune.md) |
| `bl finetune cancel` | API Key | Cancel a running fine-tune job | [finetune.md](finetune.md) |
| `bl finetune capability` | No Auth | Query fine-tune training capability — by model (which training types it supports) or by training type (which models support it) | [finetune.md](finetune.md) |
| `bl finetune checkpoints` | API Key | List checkpoints produced by a fine-tune job | [finetune.md](finetune.md) |
| `bl finetune delete` | API Key | Delete a fine-tune job record | [finetune.md](finetune.md) |
| `bl finetune export` | API Key | Publish a checkpoint as a deployable model | [finetune.md](finetune.md) |
| `bl finetune get` | API Key | Get details of a single fine-tune job | [finetune.md](finetune.md) |
| `bl finetune image create` | API Key | Create an image generation model fine-tune job (sft-lora) | [finetune.md](finetune.md) |
| `bl finetune list` | API Key | List fine-tune jobs | [finetune.md](finetune.md) |
| `bl finetune logs` | API Key | Fetch training logs for a fine-tune job | [finetune.md](finetune.md) |
| `bl finetune price` | Console | Estimate the training cost for a fine-tune job (token billing) | [finetune.md](finetune.md) |
| `bl finetune text create` | API Key | Create a text model fine-tune job (sft \| sft-lora \| dpo \| dpo-lora \| cpt) | [finetune.md](finetune.md) |
| `bl finetune video create` | API Key | Create a video generation model fine-tune job (Wan i2v/kf2v, efficient_sft) | [finetune.md](finetune.md) |
| `bl finetune watch` | API Key | Probe a fine-tune job's status (default: single non-blocking fetch). Pass --follow to poll until terminal. | [finetune.md](finetune.md) |
## By group
| Group | Commands | Reference |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `dataset` | `delete`, `get`, `list`, `upload`, `validate` | [dataset.md](dataset.md) |
| `deploy` | `audio create`, `delete`, `get`, `image create`, `list`, `models`, `pause`, `resume`, `scale`, `text create`, `update` | [deploy.md](deploy.md) |
| `finetune` | `audio create`, `cancel`, `capability`, `checkpoints`, `delete`, `export`, `get`, `image create`, `list`, `logs`, `price`, `text create`, `video create`, `watch` | [finetune.md](finetune.md) |
## Global flags
Available on every command (in addition to command-specific flags):
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | ------------------------------------- |
| `--output <format>` | string | no | Output format: text, json |
| `--timeout <seconds>` | number | no | Request timeout |
| `--quiet` | switch | no | Suppress non-essential output |
| `--verbose` | switch | no | Print HTTP request/response details |
| `--dry-run` | switch | no | Dry run mode |
| `--config <name>` | string | no | Use a config profile for this command |
| `--help` | switch | no | Show help |
| `--version` | switch | no | Print version |
## Model auth flags
Available on model-domain commands (API-key auth); also listed per command below:
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | ------------ |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
## Console auth flags
Available on console-domain commands (console login auth); also listed per command below:
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
## OpenAPI auth flags
Available on OpenAPI-domain commands (AK/SK auth); also listed per command below:
| Flag | Type | Required | Description |
| --------------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `--access-key-id <key>` | string | no | Alibaba Cloud Access Key ID (env: ALIBABA_CLOUD_ACCESS_KEY_ID) |
| `--access-key-secret <key>` | string | no | Alibaba Cloud Access Key Secret (env: ALIBABA_CLOUD_ACCESS_KEY_SECRET) |
| `--security-token <token>` | string | no | Alibaba Cloud STS Security Token (env: ALIBABA_CLOUD_SECURITY_TOKEN) |
## Notes
- Console commands (`app list`, `usage free`, `console call`) require `bl auth login --console`.
- Most API commands use `DASHSCOPE_API_KEY` or `bl auth login --api-key`.
- Token Plan commands use OpenAPI AK/SK via `bl auth login --open-api` or `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`.
- Default output: **text** unless explicitly set to `json` with `--output`, `DASHSCOPE_OUTPUT`, or config.
SKILL.md
---
name: bailian-finetune
metadata:
version: "1.21.0"
requires:
bins: ["bl"]
description: >-
阿里云百炼模型精调训练入口：用户要精调、微调、训练自己的模型（fine-tune，支持 SFT / SFT-LoRA / DPO / DPO-LoRA / CPT，
覆盖文本、语音、图像）、校验或上传训练数据集、看训练进度和日志、挑 checkpoint、导出精调产物、
把专属模型部署成服务时使用 `bl dataset` / `bl finetune` / `bl deploy`。链路是 validate 校验数据 →
upload 拿 file-id → finetune create 建任务 → watch 看进度 → export 导出 → deploy 上线，需要 API key；
写操作先用 `--dry-run` 预览。反触发：用户点名火山方舟/ark 的精调不走本 skill；只是要选哪个模型走
bailian-model-recommend；用现成模型生图生视频走 bailian-gen；百炼其他资源管理走 bailian-cli。
官方安装：`bl skill init`（与共享协议 bailian-protocol 同装）。
---
# Bailian fine-tuning pipeline (`bl dataset` / `bl finetune` / `bl deploy`)
**CRITICAL — Before executing, MUST read the shared protocol in [`../bailian-protocol/SKILL.md`](../bailian-protocol/SKILL.md): Version & updates (pre-flight checklist), Setup & auth, and CLI errors: report an issue. Command details are authoritative in [`reference/`](reference/index.md) (dataset / finetune / deploy) and `bl <command> --help` — do not guess flags. The whole pipeline requires an API key. If that protocol file is missing, stop and run `bl skill init`; do not guess auth/consent.**
## End-to-end workflow (follow in order)
```
1. Validate data bl dataset validate --file train.jsonl [--schema chatml|dpo|cpt|tts|image]
2. Upload data bl dataset upload --file train.jsonl # returns a file-id
3. Create job bl finetune text|audio|image create --base-model <base> --datasets <file-id|path>
4. Watch progress bl finetune watch --job-id ft-xxx # or get / logs
5. Pick artifact bl finetune checkpoints --job-id ft-xxx
6. Export model bl finetune export --job-id ft-xxx --checkpoint ckpt-N --model-name my-model
7. Deploy service bl deploy text|audio|image create --model-name my-model --display-name my-svc
```
- Unsure which training methods a base model supports → `bl finetune capability --base-model <base>` or `--training-type sft|sft-lora|dpo|cpt`.
- Text `--training-type` values: `sft` / `sft-lora` / `dpo` / `dpo-lora` / `cpt`. Audio bases include `cosyvoice-v3-flash`; image bases include `wan2.7-image-pro`.
- Deployment plans: audio defaults to `--plan mu`; text/image default to `lora`.
- For `risk: high` or `requires_confirmation`, follow `bailian-protocol`; never add `--yes` automatically.
## When to use which command
| Intent | Command |
| ------------------------------- | ------------------------------------------------------------------------------------------------ |
| Validate / upload training data | `bl dataset validate` / `upload` (`.jsonl` or `.zip`) |
| Dataset list / detail / delete | `bl dataset list` / `get` / `delete` |
| Create a fine-tuning job | `bl finetune text\|audio\|image create` |
| Job list / detail / follow | `bl finetune list` / `get` / `watch` / `logs` |
| Artifacts and export | `bl finetune checkpoints` / `export` |
| Cancel / delete a job | `bl finetune cancel` / `delete` |
| Trainable capability lookup | `bl finetune capability` |
| Deploy / lifecycle | `bl deploy text\|audio\|image create`, `list` / `get` / `update` / `scale` / `delete` / `models` |
Flags, usage, and examples: see [`reference/`](reference/index.md) or `bl <command> --help` — do not guess flags.
## Quick examples
```bash
bl dataset validate --file train.jsonl
bl dataset upload --file train.jsonl
bl finetune text create --base-model qwen3-8b --training-type sft-lora --datasets file-xxx
bl finetune watch --job-id ft-xxx
bl finetune export --job-id ft-xxx --checkpoint ckpt-3 --model-name my-qwen-sft
bl deploy text create --model-name my-qwen-sft --display-name my-svc
```
## Common hand-offs
软 hand-off（按 skill **名**；已安装则 Read，否则 `--help` / 提示 `bl skill init`）：
- After deployment, try the model or generate content → skill `bailian-gen` (media) or `bl text chat` (fallback: `bl image\|video\|text --help`).
- Unsure which base model to pick → `bailian-model-recommend` / `bl advisor recommend`.
- Training quota / usage questions → skill `bailian-cli` (fallback: `bl quota` / `bl usage --help`).
## references
- [bailian-protocol](../bailian-protocol/SKILL.md) — shared protocol (install via `bl skill init`)
- [reference/](reference/index.md) — command details