tao-finetune-huggingface-model

tao-finetune-huggingface-model

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

针对 HuggingFace 模型进行本地 NVIDIA GPU 微调，以实时获取的文档为依据，并以精选参考资料作为安全备用方案。一个 NGC 容器、几个专注的脚本，一次推送到 HF Hub。遵循本文件中的规则；不要自行发挥。

专用模型路由关卡

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

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 容器；任何基于虚拟环境的训练路径都需要用户明确提出要求。

优先级顺序（从高到低）：

1. 用户输入 — 明确指定的 model_id、dataset_id、training_method、config.yaml 覆盖项。
2. 实时研究 — 模型卡、HF 仓库示例、作者的微调脚本、HF 任务文档、论文；始终获取（步骤 3 + references/research-priorities.md）。
3. 精选参考资料（references/*.md）— 实时研究缺失或含糊时作为备用。
4. 你的训练数据记忆 — 最后手段；应视为可疑，并与（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}（默认：自动检测）。
• （省略） — Agent 推荐热门数据集 (来源：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 (per-step journal)
emit_report:       false   # reports/report.{pdf,html} with curves & samples
emit_unit_tests:   false   # tests/ with fake-data heterogeneous-batch 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 身份验证、挂载、环境变量透传、本地/远程 Docker 作业预检（守护进程、GPU 冒烟测试）	tao-skill-bank:tao-run-on-docker

默认平台： local-docker——构建一次性镜像（run-<short>:latest），并在本地 Docker 守护进程上运行。仅当用户明确需要其他后端（Brev 远程 GPU、SLURM/Kubernetes）时才询问；此时先运行该平台的预检，并通过该平台执行步骤 4–5 中的 docker run 命令。GPU 运行时和仅检查凭据是否存在的预检（绝不读取凭据值）、规范的 docker run 标志集、从已安装的平台技能中发现执行平台（tao-run-on-docker / -slurm / -kubernetes / -brev，以及任何外部平台；若运行时仅显示核心路由技能，则读取 skills/platform/tao-run-on-*/SKILL.md frontmatter），以及工作流专用标志（--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 参数 / collator / transforms（步骤 3）。
• 任何完整运行前，都要使用真实数据进行 --max_steps 1 冒烟测试；未通过验证的冒烟测试，不得启动批量作业。
• 绝不要擅自替换 model_id、dataset_id 或 training_method——如果用户要求的内容无法加载，就停止并询问。
• 错误恢复应尽量少改动。 OOM → 将 batch 减半、将 grad_accum 加倍、启用 gradient checkpointing（未经批准不得切换到 LoRA）；NaN → 将 LR 降低 10 倍；loss 持平 → 检查 collator；相同错误出现 3 次 → 停止并询问。不要循环重试。
• 必须在 collator 之前验证数据集列——在 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、在步骤 3 中填写的 research_sources: []、来自步骤 1 的 applicable_workarounds:、用于记录参考资料回退情况的 notes: []、默认值为 true 的 push_to_hub——带注释的模板见 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）：

1. GPU 主机运行时 — 执行 tao-setup-nvidia-gpu-host 的 setup-nvidia-gpu-host.sh --backend docker --check-only；如果失败，请求批准， 然后使用 --install --yes 重新运行。
2. 可用磁盘空间软警告 — 通过 MIN_DISK_GB 覆盖（默认值为 100 GB）；建议 ≥ 100 GB，用于 NGC 基础镜像（约 20 GB）+ HF 缓存 + 检查点 + 数据。
3. 按需检查凭据是否存在（绝不读取凭据值）— 仅当启用门控或启用 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 ≤ 检测到的 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（driver ≥ 545；存在 SDPA+GQA 错误 — 如果 num_key_value_heads < num_attention_heads，设置 attn_implementation: "eager"）。 在 config.yaml 中记录 ngc_image。

2c. 重新评估依赖硬件的兼容性规则： 重新检查 compat-workarounds.md 中 detect 需要 hw 的条目；就地更新 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 步不可省略。按优先级顺序 （Priority 1 → 6）查阅 references/research-priorities.md；针对检测到的任务，收集以下内容后即可停止：

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

将发现记录在 meta/recipe.md，并将来源 URL 附加到 config.yaml: research_sources:。如果某项没有实时调研结果，则使用匹配的脚手架 （cv-scripts.md / vlm-scripts.md），并在 notes: 下记录为“回退到脚手架 — 没有针对 的实时来源”。 冲突解决规则见 references/research-priorities.md。

门槛： 每个必需项均已填写，并附有来源 URL 或脚手架回退说明。

---

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

**目标：**编写所有脚本、构建镜像、准备数据，并使用真实数据运行 1 步冒烟测试（执行 1 次 docker build 和 2 次 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。以 Step 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）：

• 无异常
• Loss 为有限值（不是 0.0，也不是 NaN）
• 第 1 步时 grad_norm > 0

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

4c. 预检摘要 — 在完整训练之前，打印并核实：参考 URL、数据集列、Hub 目标、监控目标、NGC 镜像、硬件、冒烟测试 loss/grad norm。

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

---

步骤 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：loss 应在 10-20 步内下降；loss 持平（collator/标签屏蔽错误）、出现 NaN（LR 过高）和 OOM 都应停止运行——恢复方法见 references/core-rules.md。如果 emit_report: true，根据 references/reporting.md，在 Step 5e 后运行 report.py。

**关卡：**以下条件全部满足：

• checkpoints/final/（LoRA 时为 checkpoints/merged/）存在
• reports/eval_results.json 中包含数值型主指标
• reports/baseline_results.json 存在（除非已跳过）
• reports/inference_samples/ 中有 5 个样本
• wandb URL 显示 loss 逐渐下降

---

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

**目标：**发布本次运行结果，并确保无需重新研究即可复现。

根据 references/hub-push.md 推送（权重、模型卡、评估/基线 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 注释；缺少这些内容时，任何生成器都必须失败。

**关卡（完成标准）：**以下条件全部满足：

• 已满足 Step 5 的关卡要求
• HF Hub 仓库已在解析后的 URL 创建，其中包含权重、模型卡和 results/（除非 push_to_hub: false）
• <output_dir>/skills/run-<short>/SKILL.md 存在，没有遗留的 <placeholder>，并按照 pipeline-skill-template.md 包含元数据和版权 HTML 注释

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

---

错误处理手册

遇到已知运行时错误时，在重新设计任何内容之前，先查阅 references/error-playbook.md 中的“症状 → 最小修复”表 （NGC entrypoint、PyTorch/Transformers 回归问题、 numpy ABI、Albumentations bbox、PEFT/检查点、LoRA 目标范围、CV 数据增强缺失、步骤 0 时 OOM）。如果某一行在多次运行中触发两次，就将其移入 compat-workarounds.md，并添加 detect 规则 — 在步骤 1 中自动应用，避免错误触发。

---

沟通风格

• 简洁。不要填充内容，不要复述请求；适当时只用一个词回答。
• 提及工件时，始终附上直接的 Hub 和 wandb URL。
• 遇到错误：说明出了什么问题、原因以及你做了什么更改 — 不要提供选项菜单。
• 对于有明确答案的请求，绝不要给出“选项 A/B/C”。直接执行。