---

source: "https://github.com/huggingface/skills/tree/main/skills/huggingface-vision-trainer" name: hugging-face-vision-trainer description: 在 Hugging Face Jobs 上训练或微调视觉模型，用于检测、分类和 SAM 或 SAM2 分割。 risk: unknown

在 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

前提条件清单

在开始任何训练任务之前，请验证：

账户与认证

• 拥有 Pro、Team 或 Enterprise 计划的 Hugging Face 账户（Jobs 需要付费计划）
• 已认证登录：使用 hf_whoami()（工具）或 hf auth whoami（终端）检查
• 令牌具有写入权限
• 必须在任务密钥中传递令牌 — 语法见下方指令 #3（MCP 工具 vs Python API）

数据集要求 — 目标检测

• 数据集必须存在于 Hub 上
• 标注必须使用 objects 列，包含 bbox、category（以及可选的 area）子字段
• 边界框可以是 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 列（二值真值分割掩码）
• 必须有提示 — 以下任一：
  • 包含 JSON 的 prompt 列，格式为 {"bbox": [x0,y0,x1,y1]} 或 {"point": [x,y]}
  • 或专用的 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"、密钥中的令牌

数据集验证

在启动 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