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 分类器）
• 使用边界框或点提示词微调 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

前置条件检查清单

开始任何训练任务前，请确认：

账户与身份验证

• 拥有 Hugging Face 账户，并订阅 Pro、Team 或 Enterprise 计划（Jobs 需要付费计划）
• 已通过身份验证登录：使用 hf_whoami()（工具）或 hf auth whoami（终端）检查
• 令牌具有 write 权限
• 必须在任务密钥中传递令牌——语法请参阅下方指令 #3（MCP 工具与 Python API）

数据集要求 — 目标检测

• 数据集必须存在于 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 列
  • 或专用的 bbox 列，值为 [x0,y0,x1,y1]
  • 或专用的 point 列，值为 [x,y] 或 [[x,y],...]
• 边界框应采用 xyxy 格式（绝对像素坐标）
• 示例数据集：merve/MicroMat-mini（使用边界框提示词进行图像抠图）
• 在使用 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}")

两种方法之间的关键差异：

	hf_jobs MCP 工具	HfApi().run_uv_job()
script 参数	Python 代码字符串或 URL（不是本地路径）	.py 文件路径（不是文件内容）
secrets 中的 Token	"$HF_TOKEN"（自动替换）	get_token()（实际 Token 值）
超时格式	字符串（"4h"）	秒数（14400）

两种方法的规则：

• 训练脚本必须包含带依赖项的 PEP 723 内联元数据
• 不要使用 image 或 command 参数（这些参数属于 run_job()，不属于 run_uv_job()）

2. 通过作业机密进行身份验证 + 显式注入 hub_token

作业配置必须在机密中包含令牌——具体语法取决于提交方式（参见上方表格）。

训练脚本要求： 当 push_to_hub=True 时，Transformers Trainer 会在 __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）——在 Jobs 中不可靠
• 完整详情请参阅 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 传入。布尔参数有两种语法：

• 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 个 epoch）	1 小时
开发（500–1K 张图像，15–20 个 epoch）	2–3 小时
生产（1K–5K 张图像，30 个 epoch）	4–6 小时
大型数据集（5K+ 张图像）	6–12 小时

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	最佳入门选择——速度快、成本低、SOTA 质量
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	移动端 Transformer——准确率与速度之间的平衡良好
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 也绰绰有余。对于 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 对两种提交方法均相同。两者的关键区别请参阅指令 #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 数据集，使用 "785" 即约 10%）
• --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 内存不足）

减小 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”

只有一个类别时，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 分割训练脚本（边界框和点提示）
• scripts/dataset_inspector.py — 验证目标检测、分类和 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 模型文档
• 目标检测数据集
• 图像分类数据集