メインコンテンツへスキップ
学習ガイドの章 すべてのドキュメント

学習 CLI：コマンドとオプション

プロジェクトの初期化から復旧、評価、エクスポートまでを扱う SDK 0.2.0 の 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 必須 / 既定値なし レビュー済みの有効な計画と有効な利用資格が必要です。1つの実行をロックし、予算内で実際に学習します。
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.

安全に一時停止、再開、キャンセルする

制御コマンドは、実行が所有する1つのディレクトリを対象にします。一時停止は、アトミックなチェックポイントの保存と worker の確認を待ちます。再開では、モデル、データ、設定、評価器、分散トポロジーが同一であることを検証します。キャンセルはその実行の worker だけを停止し、終了状態として記録します。制御要求を繰り返しても、別の学習プロセスを起動してはなりません。

  • 一時停止中の実行は復旧可能ですが、完了ではありません。キャンセルされた実行は、受け入れ済みの成果物ではありません。
  • フォアグラウンドで実行中に制御する場合は、別のターミナルを使ってください。
  • タイムアウト後は再試行する前に状態を読み取ります。ロックファイルを削除したり、無関係な GPU ジョブを終了したりしないでください。
コマンドオプション
フィールドまたはインターフェース型または結果既定値または終了コード動作と検証
--directory path 必須 / 既定値なし init で必須です。書き込み可能な新規プロジェクトディレクトリを指定します。
--config path 必須 / 既定値なし doctor、plan、run で必須です。完全なスキーマ 1.0 ファイルのパスを指定します。
--run path 必須 / 既定値なし status、pause、resume、cancel、evaluate、export で必須です。アカウント ID やセッション 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.

状態と終了コードを併せて判断する

終了コード 0 は要求した操作が成功したことを示します。ただし、状態の読み取り、一時停止、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.