Name: HuggingFace模型微调Skill
Rating: 5 (1 reviews)
Author: tao-finetune-huggingface-model


名称	tao-finetune-huggingface-model
描述	> 当没有专用TAO模型技能匹配时，在NGC PyTorch容器内在本地NVIDIA GPU上微调任何HuggingFace CV / VLM / LLM模型。当用户想要微调HuggingFace模型（全量或LoRA）、端到端训练视觉/VLM/LLM模型、生成可复现的HF训练流水线、在扩展前在本地冒烟测试HuggingFace模型、将微调模型与模型卡推送到HF Hub，或为现有的HuggingFace微调发出一个自包含的重跑技能时使用。支持图像分类、目标检测、语义/实例/全景分割、深度估计、图像-文本到文本VLM（SFT / LoRA），以及LLM SFT / DPO / GRPO。六步工作流：检查并鉴定、硬件与NGC镜像、研究、生成并冒烟、训练+评估+推理、推送并生成重跑技能。不要用于由专用`skills/models/*`技能声明的任何Hugging Face模型ID；模型技能及其声明的执行环境优先。
开源协议	Apache-2.0 tags: - finetuning - huggingface - nvidia-tao - computer-vision - training metadata:
作者	NVIDIA Corporation
版本	“0.1.0” allowed-tools: Read Bash Write

tao-finetune-huggingface-model

独立安装？ 如果此会话不是由TAO技能库插件初始化的，请先运行tao-setup技能（主机预检、凭据、跨技能发现）。

本地NVIDIA GPU微调HuggingFace模型，以实时获取的文档为基础，并以整理好的参考资料作为后备安全网。一个NGC容器、几个重点脚本、一次推送到HF Hub。遵守本文件中的规则；不要即兴发挥。

专用模型路由门

在步骤1或任何探测、镜像选择、软件包安装、虚拟环境创建或训练代码生成之前，请根据打包的模型所有者注册表解析model_id。使用加载此文件所用的绝对技能库根路径：

python <bank-root>/scripts/resolve_tao_model.py \
  --skill-bank <bank-root> \
  --model "$MODEL_ID" \
  --format json

解析器匹配模型元数据，包括huggingface_model_ids、network_arch、技能名称和旧别名。路由是内部的：模型ID和任务就足够了。永远不要要求用户提供关于技能、容器或检查点格式的样板提示。

退出0：停止此工作流并遵循所属模型技能的环境、操作元数据、预检和检查点准备。
退出3：没有打包的模型技能拥有该ID。这是唯一允许进入通用工作流步骤1的结果。
任何其他非零退出：所有权发现已损坏或存在歧义。停止并解决该错误；不要静默回退到通用Hugging Face训练。

Hugging Face托管永远不会覆盖所有权。不要使用此工作流绕过匹配的技能或要求用户规定其内部准备。例如，nvidia/Cosmos3-Nano路由到tao-finetune-cosmos-reason。

不要在此工作流中创建主机训练虚拟环境。其默认执行路径是下面记录的NGC容器；基于虚拟环境的训练路径需要明确的用户请求。

权限顺序（最高优先）：

用户输入 — 明确的model_id、dataset_id、training_method、config.yaml覆盖。
实时研究 — 模型卡、HF仓库示例、作者微调脚本、HF任务文档、论文；始终获取（步骤3 + references/research-priorities.md）。
整理好的参考资料（references/*.md）— 当实时研究无结果或含糊时作为后备。
你的训练数据记忆 — 最后的手段；不可信，与(2)/(3)交叉核对。

(2)和(3)之间的冲突解决以及源代码行差异说明见references/research-priorities.md。

输入

必需：

model_id — HuggingFace模型ID，例如google/vit-base-patch16-224

条件凭据（从会话环境读取，存在并在启动前导出）：

HF_TOKEN — 仅当模型/数据集受控（读取）或push_to_hub开启（写入）时需要；公开+公开+push_to_hub: false则不需要。值永远不读取——仅通过[ -n "$HF_TOKEN" ]检查是否存在。
WANDB_API_KEY、WANDB_PROJECT — 仅在启用WandB时需要；WANDB_MODE=disabled可选择退出。

数据集 — 恰好一个：

dataset_id — HuggingFace数据集ID (来源：hf)
local_dataset_path — 本地文件夹或文件 (来源：local)；可选local_dataset_format ∈ {auto, imagefolder, coco, voc, jsonl, arrow, parquet, csv}（默认：自动检测）。
(省略) — 代理推荐流行数据集 (来源：recommend)

可选（有默认值）：

task_type — 根据配置和模型卡自动检测
n_train=10000、n_eval=1000、n_epochs=3、lora_r=16
output_dir=./output/<model_short_name>
hf_model_repo — 推送目标；如果未设置且HF_TOKEN具有写入权限，自动推导为<whoami>/<model_short_name>-finetuned。
push_to_hub=True — 设置为False以跳过
skip_baseline=False — 跳过零样本基线评估

可选交付物（默认关闭）：

emit_progress_log: false   # output_dir/PROGRESS.md（逐步日志）
emit_report:       false   # reports/report.{pdf,html}，包含曲线和样本
emit_unit_tests:   false   # tests/，包含假数据的异构批处理测试

所有值都存在于output_dir/config.yaml中。不要硬编码到Python中。

执行平台

此技能编排要运行的内容；平台技能拥有如何在GPU主机上运行的权利 — 请先阅读它们。

关注点	权威技能
GPU主机运行时（驱动580、CUDA Toolkit 13.0、NVIDIA Container Toolkit 1.19.0）	`tao-skill-bank:tao-setup-nvidia-gpu-host`
`docker run`标志、NGC认证、挂载、环境透传	`tao-skill-bank:tao-run-on-docker`
本地Docker作业预检（守护进程、GPU冒烟）	`tao-skill-bank:tao-run-on-local-docker`

默认平台： local-docker — 构建一次性镜像（run-<short>:latest）并在本地Docker守护进程上运行它。仅当用户明确需要不同的后端（Brev远程GPU、SLURM/Kubernetes）时才询问；然后先运行该平台的预检并将其步骤4-5的docker run命令路由到该平台。GPU运行时和仅存在凭据的预检（值从不读取）、规范docker run标志集、list_tao_platforms.py选择命令以及工作流特定标志（--entrypoint /bin/bash -lc、PYTORCH_CUDA_ALLOC_CONF、--name hft_train）都在references/workflow-intake-preflight.md中。

参考资料 — 后备安全网

仅当实时研究无结果、含糊或不可用时查阅；实时文档对特定模型和当前API总是胜出。每个步骤链接它需要的参考资料；完整目录在references/detailed-workflow.md中。

始终开启：core-rules.md、error-playbook.md、compat-workarounds.md、model-discovery.md、dataset-recommendations.md、dataset-sources.md、dataset-patterns.md、hardware-container.md、research-priorities.md、cv-scripts.md、vlm-scripts.md、docker-runs.md、hub-push.md、pipeline-skill-template.md、deliverables.md。可选（当其标志/需求适用时）：progress-tracking.md、testing.md、reporting.md、workflow-intake-preflight.md、workflow-generate-train.md、workflow-push-rerun.md。

规则： 在回退之前，记录你尝试过的实时源以及不足的原因（config.yaml中的notes:，以及如果启用了PROGRESS.md）。cv-scripts.md / vlm-scripts.md中的[FETCH LIVE]标记是研究清单，不是要内联的代码 — 如果某个块没有步骤3的发现，则重新获取列出的URL。

核心规则

不可协商的行为。短版（完整列举 — 幻觉导入列表、未经批准绝不做的列表、完整的错误恢复和硬件规模表 — 在references/core-rules.md中，在任何训练时决策前查阅）：

你的HF库知识已经过时。 在编写任何ML代码之前获取实时文档（模型卡、HF仓库示例、任务文档）— 不要凭记忆生成trainer参数 / 数据整理器 / 变换（步骤3）。
在真实数据上使用--max_steps 1进行冒烟测试 在任何完整运行之前；没有经过验证的冒烟测试，不批量启动。
绝不静默替换 model_id、dataset_id或training_method — 如果用户要求的内容无法加载，停下来询问。
错误恢复是最小变更。 OOM → 批大小减半、梯度累积加倍、启用梯度检查点（未经批准不切换LoRA）；NaN → 学习率降低10倍；损失平坦 → 检查数据整理器；同一错误3次 → 停下来询问。不要循环。
在数据整理器之前验证数据集列 — 在prepare_data.py中重命名；如果需要进行结构重组 → 停下来询问。
硬件规模经验法则（bf16）： ≤3B → 24 GB，7–13B → 80 GB，30B+ → 多GPU或1×80 GB上LoRA，70B+ → 8×80 GB或LoRA。全量微调无法容纳且未请求LoRA → 在切换前询问。

工作流 — 6个步骤

单次通过，顺序执行；每个步骤在进入下一步前都有明确的关口。

步骤1 — 检查并鉴定

目标： 决定是否继续。探测模型+数据集，应用接受/拒绝，注册适用的兼容性修复，写入初始config.yaml。

前置条件：MODEL_ID、可选DATASET_ID / local_dataset_path、可选HF_TOKEN、OUTPUT_DIR（默认./output/<model_short_name>）。探测在仅CPU的python:3.12-slim Docker容器中运行（绑定挂载.probe/临时空间），因此主机不需要虚拟环境 — 但Docker必须先存在。Docker存在性保护、容器环境、完整探测调用以及模型/数据集探测脚本在references/workflow-intake-preflight.md、references/model-discovery.md和references/dataset-sources.md中。

探测要求：

模型：加载AutoConfig，读取模型卡标签，根据architectures + 标签 + 卡片示例检测任务（后备日志记录在model-discovery.md中）。
数据集：对于推荐数据集，首先从dataset-recommendations.md中呈现3-5个选择；对于本地数据，以只读方式绑定挂载并使用dataset-sources.md的格式检测。
如果模型配置失败、任务超出范围、不存在配方源或数据集无法加载/匹配任务模式，则提前拒绝。
根据模型/任务评估compat-workarounds.md；将依赖硬件的规则推迟到步骤2。

写入初始config.yaml（model_id、task、dataset_id或local_dataset_path、research_sources: []在步骤3填充、applicable_workarounds:来自步骤1、notes: []用于参考回退、push_to_hub: true默认 — 带注释的模板在references/workflow-intake-preflight.md中）。可选地，一旦满足关口，rm -rf "$OUTPUT_DIR/.probe"。

关口： config.yaml存在，包含模型、数据集、任务、applicable_workarounds；如果任何字段缺失，不要继续。

步骤2 — 硬件审计和NGC镜像

目标： 验证Docker + GPU +磁盘，实时选择NGC PyTorch镜像，最终确定依赖硬件的兼容规则。

2a. 审计（硬性关口） — 三项检查（命令在references/workflow-intake-preflight.md中）：

GPU主机运行时 — tao-setup-nvidia-gpu-host的setup-nvidia-gpu-host.sh --backend docker --check-only；失败时，获得批准后使用--install --yes重新运行。
磁盘空间不足软警告 — 通过MIN_DISK_GB覆盖（默认100 GB）；NGC基础（约20 GB）+ HF缓存 + 检查点 + 数据推荐≥100 GB。
条件凭据存在性（来自会话环境，值从不读取） — 仅当受控或push_to_hub开启时需要HF_TOKEN；仅当WandB开启时需要WANDB_*。

在硬性失败时不要继续到步骤4 — 步骤4的docker build会拉取20+ GB的NGC基础镜像，而缺少nvidia-container-toolkit只会后来以could not select device driver "" with capabilities: [[gpu]]出现。在config.yaml中记录gpu_count、gpu_name、driver_major、vram_gb_per_gpu。

2b. 选择NGC镜像（实时）： 从NVIDIA深度学习框架支持矩阵（https://docs.nvidia.com/deeplearning/frameworks/support-matrix/index.html）的PyTorch NGC容器部分，选择满足Min driver ≤ detected driver_major且容器CUDA ≤ 主机CUDA Toolkit的最高版本镜像（紧密匹配，以便cuDNN / TensorRT对齐）。不要因为PyTorch标签上的aN/bN/rcN而拒绝镜像 — NGC验证完整镜像；选择最新的CUDA对齐的一个，并让compat-workarounds.md处理每版本问题。如果矩阵不可达，使用references/hardware-container.md中的后备；默认nvcr.io/nvidia/pytorch:24.09-py3 （驱动≥545；SDPA+GQA bug — 如果num_key_value_heads < num_attention_heads，设置attn_implementation: "eager"）。在config.yaml中记录ngc_image。

2c. 重新评估依赖硬件的兼容规则： 为detect需要hw的条目重新运行compat-workarounds.md遍历；就地更新applicable_workarounds:。

2d. 模型适配检查： 估算param_bytes ≈ 2×param_count（bf16）；如果> vram_gb_per_gpu × 1e9的60%，在面向用户的摘要中推荐LoRA。

关口： config.yaml具有ngc_image、gpu_count、gpu_name、driver_major、vram_gb_per_gpu；记录依赖硬件的兼容修复。

步骤3 — 研究配方

目标： 获取实时配方 — 对transformers/trl/peft的训练数据知识是不可信的，因此步骤3是不可协商的。按优先顺序（优先级1 → 6）遍历references/research-priorities.md；一旦你获得检测任务的以下内容就停止：

AutoModel / 处理器类
训练+评估变换
数据整理器
compute_metrics
超参数提示（学习率、批大小、epochs、调度器）

将发现记录在meta/recipe.md中，将源URL附加到config.yaml: research_sources:。没有实时发现的槽位回退到匹配的脚手架（cv-scripts.md / vlm-scripts.md），在notes:下记录为“回退到脚手架 — 没有实时源用于<槽位>”。冲突解决规则在references/research-priorities.md中。

关口： 每个必需槽位都已填写，带有源URL或脚手架回退说明。

步骤4 — 生成项目并进行冒烟测试

目标： 编写所有脚本、构建镜像、准备数据、在真实数据上运行1步冒烟测试（一次docker build，两次docker run）。

4a. 生成项目文件 在output_dir/中：config.yaml、Dockerfile、requirements.txt、prepare_data.py、train.py、run_eval.py、infer.py、可选merge_lora.py、可选tests/、.gitignore。实时步骤3研究是权威；cv-scripts.md / vlm-scripts.md 只给出脚手架形状。将每个applicable_workarounds条目应用为Dockerfile块、需求固定、配置覆盖或运行时环境变量。硬性规则：run_eval.py保持该确切文件名（避免与HF evaluate包冲突）；每个生成的.py以NVIDIA Apache-2.0版权头开头，任何生成器在缺失时都会失败；emit_unit_tests: true按references/testing.md生成并运行测试。脚本主体、Dockerfile形状和生成器约定在references/workflow-generate-train.md中。

4b. 构建、准备、冒烟 — docker build -t run-<short>:latest .，然后prepare_data和--smoke --max_steps 1运行（references/docker-runs.md §1-3）。冒烟通过标准（在logs/smoke.log中）：

无异常
损失有限（不是0.0，不是NaN）
步骤1时grad_norm > 0

如果emit_unit_tests: true，还要在容器中运行pytest tests/。任何失败 → 停止。

4c. 预检摘要 — 在完整训练前，打印并验证：参考URL、数据集列、Hub目标、监控目标、NGC镜像、硬件、冒烟损失/梯度范数。

关口： 项目文件已写入，镜像已构建，冒烟测试通过，预检没有空白字段。

步骤5 — 训练、评估、推理

目标： 基线评估、完整训练、训练后评估、可选的LoRA合并、5个推理样本（所有命令：references/docker-runs.md §4-8）。

子步骤	docker-runs.md	如果以下情况则跳过
5a. 基线评估（零样本）	§4	`skip_baseline: true`
5b. 完整训练（分离）	§5	—
5c. LoRA合并	§6	不是VLM+LoRA
5d. 训练后评估	§7	—
5e. 推理（5个样本）	§8	—

多GPU：在python train.py前加torchrun --nproc_per_node=$gpu_count。

训练流式输出时，观看docker logs -f hft_train：损失应在10-20步内下降；平坦损失（数据整理器/标签掩码错误）、NaN（学习率太高）和OOM都会停止运行 — 恢复方法在references/core-rules.md中。如果emit_report: true，在步骤5e后按references/reporting.md运行report.py。

关口： 所有以下项：

checkpoints/final/（对于LoRA为checkpoints/merged/）存在
reports/eval_results.json具有数值主指标
reports/baseline_results.json存在（除非跳过）
reports/inference_samples/有5个样本
wandb URL显示下降的损失

步骤6 — 推送并生成重跑技能

目标： 发布运行并无须重新研究使其可重现。

按references/hub-push.md推送（权重、模型卡、eval/baseline JSON、config.yaml、Dockerfile、requirements.txt、推理样本、生成报表时包括报表），除非push_to_hub: false明确。从references/pipeline-skill-template.md生成<output_dir>/skills/run-<short>/SKILL.md — 替换每个占位符，包括完整的YAML元数据和NVIDIA版权HTML注释，并使任何生成器在缺失时失败。

关口（完成标准）： 所有以下项：

步骤5关口已满足
HF Hub仓库存在于解析后的URL，包含权重 + 卡片 + results/（除非push_to_hub: false）
<output_dir>/skills/run-<short>/SKILL.md存在，没有<placeholder>遗留，带元数据和版权HTML注释，符合pipeline-skill-template.md

最终消息：wandb URL、HF Hub URL、基线 → 微调后的主指标、reports/inference_samples/、以及重跑技能路径。

错误手册

遇到已知运行时错误时，在重新设计任何内容之前，查阅references/error-playbook.md中的症状→最小修复表（NGC入口点、PyTorch/Transformers回归、numpy ABI、Albumentations bbox、PEFT/检查点、LoRA目标广度、CV增强差距、第0步OOM）。当一行在该表中跨运行触发两次时，将其提升到具有detect规则的compat-workarounds.md — 在步骤1中在错误可能触发之前自动应用。

沟通风格

简洁。没有填充词，不重述请求；适当的时候用一个词回答。
引用工件时始终包含直接Hub和wandb URL。
出错时：说明出了什么问题、原因、你更改了什么 — 不要列出菜单。
对于具有明确答案的请求，绝不呈现“选项A/B/C”。行动起来。

HuggingFace模型微调Skill tao-finetune-huggingface-model