arkcli-custommodel

# arkcli models custommodel **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，其中包含认证闸门、配置排查与共享安全规则** **CRITICAL — 所有 `models custommodel` 命令在执行之前，务必先用 Read 工具读取其对应的 reference 文档，禁止直接盲目调用命令。** **CRITICAL — 写操作（upload / update / delete / quantize）必须先确认用户意图。删除前必须确认是否还有 endpoint 引用。** ## 守卫与使用原则 - 自定义模型相关需求优先使用 `arkcli models custommodel ...` - 这些命令虽然是标准 CLI 类型，但实现入口仍然来自 `shortcuts/models/` - 只有产品命令无法覆盖时，才回退到 [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md) - 本 skill 不是基础模型查询入口；基础模型目录查询转 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) - 写操作和异步任务必须把影响范围、轮询方式和后续动作串起来，不要停在单条命令 ## 适用场景 - 把训练好/微调好的权重从 veTOS 导入到 ARK 自定义模型 - 查询账号下已有的自定义模型（"我的自定义模型有哪些 / 状态如何"） - 查看自定义模型详情、产物形态、活跃 endpoint 引用 - 修改自定义模型展示名或描述 - 删除不再使用的自定义模型 - 把已 `ready` 的自定义模型量化，准备给 `+deploy` 当目标 ## 反唤起信号 - 找官方基础模型 → 用 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) 的 `search/list/get` - 直接调用自定义模型推理 → 必须先 `+deploy`，再走 `+chat` / `+gen` - 触发模型微调任务（customization job 本身）→ 转 [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md) - **从精调任务的 step（`global_step_N`）注册成 `cm-`**(=「导出训练产物」)→ 转 [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md) 的 `arkcli train finetune artifacts list / export`，**不要**用本 skill 的 `upload`(那是给"用户自己的 TOS 文件"用的,后端 Action `UploadModel`;mcj 输出走 `CreateCustomModel`,完全不同的 API) - 已经拿到 endpoint-id 后想管理 endpoint → 转 [`../arkcli-infer-endpoint/SKILL.md`](../arkcli-infer-endpoint/SKILL.md) ## `cm-*` 直接推理边界 - 用户要求“用 `cm-*` 直接对话/推理/试效果”时也必须加载本 skill。明确说明 `cm-*` 是自定义模型资源 ID，不能直接传给 `+chat` / `+gen`；推理前需要单独获得或部署 Endpoint。 - 该请求本身不授权部署、查询账号下 Endpoint 或发起推理。未经用户继续授权，不执行 `arkcli +deploy`、`arkcli +chat`、`arkcli infer endpoint list`，也不拼接 `jq` 等扫描方案。 - 只说明边界和下一步选择；用户明确要求继续部署后，才转 [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md) 并遵守其确认流程。 ## 核心概念 - 本 skill 统一把 `arkcli models custommodel ...` 管理的资源称为**自定义模型**（CustomModel，ID 形如 `cm-xxxxx`）；它与 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) 中 `search/list/get` 操作的官方基础模型（FoundationModel）是**两套独立资源** - 自定义模型来源有两类： - `import` —— 用户从 TOS 上传权重导入(本 skill `upload` 命令,走 `UploadModel` API) - `customization` —— 通过模型微调任务产出(走 [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md) 的 `train finetune artifacts export`,**底层是另一个 OpenAPI Action `CreateCustomModel`**,跟 `upload` 不互通) - 生命周期状态机：`preparation → processing → ready`（成功）或 `failed`；导出场景另有 `exporting` / `exportfailed` - 量化是单独流程：先 `available-quantizations <id>` 查可用模式，并查看 `supported_inference_types_by_quantization` 预判每种量化方式支持的部署/付费形态；再 `quantize <id> --quantization <mode>` 提交量化任务，结果是一个**独立的新 cm-xxxxx**。源模型、量化结果模型、最终部署出来的 endpoint 是三类不同资源，不能混用 ID - 自定义模型 ID（`cm-xxxxx`）**不是** `<name>-<primary_version>` 形式，**不能直接作为 `+chat` / `+gen` 的 `--model`**；必须先通过 `arkcli +deploy` 获得 endpoint，拿 `ep-xxx` 才能调用推理。若该自定义模型已有 Running Endpoint，`+deploy` 会直接复用已有 endpoint ## 快速决策 - 用户问"我的自定义模型"：读 [`references/arkcli-custommodel-list.md`](references/arkcli-custommodel-list.md)，用 `arkcli models custommodel list --mine` - 用户要按名称 / ID / base 模型 display name 模糊查找：读 [`references/arkcli-custommodel-list.md`](references/arkcli-custommodel-list.md)，用 `list --search <kw>` - 用户已有 `cm-xxxxx` 并要状态 / 详情 / endpoint 引用 / artifact types：读 [`references/arkcli-custommodel-get.md`](references/arkcli-custommodel-get.md)，用 `get` - 用户要从 TOS 导入权重：读 [`references/arkcli-custommodel-upload.md`](references/arkcli-custommodel-upload.md)。用户已有 `tos://...` 时确认 TOS URI、base model 和名称；用户还没有 TOS URI 时先引导开通/上传 TOS，不要直接跑 `upload` - 用户要改名 / 改描述：读 [`references/arkcli-custommodel-update.md`](references/arkcli-custommodel-update.md)，确认意图后用 `update` - 用户要删除：读 [`references/arkcli-custommodel-delete.md`](references/arkcli-custommodel-delete.md)，先查 `active_endpoints`，确认后再执行 - 用户要量化：先读 [`references/arkcli-custommodel-available-quantizations.md`](references/arkcli-custommodel-available-quantizations.md)，再读 [`references/arkcli-custommodel-quantize.md`](references/arkcli-custommodel-quantize.md) ## 列表参数与输出契约 - `custommodel list --sort-order` 只接受小写 `asc` / `desc`。收到其他值时应把它视为本地参数错误，不要尝试调用接口或改成其他大小写后盲目重试。 - 使用 `--format table` 或 `--format csv` 时，每个 `result.items[]` 模型是一行；不要把分页响应根对象或 `result` map 当成模型记录。需要保留完整分页元数据时使用 JSON/YAML。 ## 部署前的自定义模型目标澄清 仅当用户的最终目标是“把我的自定义模型部署成 Endpoint”、但没有给出唯一 `cm-*` 时执行本节；用户已明确给出 `cm-*` 时跳过。 1. 先执行同范围只读查询：`arkcli models custommodel list --mine --statuses ready --page-all --page-delay 500 --format json`。保留退出码与 stderr，不能把认证、权限或网络失败当作空清单；认证/权限错误按 shared 处理，不扫描凭证或自动切身份。 2. 候选只能来自本轮完整结构化结果。输出被宿主截断时，先读取工具保存的完整文件；确实没有完整捕获时，允许把同一只读查询的 stdout 重新落盘，stderr 单独保留，再用 `jq` / `sed` 检查 `result.items` 与分页信息。该同范围补查一轮最多执行一次，不循环重试。`jq` 空结果或字段缺失时先核对当前 reference 与原始 JSON，不盲猜字段、不凭记忆补 `cm-*`。分页未取全、补查仍失败或关键字段仍缺失时，说明具体边界并停止；拿全候选前不出选择题，更不执行部署。 3. 按 0 / 1 / N 收敛： - 0 个：停止，提示用户先 upload、量化或完成精调产物导出。 - 1 个：复述该模型的 `id / name / foundation_model / create_time`，将它作为唯一目标转交 `arkcli-deploy`。 - N 个：使用宿主提供的结构化选择能力，把每个候选的 `id / name / foundation_model / create_time` 直接列给用户选择；不要在通用 Skill 中写死某个宿主的工具名，也不要额外写死 `Other` 选项。 4. 唯一目标确定前，不执行 `arkcli +deploy`、`arkcli infer endpoint create` 或 Raw API。目标选择完成后转 `arkcli-deploy`，并继续遵守其写操作确认；选择模型本身不等于授权部署。 ## Agent 快速执行顺序 1. 不确定认证状态时，先 `arkcli auth status` 2. "我的自定义模型"语义：直接 `custommodel list --mine`，**不要套 shared 的 Tags 默认过滤**（custommodel 服务端原生支持 `--mine`） 3. 上传前必填三项：`--name` / `--base-model <foundation-model-id>` / `--tos tos://<bucket>/<prefix>`；缺任一会被服务端拒 4. `upload` / `quantize` 是异步任务：返回后用 `custommodel get <id>` 轮询 status，**不要原地循环 upload/quantize** 5. `quantize` 前必跑 `available-quantizations <id>`：不同 base model 支持的量化模式不同，盲传服务端会拒；若用户关心 token / 模型单元等部署形态，优先看返回里的 `supported_inference_types_by_quantization` 6. `quantize --dry-run` 只输出本地 `preview.v1`，不会调用 `CreateQuantizedCustomModel`；`steps[].payload` 只描述真实请求字段，不应出现后端 `DryRun`。它不是服务端校验，核对后仍需确认再执行真实量化 7. `delete` / `update` / `quantize` 是写操作，执行前向用户复述影响范围 8. `delete` 默认会走 [Y/N] 二次确认；`--yes` 表示跳过本地二确，`--dry-run` 表示只预览不删除。只有用户已经明确确认删除目标和影响范围后，agent 才能把 `--yes` 加到命令里 9. `get --transform` 是 `custommodel get` 自己的字段白名单，不是全局 GJSON 表达式；要查嵌套路径时不要把它当作全局 `--transform` ## 典型业务链路 ### 1. 从 TOS 上传新自定义模型 ``` auth status → custommodel upload --name X --base-model <fm-id> --tos tos://b/p → custommodel get <id> （轮询直到 status=ready） → custommodel get <id> --transform 'artifact_types' （看产物形态） ``` ### 2. 量化已就绪的自定义模型 ``` custommodel get <id> （确认 status=ready） → custommodel available-quantizations <id> （看支持哪些 mode） → custommodel quantize <id> --quantization <mode> --dry-run → 用户确认量化目标和影响范围 → custommodel quantize <id> --quantization <mode> → custommodel get <new-id> （量化结果是新 cm-xxxxx，再次轮询） ``` ### 3. 准备给 `+deploy` 当目标 ``` custommodel list --mine --statuses ready --page-all --page-delay 500 --format json → 按 0 / 1 / N 澄清唯一 cm-xxxxx → +deploy --model cm-xxxxx ... （若已有 Running Endpoint 会复用；详见 ../arkcli-deploy/SKILL.md） ``` ### 4. 清理不再使用的自定义模型 ``` custommodel get <id> --transform 'active_endpoints' （确认无 endpoint 引用） → custommodel delete <id> --dry-run → custommodel delete <id> （交互二确）或 custommodel delete <id> --yes ``` ## 反模式（agent 必读） - 不要用 `arkcli models search` / `list` 找自定义模型 —— 那两条只走 FoundationModel 目录，自传模型一律不在里面。要找自传模型用 `custommodel list --search <kw>` 或 `--mine` - 不要在 `upload` 之后立刻 `quantize` —— upload 是异步任务，status 经历 `preparation → processing → ready`；先 `custommodel get <id>` 确认 ready，再走 `available-quantizations` → `quantize` - 不要给 `quantize` 传一个 `available-quantizations` 没列的 mode —— 不同 base model 支持的量化集合不同，盲传必失败。先 `available-quantizations <id>`，从返回里挑 - 不要把 `cm-xxxxx` 直接传给 `+chat` / `+gen` 的 `--model` —— 自定义模型必须先通过 `+deploy` 获得 endpoint（`ep-xxx`）才能推理调用；`+deploy` 可能复用已有 Running Endpoint - 不要在多个 ready 自定义模型中自行挑一个部署 —— 先按“部署前的自定义模型目标澄清”让用户从本轮实时结果中选择 - 不要为了自动化主动补 `--yes` —— 没 `--yes` 时 CLI 会走 [Y/N] 二确；只有用户已经确认删除 `cm-xxxxx` 且知道 endpoint 引用风险时才带 - 不要在 "我的" 语义下走 shared 的 Tags 客户端过滤 —— `custommodel list --mine` 是服务端原生过滤，更准也更省请求 - 不要密集刷 `get` 来轮询 status —— 推荐间隔 ≥ 10s，否则会被限流 ## 命令一览 | 命令 | 说明 | |------|------| | `arkcli models custommodel list` | 翻页 + 多维过滤 | | `arkcli models custommodel get <id>` | 详情 / 轮询 status | | `arkcli models custommodel upload` | 从 TOS 导入（异步） | | `arkcli models custommodel update <id>` | 改名 / 改描述 | | `arkcli models custommodel delete <id> [--yes] [--dry-run]` | 删除（破坏性，不可逆）；默认二确，`--yes` 跳过，`--dry-run` 预览 | | `arkcli models custommodel available-quantizations <id>` | 查可用量化模式（quantize 前必跑） | | `arkcli models custommodel quantize <id> --quantization <mode> [--dry-run]` | 量化（异步）；`--dry-run` 仅本地预览，不调用后端 | ## 常见降级 - 认证失败：转 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md) - profile / region 看起来不对：转 [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md) - 找的是基础模型不是自定义模型：转 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) - 拿到自定义模型后要部署：转 [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md) - 产品命令未覆盖（例如想直接触发 customization job）：转 [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md) ## 参考 - [`references/arkcli-custommodel-list.md`](references/arkcli-custommodel-list.md) - [`references/arkcli-custommodel-get.md`](references/arkcli-custommodel-get.md) - [`references/arkcli-custommodel-upload.md`](references/arkcli-custommodel-upload.md) - [`references/arkcli-custommodel-update.md`](references/arkcli-custommodel-update.md) - [`references/arkcli-custommodel-delete.md`](references/arkcli-custommodel-delete.md) - [`references/arkcli-custommodel-available-quantizations.md`](references/arkcli-custommodel-available-quantizations.md) - [`references/arkcli-custommodel-quantize.md`](references/arkcli-custommodel-quantize.md) - [`references/evals.md`](references/evals.md) - [arkcli-models](../arkcli-models/SKILL.md) — 基础模型查询（与本 skill 是两套资源） - [arkcli-deploy](../arkcli-deploy/SKILL.md) — 拿到 ready 的自定义模型后部署成 endpoint - [arkcli-shared](../arkcli-shared/SKILL.md) — 认证、全局 flag、安全规则