跳到主要内容
训练指南章节 全部文档

训练 CLI：命令与选项

项目命令行的完整说明，涵盖初始化、恢复、评估、导出和退出码。

训练指南章节

所有语言版本中的命令和代码均保持英文。请将大写占位符替换为您账户和付费作业中的实际值；请勿将真实密钥粘贴到共享笔记本或日志中。

命令行工作流

每条命令都有明确副作用和实际结果。
  1. init / doctor 创建并检查项目
  2. plan 审核设置，不进行训练
  3. run 在预算内训练
  4. evaluate 检查留出标准
  5. export 验证并打包

按明确的命令顺序操作

fpai-training 是 SDK 0.2.0 提供的命令行工具。以下流程与 Python 接口使用相同的项目引擎：初始化、检查兼容性、审核 dry-run 计划、执行、评估和导出。读取状态或计划并不能证明训练成功。

  • 身份验证信息从 FUSIONPOINTAI_API_KEY 读取；命令行没有 API key 参数。
  • 可对可执行程序或具体命令使用 --help。--version 会报告已安装的软件包版本。
  • 审核通过的计划会固定解析后的设置。不支持未文档化的 CLI 超参数覆盖。
CLI 命令完整参考
字段或接口类型或结果默认值或退出码行为与验证规则
init --directory PATH command 必填 / 无默认值 创建新的项目骨架和示例配置；若目录已存在且非空，则拒绝操作。不训练，也不发起付费请求。
doctor --config PATH command 必填 / 无默认值 检查规范、本地模型文件、依赖项、存储、设备和适配器兼容性。不更新权重，也不生成教师内容。
plan --config PATH --dry-run command 必填 / 无默认值 解析默认值、固定指纹并显示主题、共享策略、预算和输出。不做优化，也不执行付费教师操作。
run --config PATH command 必填 / 无默认值 要求计划有效且已审核，并具有有效权益；锁定一个运行并在预算内执行真实训练。
status --run PATH command 必填 / 无默认值 读取经过脱敏的本地运行快照。不会重启 worker 或生成教师请求。
pause --run PATH command 必填 / 无默认值 请求安全暂停并等待完整的原子检查点。仅适用于正在运行且由本次运行拥有的任务。
resume --run PATH command 必填 / 无默认值 只有在严格验证检查点和计划后，才能恢复已暂停或中断且可恢复的运行。
cancel --run PATH command 必填 / 无默认值 停止本次运行拥有的 worker、释放其资源并记录取消状态；保留有效输出和诊断信息。
evaluate --run PATH --split test command 必填 / 无默认值 使用验证集或测试集评估固定版本的模型。不做优化，也不共享隐藏数据。
export --run PATH --format safetensors command 必填 / 无默认值 验证并打包已验收且受支持的输出；不上传到外部，也不部署到线上。
示例 · bash 
fpai-training --version
fpai-training --help
fpai-training init --directory ./german-project
# Replace training.json and rubric/data files with your reviewed configuration.
fpai-training doctor --config ./german-project/training.json
fpai-training plan --config ./german-project/training.json --dry-run
# Inspect resolved values, data sharing and budgets BEFORE the next command.
fpai-training run --config ./german-project/training.json
fpai-training status --run ./german-project/runs/german-001
fpai-training evaluate --run ./german-project/runs/german-001 --split test
fpai-training export --run ./german-project/runs/german-001 --format safetensors
# Supply the key through FUSIONPOINTAI_API_KEY, never a command-line argument.

安全地暂停、恢复或取消

控制命令针对一个由本次运行拥有的目录。暂停操作会等待原子化检查点写入完成并收到 worker 确认。恢复操作会验证相同的模型、数据、配置、评估器和分布式拓扑。取消操作只会停止该运行的 worker，并记录终止状态。重复发送控制请求不得启动额外的训练进程。

  • 暂停的运行可以恢复，但并未完成。取消的运行不能作为已验收的交付成果。
  • 前台运行期间，请在另一个终端执行控制命令。
  • 超时后先读取状态再重试。不要删除锁文件，也不要终止无关的 GPU 作业。
命令选项
字段或接口类型或结果默认值或退出码行为与验证规则
--directory path 必填 / 无默认值 init 必填。必须是可写的新项目目录。
--config path 必填 / 无默认值 doctor、plan 和 run 必填。完整规范 1.0 文件的路径。
--run path 必填 / 无默认值 status、pause、resume、cancel、evaluate 和 export 必填。由本次运行拥有的目录，不是账户或会话 ID。
--dry-run flag true 明确的 plan 命令标志；计划始终不会更改权重或执行付费操作。不存在 false/off 执行模式。
--split enum "test" 仅用于 evaluate：validation 或 test。测试数据绝不用于改进。
--format enum "safetensors" 仅用于 export：safetensors 或 adapters，具体取决于适配器能力。
--help flag false 显示可执行程序或命令的帮助信息，不访问服务商。
--version flag false 显示实际安装版本的元数据，而不是配置规范版本。
示例 · bash 
# Run controls from a separate terminal if training is active.
fpai-training pause --run ./german-project/runs/german-001
# Wait for status=paused and a completed atomic checkpoint before stopping a host.
fpai-training status --run ./german-project/runs/german-001
fpai-training resume --run ./german-project/runs/german-001
# Cancellation is terminal; preserve existing artifacts, do not pretend it passed.
fpai-training cancel --run ./german-project/runs/german-001
# Repeat status, not run(), after a timeout. Never kill an unrelated process.

结合状态与退出码判断结果

退出码为零表示请求的操作成功；成功读取状态、暂停或执行 dry run，都不等于训练已通过验收。训练结果还必须处于完成状态、具有获认可的停止原因，并通过所有必需评估标准。失败的目标应继续如实显示在报告中，不得重新标记为成功。

  • 命令会将机器可读的 JSON 写入 stdout，将已脱敏的诊断信息写入 stderr。两个输出流都不会包含秘密。
  • run 和 resume 会等待进入终止或暂停状态；status 会返回当前快照。
  • 收到 SIGINT 后，程序会尽力清理本次运行拥有的 worker，然后以退出码 130 结束。中断的进程不能伪造已完成的检查点。
示例 · text 
SDK 0.2.0 EXIT AND STATE CONTRACT
0   accepted, successful read/control, or successful dry-run; inspect operation.
2   invalid configuration; no training started.
3   incompatible model/runtime/method/export combination.
4   authentication, entitlement or authorized-sharing failure.
5   resource budget exhausted; preserve latest valid checkpoint and report.
6   evaluation requirements not met; not an accepted model.
7   execution, checkpoint, cancellation-control or export failure.
130 interrupted by the caller.

Lifecycle:
planned -> preparing -> training -> evaluating -> completed
training -> pausing -> paused -> training (validated resume)
active -> cancelling -> cancelled
active -> failed

stop_reason: accepted | budget_exhausted | no_progress | regression |
             cancelled | failed
paused is a recoverable state, not an accepted training result.
completed requires stop_reason=accepted and all required criteria passing.
Repeated control requests must read/reuse the owned transition, not spawn workers.
One run lock prevents duplicate execution of the same run directory.