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ツール vs Pythonライブラリ)

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

• データセットはHub上に存在する必要がある
• アノテーションは bbox、category (およびオプションで area) サブフィールドを持つ objects 列を使用する必要がある
• バウンディングボックスはxywh (COCO) または**xyxy (Pascal VOC)**形式で指定できます — 自動検出と変換
• カテゴリは整数または文字列で指定できます — 文字列は自動的に整数IDに再マップされます
• image_id 列はオプション — 欠落している場合は自動生成
• GPU訓練前に未知のデータセットを常に検証してください (データセット検証セクション参照)

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

• データセットはHub上に存在する必要がある
• image 列 (PIL画像) と**label 列** (整数クラスIDまたは文字列) を持つ必要がある
• ラベル列は ClassLabel 型 (名前付き) またはプレーン整数/文字列です — 文字列は自動的に再マップされます
• 一般的な列名は自動検出されます: label、labels、class、fine_label
• GPU訓練前に未知のデータセットを常に検証してください (データセット検証セクション参照)

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

• データセットはHub上に存在する必要がある
• image 列 (PIL画像) と**mask 列** (バイナリグラウンドトゥルースセグメンテーションマスク) を持つ必要がある
• プロンプトを持つ必要があります — 以下のいずれか:
  • {"bbox": [x0,y0,x1,y1]} または {"point": [x,y]} を含むJSON形式の**prompt 列**
  • またはDedicated bbox 列 ([x0,y0,x1,y1] 値)
  • またはDedicated point 列 ([x,y] または [[x,y],...] 値)
• バウンディングボックスはxyxy形式 (絶対ピクセル座標) である必要があります
• 例: merve/MicroMat-mini (bboxプロンプト付き画像マッティング)
• GPU訓練前に未知のデータセットを常に検証してください (データセット検証セクション参照)

重要な設定

• タイムアウトは予想訓練時間を超える必要があります — デフォルトの30分は短すぎます。指令 #6 で推奨値を参照してください。
• Hub pushを有効にする必要があります — push_to_hub=True、hub_model_id="username/model-name"、secrets 内のトークン

データセット検証

GPU訓練を開始する前にデータセット形式を検証して、訓練失敗の第1原因であるフォーマットの不一致を防いでください。

未知のカスタムデータセット、または以前に訓練したことのないデータセットについては常に検証してください。 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 — 前処理が必要です (マッピングコードは出力で提供されます)

自動バウンディングボックス前処理

物体検出訓練スクリプト (scripts/object_detection_training.py) は自動的にバウンディングボックス形式検出 (xyxy→xywh変換)、バウンディングボックス衛生化、image_id 生成、文字列カテゴリ→整数リマップ、およびデータセット切り詰めを処理します。手動前処理は不要です — データセットが objects.bbox と objects.category 列を持つことを確認するだけです。

訓練ワークフロー

このチェックリストをコピーして進捗を追跡してください:

訓練進捗:
- [ ] ステップ 1: 前提条件を確認 (アカウント、トークン、データセット)
- [ ] ステップ 2: データセット形式を検証 (dataset_inspector.py を実行)
- [ ] ステップ 3: ユーザーにデータセットサイズと検証分割について質問
- [ ] ステップ 4: 訓練スクリプトを準備 (OD: scripts/object_detection_training.py、IC: scripts/image_classification_training.py、SAM: scripts/sam_segmentation_training.py)
- [ ] ステップ 5: スクリプトをローカルに保存、ジョブを送信、詳細を報告

ステップ 1: 前提条件を確認

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

ステップ 2: データセットを検証

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

ステップ 3: ユーザーの設定を質問

常にAskUserQuestionツールをオプションスタイル形式で使用してください:

AskUserQuestion({
    "questions": [
        {
            "question": "最初にデータの一部でクイックテストを実行しますか?",
            "header": "データセットサイズ",
            "options": [
                {"label": "クイックテスト実行 (データの10%)", "description": "より速く、より安い (~30-60分、~$2-5) セットアップ検証用"},
                {"label": "完全なデータセット (推奨)", "description": "最高のモデル品質のための完全な訓練"}
            ],
            "multiSelect": false
        },
        {
            "question": "訓練データから検証分割を作成しますか?",
            "header": "データを分割",
            "options": [
                {"label": "はい (推奨)", "description": "訓練データの15%を自動的に検証に分割"},
                {"label": "いいえ", "description": "データセットの既存検証分割を使用"}
            ],
            "multiSelect": false
        },
        {
            "question": "どのGPUハードウェアを使用しますか?",
            "header": "ハードウェアフレーバー",
            "options": [
                {"label": "t4-small ($0.40/hr)", "description": "1x T4、16 GB VRAM — 100M以下のすべてのODモデルで十分"},
                {"label": "l4x1 ($0.80/hr)", "description": "1x L4、24 GB VRAM — 大きい画像またはバッチサイズにより多くのヘッドルーム"},
                {"label": "a10g-large ($1.50/hr)", "description": "1x A10G、24 GB VRAM — より高速な訓練、より多くのCPU/RAM"},
                {"label": "a100-large ($2.50/hr)", "description": "1x A100、80 GB VRAM — 最速、非常に大きなデータセットまたは画像サイズ用"}
            ],
            "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ツール vs Pythonライブラリ

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ライブラリを直接使用してください:

from huggingface_hub import HfApi, get_token
api = HfApi()
job_info = api.run_uv_job(
    script="path/to/training_script.py",  # ファイルパス、コンテンツではない
    script_args=["--dataset_name", "cppe-5", ...],
    flavor="a10g-large",
    timeout=14400,  # 秒 (4時間)
    env={"PYTHONUNBUFFERED": "1"},
    secrets={"HF_TOKEN": get_token()},  # "$HF_TOKEN" ではなく get_token() を使用
)
print(f"Job ID: {job_info.id}")

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

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

両方の方法のルール:

• 訓練スクリプトはPEP 723インラインメタデータと依存関係を含む必要がある
• image または command パラメータを使用しないでください (これらは run_job() に属し、run_uv_job() ではない)

2. ジョブシークレット経由の認証 + 明示的なhub_tokenインジェクション

ジョブ構成は送信方法に依存する構文でシークレットにトークンを含める必要があります (上記の表を参照)。

訓練スクリプト要件: Transformers Trainer は push_to_hub=True のとき __init__() 中に create_repo(token=self.args.hub_token) を呼び出します。訓練スクリプトは HF_TOKEN を training_args.hub_token にインジェクトする必要があります (引数解析後だが Trainer 作成前)。テンプレート 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(...) 呼び出しの前にこのトークンインジェクションを含める必要があります。

• カスタムスクリプトで login() を呼び出さないでください (scripts/object_detection_training.py から完全なパターンを複製する場合を除く)
• 暗黙的なトークン解決 (hub_token=None) に依存しないでください — Jobs では信頼性がない
• 完全な詳細については hugging-face-jobs スキル → Token Usage Guide を参照してください

3. JobInfo属性

ジョブ識別子に .id を使用してアクセス (.job_id または .name ではない — これらは存在しない):

job_info = api.run_uv_job(...)  # または hf_jobs("uv", {...})
job_id = job_info.id  # 正しい -- "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          # 必須: image列を保存
--no_eval_do_concat_batches         # 必須: 画像は異なる数のターゲットボックスを持つ
--push_to_hub                       # 必須: 環境は一時的
--hub_model_id username/model-name
--metric_for_best_model eval_map
--greater_is_better True            # 明示的に "True" を渡す必須 (Optional[bool])
--do_train
--do_eval

画像分類の必須フラグ:

--no_remove_unused_columns          # 必須: image列を保存
--push_to_hub                       # 必須: 環境は一時的
--hub_model_id username/model-name
--metric_for_best_model eval_accuracy
--greater_is_better True            # 明示的に "True" を渡す必須 (Optional[bool])
--do_train
--do_eval

SAM/SAM2セグメンテーションの必須フラグ:

--remove_unused_columns False       # 必須: input_boxes/input_pointsを保存
--push_to_hub                       # 必須: 環境は一時的
--hub_model_id username/model-name
--do_train
--prompt_type bbox                  # または "point"
--dataloader_pin_memory False       # 必須: カスタムcollatorでpin_memory問題を回避

5. タイムアウト管理

デフォルトの30分は物体検出には短すぎます。最小2-4時間を設定してください。モデル読み込み、前処理、Hub pushの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 (16 GB VRAM、$0.40/hr) はすべてに十分です。 画像分類モデルは一般的に物体検出モデルより小さく高速です — t4-small はViT-Baseでも快適に処理します。SAM2モデル (マスクデコーダのみ訓練されるため hiera-base-plus まで)、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 は両方の送信方法で同じです。両者の重要な違いについては指令 #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 — Dedicated バウンディングボックス列 (JSON プロンプト列の代替)
• --point_column_name — Dedicated ポイント列 (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")                                   # すべてのジョブをリスト
hf_jobs("logs", {"job_id": "your-job-id"})      # ログを表示
hf_jobs("inspect", {"job_id": "your-job-id"})   # ジョブ詳細

Pythonライブラリフォールバック:

from huggingface_hub import HfApi
api = HfApi()
api.list_jobs()                                  # すべてのジョブをリスト
api.get_job_logs(job_id="your-job-id")           # ログを表示
api.get_job(job_id="your-job-id")                # ジョブ詳細

一般的な失敗モード

OOM (CUDA メモリ不足)

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 push失敗 (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' (テスト分割欠落)

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

シングルクラスデータセット: 「iteration over a 0-d tensor」

torchmetrics.MeanAveragePrecision はシングルクラスの場合、クラスごとのメトリクスに対してスカラー (0-d) テンソルを返します。テンプレート 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およびポイントプロンプト)
• 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、transforms、完全な例)
• references/hub_saving.md — 詳細なHub永続化ガイドと検証チェックリスト
• references/reliability_principles.md — プロダクション経験からの失敗防止原則

外部リンク

• Transformers 物体検出ガイド
• Transformers 画像分類ガイド
• DETRモデルドキュメンテーション
• ViTモデルドキュメンテーション
• HF Jobsガイド — メインJobsドキュメンテーション
• HF Jobs構成 — ハードウェア、シークレット、タイムアウト、ネームスペース
• HF Jobs CLIリファレンス — コマンドラインインターフェース
• 物体検出モデル
• 画像分類モデル
• SAM2モデルドキュメンテーション
• SAMモデルドキュメンテーション
• 物体検出データセット
• 画像分類データセット