scenario-model-training

シナリオモデルのトレーニング

概要

アイコンセット、繰り返し登場するキャラクター、製品ラインなど、多数のアセットで同じ見た目を保つ必要がある場合は、カスタムモデルをトレーニングします。プロンプト、参照画像、コントロールマップを使う方法が、より低コストな最初の選択肢です。scenario-consistency を参照してください。トレーニングの見積もりを提示する前に、対象に応じて scenario-consistency が説明する参照テストを実施します。見た目を確認する場合は、承認済みのアートをスタイル参照として使い（スタイルのみを指定するようプロンプトに明記します）、キャラクターや製品を確認する場合は、ヒーロー画像を被写体参照として使います。執筆時点では、同等の画像単価で同じブリーフを使ったカスタム LoRA の見た目に、スタイルテストで 1 回の生成分の費用で近づけました。トレーニングは、そのテストでセット全体にばらつきが出た場合に行い、それまでは実施しません。以下の実例は、そのテストの後から始まります。

判断の根拠となるリファレンスは 2 つあります。 references/base-model-selection.md（recommend_training に入力するユーザーへのヒアリング）と、references/dataset-curation.md（トレーニングの種類ごとのデータセットサイズ、画像のルール、キャプション、レビュー）です。

接続方法と基本的な生成の流れについては、scenario スキルを参照してください。ここで名前を挙げた関連スキルが利用可能なスキルに見つからない場合は、ユーザーにインストールを依頼します（npx skills add scenario-labs/skills --skill <name>）。無人で作業を続ける場合は、ツールスキーマに基づいて進め、不足があることを明示してください。

トレーニングツールはデフォルトのツールセットに含まれていません。scenario_tools_search でスキーマを取得し、読み取り操作（recommend_training、model_get）には scenario_tool_execute_read、書き込み操作（model_create、train、model_update）には scenario_tool_execute_write を使用するか、?toolsets=full を指定して再接続してください。

クイックリファレンス

手順	ツール
ベースアーキテクチャを選択	recommend_training（LLM を活用。費用がかかります）
モデルのシェルを作成	model_create（推奨結果の data.type を使用）
データセットをアップロード	upload_asset + upload_asset_complete
トレーニング画像を追加	train アクション upload_images、1 回につきアセット ID を 10 個指定
費用を見積もる	train アクション configure に dry_run: true を指定（見積もりのみ。ジョブは作成されません）
各エポックをプレビュー	config.sample_prompts。複数エポックを実行する場合は、少なくとも 1 つ指定します
開始	train アクション start に同じ config を指定するか、デフォルトを使う場合は省略します
待機	返されたジョブ ID を jobs_wait に指定します
生成	お使いのモデル ID で model_schema_get を実行し、その後 model_run を実行します
管理	models_list、model_get、model_update

実例：ゲーム用小道具のスタイル LoRA

1. recommend_training を prompt: "hand-painted prop icons for a mobile RPG"、 modality: "image"、dataset_shape: "single_images" に加え、インタビューで確認した subject、style、priority を指定して実行します。推奨バリアント、代替案、および dataset_requirements（形状とサイズの範囲）が返されます。費用が発生するため、意図を明確にして一度だけ呼び出してください。
2. model_create を data: {"name": "rpg-prop-icons", "type": "<type from step 1>"} で実行します。返されたモデル ID を控えてください。
3. まずデータセット参照に従ってデータセットを整理し、手順 1 の dataset_requirements に合わせます。その後、upload_asset と upload_asset_complete を使って各ファイルをアップロードし（scenario スキルを参照）、アセット ID を収集します。 image_pairs データセットでは、train アクションの set_pairs でペアを対応付けます。
4. train を action: "upload_images"、model_id、images: [<asset ids>] で実行します。1 回あたり最大 10 件です（データセットの制限を参照）。データが変更されるため、team_id と project_id を渡してください（スコープについては scenario スキルを参照）。
5. train を action: "configure"、 config: {"epochs": 12, "sample_prompts": ["a rusty lantern icon, centered, plain field", "a blue mana potion icon, three-quarter view, plain field"]}、 dry_run: true で実行すると、見積もりが返され、何も開始されません。epochs は主なコスト調整項目です（線形に増加します）。ほかの調整項目はデータセットのサイズに応じて設定してください（データセット参照）。複数エポックの実行では sample_prompts は必須です。トレーナーがエポックごとのチェックポイントを公開するのは、これらを指定した実行だけだからです。指定しない実行では最終ウェイトしか残らず、epochs で指定した回数から選べるのではなく 1 エポック分だけになり、モデルが過学習しても以前の状態に戻せません。実際に、12 エポックの実行が選択可能なエポック 1 つだけで返された例があります。上限はファミリーごとに異なり、執筆時点では Flux LoRA ファミリーで 8、Flux.2、Qwen、ZImage LoRA で 4 です。train のスキーマで上限を確認してください。学習タイプのキャプション規則に従い、データセット外の概念を試すプロンプトを作成してください（スタイルセットでは新しい被写体を指定し、スタイルは指定しません。キャラクターセットではトリガーワードから始め、新しいポーズや設定を指定します）。これらはエポックを選ぶためのプレビューです。一般的なプロンプトではどのエポックでも一般的なシーンが返されるため、ある実行では見積もり全額を使って、関連のない 4 つの風景のプレビューを 20 枚生成してしまいました。編集ファミリーでは、各プロンプトにつきアセット ID を 1 つ、同じ順序で sample_source_images に指定します。それ以外のファミリーでは、このフィールドは拒否されます。ユーザーに見積もりを提示して承認を得てから、同じ config で action: "start" を実行します（無人実行の場合は、タスクですでに学習が承認されているか、その費用をまかなう予算がある場合に限って開始してください。それ以外の場合は停止して、見積もりを報告します）。configure は常に見積もりを返し、実行は開始しません。そこで dry_run: false を指定すると拒否されます。学習を開始するのは start だけです。start に dry_run: true を指定すると、代わりに見積もりが返されます。start は見積もり全額を使うものとして扱ってください。stop してもその分が戻るとは考えないでください。
6. 起動レスポンスにはジョブが含まれます。その ID を job_ids に指定して jobs_wait を実行します。ジョブ ID がない場合は何も起動されていません。再試行せず、その旨を報告してください。学習はサーバーの待機時間上限を超えるため、完了するまで返された pending_job_ids を使って再度呼び出してください。job_get でポーリングしてはいけません。
7. 生成前にプレビューを見てエポックを選びます。プレビューは Web アプリのモデルページに表示され、最良のものが最後のエポックとは限りません。選択するのはユーザーです。無人実行では学習済みモデルのまま生成し、エポックの選択は未確定のままであることを伝えて続行してください。その後、新しいモデル ID で model_schema_get を実行してから model_run を実行します。カスタムモデルにはそれぞれ独自のパラメーター仕様があります。LoRA はスキーマの runs_as と run_with.required_arguments で指定されたベースで実行し（scenario を参照）、Z-Image LoRA が Z-Image の各バリアントで使用できるという文書化された例外を除き、同じファミリーのほかのバリアントでは実行できません（ベースの参照を参照）。生成時の size mismatch または weight dimension エラーは、別のバリアントがベースとして渡されたことを意味し、学習の失敗ではありません。再学習せず、run_with を再確認して、そこで指定された組み合わせで実行してください。
8. 管理：models_list を filters: {"privacy": "private", "status": "trained"} で実行すると、準備が整ったモデルが一覧表示されます。model_get を include_description: true で実行すると、ドキュメント全体を取得できます。model_update では名前、説明、プライバシーを編集できます。

実行を妨げるデータセットの制限

train の失敗のほとんどは、ハイパーパラメーターではなくデータセットの処理が原因です。

• 1 回の呼び出しにつき ID は 10 個までです。 upload_images が受け付けるアセット ID は最大 10 個です。それを超えると 400 Too many assetIds provided in a single request が返されます。10 個ずつに分けて呼び出してください。モデルには全体が蓄積されます。
• チャンクを重複させないでください。 すでに追加済みの ID を再送すると 400 The provided assetId is already a training image of this model が返されます。一部が失敗した場合は、取り込まれなかったチャンクだけを再送してください。
• プランには別々の 2 つの上限があります。 データセットのサイズにはチームごとの上限があります。これを超えると、upload_images は add-training-image を示す 429 を返し、上限は actionLimit に含まれます。チャンク分割では回避できません。最適な画像に絞るか、プランのアップグレードを案内してください。並行して実行できるトレーニング数には別途 parallel-training の上限があり、プランによっては 0 に設定されています。
• 設定の前に画像を追加してください。 空のデータセットに対する configure または start は、トレーニング画像数の検証に失敗します。ペアのデータセットでは、ペアをすべてそろえる必要があり、ファミリーごとに最低数も 1 より大きくなります。
• 起動できるのは一度に 1 件です。 実行中に再度起動すると 400 Model is already training が返されます。jobs_wait で待つか、train の action: "stop" を使ってください。起動を繰り返すと、remainingSeconds を示す 429 が返されるクールダウンにも達します。

よくある間違い

• 1 回限りの用途でトレーニングすること。スタイル画像が 1 枚なら、プロンプトと参照画像を使うジョブで対応できます。公開カタログにはトレーニング済みの LoRA が多数あるため、まず search を使ってください。
• どの出力にも同じ見慣れない顔が現れるのを、通常のブレだと捉えること。毎回同じ見知らぬ人を再現するモデルは、画像ではなくキャプションを学習しています。通常、画像がすべて 1 枚の元画像から作られ、見た目だけが異なるため、人物の特徴を示す情報が不足しており、データセットが同じ構図のほぼ重複画像として認識されています。エポック数ではなく、データセットを修正してください（実際に異なるショット、変数だけを示すキャプション、トリガーワードを使用。データセットのリファレンスを参照）。
• 生成モデルを選ぶために recommend_training を使うこと。これはトレーニング用のベースモデルだけを選びます。recommend または search を使ってください。
• ローカルパスや URL を train に渡すこと。まず upload_asset でアップロードし、アセット ID を渡してください。それ以外を渡すと、assetId を示すボディの形式エラーが発生します。
• 400 Custom models only are supported for this endpoint をパラメーターの問題だと捉えること。このルートで受け付けるのは、自分でトレーニングしたモデルだけです。models_list で ID を再確認してください。
• sample_prompts を指定せずに複数エポックを起動すること。実行は完了しますが、エポック数は 1 でプレビューもないため、見積もりを取得しても比較できません。
• 見積もりを起動だと捉えること。configure は training_started: false を返し、ジョブは作成しません。承認後に start から起動し、待機する前にジョブ ID が返されたことを必ず確認してください。
• models_list を status: "ready" でフィルタリングすること。任意の値は無視されるため、削除済みモデルを含むすべてのモデルが返されます。"trained" を使ってください。
• model_update の data.tags でタグの差分だけを更新しようとすること。これはタグセット全体を置き換えます。差分には model_add_tags／model_remove_tags を使ってください。
• recommend_training が古いベースモデルを返すと期待すること。デフォルトではレガシーファミリーが除外されます。プロジェクトで同じファミリーを使い続ける必要がある場合に限り、legacy_ok: true を設定してください。

音声のクローン作成

音声のクローン作成は、modality: "voice" と dataset_shape: "short_audio" または "long_audio" を指定した同じ recommend_training 呼び出しから始めます。返された type は、同じ方法で model_create に渡します。