在 Hugging Face Jobs 云 GPU…

当需要在 Hugging Face Jobs 云 GPU 上微调目标检测、图像分类或 SAM/SAM2 分割模型时，用这套流程完成数据校验、任务提交、监控与 Hub 持久化。

适用场景

解决思路

1. 先核对前置条件：Hugging Face 账号需为 Pro/Team/Enterprise 付费计划；用 `hf_whoami()` 或 `hf auth whoami` 确认已登录；token 需有 write 权限；token 必须通过 job secrets 传入。
2. 按任务类型核对数据集要求：目标检测需 `objects` 列含 `bbox`、`category`（可选 `area`），bbox 支持 xywh(COCO) 或 xyxy(Pascal VOC) 自动检测转换，类别可为整数或字符串自动重映射，`image_id` 可选自动生成；图像分类需 `image` 列(PIL)和 `label` 列(整数或字符串)，常见列名 `label`/`labels`/`class`/`fine_label` 会自动识别；SAM/SAM2 分割需 `image` 列和 `mask` 列(二值掩码)，以及 prompt（`prompt` 列 JSON 含 `{"bbox":[x0,y0,x1,y1]}` 或 `{"point":[x,y]}`，或独立 `bbox` 列 xyxy 绝对像素，或独立 `point` 列）。
3. 在启动 GPU 训练前先运行 `scripts/dataset_inspector.py` 校验数据集格式（未知/自定义数据集必做，`cppe-5` 可跳过）。可通过 HF Jobs 运行（推荐，避免本地 SSL/依赖问题）：`hf_jobs("uv", {"script": "path/to/dataset_inspector.py", "script_args": ["--dataset", "username/dataset-name", "--split", "train"]})`；或本地 `uv run scripts/dataset_inspector.py --dataset username/dataset-name --split train`；或用 `HfApi().run_uv_job(script="scripts/dataset_inspector.py", script_args=[...], flavor="cpu-basic", timeout=300)`。结果 `✓ READY` 可直接用，`✗ NEEDS FORMATTING` 需按输出提供的映射代码预处理。
4. 目标检测的 bbox 预处理由 `scripts/object_detection_training.py` 自动完成（xyxy→xywh 转换、bbox 清洗、生成 `image_id`、字符串类别转整数、数据集截断），无需手动预处理，只需保证有 `objects.bbox` 和 `objects.category` 列。
5. 按训练清单推进：Step 1 核对前置条件（账号、token、数据集）；Step 2 运行 dataset_inspector.py 校验格式；Step 3 用 AskUserQuestion 询问数据集规模与验证集划分；Step 4 准备训练脚本（OD 用 `scripts/object_detection_training.py`，IC 用 `scripts/image_classification_training.py`，SAM 用 `scripts/sam_segmentation_training.py`）；Step 5 本地保存脚本、提交任务并报告详情。
6. 用 AskUserQuestion 以选项形式询问用户三件事：是否先用 10% 数据快速测试（约 30-60 分钟、约 $2-5）还是全量训练；是否从训练数据自动划分 15% 作为验证集；选择 GPU 硬件（t4-small $0.40/hr、l4x1 $0.80/hr、a10g-large $1.50/hr、a100-large $2.50/hr）。
7. 训练脚本统一用 `HfArgumentParser`，所有配置通过 `script_args` 的 CLI 参数传入，不要直接改 Python 变量。timm 模型细节见 `references/timm_trainer.md`，SAM2 训练细节见 `references/finetune_sam2_trainer.md`。
8. 提交任务时把脚本保存到工作区根的 `submitted_jobs/` 目录，命名如 `training_<dataset>_<YYYYMMDD_HHMMSS>.py` 并告知用户路径；用 `hf_jobs` MCP 工具（优先）或 `HfApi().run_uv_job()` 提交，所有配置通过 `script_args` 传入；报告 job ID（取 `.id` 属性）、监控 URL、Trackio 面板 `https://huggingface.co/spaces/{username}/trackio`、预计时间与成本；等待用户主动请求状态检查，不要自动轮询。
9. 区分两种提交方式：`hf_jobs()` 是 MCP 工具不是 Python 函数，不能从 `huggingface_hub` 导入，调用形式为 `hf_jobs("uv", {"script": training_script_content, "flavor": "a10g-large", "timeout": "4h", "secrets": {"HF_TOKEN": "$HF_TOKEN"}})`；若 MCP 工具不可用则用 Python API `api.run_uv_job(script="path/to/training_script.py", script_args=[...], flavor="a10g-large", timeout=14400, env={"PYTHONUNBUFFERED": "1"}, secrets={"HF_TOKEN": get_token()})`。两者差异：`script` 参数 MCP 传代码字符串或 URL（不能是本地路径），Python API 传 `.py` 文件路径（不能是内容）；secrets 中 token MCP 用 `"$HF_TOKEN"` 自动替换，Python API 用 `get_token()` 实际值；timeout MCP 用字符串 `"4h"`，Python API 用秒数 `14400`。两种方式都要求训练脚本含 PEP 723 内联依赖元数据，且不要用 `image` 或 `command` 参数（那属于 `run_job()` 而非 `run_uv_job()`）。
10. 认证：job 配置必须把 token 放进 secrets；训练脚本必须在解析参数之后、创建 `Trainer` 之前把 `HF_TOKEN` 注入 `training_args.hub_token`（模板已含：`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`）；自定义脚本必须包含此注入；不要在自定义脚本中调用 `login()`（除非完整复刻模板模式）；不要依赖隐式 token 解析（`hub_token=None` 在 Jobs 中不可靠）。
11. 用 `.id` 获取 job 标识（不是 `.job_id` 或 `.name`，这两个不存在）：`job_id = job_info.id`，返回形如 `"687fb701029421ae5549d998"` 的字符串。
12. 注意 HfArgumentParser 的布尔语法：`bool` 字段用裸标志（`--push_to_hub`）或用 `--no_` 前缀取反（`--no_remove_unused_columns`）；`Optional[bool]` 字段必须显式传值（`--greater_is_better True`），裸写 `--greater_is_better` 会报 `error: expected one argument`。
13. 目标检测必传标志：`--no_remove_unused_columns`（保留 image 列供 pixel_values）、`--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）、`--do_train`、`--do_eval`。
14. 图像分类必传标志：`--no_remove_unused_columns`、`--push_to_hub`、`--hub_model_id username/model-name`、`--metric_for_best_model eval_accuracy`、`--greater_is_better True`（必须显式传 True）、`--do_train`、`--do_eval`。
15. 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 问题）。
16. 设置超时：默认 30 分钟太短，目标检测最少 2-4 小时，并为模型加载、预处理和 Hub 推送预留 30% 缓冲。参考：快速测试（100-200 图、5-10 epoch）1h；开发（500-1K 图、15-20 epoch）2-3h；生产（1K-5K 图、30 epoch）4-6h；大数据集（5K+ 图）6-12h。
17. 监控：目标检测脚本始终启用 Trackio（自动调用 `trackio.init()` 和 `trackio.finish()`），无需传 `--report_to trackio`，项目名取自 `--output_dir`、运行名取自 `--run_name`；图像分类需在 TrainingArguments 中传 `--report_to trackio`。面板地址 `https://huggingface.co/spaces/{username}/trackio`。
18. 选择模型：目标检测推荐 `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)、`PekingU/rtdetr_v2_r101vd`(76M)；图像分类推荐 `timm/mobilenetv3_small_100.lamb_in1k`(2.5M，快速迭代)、`timm/mobilevit_s.cvnets_in1k`(5.6M)、`timm/resnet50.a1_in1k`(25.6M)、`timm/vit_base_patch16_dinov3.lvd1689m`(86.6M)；SAM/SAM2 推荐 `facebook/sam2.1-hiera-tiny`(38.9M)、`facebook/sam2.1-hiera-small`(46.0M，最佳起点)、`facebook/sam2.1-hiera-base-plus`(80.8M)、`facebook/sam2.1-hiera-large`(224.4M)、`facebook/sam-vit-base`(93.7M)、`facebook/sam-vit-large`(312.3M)、`facebook/sam-vit-huge`(641.1M)。
19. 选择硬件：所有推荐 OD/IC 模型均低于 100M 参数，`t4-small`(16 GB VRAM, $0.40/hr) 足够；SAM2 到 `hiera-base-plus` 用 `t4-small` 也够（只训练 mask decoder）；`sam2.1-hiera-large` 或 SAM v1 用 `l4x1` 或 `a10g-large`。只有大 batch 导致 OOM 才升级硬件，先降 batch size。升级路径：`t4-small` → `l4x1`($0.80/hr, 24 GB) → `a10g-large`($1.50/hr, 24 GB)。
20. 目标检测快速启动的 `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`。关键参数：`--image_square_size` 用 480（快速迭代）或 800（更高精度）；`--train_val_split` 默认 0.15；`--max_train_samples`/`--max_eval_samples` 可截断做快速测试。
21. 图像分类快速启动的 `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`。关键参数：`--image_column_name` 默认 `"image"`；`--label_column_name` 默认 `"label"`；分类通常 3-5 epoch；batch size 16-64。
22. SAM/SAM2 快速启动的 `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`。关键参数：`--prompt_type` 为 `"bbox"` 或 `"point"`；`--bbox_column_name`/`--point_column_name` 可替代 JSON prompt 列；`--mask_column_name` 默认 `"mask"`；`--freeze_vision_encoder`/`--freeze_prompt_encoder` 默认都冻结只训 mask decoder；`--train_val_split` 默认 0.1。
23. 检查任务状态：MCP 工具用 `hf_jobs("ps")` 列任务、`hf_jobs("logs", {"job_id": "your-job-id"})` 看日志、`hf_jobs("inspect", {"job_id": "your-job-id"})` 看详情；Python API 用 `api.list_jobs()`、`api.get_job_logs(job_id="your-job-id")`、`api.get_job(job_id="your-job-id")`。
24. 处理常见失败：OOM 时降低 `per_device_train_batch_size`（先试 4 再试 2）、降低 `IMAGE_SIZE` 或升级硬件；数据集格式错误先跑 `scripts/dataset_inspector.py`，确保 `objects.bbox` 是绝对像素的 4 值列表、`objects.category` 是整数或字符串；Hub 推送 401 时检查 job secrets 含 token、脚本在创建 `Trainer` 前设置 `training_args.hub_token`、`push_to_hub=True`、`hub_model_id` 正确、token 有 write 权限；任务超时则增加 timeout、减少 epoch/数据集或用 `hub_strategy="every_save"` 检查点策略；`KeyError: 'test'` 时用最新 `scripts/object_detection_training.py`（会回退到 validation split）；单类别数据集报 "iteration over a 0-d tensor" 时用最新模板（对 0-d 张量调用 `.unsqueeze(0)`）；检测性能差（mAP < 0.15）时增加 epoch 到 30-50、确保 500+ 图、检查各类别 mAP、尝试 1e-5 到 1e-4 学习率、增大图像尺寸。
25. 参考文件：`scripts/object_detection_training.py`、`scripts/image_classification_training.py`、`scripts/sam_segmentation_training.py`、`scripts/dataset_inspector.py`、`scripts/estimate_cost.py`、`references/object_detection_training_notebook.md`、`references/image_classification_training_notebook.md`、`references/finetune_sam2_trainer.md`、`references/timm_trainer.md`、`references/hub_saving.md`、`references/reliability_principles.md`。

适用边界 · 注意事项

• 非训练类的 HF Jobs 问题（如 secrets 机制、可用硬件、token 传递）应参考 `hugging-face-jobs` 技能。
• 基于 TRL 的语言模型训练（SFT、DPO、GRPO）应使用 `hugging-face-model-trainer` 技能。
• 需要付费 Hugging Face 计划（Pro/Team/Enterprise）才能使用 Jobs，无付费账号时无法按此流程执行。