tao-finetune-huggingface-model

tao-finetune-huggingface-model

针对 HuggingFace 模型的本地 NVIDIA GPU 微调，以实时获取的文档为依据，并以精选参考资料作为备用保障。一个 NGC 容器、一小组专用脚本，一次推送到 HF Hub。行为由本文件中的规则决定——请遵守，不要自行发挥。

权威顺序（从高到低）：（1）用户输入 →（2）实时调研（模型卡、HF 仓库示例、作者脚本、任务文档、论文——始终获取，步骤 3）→（3）精选的 references/*.md（实时调研未提供信息时的备用资料）→（4）训练数据记忆（最后手段，需谨慎对待）。如有冲突，针对特定模型和当前 API 的实时调研优先。完整的顺序和冲突解决规则请参阅 references/core-rules.md。

---

输入

必需：

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

条件凭据（由 SessionStart hook 从 ~/.config/tao/.env 加载）：

• HF_TOKEN — 仅当模型／数据集为受限访问（读取），或启用了 push_to_hub（写入）时需要；运行公开模型且 push_to_hub: false 时无需此凭据。Agent 不会读取其值——只通过 [ -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 → output_dir/PROGRESS.md（按步骤记录 ✅/⚠️/❌）；emit_report → 包含曲线和样例的 reports/report.{pdf,html}；emit_unit_tests → 使用伪造数据进行异构批次测试的 tests/。

所有值都存放在 output_dir/config.yaml 中。切勿在 Python 中硬编码。

---

执行平台

本技能负责协调运行什么；平台技能负责如何运行（请先阅读，不要在此重复编写其约定）： tao-setup-nvidia-gpu-host （GPU 主机运行时——driver 580、CUDA Toolkit 13.0、NVIDIA Container Toolkit 1.19.0）、tao-run-on-docker （docker run 标志、NGC 身份验证、--gpus、挂载、环境变量传递、 --ipc=host／--shm-size、错误模式），以及 tao-run-on-local-docker （本地 Docker 作业预检——守护进程可访问、GPU 冒烟测试）。

默认平台： local-docker——构建一次性镜像 （run-<short>:latest），并在本地 Docker 守护进程上运行。只有在用户需要其他后端（Brev、Lepton/SLURM/Kubernetes）时才询问。此路径以及备用后端路由、GPU 运行时预检、凭据策略和 docker run 约定，请参阅 references/execution-platform.md。

---

参考资料 — 后备安全网

只有在实时调研没有结果、存在歧义或无法进行时，才会查阅精选的 references/*.md；针对特定模型和当前 API，始终以实时文档为准。以下工作流步骤会直接链接每一步所需的文件。使用后备资料前，记录你尝试过的实时来源以及它为何不足（写入 config.yaml 的 notes:，若启用，还要写入 PROGRESS.md）。cv-scripts.md / vlm-scripts.md 中的 [FETCH LIVE] 标记是调研清单，不是要内联的代码——如果某个代码块没有 Step 3 的发现，就重新获取所列 URL 的内容。

完整索引见 references/reference-index.md，其中包含所有常驻参考资料，以及由标志控制的三个可选参考资料（progress-tracking.md ← emit_progress_log、testing.md ← emit_unit_tests、reporting.md ← emit_report），并说明了每个文件在各步骤中的作用。

---

核心规则

不可妥协的行为。完整内容见 references/core-rules.md。 简要版：

• 你对 HF 库的了解已经过时。 编写任何 ML 代码前，先获取实时文档；绝不可凭记忆生成 trainer 参数 / collator / transforms（Step 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 → 询问。

references/core-rules.md 包含完整条目（虚构的导入项、未经批准绝不可执行的操作清单、完整的错误恢复和硬件配置表）。

---

工作流 — 6 个步骤

单次顺序执行。每一步在开始下一步之前都有明确的关卡。

Step 1 — 检查并评估

决定是否继续。通过两个仅使用 CPU、在 python:3.12-slim 容器中运行的探测程序，完成 1a. 探测模型和 1b. 探测数据集（无主机 Python 前置要求）：模型探测程序报告 model_type、architectures、tags 和 head 数量；数据集探测程序验证数据集能否加载及其列架构。根据 architectures + tags + 卡片正文检测 task（如果卡片没有提及 AutoModelFor...，则查看 references/model-discovery.md，并记录在 notes: 下）。对于 source = recommend，从 references/dataset-recommendations.md 中提供 3–5 个选项；对于 source = local，使用 references/dataset-sources.md 中的加载器。1c. 接受或拒绝，1d. 逐项检查 references/compat-workarounds.md，并在 config.yaml 的 applicable_workarounds: 中记录匹配项，然后 1e. 编写 config.yaml 骨架。

完整的探测脚本和 docker run 调用方式、Docker 守护进程预检、前置要求（MODEL_ID、可选的 DATASET_ID / HF_TOKEN、默认为 ./output/<model_short_name> 的 OUTPUT_DIR，由 Step 4–5 绑定挂载）、数据集列验证和重命名规则、完整拒绝标准、兼容性检查详情、准确的骨架，以及 .probe 清理方式，见 references/step1-probes.md。

关卡： config.yaml 中必须包含 model、dataset、task、applicable_workarounds。任何字段缺失都不得继续。

第 2 步 — 硬件审计与 NGC 镜像

验证 Docker、GPU 和磁盘，实时选择 NGC PyTorch 镜像，并最终确定依赖硬件的兼容性规则。2a. 审计（硬性门槛）：运行 tao-setup-nvidia-gpu-host --check-only（驱动分支 580、CUDA Toolkit 13.0、NVIDIA Container Toolkit 1.19.0）；如果失败，请求授权安装，然后重新运行；可用磁盘空间 < 100 GB 时发出软警告；只检查本次运行需要的凭据；硬性检查失败时，不得继续执行第 4 步；记录 gpu_count、gpu_name、driver_major、vram_gb_per_gpu。2b. 选择 NGC 镜像（实时）——选择版本号最高的 PyTorch NGC 镜像，且满足 Min driver ≤ driver_major、容器 CUDA 版本 ≤ 主机 CUDA Toolkit 版本（绝不能因 aN/bN/rcN 后缀而拒绝）；WebFetch 失败时 → 使用 references/hardware-container.md 作为后备方案。2c. 重新评估依赖 hw 的兼容性规则。2d. 模型适配检查——bf16 的 param_bytes ≈ 2×param_count；如果超过 vram_gb_per_gpu × 1e9 的 60%，则建议使用 LoRA。

完整的审计脚本、软警告与 MIN_DISK_GB 覆盖设置、实时选择规则、支持矩阵 WebFetch URL、24.09-py3 / SDPA+GQA 的 attn_implementation: "eager" 后备方案，以及 could not select device driver 故障说明，请参阅 references/hardware-audit-ngc.md。

门槛：config.yaml 中包含 ngc_image、gpu_count、gpu_name、driver_major、vram_gb_per_gpu。已记录依赖硬件的兼容性修复。

---

第 3 步 — 研究配方

获取实时配方——Agent 对 transformers/trl/peft 的记忆并不可靠，因此第 3 步不可跳过。按优先级顺序依次查阅 references/research-priorities.md（优先级 1 → 6）。

针对检测到的任务，获取以下信息后停止：AutoModel / 处理器类、训练和评估变换、整理器、compute_metrics 以及超参数提示（学习率、批次大小、训练轮数、调度器）。将研究结果记录在 meta/recipe.md 中，并将来源 URL 追加到 config.yaml: research_sources:。如果某个项目没有实时研究结果，则使用匹配的脚手架（cv-scripts.md / vlm-scripts.md）作为后备方案，并在 notes: 下记录 "fallback to scaffold — no live source for "。冲突解决规则：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（评估脚本 必须命名为 run_eval.py，绝不能命名为 evaluate.py — 这会与 HF evaluate 冲突）、 infer.py、用于 VLM-LoRA 的 merge_lora.py、.gitignore。权威顺序：第 3 步 的实时调研 → 脚手架参考文档（cv-scripts.md / vlm-scripts.md），仅用于 结构，绝不使用其中的 [FETCH LIVE] 区块。将每条 applicable_workarounds 作为 Dockerfile 区块、requirements 固定版本、配置覆盖项或运行时环境变量应用。每个生成的 .py 文件都必须以 NVIDIA Apache-2.0 # 注释版权声明开头（否则生成器必须失败）。如果 emit_unit_tests: true，还要按照 references/testing.md 生成 tests/。完整文件列表、 准确的版权声明以及 Dockerfile 模板（依赖 → 兼容性 → 代码层顺序）参见 references/project-scaffold.md。

4b. 构建、准备、冒烟测试 — 执行 docker build -t run-<short>:latest .，然后运行 references/docker-runs.md 中的 §1（构建）、§2（prepare_data）、§3（冒烟测试， --smoke --max_steps 1）；§3 列出了冒烟测试通过标准（无异常、loss 为有限值、 第 1 步时 grad_norm > 0）。如果 emit_unit_tests: true，还要在容器内运行 pytest tests/。任何失败 → 停止。

4c. 预检摘要 — 打印框线格式的 ─ PREFLIGHT ─ 摘要（参考 URL、数据集列、push_to_hub 仓库、 wandb 监控、ngc_image、硬件、冒烟测试结果），并在启动完整训练前确认每个字段均已填写。 准确格式：references/project-scaffold.md。

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

---

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

按顺序运行 references/docker-runs.md 中的所有命令：5a 基线评估 （§4，如果 skip_baseline: true 则跳过）、5b 在后台运行完整训练（§5）、5c LoRA 合并（§6，仅限使用 LoRA 的 VLM）、5d 训练后评估（§7）、5e 对 5 个样本进行推理（§8）。多 GPU：在 python train.py 前添加 torchrun --nproc_per_node=$gpu_count。 监控 docker logs -f hft_train：loss 应在 10–20 步内下降（保持不变 → 停止；NaN → 降低学习率；OOM → 将批量大小减半；完整恢复方法见 references/core-rules.md + references/error-playbook.md）。如果 emit_report: true，按照 references/reporting.md 在第 5 步 e 后运行 report.py。

**关卡：**以下各项全部满足 — checkpoints/final/（或 LoRA 的 checkpoints/merged/） 存在；reports/eval_results.json 中的主要指标为数值；reports/baseline_results.json 存在 （除非已跳过）；reports/inference_samples/ 中有 5 个样本；wandb URL 显示 loss 正在下降。

---

步骤 6 — 推送并生成重新运行技能

发布运行结果，并使其可复现，无需重新研究。

6a. 推送到 HF Hub — 使用 references/hub-push.md（推送合并后的权重或最终权重、生成的模型卡 README.md、results/{eval,baseline}_results.json、config.yaml、Dockerfile、requirements.txt、inference_samples/*.jpg，以及 report.{pdf,html}，前提是 emit_report: true）。仅当 config.yaml 中明确设置了 push_to_hub: false 时跳过。

6b. 生成重新运行技能 — 按照 references/pipeline-skill-template.md，生成到 <output_dir>/skills/run-<short>/SKILL.md。每个 <placeholder> 都必须替换为实际值（保留字面占位符属于错误）；包含完整 YAML（license、compatibility、metadata、allowed-tools），并在结束的 --- 后立即添加该模板中的 NVIDIA 版权声明 HTML 注释；如果生成的 SKILL.md 缺少这些字段或版权注释，生成器必须报错。

门槛（完成标准）： 以下条件必须全部满足 — 达到步骤 5 的门槛；HF Hub 仓库已在解析后的 URL 上创建，且包含权重、模型卡和 results/（除非 push_to_hub: false）；<output_dir>/skills/run-<short>/SKILL.md 已存在，没有遗留 <placeholder>，并包含 pipeline-skill-template.md 要求的元数据和版权 HTML 注释。

给用户的最终消息 — 简短，并附上直接 URL：wandb URL；HF Hub URL；主要指标基线 → 微调后（Δ）；reports/inference_samples/ 的路径；<output_dir>/skills/run-<short>/SKILL.md 的路径。

---

错误处理手册

遇到已知运行时错误时，重新设计之前先查阅 references/error-playbook.md — 其中的症状 → 最小修复表涵盖 NGC ENTRYPOINT、SDPA+GQA、transformers>=4.51 回归、numpy 2.x ABI、Albumentations bbox、PEFT + gradient_checkpointing、SmolVLM SDPA、LoRA 目标正则表达式、缺少 CV 增强、步骤 0 OOM 等问题。如果某一行在多次运行中触发两次，就将其纳入 references/compat-workarounds.md，添加 detect 规则，并在错误触发前于步骤 1d 自动应用。

---

沟通风格

简洁：不说废话，不复述请求；始终附上直接的 Hub + wandb URL；发生错误时说明出了什么问题、原因以及做了哪些更改（不提供选项菜单；答案明确时不要写“选项 A/B/C”——直接采取行动）。完整内容见： references/core-rules.md。

示例工作流

• tao-rerun-convnext-cifar10 — facebook/convnext-tiny-224 在 cifar10 上运行（图像分类，10 个类别，子集 5000/1000）。
• tao-rerun-detr-cppe5 — facebook/detr-resnet-50 在 cppe-5 上运行（目标检测，5 个类别，子集 800/200）。
• tao-rerun-segformer-foodseg103 — nvidia/mit-b0 在 EduardoPacheco/FoodSeg103 上运行（语义分割，103 个类别 + 背景，子集 1000/200）。
• tao-rerun-smolvlm-vqav2 — HuggingFaceTB/SmolVLM-256M-Instruct 在 merve/vqav2-small 上运行（图像文本到文本 VLM LoRA，子集 500/100，5 个 epoch）。