huggingface-vision-trainer

Hugging Face Jobs でのビジョンモデルのトレーニング

マネージドクラウド GPU で、物体検出、画像分類、SAM/SAM2 セグメンテーションモデルをトレーニングできます。ローカルで GPU をセットアップする必要はありません。結果は Hugging Face Hub に自動的に保存されます。

このスキルを使用するタイミング

ユーザーが次のことを希望する場合に、このスキルを使用してください。

• クラウド GPU またはローカル環境で、物体検出モデル（D-FINE、RT-DETR v2、DETR、YOLOS）をファインチューニングする
• クラウド GPU またはローカル環境で、画像分類モデル（timm：MobileNetV3、MobileViT、ResNet、ViT/DINOv3、または任意の Transformers 分類器）をファインチューニングする
• bbox またはポイントプロンプトを使用して、セグメンテーション／画像マッティング用の SAM または SAM2 モデルをファインチューニングする
• カスタムデータセットでバウンディングボックス検出器をトレーニングする
• カスタムデータセットで画像分類器をトレーニングする
• プロンプトを使用して、カスタムマスクデータセットでセグメンテーションモデルをトレーニングする
• Hugging Face Jobs インフラストラクチャでビジョンモデルのトレーニングジョブを実行する
• トレーニング済みのビジョンモデルが Hub に永続的に保存されるようにする

関連スキル

• hugging-face-jobs — HF Jobs インフラストラクチャ全般：トークン認証、ハードウェアの種類、タイムアウト管理、コストの見積もり、シークレット、環境変数、スケジュール済みジョブ、結果の永続化。トレーニング固有でない Jobs に関する質問（例：「シークレットの仕組みは？」「どのようなハードウェアが利用できますか？」「トークンを渡すにはどうすればよいですか？」）には、Jobs スキルを参照してください。
• hugging-face-model-trainer — TRL ベースの言語モデルのトレーニング（SFT、DPO、GRPO）。テキスト／言語モデルのファインチューニングには、このスキルを使用してください。

ローカルスクリプトの実行

ヘルパースクリプトは PEP 723 のインライン依存関係を使用します。uv run で実行してください。

uv run scripts/dataset_inspector.py --dataset username/dataset-name --split train
uv run scripts/estimate_cost.py --help

前提条件チェックリスト

トレーニングジョブを開始する前に、以下を確認してください。

アカウントと認証

• Pro、Team、または Enterprise プランの Hugging Face アカウント（Jobs の利用には有料プランが必要です）
• 認証済みのログイン：hf_whoami()（ツール）または hf auth whoami（ターミナル）で確認します
• トークンに書き込み権限があること
• ジョブのシークレットにトークンを必ず渡してください — 構文については、以下のディレクティブ #3 を参照してください（MCP ツールと Python API では異なります）

データセットの要件 — 物体検出

• データセットが Hub 上に存在すること
• アノテーションに、bbox、category（および任意で area）サブフィールドを含む objects 列を使用していること
• bbox は xywh（COCO） または xyxy（Pascal VOC） 形式にできます — 形式は自動検出され、変換されます
• カテゴリには整数または文字列を使用できます — 文字列は整数 ID に自動的に再マッピングされます
• image_id 列は任意です — 存在しない場合は自動生成されます
• GPU でトレーニングする前に、未知のデータセットを必ず検証してください（「データセットの検証」セクションを参照）

データセットの要件 — 画像分類

• データセットが Hub 上に存在すること
• image 列（PIL 画像）と**label 列**（整数のクラス ID または文字列）が必要です
• label 列には ClassLabel 型（名前付き）または通常の整数／文字列を使用できます — 文字列は自動的に再マッピングされます
• 一般的な列名は自動検出されます：label、labels、class、fine_label
• GPU でトレーニングする前に、未知のデータセットを必ず検証してください（「データセットの検証」セクションを参照）

データセットの要件 — SAM/SAM2 セグメンテーション

• データセットが Hub 上に存在すること
• image 列（PIL 画像）と**mask 列**（正解データの二値セグメンテーションマスク）が必要です
• プロンプトが必要です。次のいずれかを使用できます。
  • {"bbox": [x0,y0,x1,y1]} または {"point": [x,y]} を含む JSON を格納した prompt 列
  • または、[x0,y0,x1,y1] の値を格納した専用の bbox 列
  • または、[x,y] または [[x,y],...] の値を格納した専用の point 列
• bbox は xyxy 形式（絶対ピクセル座標）にしてください
• データセットの例：merve/MicroMat-mini（bbox プロンプトを使用した画像マッティング）
• GPU でトレーニングする前に、未知のデータセットを必ず検証してください（「データセットの検証」セクションを参照）

重要な設定

• タイムアウトは予想されるトレーニング時間より長く設定してください — デフォルトの 30 分では短すぎます。推奨値についてはディレクティブ #6 を参照してください。
• Hub へのプッシュを有効にしてください — push_to_hub=True、hub_model_id="username/model-name" を設定し、トークンを secrets に指定します

データセットの検証

GPU トレーニングを開始する前にデータセットの形式を検証し、トレーニング失敗の最大の原因である形式の不一致を防いでください。

不明なデータセットや、これまでトレーニングに使用したことのないデータセットは、必ず検証してください。トレーニングスクリプトのデフォルトである cppe-5 は、検証を省略できます。

インスペクターの実行

オプション 1：HF Jobs 経由（推奨 — ローカルの SSL／依存関係の問題を回避できます）：

hf_jobs("uv", {
    "script": "path/to/dataset_inspector.py",
    "script_args": ["--dataset", "username/dataset-name", "--split", "train"]
})

オプション 2：ローカルで実行：

uv run scripts/dataset_inspector.py --dataset username/dataset-name --split train

オプション 3：HfApi().run_uv_job() 経由（hf_jobs MCP を利用できない場合）：

from huggingface_hub import HfApi
api = HfApi()
api.run_uv_job(
    script="scripts/dataset_inspector.py",
    script_args=["--dataset", "username/dataset-name", "--split", "train"],
    flavor="cpu-basic",
    timeout=300,
)

結果の読み方

• ✓ READY — データセットに互換性があります。そのまま使用してください
• ✗ NEEDS FORMATTING — 前処理が必要です（出力にマッピングコードが示されます）

bbox の自動前処理

物体検出トレーニングスクリプト（scripts/object_detection_training.py）は、bbox 形式の検出（xyxy→xywh 変換）、bbox のサニタイズ、image_id の生成、文字列のカテゴリーから整数への再マッピング、データセットの切り詰めを自動的に処理します。手動での前処理は不要です。データセットに objects.bbox 列と objects.category 列があることだけ確認してください。

トレーニングのワークフロー

このチェックリストをコピーして、進捗を記録してください。

Training Progress:
- [ ] Step 1: Verify prerequisites (account, token, dataset)
- [ ] Step 2: Validate dataset format (run dataset_inspector.py)
- [ ] Step 3: Ask user about dataset size and validation split
- [ ] Step 4: Prepare training script (OD: scripts/object_detection_training.py, IC: scripts/image_classification_training.py, SAM: scripts/sam_segmentation_training.py)
- [ ] Step 5: Save script locally, submit job, and report details

ステップ 1：前提条件を確認する

上記の前提条件チェックリストに従ってください。

ステップ 2：データセットを検証する

GPU 時間を使う前に、データセットインスペクターを実行してください。上記の「データセットの検証」セクションを参照してください。

ステップ 3：ユーザーの希望を確認する

必ず AskUserQuestion ツールをオプション形式で使用してください。

AskUserQuestion({
    "questions": [
        {
            "question": "Do you want to run a quick test with a subset of the data first?",
            "header": "Dataset Size",
            "options": [
                {"label": "Quick test run (10% of data)", "description": "Faster, cheaper (~30-60 min, ~$2-5) to validate setup"},
                {"label": "Full dataset (Recommended)", "description": "Complete training for best model quality"}
            ],
            "multiSelect": false
        },
        {
            "question": "Do you want to create a validation split from the training data?",
            "header": "Split data",
            "options": [
                {"label": "Yes (Recommended)", "description": "Automatically split 15% of training data for validation"},
                {"label": "No", "description": "Use existing validation split from dataset"}
            ],
            "multiSelect": false
        },
        {
            "question": "Which GPU hardware do you want to use?",
            "header": "Hardware Flavor",
            "options": [
                {"label": "t4-small ($0.40/hr)", "description": "1x T4, 16 GB VRAM — sufficient for all OD models under 100M params"},
                {"label": "l4x1 ($0.80/hr)", "description": "1x L4, 24 GB VRAM — more headroom for large images or batch sizes"},
                {"label": "a10g-large ($1.50/hr)", "description": "1x A10G, 24 GB VRAM — faster training, more CPU/RAM"},
                {"label": "a100-large ($2.50/hr)", "description": "1x A100, 80 GB VRAM — fastest, for very large datasets or image sizes"}
            ],
            "multiSelect": false
        }
    ]
})

ステップ 4：トレーニングスクリプトを準備する

物体検出には、scripts/object_detection_training.py を本番環境で使用できるテンプレートとして使用してください。画像分類には、scripts/image_classification_training.py を使用してください。SAM／SAM2 セグメンテーションには、scripts/sam_segmentation_training.py を使用してください。すべてのスクリプトは HfArgumentParser を使用します。設定はすべて script_args の CLI 引数で渡し、Python 変数は編集しません。timm モデルの詳細については、references/timm_trainer.md を参照してください。SAM2 トレーニングの詳細については、references/finetune_sam2_trainer.md を参照してください。

ステップ 5：スクリプトを保存してジョブを送信し、結果を報告する

1. スクリプトをローカルに保存する：ワークスペースのルートにある submitted_jobs/ に、training_<dataset>_<YYYYMMDD_HHMMSS>.py のような内容が分かる名前で保存してください（必要に応じて作成します）。保存先のパスをユーザーに伝えてください。
2. hf_jobs MCP ツール（推奨）または HfApi().run_uv_job() を使用して送信します。両方の方法については、指示 #1 を参照してください。すべての設定は script_args 経由で渡してください。
3. ジョブ ID（.id 属性から取得）、監視 URL、Trackio ダッシュボード（https://huggingface.co/spaces/{username}/trackio）、予想所要時間、推定コストを報告します。
4. ステータス確認は、ユーザーから依頼があるまで待ってください。自動でポーリングしないでください。トレーニングジョブは非同期で実行され、数時間かかることがあります。

重要な指示

以下のルールは、よくある失敗を防ぐためのものです。必ず正確に従ってください。

1. ジョブの送信：hf_jobs MCP ツールと Python API

hf_jobs() は MCP ツールであり、Python 関数ではありません。huggingface_hub からインポートしようとしないでください。ツールとして呼び出してください。

hf_jobs("uv", {"script": training_script_content, "flavor": "a10g-large", "timeout": "4h", "secrets": {"HF_TOKEN": "$HF_TOKEN"}})

hf_jobs MCP ツールを利用できない場合は、Python API を直接使用してください。

from huggingface_hub import HfApi, get_token
api = HfApi()
job_info = api.run_uv_job(
    script="path/to/training_script.py",  # file PATH, NOT content
    script_args=["--dataset_name", "cppe-5", ...],
    flavor="a10g-large",
    timeout=14400,  # seconds (4 hours)
    env={"PYTHONUNBUFFERED": "1"},
    secrets={"HF_TOKEN": get_token()},  # MUST use get_token(), NOT "$HF_TOKEN"
)
print(f"Job ID: {job_info.id}")

2 つの方法の重要な違い：

	hf_jobs MCP ツール	HfApi().run_uv_job()
script パラメーター	Python コード文字列または URL（ローカルパスは不可）	.py ファイルへのパス（コンテンツは不可）
シークレット内のトークン	"$HF_TOKEN"（自動で置換）	get_token()（実際のトークン値）
タイムアウト形式	文字列（"4h"）	秒数（14400）

両方の方法に共通するルール：

• トレーニングスクリプトには、依存関係を含む PEP 723 インラインメタデータを必ず含めてください
• image または command パラメーターは使用しないでください（これらは run_uv_job() ではなく run_job() 用です）

2. ジョブシークレットによる認証と明示的な hub_token の注入

ジョブ設定には、シークレットにトークンを含める必要があります。構文は送信方法によって異なります（上の表を参照）。

トレーニングスクリプトの要件： Transformers の Trainer は、push_to_hub=True の場合、__init__() 内で create_repo(token=self.args.hub_token) を呼び出します。トレーニングスクリプトでは、引数を解析した後、Trainer を作成する前に、HF_TOKEN を training_args.hub_token に注入する必要があります。テンプレートの scripts/object_detection_training.py には、すでに次の処理が含まれています。

hf_token = os.environ.get("HF_TOKEN")
if training_args.push_to_hub and not training_args.hub_token:
    if hf_token:
        training_args.hub_token = hf_token

カスタムスクリプトを作成する場合は、Trainer(...) の呼び出し前にこのトークン注入処理を必ず含めてください。

• カスタムスクリプトでは、scripts/object_detection_training.py の完全なパターンを再現する場合を除き、login() を呼び出さないでください。
• 暗黙的なトークン解決（hub_token=None）に依存しないでください。ジョブでは信頼性に欠けます。
• 詳細については、hugging-face-jobs スキル → トークン使用ガイドを参照してください。

3. JobInfo 属性

ジョブ識別子には .id を使ってアクセスしてください（.job_id や .name ではありません。これらは存在しません）。

job_info = api.run_uv_job(...)  # or hf_jobs("uv", {...})
job_id = job_info.id  # Correct -- returns string like "687fb701029421ae5549d998"

4. 必須のトレーニングフラグと HfArgumentParser のブール値構文

scripts/object_detection_training.py は HfArgumentParser を使用します。すべての設定は script_args 経由で渡します。ブール値の引数には、次の 2 つの構文があります。

• bool フィールド（例：push_to_hub、do_train）：値を付けないフラグ（--push_to_hub）として使うか、--no_ プレフィックスを付けて否定します（--no_remove_unused_columns）。
• Optional[bool] フィールド（例：greater_is_better）：明示的な値を渡す必要があります（--greater_is_better True）。値を付けずに --greater_is_better を指定すると、error: expected one argument が発生します。

物体検出に必須のフラグ：

--no_remove_unused_columns          # MUST: preserves image column for pixel_values
--no_eval_do_concat_batches         # MUST: images have different numbers of target boxes
--push_to_hub                       # MUST: environment is ephemeral
--hub_model_id username/model-name
--metric_for_best_model eval_map
--greater_is_better True            # MUST pass "True" explicitly (Optional[bool])
--do_train
--do_eval

画像分類に必須のフラグ：

--no_remove_unused_columns          # MUST: preserves image column for pixel_values
--push_to_hub                       # MUST: environment is ephemeral
--hub_model_id username/model-name
--metric_for_best_model eval_accuracy
--greater_is_better True            # MUST pass "True" explicitly (Optional[bool])
--do_train
--do_eval

SAM／SAM2 セグメンテーションに必須のフラグ：

--remove_unused_columns False       # MUST: preserves input_boxes/input_points
--push_to_hub                       # MUST: environment is ephemeral
--hub_model_id username/model-name
--do_train
--prompt_type bbox                  # or "point"
--dataloader_pin_memory False       # MUST: avoids pin_memory issues with custom collator

5. タイムアウトの管理

デフォルトの 30 分では、物体検出には短すぎます。最低 2〜4 時間に設定してください。モデルの読み込み、前処理、Hub へのプッシュに備えて、30% の余裕を加えてください。

シナリオ	タイムアウト
簡易テスト（画像 100〜200 枚、5〜10 エポック）	1h
開発（画像 500〜1K 枚、15〜20 エポック）	2〜3h
本番（画像 1K〜5K 枚、30 エポック）	4〜6h
大規模データセット（画像 5K 枚以上）	6〜12h

6. Trackio によるモニタリング

Trackio は物体検出トレーニングスクリプトで常に有効になっており、trackio.init() と trackio.finish() が自動的に呼び出されます。--report_to trackio を渡す必要はありません。プロジェクト名には --output_dir の値が、実行名には --run_name の値が使われます。画像分類では、TrainingArguments に --report_to trackio を渡してください。

ダッシュボード：https://huggingface.co/spaces/{username}/trackio

モデルとハードウェアの選択

推奨する物体検出モデル

モデル	パラメーター数	用途
ustc-community/dfine-small-coco	10.4M	最初のモデルに最適。高速、低コスト、最先端の品質
PekingU/rtdetr_v2_r18vd	20.2M	軽量なリアルタイム検出器
ustc-community/dfine-large-coco	31.4M	より高精度で、効率性も維持
PekingU/rtdetr_v2_r50vd	43M	優れたリアルタイムのベースライン
ustc-community/dfine-xlarge-obj365	63.5M	最高精度（Objects365 で事前学習済み）
PekingU/rtdetr_v2_r101vd	76M	RT-DETR v2 の最大バリアント

高速に反復するには、ustc-community/dfine-small-coco から始めてください。精度を高めたい場合は、D-FINE Large または RT-DETR v2 R50 に切り替えてください。

推奨画像分類モデル

すべての timm/ モデルは、AutoModelForImageClassification（TimmWrapperForImageClassification として読み込まれます）を通じてすぐに利用できます。詳細は references/timm_trainer.md を参照してください。

モデル	パラメーター数	用途
timm/mobilenetv3_small_100.lamb_in1k	2.5M	超軽量 — モバイル／エッジ向け、トレーニングが最速
timm/mobilevit_s.cvnets_in1k	5.6M	モバイル向けトランスフォーマー — 精度と速度のバランスが良好
timm/resnet50.a1_in1k	25.6M	強力な CNN ベースライン — 信頼性が高く、十分に研究されています
timm/vit_base_patch16_dinov3.lvd1689m	86.6M	最高精度 — DINOv3 の自己教師あり ViT

高速に試行錯誤するには、timm/mobilenetv3_small_100.lamb_in1k から始めてください。精度を高めるには、timm/resnet50.a1_in1k または timm/vit_base_patch16_dinov3.lvd1689m に切り替えてください。

推奨 SAM/SAM2 セグメンテーションモデル

モデル	パラメーター数	用途
facebook/sam2.1-hiera-tiny	38.9M	最速の SAM2 — 手早い実験に適しています
facebook/sam2.1-hiera-small	46.0M	最適な出発点 — 品質と速度のバランスが良好
facebook/sam2.1-hiera-base-plus	80.8M	複雑なセグメンテーションに対応する高い容量
facebook/sam2.1-hiera-large	224.4M	SAM2 で最高の精度 — より多くの VRAM が必要です
facebook/sam-vit-base	93.7M	オリジナルの SAM — ViT-B バックボーン
facebook/sam-vit-large	312.3M	オリジナルの SAM — ViT-L バックボーン
facebook/sam-vit-huge	641.1M	オリジナルの SAM — ViT-H、SAM v1 で最高の精度

高速に試行錯誤するには、facebook/sam2.1-hiera-small から始めてください。SAM2 モデルは、同程度の品質であれば、一般に SAM v1 より効率的です。デフォルトでは、マスクデコーダーのみがトレーニングされます（ビジョンエンコーダーとプロンプトエンコーダーは凍結されます）。

ハードウェアの推奨

推奨する OD モデルと IC モデルはすべて 100M パラメーター未満です — t4-small（VRAM 16 GB、$0.40/hr）ですべてに十分対応できます。 画像分類モデルは一般に物体検出モデルより小さく高速です — t4-small なら ViT-Base も余裕を持って処理できます。hiera-base-plus までの SAM2 モデルは、マスクデコーダーのみをトレーニングするため、t4-small で十分です。sam2.1-hiera-large または SAM v1 モデルには、l4x1 か a10g-large を使用してください。大きなバッチサイズによって OOM が発生した場合にのみアップグレードしてください — ハードウェアを切り替える前に、まずバッチサイズを小さくしてください。一般的なアップグレードの手順は、t4-small → l4x1（$0.80/hr、24 GB）→ a10g-large（$1.50/hr、24 GB）です。

ハードウェアフレーバーの全一覧は、hugging-face-jobs スキルを参照してください。コストの見積もりには、scripts/estimate_cost.py を実行してください。

クイックスタート — 物体検出

以下の script_args は、どちらの送信方法でも同じです。両者の重要な違いについては directive #1 を参照してください。

OD_SCRIPT_ARGS = [
    "--model_name_or_path", "ustc-community/dfine-small-coco",
    "--dataset_name", "cppe-5",
    "--image_square_size", "640",
    "--output_dir", "dfine_finetuned",
    "--num_train_epochs", "30",
    "--per_device_train_batch_size", "8",
    "--learning_rate", "5e-5",
    "--eval_strategy", "epoch",
    "--save_strategy", "epoch",
    "--save_total_limit", "2",
    "--load_best_model_at_end",
    "--metric_for_best_model", "eval_map",
    "--greater_is_better", "True",
    "--no_remove_unused_columns",
    "--no_eval_do_concat_batches",
    "--push_to_hub",
    "--hub_model_id", "username/model-name",
    "--do_train",
    "--do_eval",
]

from huggingface_hub import HfApi, get_token
api = HfApi()
job_info = api.run_uv_job(
    script="scripts/object_detection_training.py",
    script_args=OD_SCRIPT_ARGS,
    flavor="t4-small",
    timeout=14400,
    env={"PYTHONUNBUFFERED": "1"},
    secrets={"HF_TOKEN": get_token()},
)
print(f"Job ID: {job_info.id}")

主要な OD script_args

• --model_name_or_path — 推奨値："ustc-community/dfine-small-coco"（上記のモデル表を参照）
• --dataset_name — Hub のデータセット ID
• --image_square_size — 480（高速な試行錯誤向け）または 800（より高い精度向け）
• --hub_model_id — Hub に保存する場合は "username/model-name"
• --num_train_epochs — 収束まで通常 30 エポック
• --train_val_split — 検証用に分割する割合（デフォルトは 0.15）。データセットに検証用の分割がない場合に設定します
• --max_train_samples — トレーニングセットを切り詰めます（簡単なテスト実行に便利です。例：7.8K のデータセットの約 10% なら "785"）
• --max_eval_samples — 評価セットを切り詰めます

クイックスタート — 画像分類

IC_SCRIPT_ARGS = [
    "--model_name_or_path", "timm/mobilenetv3_small_100.lamb_in1k",
    "--dataset_name", "ethz/food101",
    "--output_dir", "food101_classifier",
    "--num_train_epochs", "5",
    "--per_device_train_batch_size", "32",
    "--per_device_eval_batch_size", "32",
    "--learning_rate", "5e-5",
    "--eval_strategy", "epoch",
    "--save_strategy", "epoch",
    "--save_total_limit", "2",
    "--load_best_model_at_end",
    "--metric_for_best_model", "eval_accuracy",
    "--greater_is_better", "True",
    "--no_remove_unused_columns",
    "--push_to_hub",
    "--hub_model_id", "username/food101-classifier",
    "--do_train",
    "--do_eval",
]

from huggingface_hub import HfApi, get_token
api = HfApi()
job_info = api.run_uv_job(
    script="scripts/image_classification_training.py",
    script_args=IC_SCRIPT_ARGS,
    flavor="t4-small",
    timeout=7200,
    env={"PYTHONUNBUFFERED": "1"},
    secrets={"HF_TOKEN": get_token()},
)
print(f"Job ID: {job_info.id}")

主要な IC script_args

• --model_name_or_path — 任意の timm/ モデルまたは Transformers 分類モデル（上記のモデル表を参照）
• --dataset_name — Hub データセット ID
• --image_column_name — PIL 画像を含む列（デフォルト: "image"）
• --label_column_name — クラスラベルを含む列（デフォルト: "label"）
• --hub_model_id — Hub への保存用の "username/model-name"
• --num_train_epochs — 分類では通常 3〜5（OD より少ない）
• --per_device_train_batch_size — 16〜64（分類モデルは OD よりもメモリ使用量が少ない）
• --train_val_split — 検証用に分割する割合（デフォルト 0.15）。データセットに検証用分割がない場合に設定します
• --max_train_samples / --max_eval_samples — クイックテスト用に切り詰める

クイックスタート — SAM/SAM2 セグメンテーション

SAM_SCRIPT_ARGS = [
    "--model_name_or_path", "facebook/sam2.1-hiera-small",
    "--dataset_name", "merve/MicroMat-mini",
    "--prompt_type", "bbox",
    "--prompt_column_name", "prompt",
    "--output_dir", "sam2-finetuned",
    "--num_train_epochs", "30",
    "--per_device_train_batch_size", "4",
    "--learning_rate", "1e-5",
    "--logging_steps", "1",
    "--save_strategy", "epoch",
    "--save_total_limit", "2",
    "--remove_unused_columns", "False",
    "--dataloader_pin_memory", "False",
    "--push_to_hub",
    "--hub_model_id", "username/sam2-finetuned",
    "--do_train",
    "--report_to", "trackio",
]

from huggingface_hub import HfApi, get_token
api = HfApi()
job_info = api.run_uv_job(
    script="scripts/sam_segmentation_training.py",
    script_args=SAM_SCRIPT_ARGS,
    flavor="t4-small",
    timeout=7200,
    env={"PYTHONUNBUFFERED": "1"},
    secrets={"HF_TOKEN": get_token()},
)
print(f"Job ID: {job_info.id}")

主要な SAM script_args

• --model_name_or_path — SAM または SAM2 モデル（上記のモデル表を参照）。SAM か SAM2 かを自動判別します
• --dataset_name — Hub データセット ID（例: "merve/MicroMat-mini"）
• --prompt_type — "bbox" または "point" — データセット内のプロンプトの種類
• --prompt_column_name — JSON エンコードされたプロンプトを含む列（デフォルト: "prompt"）
• --bbox_column_name — 専用の bbox 列（JSON プロンプト列の代替）
• --point_column_name — 専用の point 列（JSON プロンプト列の代替）
• --mask_column_name — 正解マスクを含む列（デフォルト: "mask"）
• --hub_model_id — Hub への保存用の "username/model-name"
• --num_train_epochs — SAM のファインチューニングでは通常 20〜30
• --per_device_train_batch_size — 2〜4（SAM モデルは多くのメモリを使用します）
• --freeze_vision_encoder / --freeze_prompt_encoder — エンコーダーの重みを凍結（デフォルト: 両方とも凍結され、マスクデコーダーのみが学習されます）
• --train_val_split — 検証用に分割する割合（デフォルト 0.1）

ジョブのステータスを確認する

MCP ツール（利用可能な場合）:

hf_jobs("ps")                                   # List all jobs
hf_jobs("logs", {"job_id": "your-job-id"})      # View logs
hf_jobs("inspect", {"job_id": "your-job-id"})   # Job details

Python API のフォールバック:

from huggingface_hub import HfApi
api = HfApi()
api.list_jobs()                                  # List all jobs
api.get_job_logs(job_id="your-job-id")           # View logs
api.get_job(job_id="your-job-id")                # Job details

よくある失敗モード

OOM（CUDA out of memory）

per_device_train_batch_size を減らす（4、次に 2 を試す）、IMAGE_SIZE を減らす、またはハードウェアをアップグレードしてください。

データセット形式のエラー

まず scripts/dataset_inspector.py を実行してください。学習スクリプトは xyxy と xywh を自動判別し、文字列カテゴリを整数 ID に変換し、image_id がなければ追加します。objects.bbox に絶対ピクセル単位の 4 値の座標リストが含まれ、objects.category に整数 ID または文字列ラベルのいずれかが含まれていることを確認してください。

Hub へのプッシュ失敗（401）

次を確認してください: (1) ジョブシークレットにトークンが含まれている（ディレクティブ #2 を参照）、(2) スクリプトが Trainer を作成する前に training_args.hub_token を設定している、(3) push_to_hub=True が設定されている、(4) hub_model_id が正しい、(5) トークンに書き込み権限がある。

ジョブのタイムアウト

タイムアウトを増やす（ディレクティブ #5 の表を参照）、エポック数やデータセットを減らす、または hub_strategy="every_save" を使ったチェックポイント戦略を使用してください。

KeyError: 'test'（test 分割がない）

物体検出の学習スクリプトはこれを適切に処理します — validation 分割にフォールバックします。最新の scripts/object_detection_training.py を使用していることを確認してください。

単一クラスのデータセット: 「iteration over a 0-d tensor」

クラスが 1 つだけの場合、torchmetrics.MeanAveragePrecision はクラスごとのメトリクスに対してスカラー（0 次元）テンソルを返します。テンプレート scripts/object_detection_training.py は、これらのテンソルに対して .unsqueeze(0) を呼び出すことでこれを処理します。最新のテンプレートを使用していることを確認してください。

検出性能が低い（mAP < 0.15）

エポック数を増やし（30〜50）、画像が 500 枚以上あることを確認し、不均衡なクラスがないかクラスごとの mAP を確認し、異なる学習率（1e-5〜1e-4）を試し、画像サイズを大きくしてください。

包括的なトラブルシューティングについては、references/reliability_principles.md を参照してください。

参考ファイル

• scripts/object_detection_training.py — 本番環境に対応した物体検出のトレーニングスクリプト
• scripts/image_classification_training.py — 本番環境に対応した画像分類のトレーニングスクリプト（timm モデルに対応）
• scripts/sam_segmentation_training.py — 本番環境に対応した SAM/SAM2 セグメンテーションのトレーニングスクリプト（bbox と point プロンプトに対応）
• scripts/dataset_inspector.py — OD、画像分類、SAM セグメンテーションのデータセット形式を検証
• scripts/estimate_cost.py — あらゆるビジョンモデル（SAM/SAM2 を含む）のトレーニングコストを見積もり
• references/object_detection_training_notebook.md — 物体検出のトレーニングワークフロー、データ拡張戦略、トレーニングパターン
• references/image_classification_training_notebook.md — ViT、前処理、評価を含む画像分類のトレーニングワークフロー
• references/finetune_sam2_trainer.md — MicroMat データセット、DiceCE 損失、Trainer との統合を使った SAM2 ファインチューニングの手順
• references/timm_trainer.md — HF Trainer での timm モデルの使用方法（TimmWrapper、変換、完全な例）
• references/hub_saving.md — Hub への永続化の詳細ガイドと検証チェックリスト
• references/reliability_principles.md — 本番環境での経験に基づく障害防止の原則

外部リンク

• Transformers 物体検出ガイド
• Transformers 画像分類ガイド
• DETR モデルのドキュメント
• ViT モデルのドキュメント
• HF Jobs ガイド — Jobs の主なドキュメント
• HF Jobs の設定 — ハードウェア、シークレット、タイムアウト、名前空間
• HF Jobs CLI リファレンス — コマンドラインインターフェース
• 物体検出モデル
• 画像分類モデル
• SAM2 モデルのドキュメント
• SAM モデルのドキュメント
• 物体検出データセット
• 画像分類データセット