在托管的云 GPU 上训练目标检测、图像分类和 SAM/SAM2 分割模型。无需本地 GPU 设置——结果会自动保存到 Hugging Face Hub。

辅助脚本使用 PEP 723 内联依赖。使用 uv run 运行它们：

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

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

在启动 GPU 训练之前验证数据集格式，以防止训练失败的头号原因：格式不匹配。

始终验证未知/自定义数据集或任何你之前没有用过进行训练的数据集。跳过cppe-5（训练脚本中的默认值）。

选项 1：通过 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

选项 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,
)

目标检测训练脚本（scripts/object_detection_training.py）会自动处理边界框格式检测（xyxy→xywh转换）、边界框清理、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

在花费 GPU 时间之前运行数据集检查器。请参阅上面的“数据集验证”部分。

始终使用带选项格式的 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
        }
    ]
})

对于目标检测，请使用 scripts/object_detection_training.py 作为生产就绪模板。对于图像分类，请使用 scripts/image_classification_training.py。对于 SAM/SAM2 分割，请使用 scripts/sam_segmentation_training.py。所有脚本都使用 HfArgumentParser —— 所有配置都通过 CLI 参数在 script_args 中传递，而不是通过编辑 Python 变量。有关 timm 模型的详细信息，请参见 references/timm_trainer.md。有关 SAM2 训练的详细信息，请参见 references/finetune_sam2_trainer.md。

第5步：保存脚本、提交作业并报告

这些规则可以防止常见的故障。请严格遵守它们。

1. 作业提交：hf_jobs MCP 工具 vs 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}")

script param Python code string or URL (NOT local paths) File path to .py file (NOT content)

Token in secrets "$HF_TOKEN" (auto-replaced) get_token() (actual token value)

Timeout format String ("4h") Seconds (14400)

2. 通过作业密钥进行身份验证 明确的 hub_token 注入

作业配置 必须在 secrets 中包含令牌——语法取决于提交方法（见上表）。

训练脚本要求: 当 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(...) 之前包含这个令牌注入。

使用 .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 传递。布尔参数有两种语法：

--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

--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

默认 30 分钟对于目标检测来说太短了。设置最少 2-4 小时。为模型加载、预处理和 Hub 推送增加 30% 的缓冲时间。

Quick test (100-200 images, 5-10 epochs) 1h

Development (500-1K images, 15-20 epochs) 2-3h

Production (1K-5K images, 30 epochs) 4-6h

在目标检测训练脚本中，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 Best starting point — fast, cheap, SOTA quality

PekingU/rtdetr_v2_r18vd 20.2M Lightweight real-time detector

Hugging Face Vision Trainer 实用指南

Trains and fine-tunes vision models for object detection (D-FINE, RT-DETR v2, DETR, YOLOS), image classification (timm models — MobileNetV3, MobileViT, ResNet, ViT/DINOv3 — plus any Transformers classifier), and SAM/SAM2 segmentation using Hugging Face Transformers on Hugging Face Jobs...

人工智能

开发工具

云计算

Hugging Face Vision Trainer 实战指南：零门槛微调目标检测、图像分类与SAM/SAM2分割模型。支持云GPU训练、自动Hub持久化，涵盖D-FINE、RT-DETR、ViT等主流模型。提供数据集验证、成本估算、超时管理及故障排查，附完整脚本模板，助你快速上手视觉模型训练。

身份验证

Python

Agent

JSON

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

Hugging Face Vision Trainer 实用指南

Hugging Face Vision Trainer 实用指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐