@volcengine/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.dc921200a42d

package/skills/arkcli-train-finetune/references/create.md

@@ -0,0 +1,262 @@
+# 创建精调任务
+
+`--train-file` 与 `--validation-file` 都会在在线 `--estimate` 或真实提交前上传到 TOS；最终 `data.TrainingSet` / `data.ValidationSet` 使用 `TosBucket` 和 `TosPaths`，不把本地路径交给服务端。`uploaded_files` 包含两组上传记录，训练 token 预估只使用训练集。即使训练集已是 TOS 引用，本地验证集也会上传；上传失败时停止提交。`--estimate` 会上传文件，但不会创建训练任务。
+
+> **执行面：** `train finetune create` / `--estimate` 都是控制面命令，认证走 SSO/STS；不要传
+> `--api-key` / `--base-url`（控制面会 fail-fast）。`.env` 里的 API Key 只能用于数据面推理，不能用于训练创建或
+> TOS 上传。本地训练/验证文件由 CLI 通过 `--train-file` / `--validation-file` 自动上传到 Ark 托管 TOS。
+
+创建输出仍为 `id` 和 `url`；火山链接继续使用 `console.volcengine.com`。
+
+- 参考以下顺序完成创建；当用户提供信息不足时，查询并给出建议。
+- 若参数已明确，允许直接执行 `create --estimate` 获取在线 Token 与费用估算；估算失败或信息不足时，再按错误类型补查。
+- 真实 create 必须等待用户确认。
+
+训练数据格式、参数含义等知识缺口可转 [`arkcli-docs`](../../arkcli-docs/SKILL.md)，搜索后读取返回的正文；实时能力、价格、资源权限仍以本流程的查询命令为准，文档不能代替创建确认。
+
+## 1. 查询模型、训练方法、价格与部署能力
+
+| 命令                                     | 何时用                        | 常用参数                                                    |
+| :------------------------------------- | :------------------------- | :------------------------------------------------------ |
+| `arkcli models search <keyword>`       | 找候选基础模型（是否支持精调的信息仅供参考）     | `--modality`、`--strict-filter`                          |
+| `arkcli models versions <model>`       | 找基础模型下的模型版本（是否支持精调的信息仅供参考） | 无                                                       |
+| `arkcli train finetune capability get` | 查某模型版本支持的训练方法（以此为准）        | `--model`、`--version`                                   |
+| `arkcli train finetune pricing`        | 按 Token 或实例计费查询训练价格          | `--model`、`--model-version`、`--type`、`--billing-method` |
+| `arkcli train finetune resource-group list` | 查询资源组权限、任务资源需求和匹配结果 | `--model`、`--model-version`、`--type`、`--only-matched` |
+| `arkcli infer endpoint capability get` | 查询基础模型（model+version）、自定义模型（custom-model-id）支持的推理部署方式             | `--model`、`--version` 、`--model-id` |
+
+这些命令的 flags 会随 CLI 演进；常规场景可直接按本 reference 使用，遇到报错或不确定再查 `--help`
+
+根据用户目标搜索候选模型。选定模型后，查询：
+
+```bash
+arkcli models versions <model>
+arkcli train finetune capability get --model <model> --version <version>
+arkcli train finetune pricing --model <model> --type <type>
+# token 是默认计费方式；不要改用通用 arkcli pricing models
+# 实例计费必须使用精确版本和训练方法；自定义超参需与后续创建保持一致
+arkcli train finetune pricing --model <model> --model-version <version> --type <type> \
+  --billing-method instance --hyperparameters '{"epoch":"3"}'
+arkcli infer endpoint capability get --model <model> --version <version>
+```
+
+向用户说明：
+
+- 该版本支持哪些训练方法。
+- 选定训练方法的计价单位和价格。
+- `token` 返回按 Token 计费项；`instance` 会先校验该模型版本和训练方法支持 Instance，
+  再返回资源模板、机型单价、角色数量对应的小时价及整体小时价范围。只有
+  `price_complete=true` 时价格范围才是完整的；否则必须报告 `missing_flavor_ids`，不得按 0 元解释。
+- 选定版本及训练方法，训练后支持的部署方式。
+  - 使用`--model`、`--version`或`--model-id`查询到的是基础模型的部署能力，为精调产物的潜在部署能力，不保证具备完全相同的能力。
+  - 训练完成后的实际部署方式需要用 `--custom-model-id` 再查，并由部署 skill 继续处理。
+
+默认训练类型与训练方法：
+
+- 用户未指定训练类型（`--type`）时，默认 SFT。
+- 用户未指定 LoRA 还是全量训练等训练方法时，默认 LoRA。
+- 因此，在模型支持 LoRA 时，默认选择 LoRA 对应的 `--type`；若模型不支持 LoRA，再展示可用训练类型和训练方法并请用户选择。
+- 用户明确要求全量训练时，使用该训练类型对应的全量训练 `--type`，并在继续前提示：当前 ArkCLI 还不支持对全量训练产物进行部署，训练完成后的部署需要到控制台完成。
+
+若用户未指定模型，展示少量相关候选项并请用户选择，不要自行提交高成本任务。
+
+## 2. ArkCLI 能力回退
+
+精调 SDK 是 fallback，不是默认入口。
+
+先检查当前版本的 `arkcli train finetune`、`arkcli models finetune-config` 和相关 `--help`。ArkCLI 能完整表达用户配置时继续标准流程；不能表达复杂强化学习、自定义 job、grader、rollout plugin 或自定义训练代码时，暂停并询问：
+
+> 当前配置超出 ArkCLI 标准创建能力。是否转交扩展精调流程继续处理？
+
+只有用户明确确认后，才读取 [`ark-finetune-sdk.md`](ark-finetune-sdk.md)，并停止执行本 reference 的后续创建步骤。安装、鉴权、配置和提交均由该文档负责；用户拒绝时不要安装或提交。
+
+## 常用创建参数
+
+检查用户要求能否由当前 ArkCLI flags 完整表达：
+
+```bash
+arkcli train finetune --help
+arkcli train finetune create --help
+```
+
+<br />
+
+`arkcli train finetune create` 的高频参数：
+
+| 参数                                                           | 说明                                                           |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| `--name`                                                     | 任务名称                                                         |
+| `--description`                                              | 任务描述                                                         |
+| `--model` + `--model-version`                                | 基于基础模型训练                                                     |
+| `--model-id`                                                 | 基于已有 custom model 继续训练；与 `--model/--model-version` 互斥        |
+| `--type`                                                     | 训练类型；未指定时按“默认 SFT + LoRA”处理                                  |
+| `--train-file`                                               | 本地训练文件，可重复                                                   |
+| `--train-tos-uri`                                            | 已上传训练数据 TOS URI                                              |
+| `--train-dataset <dataset-id>:<version-id>`                  | 已有训练 Dataset；旧的独立 `--train-dataset-version` 仍兼容                    |
+| `--train-path <json>`                                       | 普通训练 Dataset，可重复；每项设置 `dataset_id`、`dataset_version_id`，最多再设置 `multiplier`/`sample_count` 之一 |
+| `--preset-dataset <json>`                                   | 模型支持的预置数据集，可重复；每项设置 `dataset_version_id`，并在 `inject_multiplier`/`inject_sample_count` 中二选一 |
+| `--validation-file`                                          | 本地验证文件，可重复                                                   |
+| `--validation-tos-uri`                                       | 已上传验证集 TOS URI                                               |
+| `--validation-dataset <dataset-id>:<version-id>`             | 已有验证 Dataset；旧的独立版本参数仍兼容                                    |
+| `--validation-percentage`                                    | 从训练集中切分验证集；与显式验证集互斥                                          |
+| `--hyperparameters`                                          | JSON 字符串或 `@file`；值按后端要求传字符串                                 |
+| `--epochs`、`--lr`、`--lora-rank`、`--beta`                     | 旧式快捷参数；可用时会合并进 hyperparameters，快捷参数冲突时优先                     |
+| `--max-invalid-records-ratio`、`--max-invalid-records-number` | 数据容错                                                         |
+| `--shuffle-random-seed`                                      | 数据顺序控制：随机、不打乱或固定种子                                           |
+| `--save-model-limit`                                         | 保留训练产物数量                                                     |
+| `--enable-trajectory`                                        | RL 轨迹日志；需要任务和项目配置支持                                          |
+| `--pipeline`                                                 | RL pipeline 配置文件；若需要 Python plugin 且 CLI 不能表达，按“ArkCLI 能力回退”处理 |
+| `--resource-group`                                           | `resource-group list` 返回的稳定资源组 ID；按不透明字符串原样传入，CLI 会在 estimate 和真实提交前重新校验权限、任务资源需求与可用性 |
+| `--yes`                                                      | 跳过 CLI 确认；Agent 只能在用户二次确认/明确表示直接创建后添加                        |
+
+## 3. 获取并校验训练数据
+
+本 skill 不创建或维护平台 Dataset；只有独立 Dataset 生命周期操作或不涉及精调任务的独立校验才转 [`../../arkcli-datasets/SKILL.md`](../../arkcli-datasets/SKILL.md)。精调任务创建或预检所需的本地/TOS 数据校验继续留在本流程，直接使用下方 `arkcli dataset validate`。创建任务可接受：
+
+- 本地训练文件
+- 已上传的 TOS URL
+- 平台 Dataset 的 `<dataset-id>:<version-id>` 引用
+- 模型配置明确支持的 preset Dataset
+
+同一训练集或验证集只能选择一种普通数据来源；Dataset 与对应的 TOS/本地文件参数互斥。单个普通 Dataset 默认 `Multiplier=1`；需要重复引用、倍率或采样数时使用可重复的 `--train-path`。每项最多设置 `multiplier`/`sample_count` 之一，均不设置时仍默认 `Multiplier=1`：
+
+```bash
+--train-path '{"dataset_id":"ds-...","dataset_version_id":"dsv-...","multiplier":2}'
+--train-path '{"dataset_id":"ds-...","dataset_version_id":"dsv-...","sample_count":500}'
+```
+
+`--train-path` 不能和 `--train-dataset`、训练 TOS 或本地文件混用。preset 使用可重复 JSON，`inject_multiplier` 与 `inject_sample_count` 也必须且只能设置一个：
+
+```bash
+--preset-dataset '{"dataset_version_id":"dsv-...","inject_sample_count":100}'
+```
+
+CLI 会根据精确模型版本和训练类型检查 Dataset schema，并拒绝模型配置未声明支持的 preset。
+
+用户未提供数据时，请其提供训练集文件或现有数据引用。
+
+### 使用 CLI 校验数据
+
+本 skill 内直接使用 `arkcli dataset validate` 校验本地文件或 TOS 数据，无需为此创建 Dataset 或切换到数据集管理流程。先确认模型、精确版本及实际训练 `--type`，与后续创建保持一致；查看当前命令支持的参数：
+
+```bash
+arkcli dataset validate --help
+
+# 本地 JSONL；多个文件重复 --local
+arkcli dataset validate --model <model> --model-version <version> --type <type> \
+  --local <train.jsonl>
+
+# 已有 TOS 数据；多个 URI 重复 --tos-uri
+arkcli dataset validate --model <model> --model-version <version> --type <type> \
+  --tos-uri tos://<bucket>/<path>
+```
+
+- CLI 自动读取模型配置中的 `dataset_schema`，无需 Agent 先查格式文档、维护静态 schema 映射或自写校验器。训练集和显式验证集都要覆盖；可按数据集分别执行，便于归属结果。
+- `--local` 与 `--tos-uri` 二选一。本地文件会上传并触发服务端校验，不是离线检查；执行前按主 skill 的上传确认规则处理。已有上传授权时不重复询问。
+- TOS URI 必须可列举且包含 `.jsonl` 对象；同一次调用的多个 URI 必须属于同一 bucket，不能使用 `ds-ds/*` 上传暂存路径。以当前 `--help` 为准。
+- 当前命令不直接接收 `ds-*/dsv-*`、preset 或 `--model-id`。已有 Dataset/preset 继续走创建流程的 schema/能力检查；需要内容校验时使用可确认来源的本地文件或受支持 TOS URI。自定义模型续训不能猜测基础模型映射，未确认校验上下文时说明能力缺口。
+
+### 校验结果与失败处理
+
+以 CLI 返回的服务端校验任务结果为准，汇总实际校验的数据来源、模型/版本/训练类型、成功或失败状态，以及返回的错误摘要、行号或统计信息；未返回的字段不补造，不输出完整样本。
+
+- 所有目标数据校验成功后，才报告数据校验通过。`--dry-run` 只预览执行计划，不访问网络、不上传、不做真实校验；参数解析成功或 `create --estimate` 成功也不能替代数据校验结果。
+- 校验失败时，根据返回的错误定位；需要理解字段要求或修复数据时，再读取火山方舟[模型精调数据集格式说明](https://www.volcengine.com/docs/82379/1099461?lang=zh)对应章节。修复后对相同模型配置重新执行 `dataset validate`。
+- 命令不可用、鉴权/网络失败、模型未提供 schema 或校验未完成时，明确“未完成校验”及原因，不将基础检查、文档比对或用户确认格式当作校验通过。只请求补充缺失信息，不自动安装/升级 CLI 或提交训练。
+
+Token 数处理：
+
+- 环境中存在与目标模型匹配的 tokenizer 时，可以给出本地估算并注明 tokenizer 和误差来源。
+- 没有匹配 tokenizer 时，不要用字符数冒充精确 token 数；将 token 统计交给在线 `--estimate`。
+
+## 4. 查询并确认超参数
+
+| 命令                              | 何时用                               | 常用参数                         |
+| :------------------------------ | :-------------------------------- | :--------------------------- |
+| `arkcli models finetune-config` | 确定模型版本和训练方法后查支持的超参和 `dataset_schema` | `<model> <version>`、`--type` |
+| `arkcli train finetune create`  | 估算或创建任务                           | `--estimate` 在线估算，确认后真实提交       |
+
+打印参数名、默认值、范围或枚举、简短说明。不要依赖记忆填写字段名。
+
+显式传入 `--type` 时，`models finetune-config` 会使用与 `train finetune capability get` 相同的权威 `FinetuneTypes`，校验精确的模型版本是否支持该训练方法。不支持时会在读取配置 schema 前返回 validation error；不要继续 estimate 或创建任务。
+
+- 用户要求自定义超参时，请其确认覆盖值。
+- 根据用户选择的模型、偏好、数据量、效果指标、日志等信息，分析并帮助用户配置超参；如果没有更优配置，使用默认值。
+- 拒绝超出 schema 的值
+
+通用训练配置优先从 finetune-config 的 schema 读取默认值和范围。本 reference 只记稳定语义：
+
+- 训练轮数、学习率、batch size、LoRA rank/alpha/dropout、DPO beta、RL 步数等字段名可能随训练方法不同而变化。
+- `save_model_limit` 决定保留多少个训练产物；默认值和上限以当前 CLI/API 为准。
+- 数据容错和 shuffle seed 属于数据配置，不是模型超参；预览时和超参分开展示。
+
+## 5. 查询并选择稳定资源组（按需）
+
+用户要求使用资源组时，先用与后续创建完全一致的模型、训练类型和超参数查询：
+
+```bash
+arkcli train finetune resource-group list \
+  --model <model> --model-version <version> --type <type> \
+  --hyperparameters '<same-json-as-create>' --only-matched
+```
+
+基于已有自定义模型继续训练时改用 `--model-id <cm-id>`，不要同时传
+`--model/--model-version`。查询结果的解释规则：
+
+- `allowed=false` 表示当前账号或项目未开通精调资源组能力；不要给 create 添加
+  `--resource-group`。
+- `candidate_templates` 是按精确模型、版本、训练类型和超参数解析出的任务资源需求；
+  不要根据资源组名称或总容量自行猜测需求。
+- 只有 `items[].matched=true` 的资源组才能用于当前任务。未匹配项的
+  `unmatch_reasons` 是权威原因；不要绕过或静默忽略。
+- 多个资源组匹配时，展示名称、ID、命中模板和容量摘要，让用户选择；不要擅自选择。
+- 选择后在 estimate 和真实创建命令中都传入 `--resource-group <resource-group-id>`。CLI 会在两次
+  执行前重新查询权限、候选模板和可用性，并在资源组不再匹配时 fail-fast。
+- 如果指定资源组不存在或不匹配，错误会给出权威的不匹配原因，并列出当前任务所有
+  `matched=true` 的资源组名称和 ID；没有可用项时会明确显示“无”。
+
+`resource-group list` 是在线只读预检，不是 Client Preview；不要给它添加
+`--dry-run`。资源组查询与 create 的超参数必须完全一致，包括 `--epochs`、`--lr`、
+`--lora-rank`、`--beta` 等快捷覆盖值。
+
+## 6. 创建预览 校验配置、数据、Token与费用
+
+| 命令                             | 何时用     | 常用参数                   |
+| :----------------------------- | :------ | :--------------------- |
+| `arkcli train finetune create` | 估算或创建任务 | `--estimate` 在线估算，确认后真实提交 |
+
+根据 `arkcli train finetune create --help` 组装命令，先执行 `--estimate`。这是在线估算而非 Client Preview；本地文件上传如需确认，先获得用户授权。
+
+预览至少汇总：
+
+- job 名称、模型、版本、训练方法
+- 若采用默认：说明“未指定训练类型和训练方法，默认 SFT + LoRA”
+- 若采用全量训练：再次提示“当前 ArkCLI 还不支持对全量训练产物进行部署，训练完成后的部署需要到控制台完成”
+- 训练和验证数据来源、`dataset validate` 的实际结果及未覆盖项
+- 自定义超参、推荐超参及其余参数采用默认值的说明
+- 服务端统计的样本或 token 信息
+- 计价单位、单价和预估费用
+- 使用资源组时：资源组名称、ID、命中的候选资源模板和预检结果
+- 数据容错、随机种子、产物数量等非默认配置
+
+如果 estimate 没有返回某个字段，明确说明“未提供”，不要自行补造。
+
+## 7. 最终确认并创建
+
+- 认证通过后生成并在本次创建流程中复用 `ARKCLI_SKILL_FLOW_ID=ftf_<ULID>`。
+- 按 shared 单命令前缀，在第一条创建业务命令前执行
+  `arkcli train finetune _report-activity --action create_flow_enter`。
+- 仅在 `dataset validate` 或其他明确的服务端数据校验覆盖本次目标数据并成功后执行 `--action data_validation_success`；普通参数解析、文档比对、Client Preview `--dry-run` 和仅有 Token/费用估算结果均不上报。
+
+把完整预览呈现给用户，明确询问是否创建。只有用户确认后，才执行真实创建命令；非交互执行按 CLI 要求添加 `--yes`。
+
+成功后返回：
+
+- job id、名称和初始阶段
+- 模型、版本、训练方法
+- 关键数据与超参数摘要
+- 使用资源组时返回已选择的资源组 ID，并说明提交前预检已通过
+- 控制台 URL（若 CLI 返回）
+- 后续查询命令，例如 `arkcli train finetune get <job-id>` 或 `watch <job-id>`
+
+不要在本流程中自动部署模型。

package/skills/arkcli-train-finetune/references/download.md

@@ -0,0 +1,44 @@
+# 下载精调任务数据
+
+用户想找回某个精调任务实际使用的训练集 / 验证集时，使用：
+
+```bash
+arkcli train finetune download <job-id> [--set all|train|validation] [--output-dir <dir>]
+```
+
+该命令从 `GetModelCustomizationJob` 的 `Data.TrainingSet` / `Data.ValidationSet` 解析数据来源，
+再从 TOS 下载到本地。默认输出目录是 `./<job-id>-data`，默认下载训练集和验证集。
+
+## 支持的来源
+
+| Job Data 字段 | 行为 |
+|---|---|
+| `TosBucket` + `TosPaths` | 按原 TOS 对象路径下载，保留相对路径 |
+| `Datasets[]`（`DatasetId` + `DatasetVersionId`） | 先查 Dataset 版本存储位置，再下载其 `Storage.Bucket` / `Storage.Prefixes` |
+| `PresetDatasets[]` | 平台托管预设数据，不可下载；结果里列为 `skipped` |
+| `LocalFiles[]` | 仅记录创建时的本机路径，服务端不保留文件内容；结果里列为 `skipped` |
+
+如果训练集/验证集同时存在多种来源，命令会分别下载到 `train/` 或 `validation/` 子目录；
+同一集合有多个来源时再追加 `01/`、`02/` 等序号目录，避免同名文件冲突。
+
+## 示例
+
+```bash
+# 下载训练集和验证集
+arkcli train finetune download mcj-20260722153822-jqvd
+
+# 只下载训练集到指定目录
+arkcli train finetune download mcj-20260722153822-jqvd --set train --output-dir ./mcj-data
+
+# 只下载验证集
+arkcli train finetune download mcj-20260722153822-jqvd --set validation
+```
+
+结果包含每个文件的 `object_key`、本地 `path`、`size_bytes`，以及每个集合的 `bucket` / `prefixes`。
+
+## 边界
+
+- 这是控制面任务加 TOS 读取，不是 `--api-key` 数据面调用；不要传 `--api-key` / `--base-url`。
+- 输出目录已有同名文件时命令会失败，避免静默覆盖本地文件；换一个 `--output-dir` 再试。
+- 如果 job 只有 `PresetDatasets` 或 `LocalFiles`，没有可下载的 TOS 对象，命令会返回明确的无可下载数据错误。
+- 不要根据任务名、模型名或历史目录猜测数据位置；以 job 返回的 `TosBucket` / `TosPaths` 或 Dataset 版本为准。

package/skills/arkcli-train-finetune/references/evals.md

@@ -0,0 +1,14 @@
+# 精调创建回归用例
+
+使用用户明确授权的目标模型、版本、类型和数据；以下用例不是提交线上任务的授权。
+
+| 用例 | 输入场景 | 期望行为 |
+|---|---|---|
+| control-plane-auth | 用户拿 `.env` / `--api-key` 要求提交 `train finetune create` | 说明精调是控制面，只走 SSO/STS；不把 API Key 传给训练创建；不切 Agent Plan 或改用 `+chat`/`+gen`。 |
+| sft-route | 用户说“我要做 SFT / 精调这个模型” | 进入本 skill 的 `train finetune` 控制面流程；先查能力/价格，再确认数据与创建，不按 Agent Plan 模型调用选型。 |
+| mine-list | 用户说“查我创建的精调任务” | 第一条列表命令包含 `--mine`；不先拉全账号再本地过滤；降级身份明确报不支持。 |
+| job-data-download | 用户要下载某精调任务的训练集/验证集 | 使用 `train finetune download <job-id>`；按 `TosBucket/TosPaths` 或 Dataset 版本下载，preset/local-only 来源列为 skipped，不猜路径。 |
+| local-train-validation-estimate | 已授权上传训练和验证两个本地 JSONL，要求在线估算 | 使用 `create --estimate`；两组均上传并显示 TOS 引用，`uploaded_files` 包含两组，训练 token 不包含验证集；不创建任务。 |
+| remote-train-local-validation | 训练集为已存在的 TOS URI，验证集为本地文件 | 验证集仍上传并转换为 TOS 引用；缺失文件或上传失败时停止提交，不重放未知结果的创建。 |
+| volc-create-url | 用户确认提交，创建返回任务 ID | 只按返回 ID 和 `console.volcengine.com` URL 报告创建结果，不声称训练已完成。 |
+| unsupported-local-preview | 要求 `create --dry-run` | 说明当前命令不支持本地 Client Preview；在线 `--estimate` 有上传副作用，不静默替换执行。 |

package/skills/arkcli-train-finetune/references/export-deploy.md

@@ -0,0 +1,177 @@
+# 精调产物优选、导出与部署
+
+本流程覆盖两种入口：
+
+- 用户指定一个 `mcj-...`，要求根据训练效果选择、导出并部署产物。
+- 用户已指定一个或多个 `cm-...`，要求判断部署方式并部署。
+
+开始前除 shared skill 外，按阶段读取：
+
+- custom model 查询、量化和可部署版本准备：[`../../arkcli-custommodel/SKILL.md`](../../arkcli-custommodel/SKILL.md)
+- 创建在线推理 Endpoint：[`../../arkcli-deploy/SKILL.md`](../../arkcli-deploy/SKILL.md)
+- 用户要求底层 Endpoint 配置或后续管理时：[`../../arkcli-infer-endpoint/SKILL.md`](../../arkcli-infer-endpoint/SKILL.md)
+
+不要复制或凭记忆执行这些 skill 的命令。进入对应阶段时读取其要求的 reference，并遵守写操作、计费和二次确认规则。
+
+## 命令速查
+
+| 命令 | 何时用 | 常用参数 |
+|---|---|---|
+| `arkcli train finetune metrics <mcj-id>` | 选择最佳 step | `--metric`、`--from-step`、`--to-step`、`--output` |
+| `arkcli train finetune artifacts list <mcj-id>` | 列产物 | `--format table` 给人选择，`--lite` 跳过 cm 名称二查 |
+| `arkcli train finetune artifacts export <mcj-id>` | 导出产物为 `cm-*` | `--artifact-name` 可重复，`--custom-model-name-prefix` 可选 |
+| `arkcli models custommodel get <cm-id>` | 查 custom model 详情 | `--transform artifact_types,active_endpoints` |
+| `arkcli models custommodel available-quantizations <cm-id>` | 查是否能创建新可部署版本 | 量化前必查 |
+| `arkcli models custommodel quantize <cm-id>` | 创建量化新版本 | `--quantization`，异步返回新 `cm-*` |
+| `arkcli infer endpoint capability get --custom-model-id <cm-id>` | 查实际部署能力 | 部署前查询 |
+| `arkcli +deploy` | 创建或复用 Endpoint | 不支持 `--dry-run`；复述最终参数并确认后执行 |
+
+## A. 从 MCJ 选择最佳 Step
+
+用户直接提供 `cm-...` 时跳到 C。
+
+### 1. 查询任务与可用指标
+
+```bash
+arkcli train finetune get <mcj-id>
+arkcli train finetune metrics <mcj-id>
+```
+
+先从 `get` 确认训练方法和任务状态。任务尚未产生有效指标或产物时，说明当前阶段并停止导出流程。
+
+若任务是全量训练，停止 CLI 导出部署流程并提示：当前 ArkCLI 还不支持对全量训练产物进行部署，需要到控制台完成。不要继续执行 `artifacts export`、custom model 部署或 `+deploy`。
+
+第一次调用 `metrics` 不指定指标，用返回的 `available_metrics` 获取真实名称。大结果使用 `--output` 写入文件，再以结构化 JSON 工具计算，不要人工扫描长序列。
+如果用 `--from-step` 和 `--to-step` 限定区间，`to-step` 必须严格大于 `from-step`。
+
+### 2. 选择用于排名的效果指标
+
+按以下优先级选择，名称必须来自 `available_metrics`：
+
+| 任务类型 | 第一优先 | 无第一优先时 |
+|---|---|---|
+| 非 RL | test/eval/validation 范围的 loss，取最小值 | train 范围的 loss，取最小值 |
+| RL | test/eval/validation 范围的 `final_rewards`，取最大值 | train 范围的 `final_rewards`，取最大值 |
+
+匹配规则：
+
+- `test`、`eval`、`validation` 都视为评测范围，优先级相同；存在多个候选时展示候选名并说明最终使用哪个。
+- RL 优先匹配名称为或末段为 `final_rewards` 的指标。
+- 不要把 accuracy、普通 reward、grad norm 或其他指标静默替代上述主指标。
+- 若首选和 fallback 指标都不存在，列出真实可用指标并请用户指定，不要自行猜测。
+
+记录以下信息：
+
+- 实际使用的 metric 名称及选择理由
+- 最优值
+- 对应的一个或多个 step
+- 指标属于评测集还是训练集
+
+多个 step 具有相同最优值时全部保留。若用户指定 top-k，则按指标方向排序并记录 top-k；不要默认把邻近 step 当作多个“最优 step”。
+
+## B. 将最佳 Step 映射到 Artifact 并导出
+
+### 1. 查询产物
+
+```bash
+arkcli train finetune artifacts list <mcj-id>
+```
+
+从 artifact 名称或结构化字段提取其 step。只对能够可靠解析 step 的产物做自动映射；无法解析时展示列表让用户选择。
+
+对每个最佳 step：
+
+1. 优先选择 step 完全相同的 artifact。
+2. 没有完全相同时，计算与每个可导出 artifact step 的绝对距离。
+3. 选择距离最小的 artifact；距离相同则保留全部并列候选。
+4. 明确展示 `metric step → artifact step → 距离`，不得把最近产物描述成精确命中。
+
+合并不同最佳 step 映射出的重复 artifact，避免重复导出。
+
+### 2. 用户 Check
+
+导出前展示：
+
+- MCJ 和训练方法
+- 使用的效果指标、最优值和最佳 step
+- 推荐 artifact 及映射距离
+- artifact 当前 export status
+- 已导出的 custom model id（若有）
+
+要求用户确认最终导出的一个或多个 artifact。用户可以增删候选。
+
+### 3. 导出
+
+仅对用户确认且尚未导出的 artifact 执行：
+
+```bash
+arkcli train finetune artifacts export <mcj-id> \
+  --artifact-name <artifact-1> \
+  --artifact-name <artifact-2>
+```
+
+需要命名前缀时先确认，再使用当前 `--help` 支持的参数。已导出的 artifact 直接复用现有 `cm-...`，不要重复 export。
+
+说明 export 是把 MCJ 产物注册为模型仓库中的 custom model，不是下载权重。记录每个 artifact 对应的 custom model id 和状态。
+
+导出状态常见值：
+
+- `Available`：可导出。
+- `Exported`：已导出，直接复用 `custom_model_id`。
+- `Exporting`：导出中，稍后查询。
+- `ExportFailed` / `Expired`：不可直接部署，展示状态并请用户选择下一步。
+
+## C. 查询 Custom Model 与可部署版本
+
+对用户指定或刚导出的每个 `cm-...`，读取并遵循 `arkcli-custommodel` skill。
+
+至少查询：
+
+```bash
+arkcli models custommodel get <cm-id>
+arkcli models custommodel get <cm-id> --transform artifact_types,active_endpoints
+arkcli infer endpoint capability get --custom-model-id <cm-id>
+```
+
+汇总：
+
+- custom model 名称、来源、状态和基础模型
+- 当前已有 Endpoint
+- 当前模型直接支持的部署方式
+- 是否存在通过量化等方式创建新版本后可支持的其他部署方式
+
+若用户目标部署方式当前不支持，再按 `arkcli-custommodel` skill：
+
+1. 查询 `available-quantizations` 及各量化方式预期支持的推理形态。
+2. 向用户说明量化对精度、性能和资源形态的影响。
+3. 用户确认后创建新的量化 `cm-...`。
+4. 轮询新模型至 `ready`。
+5. 对新 `cm-...` 重新查询详情和实际部署能力。
+
+不要因为存在量化选项就自动创建新版本。源模型与量化模型是不同资源，必须保留清晰映射。
+
+## D. 选择并部署
+
+向用户展示一个部署候选表，至少包含：
+
+- cm id 和名称
+- 来源 artifact/step（已知时）
+- 对应最优 metric 和值（已知时）
+- 原始或量化版本
+- 当前支持的部署方式
+- 已有 Running Endpoint（若有）
+
+询问用户：
+
+1. 要部署哪一个或多个 `cm-...`
+2. 每个模型采用哪种部署方式
+3. Endpoint 名称及该方式必需的配置
+
+用户选择后读取并遵循 `arkcli-deploy` skill：
+
+1. 对每个目标分别复述最终参数与影响范围。
+2. 展示将创建或复用的 Endpoint、部署方式和计费影响。
+3. 获得最终确认后真实部署。
+4. 记录每个 `cm-... → ep-...` 映射及 Endpoint 状态。
+
+多个模型部署属于多个计费资源，必须让用户看清目标数量。不要把用户对 artifact export 的确认视为 Endpoint 部署确认。

package/skills/arkcli-train-finetune/references/job-configuration.md

@@ -0,0 +1,122 @@
+# SDK 任务配置
+
+创建或审查 `job.py`、`job.yaml`、数据设置、超参或提交命令时读取本文件。
+
+## 需要检查的文件
+
+SDK 生成的 workspace 通常包含：
+
+- `job.py`：Python 对象配置，包含 `ModelCustomizationJob(...)` 和 `submit(...)`。
+- `job.yaml`：声明式任务配置，通过 `ark create mcj` 提交。
+- `arkworkspace.toml`：workspace 元数据。
+- `requirements.txt`：远端插件运行环境依赖。
+- `plugins/`：rollout、grader 和测试辅助函数。
+- `test_faas.py` 或等价的在线插件测试文件。
+
+编辑前必须先检查当前 SDK 版本生成的文件。模板里的 import 和字段名比旧示例更可靠。
+
+## 必要配置区域
+
+多数任务需要：
+
+- `name`：可读任务名。
+- `customization_type`：当前 SDK 接受的训练方式枚举或字符串。
+- `model_reference`：带名称和版本的 `foundation_model`，或 `custom_model_id`。
+- `data`：训练集和可选验证集。
+- `hyperparameters`：所选模型版本支持的字段。
+- `custom_rl_pipeline`：自定义 RL 任务需要。
+
+## 数据输入
+
+训练集和验证集通常可使用以下模式，具体以当前 SDK 规则为准：
+
+- `local_files`：workspace 内的本地 JSONL 文件。
+- `tos_bucket` 加 `tos_paths`：对象存储文件。
+- `datasets`：数据集 id、版本 id 和可选混入控制。
+
+验证集可以是显式 `validation_set`，也可以是 `validation_percentage`。互斥规则以生成类型或当前文档为准。
+
+## 超参
+
+不要复制旧文档里的超参表。针对当前模型版本查询：
+
+```bash
+ark get foundation-model --model <model-name> --version <model-version> --fields hyperparameters
+```
+
+只把返回的受支持字段映射到 `job.py` 或 `job.yaml`。如果生成模板把超参值写成字符串，保持这种风格。
+
+## Python 配置模式
+
+优先改造生成的 `job.py`。稳定结构如下：
+
+```python
+from ark_sdk.resources.model_customization_job import ModelCustomizationJob
+
+mcj = ModelCustomizationJob(
+    name="sdk-job",
+    model_reference=...,
+    customization_type=...,
+    hyperparameters={...},
+    data=...,
+    custom_rl_pipeline=...,  # 仅 RL 需要
+    enable_trajectory=True,  # RL 且 SDK 支持时使用
+)
+mcj.submit()
+print(mcj.url)
+```
+
+RL debug 任务中，给 `submit(...)` 传入 `debug=True`，并用当前 SDK 类型名配置 debug endpoint 和 API key。
+
+## YAML 配置模式
+
+优先改造生成的 `job.yaml`。稳定结构如下：
+
+```yaml
+name: sdk-job
+customization_type: GRPOLoRA
+model_reference:
+  foundation_model:
+    name: <model-name>
+    model_version: "<model-version>"
+hyperparameters:
+  batch_size: "32"
+data:
+  training_set:
+    local_files:
+      - ./data/train.jsonl
+custom_rl_pipeline:
+  graders:
+    - plugin:
+        name: reward_fn
+        python_func: plugins.reward:reward_fn
+      weight: 1.0
+  rollout:
+    plugin:
+      name: rollout_fn
+      python_func: plugins.rollout:rollout_fn
+enable_trajectory: true
+```
+
+提交：
+
+```bash
+ark create mcj -f job.yaml
+```
+
+仅当 RL 任务具备有效 debug 配置时，才使用：
+
+```bash
+ark create mcj --file job.yaml --debug
+```
+
+## 资源组
+
+当用户需要稳定或专用资源时，先检查当前资源组支持：
+
+```bash
+ark list resource_group --mcj --file job.yaml
+ark list resource_group --mcj --file job.yaml --only-matched
+```
+
+除非当前 SDK help 明确支持，否则不要把 debug 提交和 resource group 同时使用。