# 推理与训练

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

推理部署与模型训练：接入点（Endpoint）生命周期、精调训练任务，以及训练数据管理。

- 普通交互式创建接入点走 `+deploy`（含模型澄清与复用检查）；脚本化 / CI / 无护栏场景走 `infer` 的 raw CRUD；
- `train` 管精调任务（`mcj-*`），训练数据来自 `dataset`（`ds-*` / `dsv-*`），导出产物是 `cm-*` 自定义模型；
- 导出后衔接 `models custommodel` 与 `infer`：先入模型仓库，再按接入点工作流上线。

<span id="deploy-command"></span>
## +deploy

引导式创建推理接入点：模型澄清、复用检查、Profile 默认资源同步（`infer endpoint create` 的带护栏版本）

```Bash
arkcli +deploy
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string（必填） | Endpoint 名称 |
| `--description` | string | 接入点描述 |
| `--model` | string（必填） | 模型 ID（基础模型或自定义模型） |
| `--model-unit-id` | string | 模型单元 ID |
| `--rate-limit` | string | 限流配置（JSON 字符串） |
| `--batch-only` | bool | 仅批量模式 |
| `--moderation` | string | 内容审核配置（JSON 字符串） |
| `--data-delivery` | bool | 数据投递模式 |
| `--dedicated-to-ptu` | bool | 专用于 PTU |
| `--dedicated-to-dynamic-ptu` | bool | 专用于动态 PTU |
| `--content-generation` | string | 内容生成配置（JSON 字符串） |
| `--inference-foundry` | string | 推理底座（Inference foundry）配置（JSON 字符串） |
| `--tags` | string | Tags（JSON 字符串） |
| `--yes` | bool | In an interactive terminal, skip the [y/N] model-activation (开通) prompt. NOTE: in non-interactive (agent/CI/pipe) this flag does NOT authorize 开通 — activation is hard-refused there; set ARKCLI_ALLOW_HEADLESS_ACTIVATION=1 only for genuine unattended automation. |
| `--allow-data-collected` | bool | 允许采集数据 |
| `--service-info` | string | 服务信息（JSON 字符串） |
| `--need-watermark` | bool | 是否需要水印 |
| `--watermark-info` | string | 水印信息（JSON 字符串） |
| `--intelligent-router` | string | 智能路由配置（JSON 字符串） |
| `--is-intelligent` | bool | 是否为智能版 |
| `--fallback` | string | 降级配置（JSON 字符串） |
| `--limit-coefficient` | string | 限流系数配置（JSON 字符串） |
| `--deployment-type` | string | 部署类型 |
| `--is-agentic` | bool | 是否为 agentic |
| `--agentic-strategy` | string | Agentic 策略配置（JSON 字符串） |
| `--is-aicc` | bool | 是否为 AICC |
| `--specify-region` | string | 指定地域 |
| `--set-default` | string | 把创建成功的 Endpoint 提升为当前 profile 在该模态下的默认（text\|image\|video）。 |
| `--domain` | string | 域 |

<span id="domain-dataset"></span>
## dataset

Dataset（数据集）全生命周期管理：创建、查询、更新、删除、版本化（`ds-*` / `dsv-*`）、下载与格式校验。

- 面向精调场景设计：训练集/验证集的复用、版本冻结、格式校验都在本域完成；
- 精调任务通过 `--dataset` 引用本域产物，衔接 `train` 域的精调工作流。

<span id="dataset-create-command"></span>
### dataset create

创建数据集并提交首个 V1 版本

```Bash
arkcli dataset create
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string（必填） | 数据集名称 |
| `--description` | string | 描述 |
| `--dataset-format` | string（必填） | 后端 SchemaType：LLMSft、LLMPretrain、LLMDPO、LLMRL、EmbeddingSft、ImageGenSft 或 VideoGenSft |
| `--local` | string_slice | 本地 .jsonl 文件路径，可重复 |
| `--tos-uri` | string_slice | 可列举且包含 .jsonl 的 TOS URI（tos://bucket/path），可重复且必须属于同一 bucket；不支持 ds-ds/* 上传暂存路径 |

<span id="dataset-delete-command"></span>
### dataset delete

删除数据集

```Bash
arkcli dataset delete <dataset-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互式确认 |

<span id="dataset-download-command"></span>
### dataset download

下载数据集版本中的 TOS 对象

```Bash
arkcli dataset download <dataset-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--version` | string（必填） | 版本 SID（dsv-...）或友好版本号（V1、V2 等） |
| `--output-dir` | string | 下载目录；默认 ./<dataset-id>-<version>/ |

<span id="dataset-get-command"></span>
### dataset get

获取数据集详情

```Bash
arkcli dataset get <dataset-id>
```

<span id="dataset-list-command"></span>
### dataset list

列出数据集

```Bash
arkcli dataset list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--page-number` | int | 页码（默认 1） |
| `--page-size` | int | 每页条数（1-100，默认 100） |
| `--sort-by` | string | 排序字段 |
| `--sort-order` | string | 排序方向：Asc 或 Desc |
| `--id` | string_slice | 按数据集 ID 过滤，可重复 |
| `--name` | string | 按数据集名称过滤 |
| `--schema-type` | string_slice | 按 SchemaType 过滤，可重复 |
| `--resource-origin` | string_slice | 按 ResourceOrigin 过滤，可重复 |

<span id="dataset-update-command"></span>
### dataset update

更新数据集名称或描述

```Bash
arkcli dataset update <dataset-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string | 数据集名称 |
| `--description` | string | 描述 |

<span id="dataset-validate-command"></span>
### dataset validate

按照模型微调配置校验本地文件或 TOS 数据

```Bash
arkcli dataset validate
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--local` | string_slice | 本地 .jsonl 文件路径，可重复 |
| `--tos-uri` | string_slice | 可列举且包含 .jsonl 的 TOS URI（tos://bucket/path），可重复且必须属于同一 bucket；不支持 ds-ds/* 上传暂存路径 |
| `--model` | string（必填） | 基础模型名称 |
| `--model-version` | string（必填） | 基础模型版本 |
| `--type` | string（必填） | 微调类型，例如 sft、lora、dpo、grpo、pt |

<span id="dataset-version-create-command"></span>
### dataset version create

为现有数据集创建下一个 Vn 版本

```Bash
arkcli dataset version create <dataset-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--description` | string | 描述 |
| `--local` | string_slice | 本地 .jsonl 文件路径，可重复 |
| `--tos-uri` | string_slice | 可列举且包含 .jsonl 的 TOS URI（tos://bucket/path），可重复且必须属于同一 bucket；不支持 ds-ds/* 上传暂存路径 |

<span id="dataset-version-download-command"></span>
### dataset version download

下载指定数据集版本中的 TOS 对象

```Bash
arkcli dataset version download <dataset-id> <version-id-or-vn>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--output-dir` | string | 下载目录；默认 ./<dataset-id>-<version>/ |

<span id="dataset-version-get-command"></span>
### dataset version get

获取数据集版本详情

```Bash
arkcli dataset version get <version-sid> | <dataset-id> <version-id-or-vn>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--preview` | bool | 读取并展示版本中每个对象的前 100 KiB（102400 字节） |

<span id="dataset-version-list-command"></span>
### dataset version list

列出数据集版本

```Bash
arkcli dataset version list <dataset-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--page-number` | int | 页码（默认 1） |
| `--page-size` | int | 每页条数（1-100，默认 100） |
| `--sort-by` | string | 排序字段 |
| `--sort-order` | string | 排序方向：Asc 或 Desc |
| `--id` | string_slice | 按版本 SID 过滤，可重复 |
| `--version` | string_slice | 按友好版本号 Vn 过滤，可重复 |
| `--status` | string_slice | 按版本状态过滤，可重复 |

<span id="domain-infer"></span>
## infer

推理接入点（Endpoint，ep-*）全生命周期管理：获取、列表、创建、启动、停止、删除、更新，以及模型部署形态能力查询（capability）。

- `infer endpoint create` 是**显式 raw CRUD 通道**：面向脚本化 / CI / 无护栏场景；普通交互式创建请优先使用 `+deploy` 工作流（含模型复用检查与 profile 同步）；
- 创建前可用 `capability` 确认模型支持的部署形态；启停与删除均有确认闸门。

<span id="infer-endpoint-capability-get-command"></span>
### infer endpoint capability get

查看某个模型支持的推理部署形态（在线接入点 / 共享服务 / 批量 / PTU / 规格档位 / 降级）。为 maas-fe 的 `EndpointSupportedMethods` 接口提供支撑。请在 `infer endpoint create` 之前调用，以确认模型是否可部署、以及哪些 `--type` 类参数对它有效。精调自定义模型传 --custom-model-id；基础模型传 --model + --version。

```Bash
arkcli infer endpoint capability get
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 基础模型名称（如 doubao-seed-1-6-flash）；与 --custom-model-id 互斥 |
| `--version` | string | 模型版本（配合 --model 使用） |
| `--custom-model-id` | string | 自定义模型 ID（cm-xxx）；与 --model 互斥 |

<span id="infer-endpoint-create-command"></span>
### infer endpoint create

创建推理接入点（原始 CRUD，无流程护栏；需要带模型复用检查与 Profile 同步的引导式部署请用 +deploy）

```Bash
arkcli infer endpoint create
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string（必填） | 模型 ID（基础模型或自定义模型） |
| `--name` | string（必填） | Endpoint 名称 |
| `--billing-method` | string | 计费方式：token |
| `--rpm` | int | 限流 RPM |
| `--tpm` | int | 限流 TPM |
| `--yes` | bool | In an interactive terminal, skip the [y/N] model-activation (开通) prompt. NOTE: in non-interactive (agent/CI/pipe) this flag does NOT authorize 开通 — activation is hard-refused there; set ARKCLI_ALLOW_HEADLESS_ACTIVATION=1 only for genuine unattended automation. |

<span id="infer-endpoint-delete-command"></span>
### infer endpoint delete

删除推理接入点（不可逆）。需要确认：交互式 TTY 会提示 Y/N；非交互场景（Agent / CI / 管道）需要设置 ARKCLI_ALLOW_HEADLESS_DELETE=1，此时 --yes 不生效。

```Bash
arkcli infer endpoint delete <endpoint-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互式 Y/N 提示（仅 TTY）。注意：非交互模式下本参数不构成删除授权——请改用 ARKCLI_ALLOW_HEADLESS_DELETE=1。 |

<span id="infer-endpoint-get-command"></span>
### infer endpoint get

获取推理接入点详情（同时支持普通接入点与预置推理接入点）

```Bash
arkcli infer endpoint get <endpoint-id>
```

<span id="infer-endpoint-list-command"></span>
### infer endpoint list

按条件分页列出推理接入点

```Bash
arkcli infer endpoint list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--format` | string | 输出格式：table \| json |
| `--model` | string | 按模型 ID 过滤（自定义模型） |
| `--status` | string | 按 Endpoint 状态过滤 |
| `--mine` | bool | 只列出当前 SSO 子用户创建的 Endpoint |
| `--page-number` | int | 页码（>=1） |
| `--page-size` | int | 每页条数 |

<span id="infer-endpoint-start-command"></span>
### infer endpoint start

启动推理接入点。启动请求被接受后返回的是接入点当前状态（通常是 Scheduling）——到 Running 的转换是异步的；请轮询 `infer endpoint get <id>` 直到 Status='Running' 确认。

```Bash
arkcli infer endpoint start <endpoint-id>
```

<span id="infer-endpoint-stop-command"></span>
### infer endpoint stop

停止推理接入点。停止请求被接受后返回的是接入点当前状态——到 Stopped 的转换是异步的；请轮询 `infer endpoint get <id>` 直到 Status='Stopped' 确认。

```Bash
arkcli infer endpoint stop <endpoint-id>
```

<span id="infer-endpoint-update-command"></span>
### infer endpoint update

更新推理接入点（名称 / 描述 / 限流）

```Bash
arkcli infer endpoint update <endpoint-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string | 新的 Endpoint 名称 |
| `--description` | string | 新的接入点描述（传空字符串可清空） |
| `--rpm` | int | 限流：每分钟请求数（必须与 --tpm 配对） |
| `--tpm` | int | 限流：每分钟 token 数（必须与 --rpm 配对） |
| `--cg-concurrent-requests` | int | ContentGeneration：最大并发请求数（图片生成接入点） |
| `--cg-create-task-rpm` | int | ContentGeneration：CreateTask 的 RPM（图片生成接入点） |

<span id="domain-train"></span>
## train

模型精调（Fine-tune）训练任务全生命周期：创建、查询、日志/trajectory、指标分析、最佳 step 选择、导出为 custom model（mcj-*）。

- 训练数据来自 `dataset` 域的 Dataset/版本；本域负责超参、资源组匹配、价格查询与训练方法选择；
- 导出部署衔接 `models custommodel` 与 `infer`：导出产物是 cm-* 自定义模型，再按推理接入点工作流上线。

<span id="train-finetune-artifacts-export-command"></span>
### train finetune artifacts export

把一个或多个 mcj 产物（例如 global_step_2）导出为可部署的 cm-* 实体。输出 `{job_id, items[]}`，每项含 custom_model_name / custom_model_id / export_status。命名规则：设置 --custom-model-name-prefix 时为 `<prefix>_<artifact-name>`，否则保留后端默认名。建议先用 `arkcli train finetune artifacts list <mcj-id>` 查出 artifact_name。

```Bash
arkcli train finetune artifacts export <mcj-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--artifact-name` | string_slice | 要导出的产物（output）名，例如 global_step_2。可重复。 |
| `--custom-model-name-prefix` | string | 导出后 cm-* 名称的前缀。最终名称为 `<prefix>_<artifact-name>`。留空表示沿用后端默认名。 |

<span id="train-finetune-artifacts-list-command"></span>
### train finetune artifacts list

列出精调任务的训练产物（Outputs[] 投影：artifact_name / export_status / custom_model_name / custom_model_id / create_time）。用 `--format table` 便于人工挑选。默认会并发调用 GetCustomModel 回填 custom_model_name；传 --lite 可跳过该查询。

```Bash
arkcli train finetune artifacts list <mcj-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--format` | string | 输出格式：json（默认）\| table |
| `--lite` | bool | 跳过逐个 cm 的 GetCustomModel 名称查询。更快，但 custom_model_name 会为空。 |

<span id="train-finetune-capability-get-command"></span>
### train finetune capability get

查看某个基础模型（或自定义模型的来源模型）支持哪些精调训练方法。基础模型传 --model + 可选 --version；自定义模型传 --model-id（cm-xxx）——后者会在底层解析到其来源 FoundationModel，与 maas-fe 的 CustomBoard 一致（自定义模型本身不携带能力列表，续训支持由底座的 FinetuneTypes 推导）。返回 supported_types（arkcli 参数写法：sft / lora / dpo / dpo-lora / grpo / grpo-lora / ppo / opd / opd-lora / pt，与 `train finetune create --type` 一致）与 supported_types_wire（后端 CustomizationType 字面量）。--version 语义：与 --model 同用时，--version 为空只返回主版本；--version 与 --model-id 互斥（cm 绑定的来源版本会自动解析——二者传其一，不要同时传）。配合 `models finetune-config` 可获取所选 --type 的超参数 schema。

```Bash
arkcli train finetune capability get
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 基础模型名称，如 doubao-seed-1-6-flash。与 --model-id 互斥 |
| `--version` | string | 模型版本，如 250828；留空 = 仅主版本。与 --model-id 互斥（cm 自带绑定的来源版本） |
| `--model-id` | string | 自定义模型 ID（cm-xxx）。与 --model/--version 互斥。会解析到其来源基础模型，并报告该基础模型的能力 |

<span id="train-finetune-create-command"></span>
### train finetune create

创建精调任务。除兼容旧参数（--dataset、--epochs、--lr、--lora-rank、--beta）外，还支持对齐 PRD 的新增项：本地文件、RL 流程、数据容错、超参数 JSON、模型保存上限、轨迹记录。

```Bash
arkcli train finetune create
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string（必填） | 任务名称 |
| `--type` | string（必填） | 定制类型：sft \| lora \| dpo \| dpo-lora \| grpo \| grpo-lora \| ppo \| opd \| opd-lora \| pt |
| `--description` | string | 任务描述 |
| `--model` | string | 基础模型名称（如 doubao-seed-1-6-flash），与 --model-id 互斥 |
| `--model-version` | string | 基础模型版本（如 250615），配合 --model 使用 |
| `--model-id` | string | 自定义模型 ID，与 --model/--model-version 互斥 |
| `--dataset` | string | 训练数据集：tos://bucket/path 或数据集 ID（ds-xxx）。旧版合并参数——建议改用 --train-tos-uri / --train-dataset |
| `--dataset-version` | string | 数据集版本 ID（dsv-xxx），当 --dataset 传数据集 ID 时必填。旧写法——建议改用 --train-dataset-version |
| `--train-tos-uri` | string | 训练数据 TOS URI（tos://bucket/prefix）。输入为 TOS 路径时，与 PRD 对齐的 --dataset 别名 |
| `--train-dataset` | string | 训练数据集及版本，格式 <dataset-id>:<version-id>；旧的 --train-dataset-version 分开写法仍支持 |
| `--train-dataset-version` | string | 训练数据集版本 id（dsv-yyy）。与 PRD 对齐的 --dataset-version 别名 |
| `--train-file` | string_slice | 本地训练文件路径（可重复；映射到 data.training_set.local_files[]） |
| `--train-path` | string_slice | 托管数据集路径 JSON（可重复）：{"dataset_id":"ds-...","dataset_version_id":"dsv-...","multiplier":1}，或把 multiplier 换成 sample_count |
| `--preset-dataset` | string_slice | 预设数据集 JSON（可重复）：{"dataset_version_id":"dsv-...","inject_multiplier":1}；inject_multiplier 与 inject_sample_count 二选一 |
| `--validation-dataset` | string | 验证数据集及版本，格式 <dataset-id>:<version-id>；旧的 tos:// 与分开写版本的形式仍支持 |
| `--validation-dataset-version` | string | 验证数据集版本 id（dsv-xxx） |
| `--validation-tos-uri` | string | 验证数据 TOS URI（tos://bucket/prefix）。与 PRD 对齐的别名 |
| `--validation-dataset-id` | string | 验证数据集 id（ds-xxx）。与 PRD 对齐的别名 |
| `--validation-file` | string_slice | 本地验证文件路径（可重复；映射到 data.validation_set.local_files[]） |
| `--validation-percentage` | int | 用作验证集的训练集比例（例如 10）；与 --validation-dataset/--validation-file 互斥 |
| `--max-invalid-records-ratio` | string | 允许的坏样本比例，取值 [0,1)（例如 0.01） |
| `--max-invalid-records-number` | int | 允许的坏样本绝对条数（正整数） |
| `--shuffle-random-seed` | string | -1 = 每次运行随机，0 = 不洗牌，正数 = 固定种子以便复现（字符串类型，使 0 与未设置区分开） |
| `--hyperparameters` | string | JSON 字典或 @file（例如 '{"epoch":"3","batch_size":"8"}' 或 @hyperparameters.json）。会与标量参数 --epochs/--lr/--lora-rank/--beta 合并（冲突时以标量参数为准） |
| `--epochs` | int | 训练轮数（--hyperparameters epoch 的旧写法） |
| `--lr` | string | 学习率（--hyperparameters learning_rate 的旧写法） |
| `--lora-rank` | int | LoRA 秩（--hyperparameters lora_rank 的旧写法） |
| `--beta` | string | DPO 的 beta 参数（--hyperparameters beta 的旧写法） |
| `--save-model-limit` | int | 保留的训练产物数量上限（1-10；后端默认 1） |
| `--enable-trajectory` | bool | 开启 RL rollout 轨迹记录（调试 GRPO/PPO 时推荐） |
| `--pipeline` | string | @file 形式的 JSON RL pipeline 配置路径（custom_rl_pipeline；自定义 rollout/grader 的 GRPO/PPO 必填） |
| `--resource-group` | string | 资源组 ID；请按查询结果原样传入，提交前会检查当前账号/项目权限、任务资源模板和资源组可用性 |
| `--yes` | bool | Skip the interactive confirmation prompts: the upload-to-TOS gate (--train-file) and the final submit prompt. NOTE: model activation (开通) is hard-refused in non-interactive (agent/CI/pipe) regardless of --yes — set ARKCLI_ALLOW_HEADLESS_ACTIVATION=1 for unattended activation, otherwise the base model must already be activated. |
| `--estimate` | bool | 只做在线 Token 与价格试算，不创建精调任务 |

<span id="train-finetune-delete-command"></span>
### train finetune delete

删除精调任务记录（不可逆）。用 --yes 跳过确认提示，脚本场景推荐。仅处于终态（Completed / Failed / Terminated）的任务可删除；非终态任务会在 shortcut 层被拒绝，并提示先执行 `train finetune stop`（省去一次注定失败调用上的确认往返——否则后端会以 `OperationDenied.UnsupportedPhase` 拒绝）。对 Agent 的要求：先用 `train finetune get` 查看目标，复述任务 ID 与影响，取得明确确认后再删除。

```Bash
arkcli train finetune delete <job-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互确认提示 |

<span id="train-finetune-get-command"></span>
### train finetune get

获取精调任务的完整详情（状态 / 配置 / 产物）。数据与当前的 `train finetune status` 相同，这是 PRD 规定的读取入口。要看训练步进度用 `train finetune metrics`；要实时轮询用 `train finetune watch`。不含费用——接口 schema 没有按任务的计费字段；提交前在线估算请用 `train finetune create --estimate`。

```Bash
arkcli train finetune get <job-id>
```

<span id="train-finetune-list-command"></span>
### train finetune list

列出模型精调任务

```Bash
arkcli train finetune list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--page-number` | int | 页码（必须大于等于 1，默认 1） |
| `--page-size` | int | 每页条数（1-100，默认 100） |
| `--sort-by` | string | 排序字段 |
| `--sort-order` | string | 排序方向：Asc \| Desc |
| `--phase` | string_slice | 按阶段过滤（可重复）：Preprocessing \| Queued \| Deploying \| Running \| Pausing \| Paused \| Terminating \| Terminated \| Completing \| Completed \| Failed |
| `--name` | string | 按任务名称过滤（模糊匹配） |
| `--customization-type` | string_slice | 按定制类型过滤（可重复）：FinetuneSft \| FinetuneLoRA \| DPO \| DPOLoRA \| GRPO \| GRPOLoRA \| PPO \| OPD \| OPDLoRA \| Pretrain |
| `--create-time-after` | string | 过滤该时间之后创建的任务（RFC3339，例如 2026-01-01T00:00:00Z） |
| `--create-time-before` | string | 过滤该时间之前创建的任务（RFC3339） |

<span id="train-finetune-logs-command"></span>
### train finetune logs

跟踪精调任务的训练日志。默认数据源是公网 ARK Action `GetTaskLogs`（与 maas 控制台「训练日志」页一致）——即 system / 训练框架的 stdout，任意鉴权 profile 均可访问。支持 --follow / --tail / --search / --since；任务进入终态且没有新行后 --follow 会自动退出；--tail >1000 时自动分批。加 --custom 后数据源切换为该任务专属的 CustomTLSConfig topic——RL 插件（rollout / grader）函数的 stdout，与 maas 控制台「自定义日志（TLS）」子页一致。--custom 需要火山 SSO STS（直连 TLS，与轨迹相同），且只对开启了 --enable-trajectory 并启用了 project 级 TLS 的 RL 任务有效（见 `arkcli train finetune tls config get`）；--custom 不支持 --follow。--all 会导出超过 --tail 上限的全部日志（一直翻页到后端 ListOver），并且必须配合 --output FILE，避免 10MB+ 日志撑爆 Agent 上下文。

```Bash
arkcli train finetune logs <job-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--tail` | int | Tail 大小：每次请求拉取的行数。默认 200；maas-fe 控制台默认 2000。设置 --all 时忽略。 |
| `--follow` | bool | 任务运行期间持续轮询新日志行；进入终态且无新行后自动停止。用 --interval 调整轮询节奏。不支持与 --custom 或 --all 同用。 |
| `--interval` | string | --follow 的轮询间隔，支持时长写法（5s、30s）或纯整数秒。默认 5s。 |
| `--search` | string | 服务端筛选；GetTaskLogs 来源使用 FilterExpression；TLS 自定义日志使用 content 过滤。 |
| `--since` | string | 起始时间，相对于当前时间的时长（如 30m、2h）；TLS 自定义日志默认 30 天，GetTaskLogs 来源默认不限制起始时间。 |
| `--json` | bool | 输出结构化 JSON，替代纯文本行。 |
| `--custom` | bool | 读取 RL 插件函数的 stdout（CustomTLSConfig TLS topic），而不是 system / 训练框架日志。需要火山 SSO + RL 任务 + --enable-trajectory。 |
| `--function-name` | string | 仅 TLS --custom：按插件函数名筛选（如 SingleRollout-xxx），对应 function_name 查询。 |
| `--all` | bool | 分页读取全部日志，忽略 --tail；必须提供 --output FILE。GetTaskLogs 使用 Ctx 游标，TLS 使用 Context 游标。 |
| `--output` | string | 写入日志文件：GetTaskLogs 为纯文本，TLS 自定义日志为 JSON；stdout 仅返回元数据。--all 时必填。 |

<span id="train-finetune-metrics-command"></span>
### train finetune metrics

获取精调任务的训练指标。底层分两步：先用 GetModelCustomizationJobMetrics 返回可用指标名（如 train/loss、eval/loss、train/lr、train/grad_norm；DPO/GRPO 任务前缀不同），再用 GetModelCustomizationJobMetricData 拉取逐步时间序列。用 --metric（可重复）过滤；默认返回全部可用指标。用 --output 把 JSON 落盘（便于 Agent 渲染图表）。

```Bash
arkcli train finetune metrics <job-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--metric` | string_slice | 只取一个或多个指标名（可重复）。留空表示全部可用指标 |
| `--min-sample-step` | int | 最小采样 step（服务端降采样） |
| `--max-metric-point` | int | 每个指标最多返回的采样点数（服务端会均匀降采样） |
| `--from-step` | int | 范围过滤：只返回 step >= 该值的样本 |
| `--to-step` | int | 范围过滤：只返回 step <= 该值的样本 |
| `--output` | string | 将响应 JSON 写入该文件路径；便于 Agent 渲染图表 |

<span id="train-finetune-pause-command"></span>
### train finetune pause

暂停运行中的精调任务（可通过 `train finetune resume` 恢复）。与不可逆终止的 `stop` 不同。

```Bash
arkcli train finetune pause <job-id>
```

<span id="train-finetune-pricing-command"></span>
### train finetune pricing

查询基础模型的精调价格。--billing-method=token 时，按 --type 过滤基础模型计费项：lora / lora-sft / dpo-lora / grpo-lora / opd-lora → LoRA 精调；sft / dpo / grpo / ppo / opd / pt → 全参精调。--type 为空则返回全部精调相关计费项。--billing-method=instance 时，解析出精确的模型版本/类型超参数 schema，列出可用的训练资源模板，并关联其 FlavorSum 小时价。指定 --type 时，arkcli 会与 `train finetune capability get` 交叉校验，模型不支持该训练方法时直接拒绝（对不支持的方法返回通用计费项价格会误导调用方）。

```Bash
arkcli train finetune pricing
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string（必填） | 基础模型名称，如 doubao-seed-1-6-flash |
| `--type` | string | 定制类型：sft \| lora \| lora-sft \| dpo \| dpo-lora \| grpo \| grpo-lora \| ppo \| opd \| opd-lora \| pt；留空 = 全部 |
| `--billing-method` | string | 计费方式：token \| instance |
| `--model-version` | string | 基础模型版本；--billing-method=instance 时必填 |
| `--hyperparameters` | string | 仅实例计费时：JSON 字典或 @file；会与模型默认值以及 --epochs/--lr/--lora-rank/--beta 等标量覆盖项合并 |
| `--epochs` | int | 仅实例计费时：覆盖 epoch |
| `--lr` | string | 仅实例计费时：覆盖 learning_rate |
| `--lora-rank` | int | 仅实例计费时：覆盖 lora_rank |
| `--beta` | string | 仅实例计费时：覆盖 beta |
| `--region` | string | 仅 Token 计价：价格地域，默认取当前 profile 的地域 |

<span id="train-finetune-resource-group-list-command"></span>
### train finetune resource-group list

检查资源组权限，并按当前精调模型、训练类型和超参数列出任务资源需求与可用资源组

```Bash
arkcli train finetune resource-group list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 基础模型名称；与 --model-id 互斥 |
| `--model-version` | string | 基础模型版本；使用 --model 时必填 |
| `--model-id` | string | 已有自定义模型 ID；会解析其基础模型，与 --model/--model-version 互斥 |
| `--type` | string（必填） | 训练类型：sft \| lora \| dpo \| dpo-lora \| grpo \| grpo-lora \| ppo \| opd \| opd-lora \| pt |
| `--hyperparameters` | string | 超参数 JSON 或 @file；与创建任务保持一致 |
| `--epochs` | int | epoch 快捷覆盖值 |
| `--lr` | string | learning_rate 快捷覆盖值 |
| `--lora-rank` | int | lora_rank 快捷覆盖值 |
| `--beta` | string | beta 快捷覆盖值 |
| `--only-matched` | bool | 只返回当前任务可以使用的资源组 |

<span id="train-finetune-resume-command"></span>
### train finetune resume

恢复已暂停（Paused）的精调任务；后端允许时也可重试 Failed / Terminated 任务

```Bash
arkcli train finetune resume <job-id>
```

<span id="train-finetune-sdk-login-command"></span>
### train finetune sdk login

用 arkcli 的 STS 写入 ark_sdk 的 `~/.ark/authorization.json`——替代 `ark login`。仅当用户自己跑 `python3 submit_job.py` 时才需要：ark_sdk 0.6.0 Python 库的提交热路径只读该文件（不读环境变量），属上游 SDK 限制。用 YAML 规格提交请改用 `train finetune sdk submit <yaml>`——它不会写 authorization.json（使用 0600 的临时凭证文件，作用域限定在 ark 进程内）。STS 过期会自动刷新。若已存在属于其他账号的文件，除非传 --force，否则拒绝覆盖。

```Bash
arkcli train finetune sdk login
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--refresh` | bool | 写入前强制刷新产品原生 SSO STS。 |
| `--force` | bool | 即使已存在的 authorization.json 的 account_id 与 arkcli 当前 profile 不同，也强制覆盖。 |
| `--path` | string | 覆盖输出路径。默认：~/.ark/authorization.json（与 ARK_SDK_AUTHORIZATION_FILE 环境变量一致）。 |

<span id="train-finetune-status-command"></span>
### train finetune status

获取精调任务详情（`get` 的别名；若后端拆分 API，预留给未来的精简阶段 / 进度投影）

```Bash
arkcli train finetune status <job-id>
```

<span id="train-finetune-stop-command"></span>
### train finetune stop

停止运行中的精调任务（不可逆——会终止任务；若想之后恢复请改用 `train finetune pause`）。默认 [y/N] 确认；`--yes` 跳过提示。

```Bash
arkcli train finetune stop <job-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过 [y/N] 确认提示。非交互执行（CI / 管道 / agent）时必填。 |

<span id="train-finetune-tls-config-delete-command"></span>
### train finetune tls config delete

永久删除该 project 的精调 TLS 资源——会销毁已存储的轨迹 / 自定义日志 / trace / 可解释性数据。不可逆。传 --yes 跳过 [y/N] 确认。删除后可随时通过 `arkcli train finetune tls config enable` 重新开启（会创建全新的空 topic）。

```Bash
arkcli train finetune tls config delete
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--project-name` | string | 覆盖项目名称（默认：当前 profile 的项目） |
| `--yes` | bool | 跳过 [y/N] 确认提示 |

<span id="train-finetune-tls-config-disable-command"></span>
### train finetune tls config disable

关闭 project 级精调 TLS（停止新数据写入；已有数据按 TLS 保留策略保留）。传 --yes 跳过 [y/N] 确认。若要永久删除 TLS 资源（数据一并销毁），请改用 `arkcli train finetune tls config delete`。

```Bash
arkcli train finetune tls config disable
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--project-name` | string | 覆盖项目名称（默认：当前 profile 的项目） |
| `--yes` | bool | 跳过 [y/N] 确认提示 |

<span id="train-finetune-tls-config-enable-command"></span>
### train finetune tls config enable

开启 project 级精调 TLS 资源（会创建四个后付费火山 TLS topic——产生费用）。本项目内任何任务要记录轨迹 / 自定义插件 stdout / trace / token 级数据，都必须先开启。默认 [y/N] 确认，因为会开通计费资源；传 --yes 跳过（非交互调用方 / Agent 必须传）。该在线开通流程不支持 --dry-run，请先确认当前 project 再显式确认。注意：子账号 IAM 用户可能没有权限，需请主账号管理员在 maas 控制台开启。

```Bash
arkcli train finetune tls config enable
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--project-name` | string | 覆盖项目名称（默认：当前 profile 的项目） |
| `--yes` | bool | 跳过 [y/N] 确认提示（非交互执行时必填） |

<span id="train-finetune-tls-config-get-command"></span>
### train finetune tls config get

查看 project 级精调 TLS 状态：是否已开启，以及支撑 `--enable-trajectory` / RL 插件日志 / trace / 可解释性数据的四个 topic id（trajectory / custom / trace / explainability）。project 默认取当前生效 profile 的 project，可用 --project-name 覆盖。

```Bash
arkcli train finetune tls config get
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--project-name` | string | 覆盖项目名称（默认：当前 profile 的项目） |

<span id="train-finetune-trajectory-get-command"></span>
### train finetune trajectory get

获取单条 rollout 轨迹记录（始终返回完整内容；单条约 3KB）。用 --sample-id（精确匹配）或 --step + --index（该 step 下第 i 条 rollout）指定。SSO 要求与 `trajectory list` 相同。

```Bash
arkcli train finetune trajectory get <job-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--sample-id` | string | Sample id（smpl-...）。与 --step/--index 互斥。 |
| `--step` | int | Step 序号（配合 --index 选取指定 rollout） |
| `--index` | int | 该 step 内从 0 开始的 rollout 序号（默认 0） |
| `--since` | string | 相对当前时间的时间窗口。默认 30d。 |
| `--output` | string | 将 JSON 写入该文件路径 |

<span id="train-finetune-trajectory-list-command"></span>
### train finetune trajectory list

列出某精调任务的 RL rollout 轨迹。直接从该任务对应的火山 TLS topic（TrajectoryTLSConfig.TopicID）读取——绕过 ARK 控制面。默认输出为摘要（step / sample_id / phase / reward / advantage / tokens / duration），对 Agent 友好，约 150 字节/条。传 --full 得到完整形态（展开 sample / trajectory / metrics / reward_details / plugin_details，约 3KB/条）。传 --output FILE 可把完整 JSON 落盘，stdout 只留一小段元信息。需要 SSO 认证的 profile（与 logs 的限制相同）。

```Bash
arkcli train finetune trajectory list <job-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--step` | int | 按 step 序号过滤（例如 --step 20） |
| `--phase` | string | 按阶段过滤：train \| eval |
| `--sample-id` | string | 按 sample id 过滤（smpl-...） |
| `--query` | string | 原始 TLS 查询表达式；覆盖 --step/--phase/--sample-id |
| `--limit` | int | 最多返回的条目数（默认 200；因 TLS API 单次上限 100，超过 100 会自动分页）。--all 时忽略。 |
| `--since` | string | 相对当前时间的时间窗口（30m / 2h / 24h）。默认 30d（覆盖 TLS 完整保留期）。 |
| `--full` | bool | 返回完整内容：sample / trajectory / metrics / reward_details / plugin_details（约 3KB/条，较重） |
| `--all` | bool | 一直分页直到后端把该 topic 读完。必须配合 --output FILE——拒绝把无界数据直接打到 stdout。 |
| `--output` | string | 将完整 JSON 写入该文件路径；stdout 只显示元信息（推荐 Agent 场景使用）。设置 --all 时必填。 |

<span id="train-finetune-update-command"></span>
### train finetune update

更新精调任务的可变字段（name / description）。--name 与 --description 至少要传一个；空字段不会被提交。

```Bash
arkcli train finetune update <job-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string | 新的任务名称 |
| `--description` | string | 新的任务描述 |

<span id="train-finetune-watch-command"></span>
### train finetune watch

轮询精调任务直到进入终态（Completed / Failed / Terminated）。默认模式：按阶段逐行把进度输出到 stderr；--rich 模式额外给出步进度条 / ETA / 各指标迷你走势（最近 30 步）。免去 Agent/CI 自己写轮询循环。

```Bash
arkcli train finetune watch <job-id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--interval` | string | 轮询间隔，支持时长写法（如 15s、1m、1h30m）或纯整数秒。默认 30s；--rich 模式默认 5s，与 maas-fe 的进度图一致 |
| `--timeout` | string | 总等待上限，可用时长（如 30m、2h）或纯整数秒；0 = 不超时（默认 0） |
| `--quiet` | bool | 关闭每次 tick 打印到 stderr 的进度 |
| `--rich` | bool | 渲染 PRD 风格 TUI：step / 进度条 / ETA / 迷你趋势图指标。stderr 不是 TTY 时自动关闭。 |
| `--metric` | string_slice | （--rich）要渲染成迷你走势的指标（以 / 分隔的键，例如 train/loss、train/lr、train/grad_norm）。默认：train/loss、train/lr、train/grad_norm、train/global_step。可重复。 |