# 模型与套餐

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

模型与套餐：公共基础模型查询与激活、套餐购买与席位管理、单价查询，以及 IAM 辅助与平台文档检索。

- `models` 只负责公共基础模型（doubao 等）；账号下的自定义模型（`cm-*`）走 `models custommodel`；
- `plans` 管 Agent Plan / Coding Plan（个人版 + 企业版，含席位分配与 API Key 轮换）；`pricing` 出折后单价与套餐订阅价；
- `iam` 查询身份标识与项目列表，主要供诊断与首登 project 选择使用；
- `docs` 在终端内检索方舟文档、API 契约与平台公告。

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

火山方舟平台文档检索与阅读：搜索（`search`）、列表（`list`）、按 URL 获取正文（`get`）、API 文档枚举与 OpenAPI spec 拉取（`apis list/spec`）。

- 适合在终端内直接查模型接入文档、API 契约与平台公告，不用切到浏览器。

<span id="docs-apis-list-command"></span>
### docs apis list

列出已发布的方舟 API

```Bash
arkcli docs apis list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--api-mcp-url` | string | 仅用于 apis list/spec 的 MCP 地址；也可配置 ARK_DOCS_API_MCP_URL，不改变 search/list/get 后端 |

<span id="docs-apis-spec-command"></span>
### docs apis spec

按单一选择器读取一条已发布的方舟 OpenAPI 契约

```Bash
arkcli docs apis spec
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--api-mcp-url` | string | 仅用于 apis list/spec 的 MCP 地址；也可配置 ARK_DOCS_API_MCP_URL，不改变 search/list/get 后端 |
| `--id` | string | 按目录中的唯一 id 过滤，例如 chat-ChatCompletions_create；与 --service / --api-path 互斥；公开目录推荐优先用它 |
| `--service` | string | 按目录中的文件名分组过滤，例如 chat 或 endpoints；不是粗粒度服务标签。多数分组不唯一，命中多条时请改用 --id 或 --api-path。与 --id / --api-path 互斥 |
| `--api-path` | string | 按目录中的真实路径过滤，例如 /api/v3/chat/completions 或 /?Action=ListEndpoints&Version=2024-01-01；与 --id / --service 互斥 |

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

读取方舟文档正文

```Bash
arkcli docs get <url>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--outline` | bool | 只返回该文档已发布的标题大纲（id/level/title），不返回正文；用返回的 id 再配合 --section 精确取章节 |
| `--section` | string | 仅读取指定章节（含子章节）：精确标题或 #锚点ID；仅支持公共文档后端 |
| `--compact` | bool | 正文只输出一份，保留引用和续读信息；不输出 chunks 和 raw_text |
| `--snapshot` | string | 复用 get/list 返回的 snapshot，固定分页与续读版本 |
| `--chunk-start` | int | 从第几个正文块开始读取（默认 0） |
| `--chunk-count` | int | 返回正文块数量（默认 5）；取值范围 1-50 |

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

浏览方舟文档目录

```Bash
arkcli docs list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--query` | string | 在已发布目录里按标题、描述、面包屑或路径本地过滤；搜索不可用时用它代替换词重试 |
| `--snapshot` | string | 复用 get/list 返回的 snapshot，固定分页与续读版本 |
| `--limit` | int | 每页文档数量（默认 10）；取值范围 1-100 |
| `--offset` | int | 目录起始位置（默认 0）；公共文档翻页需携带 snapshot |

<span id="docs-search-command"></span>
### docs search

搜索方舟文档

```Bash
arkcli docs search <query>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--top-k` | int | 返回结果数量（默认 5）；取值范围 1-50 |
| `--snapshot` | string | 复用 search 返回的 snapshot，固定候选集与排序后再翻页（有效期约 5 分钟） |
| `--offset` | int | 搜索结果起始位置（默认 0）；大于 0 时必须携带 --snapshot |

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

身份与访问管理辅助命令：查询当前身份标识（`userid`）、项目列表等 IAM 信息。

- 主要供诊断与首登 project 选择使用；日常业务命令的 project 归属由 profile 切面自动处理，不需要手工指定。

<span id="iam-userid-command"></span>
### iam userid

按用户名前缀解析 IAM UserID（省略 --username 时返回当前身份的 UserID）

```Bash
arkcli iam userid
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--username` | string | 逗号分隔的待查用户名前缀（例如 ivan,bob）；省略则返回当前身份的 UserID |

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

火山公共基础模型（如 doubao 系列）查询与激活：列表、搜索、详情，以及显式要求的开通/激活计费项（`activate`）。

- 只负责**公共基础模型**；账号下的自定义模型（cm-*）走 `models custommodel` 子域；
- 激活 ≠ 部署：`activate` 只是开通计费项，创建可调用的 Endpoint 请走 `+deploy` 或 `infer` 域；
- 性能敏感选型可参考 TTFT/TPOT 排名与输入长度对比。

<span id="models-activate-command"></span>
### models activate

开通基础模型计费项——封装 OpenModelChargeItem

```Bash
arkcli models activate <foundation-model-name>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--sub-services` | string_slice | 要开通的子服务: base \| context-cache \| fast-infer（逗号分隔；默认仅开通 base） |
| `--yes` | bool | 跳过 [Y/N] 确认提示（非交互） |

<span id="models-custommodel-available-quantizations-command"></span>
### models custommodel available-quantizations

列出某个自定义模型可用的量化模式

```Bash
arkcli models custommodel available-quantizations <id>
```

<span id="models-custommodel-delete-command"></span>
### models custommodel delete

从模型仓库中删除自定义模型（不可逆；需确认，或用 --yes 跳过）

```Bash
arkcli models custommodel delete <id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 确认删除 |

<span id="models-custommodel-get-command"></span>
### models custommodel get

查看自定义模型详情（底座模型、量化、状态、生效中的接入点）

```Bash
arkcli models custommodel get <id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--transform` | string_slice | 要包含的字段：id,name,active_endpoints,artifact_types |

<span id="models-custommodel-list-command"></span>
### models custommodel list

列出账号模型仓库中的自定义模型，支持按底座模型、训练类型、状态与来源过滤

```Bash
arkcli models custommodel list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--search` | string | 按名称、id 或基础模型展示名模糊搜索自定义模型 |
| `--page` | string | 分页参数，格式 <number,size>，例如 1,10 |
| `--base-models` | string_slice | 按基础模型名称过滤，逗号分隔或重复传入 |
| `--base-model-ids` | string_slice | 按基础模型 ID 过滤，逗号分隔或重复传入 |
| `--customization-types` | string_slice | 按训练类型过滤：lora,sft,dpolora,dpo,grpolora,grpo,ppo,opdlora,opd,pretrain |
| `--supported-customization-types` | string_slice | 按支持这些训练类型的基础模型过滤 |
| `--source-jobs` | string_slice | 按模型定制任务 id 过滤 |
| `--statuses` | string_slice | 按状态过滤：preparation,processing,ready,failed,exporting,exportfailed |
| `--sources` | string_slice | 按来源过滤：import,customization |
| `--mine` | bool | 只包含当前 SSO 子用户创建的自定义模型 |
| `--sort-by` | string | 排序字段，默认 CreateTime |
| `--sort-order` | string | 排序方向：asc \| desc（默认：desc） |

<span id="models-custommodel-quantize-command"></span>
### models custommodel quantize

按指定量化模式为自定义模型创建量化变体

```Bash
arkcli models custommodel quantize <id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--quantization` | string（必填） | 量化模式 |
| `--description` | string | 量化后自定义模型的描述，最长 300 字符 |

<span id="models-custommodel-update-command"></span>
### models custommodel update

重命名自定义模型或更新其描述

```Bash
arkcli models custommodel update <id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string | 新的自定义模型名称 |
| `--description` | string | 新描述，最长 300 字符 |

<span id="models-custommodel-upload-command"></span>
### models custommodel upload

从 veTOS 产物导入自定义模型到模型仓库（需要底座模型、量化模式与名称）

```Bash
arkcli models custommodel upload
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--tos` | string（必填） | veTOS URI：tos://<bucket>/<prefix> |
| `--base-model` | string（必填） | 底座模型 ID，例如 doubao-xxx-260515 |
| `--name` | string（必填） | 自定义模型名称 |
| `--quantization` | string（必填） | 量化模式 |
| `--description` | string | 描述，最长 300 字符 |

<span id="models-finetune-config-command"></span>
### models finetune-config

获取某个模型版本权威的精调超参数 schema。按训练类型返回 Parameters[]，每项含 Name/DefaultValue/Min/Max/Description。请在 `train finetune create` 之前用它确认正确的字段名（GRPO 用 lr+num_steps，SFT 用 learning_rate+epoch 等）。

```Bash
arkcli models finetune-config <model-name> [version]
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 基础模型名称，如 doubao-seed-1-6（也可作为第一个位置参数传入） |
| `--version` | string | 模型版本，如 250615（也可作为第二个位置参数传入）。留空 = 取 API 返回的第一个版本 |
| `--type` | string | 只查一种定制类型：sft \| lora \| dpo \| dpo-lora \| grpo \| grpo-lora \| ppo \| opd \| opd-lora \| pt。留空 = 所有有数据的类型 |

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

获取可见模型详情、价格与限流信息

```Bash
arkcli models get <id> [version]
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--id` | string | 模型标识，例如 doubao-seed-2-0-pro-260215（也可用位置参数传入） |
| `--version` | string | 可选的模型版本覆盖，如 260215（也可用位置参数传入） |
| `--no-cache` | bool | 绕过本地 CardView 与 ArkModels 元数据缓存 |

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

列出基础模型（支持过滤与分页）

```Bash
arkcli models list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--modality` | string | 按模态过滤：text \| image \| video \| audio \| embed |
| `--name` | string | 按模型名称过滤（不区分大小写的子串匹配；更丰富的过滤请用 `models search`） |
| `--page-number` | int | 页码（>=1） |
| `--page-size` | int | 每页条数 |
| `--sort-by` | string | 排序字段：CreateTime \| UpdateTime \| Name（也接受 create_time / update_time / name） |
| `--sort-order` | string | 排序方向：Asc \| Desc（也接受 asc / desc） |
| `--no-cache` | bool | 绕过本地 CardView 缓存，实时拉取可见模型 |

<span id="models-performance-input-length-command"></span>
### models performance input-length

比较指定模型在不同输入长度下的 TTFT 或 TPOT

```Bash
arkcli models performance input-length
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--metric` | string | 性能指标：ttft、tpot 或 all |
| `--thinking` | bool | 包含思考与思考摘要生成耗时（默认 false） |
| `--time-window` | string | 统计窗口：1h、6h、24h、3d、7d 或 30d |
| `--model` | string_slice | 必填精确模型选择器 name@version:deployment；可重复 |
| `--input-lengths` | string_slice | 输入长度桶：1k、10k、50k、100k；可重复或逗号分隔 |

<span id="models-performance-rank-command"></span>
### models performance rank

按 TTFT 或 TPOT 对基础模型进行性能排名

```Bash
arkcli models performance rank
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--metric` | string | 性能指标：ttft、tpot 或 all |
| `--thinking` | bool | 包含思考与思考摘要生成耗时（默认 false） |
| `--time-window` | string | 统计窗口：1h、6h、24h、3d、7d 或 30d |
| `--input-length` | string | 输入长度桶：1k、10k、50k 或 100k |
| `--keyword` | string | 按模型名或展示名筛选 |
| `--deployment` | string_slice | 部署方式：default 或 fast；可重复或逗号分隔 |
| `--top` | int | 每个指标返回的模型数量（1-50）（默认 10） |
| `--order` | string | 排序方向：asc 或 desc |
| `--compare` | string | 对比方式：default-deployment 或 none |

<span id="models-performance-trend-command"></span>
### models performance trend

查看指定模型的 TTFT 或 TPOT 延迟趋势

```Bash
arkcli models performance trend
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--metric` | string | 性能指标：ttft、tpot 或 all |
| `--thinking` | bool | 包含思考与思考摘要生成耗时（默认 false） |
| `--time-window` | string | 统计窗口：1h、6h、24h、3d、7d 或 30d |
| `--input-length` | string | 输入长度桶：1k、10k、50k 或 100k |
| `--model` | string_slice | 必填精确模型选择器 name@version:deployment；可重复 |
| `--max-points` | int | 向服务端请求的最大数据点数（默认 12） |

<span id="models-search-command"></span>
### models search

按关键词 + 结构化条件检索模型（模态、上下文长度、能力）

```Bash
arkcli models search [keyword]
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--keyword` | string | 检索关键词（也可用位置参数传入） |
| `--size` | int | 最多返回的结果数；0 = 不截断（默认） |
| `--modality` | string | 粗粒度模态过滤：text\|image\|video\|audio（output-modality 的别名） |
| `--input-modality` | string | 按输入模态过滤（逗号分隔，例如 text,image,video） |
| `--output-modality` | string | 按输出模态过滤（逗号分隔） |
| `--multimodal` | bool | 仅返回支持多种输入模态的模型 |
| `--min-context-window` | int | context_window 下限（Token，例如 200000） |
| `--max-context-window` | int | context_window 上限（Token） |
| `--min-input-tokens` | int | max_input_tokens 下限 |
| `--min-output-tokens` | int | max_completion_tokens 下限 |
| `--capability` | string_slice | 要求具备的能力（重复传入为 AND 关系）：thinking\|mcp\|functioncall\|web_browsing\|knowledge_base\|response_format\|reasoning_effort；caching 已废弃，请改用 --cache-type explicit_cache |
| `--cache-type` | string_slice | 要求命中的缓存类别（重复传入为 AND 关系）：explicit_cache\|implicit_cache\|session_cache\|prefix_cache |
| `--strict-filter` | bool | 丢弃缺少补充数据的模型，而不是保留（默认：保留） |
| `--include-deprecated` | bool | Include shutdown/已下线 (lifecycle_status=Shutdown 或 display_name 含'废弃/下线') 模型，默认过滤 |
| `--refresh-cache` | bool | 搜索前强制同步刷新 ArkModels 元数据缓存 |

<span id="models-versions-command"></span>
### models versions

列出基础模型对用户可见的版本及各版本 ActiveConfigurationId（作为 `models finetune-config` 的输入）

```Bash
arkcli models versions <model-name>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 基础模型名称，如 doubao-seed-1-6（也可用位置参数传入） |

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

ARK 套餐（Agent Plan / Coding Plan，个人版 + 企业版）管理：查询持有、购买、续费、模型清单、API Key 轮换；企业版含完整席位管理（seat-list / seat-assign / rotate-apikey）。

- 购买参数会逐步澄清，避免误购；`payment_failed` 提供 Order ID 后回到已有订单补单/取消，不会重新下单；
- 注意与 platform profile 区分：Token 额度包/资源包仍走 platform profile + `/api/v3`，不因“套餐”字样误入本域。

<span id="plans-buy-command"></span>
### plans buy

购买 Agent Plan / Coding Plan 套餐（个人版 + 企业版），默认开启自动续费

```Bash
arkcli plans buy
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string（必填） | 套餐名称：agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team |
| `--type` | string（必填） | 档位：small / medium / large / max（agent-plan*）\| lite / pro（coding-plan*） |
| `--duration` | int | 订阅时长（月，1-12，默认 1） |
| `--quantity` | int | 席位数量（*-team 套餐必填） |
| `--estimate` | bool | 只做在线价格试算，不下单 |
| `--yes` | bool | 确认协议并真正下单；不带该参数时只返回协议 URL 供用户查看 |

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

查看当前账号持有的 Agent Plan / Coding Plan 套餐（个人版 + 企业版）——名称与档位状态

```Bash
arkcli plans get
```

<span id="plans-harness-status-command"></span>
### plans harness-status

查看本机各 AI Agent（claude-code / codex / opencode / openclaw / trae）上内置 Agent Plan MCP 的安装状态

```Bash
arkcli plans harness-status [agent]
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--scope` | string | (仅 Trae)读取范围:global(默认)\| project(当前目录 ./.trae/mcp.json) |
| `--codex-config-scope` | string | (仅 Codex)读取范围:profile(默认,~/.codex/arkcli.config.toml)\|global(~/.codex/config.toml) |
| `--codex-profile` | string | (仅 Codex profile 模式)Codex profile 名,默认 arkcli |

<span id="plans-model-apply-command"></span>
### plans model-apply

设置套餐 ark-code-latest 的路由目标（auto 或指定某个影子模型）

```Bash
arkcli plans model-apply
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string | 套餐名称：agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team（默认：agent-plan-team） |
| `--model` | string | 路由目标：模型 id、输出名或 "auto"；非交互模式必填 |

<span id="plans-model-list-command"></span>
### plans model-list

列出某套餐支持的模型，以及当前 ark-latest-model（默认 agent-plan-team）

```Bash
arkcli plans model-list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string | 套餐名称：agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team（默认：agent-plan-team） |

<span id="plans-personal-rotate-apikey-command"></span>
### plans personal rotate-apikey

轮换（重新生成）Agent Plan 个人版 API Key——旧 Key 立即失效

```Bash
arkcli plans personal rotate-apikey
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过 [Y/N] 确认提示（非交互） |

<span id="plans-renew-command"></span>
### plans renew

续费已有的 Agent Plan / Coding Plan 套餐（个人版 + 企业版），默认开启自动续费

```Bash
arkcli plans renew
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string（必填） | 套餐名称：agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team |
| `--duration` | int | 续费时长（月，1-12，默认 1） |
| `--seat-ids` | string | 逗号分隔的待续费席位 ID（*-team 套餐必填，例如 seat-001,seat-002） |
| `--estimate` | bool | 只做在线续费价格试算，不下单 |
| `--yes` | bool | 确认协议并真正续费下单；不带该参数时只返回协议 URL 供用户查看 |

<span id="plans-team-rotate-apikey-command"></span>
### plans team rotate-apikey

轮换（重新生成）Agent Plan / Coding Plan 企业版席位 API Key——旧 Key 立即失效

```Bash
arkcli plans team rotate-apikey
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--seat-ids` | string | 管理员批量轮换用逗号分隔的席位 ID；省略则轮换自己的 agent-plan-team 席位 |
| `--yes` | bool | 跳过 [Y/N] 确认提示（非交互） |

<span id="plans-team-seat-assign-command"></span>
### plans team seat-assign

把企业版套餐席位分配（绑定）给子用户；重复传 --bind 可批量分配

```Bash
arkcli plans team seat-assign
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string（必填） | 套餐名称：agent-plan-team \| coding-plan-team |
| `--bind` | string_slice（必填） | 席位与用户的绑定关系（可重复）。格式：--bind seat-001=user-123，或 --bind seat-001=user-123:user-name（跳过 IAM 查询） |
| `--project-name` | string | 项目名称（默认：default） |

<span id="plans-team-seat-list-command"></span>
### plans team seat-list

按条件列出企业版套餐席位（Agent Plan Team / Coding Plan Team）

```Bash
arkcli plans team seat-list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string（必填） | 套餐名称：agent-plan-team \| coding-plan-team |
| `--type` | string | 档位过滤：small/medium/large/max（agent-plan-team）\| lite/pro（coding-plan-team） |
| `--seat-ids` | string | 逗号分隔的席位 ID（最多 1000 个），例如 seat-001,seat-002 |
| `--user-name` | string | 按绑定的子用户名称过滤 |
| `--seat-status` | int | 席位绑定状态：1=Idle，2=Active |
| `--billing-status` | int | 计费状态：1=待生效，2=生效中，3=已过期，4=已回收 |
| `--project-name` | string | 项目名称（默认：default） |
| `--page-number` | int | 页码（>=1） |
| `--page-size` | int | 每页条数 |

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

查询基础模型结算单价（含当前账号折扣）与 AgentPlan/CodingPlan 套餐订阅价格。

- `Price` 是后端按账号合同/活动/套餐折后的最终单价，`OriginalPrice` 是公示原价；
- 适用场景：模型选型前的成本估算、套餐价值评估、不同模态价格对比。

<span id="pricing-models-command"></span>
### pricing models

列出基础模型计费价目（Price 为当前账号折后的实际单价）

```Bash
arkcli pricing models
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 只查单个基础模型名称（如 doubao-seed-1-6）或自定义模型 id（cm-*）；cm-* 会自动解析到其基础模型，响应中带 resolved_custom_model 字段 |
| `--modality` | string | 按 FoundationModelDomain 过滤（后端枚举）：LLM \| ComputerVision \| Audio \| Embedding \| Router |
| `--region` | string | 价格地域（如 cn-beijing）；默认取当前 profile 的地域 |
| `--page-number` | int | 页码（从 1 开始，默认 1） |
| `--page-size` | int | 每页条数（默认 50） |

<span id="pricing-plans-command"></span>
### pricing plans

列出 AgentPlan 与 CodingPlan 的订阅价格（个人版与企业版）

```Bash
arkcli pricing plans
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string | 只查单个套餐 id，例如 agent-plan-personal-small |
| `--product` | string | 按产品过滤：agent-plan \| coding-plan |
| `--edition` | string | 按版本过滤：personal \| enterprise |