tao-port-huggingface-model

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

TAO-HF 集成技能

将 HuggingFace（HF）计算机视觉模型集成到 NVIDIA TAO Toolkit 生态系统中。迭代执行各阶段，而不是严格按线性顺序推进：每一步都遵循 构建 → 测试 → 调试 → 修复 → 重新测试 循环。出现失败时，先诊断并修复，再继续；通过后再进入下一步。

此 SKILL.md 是工作流协调器。每个阶段都有专门的 references/phase-N-*.md，其中包含完整的分步内容、代码、Docker 调用和检查关卡。每个阶段开始时都要阅读对应的参考文件；以下摘要并不足够。

---

仅限本地规则

所有工作都严格限制在本地。不要向任何远程端（GitLab、GitHub、HuggingFace）推送、提交或创建分支，也不要创建合并请求、拉取请求或问题，亦不得将 Docker 镜像上传或发布到任何镜像仓库或制品存储。你只能从远程端读取或克隆内容；所有编辑、Docker 构建和测试运行都必须在本地计算机上进行。

---

子模块覆盖策略

用户会将四个 TAO 仓库（tao-core、tao-pytorch、tao-deploy、tao-dataservices）分别克隆到同一个工作目录中。每个仓库内嵌套的 tao-core/ 子模块都指向未经修改的原始提交；修改只存在于顶层的 tao-core/ 中。始终从顶层 tao-core/ 安装，绝不要从 <repo>/tao-core/ 安装——嵌套子模块会静默忽略所有修改。覆盖规则：（1）挂载工作目录 -v $(pwd):/workspace；（2）在安装 tao-pytorch/tao-deploy 之前，先执行 pip install /workspace/tao-core；（3）将顶层 tao-core 放在 PYTHONPATH 的最前面，例如 -e PYTHONPATH=/workspace/tao-core:/workspace/tao-pytorch。目录结构请参阅 references/cross-cutting.md。

---

执行平台

每项测试、冒烟运行和端到端验证都在本地准备的 TAO Toolkit 容器内执行（tao-pytorch-base:latest、tao-deploy-base:latest，以及可选的 tao-dataservices-base:latest——均来自阶段 0）。平台技能负责说明如何运行；本技能规定要做什么。默认平台： local-docker。阶段 0 将驱动程序 / CUDA / NCT 预检委派给 tao-setup-nvidia-gpu-host。权威技能表、绑定挂载的理由及规范的 docker-run 标志集请参阅 references/cross-cutting.md。

---

阶段图

阶段	目标	参考
0	前置条件 + TAO Toolkit 镜像 + 本地镜像标签	phase-0-prereqs.md
1	输入、HF 检查容器、验证模型 + 数据集	phase-1-inspection.md, hf-inspection.md
2	最接近的现有 TAO 参考模型	phase-2-codebase.md, task-type-guide.md
3	tao-core 配置 + tao-pytorch 训练器 / 评估 / 推理	phase-3-implementation.md, tao-patterns.md, repo-structure.md
4	ONNX 导出 + tao-deploy TRT 引擎 / 推理 / 评估	phase-4-deploy.md
5	打包（console_scripts）+ L0 测试	phase-5-packaging.md
6	容器测试 + 端到端验证	phase-6-container-tests.md, docker-patterns.md
7	（有条件时）精度 / 延迟 / 大小调优	phase-7-optimization.md

跨阶段参考：workflow-consistency.md（CLI 流程、配置字段路径、跨阶段依赖）；cross-cutting.md（平台、隔离、模块陷阱、调试）。

**重要 — 持续执行至阶段 6：**第 3–5 阶段结束后，切勿停下来等用户运行测试。阶段 6 是必需的——只有容器内测试通过且端到端流水线完成验证，才算完成。

---

开发循环

每一步都要：编写代码 → 立即测试（导入检查、单元测试或试运行）→ 如果失败，读取回溯信息 → 诊断 → 修复 → 重新测试；如果通过，继续下一步。切勿积累未经测试的代码——只在最后测试会导致错误不断累积。

---

调试手册

出现故障时，先查阅 references/cross-cutting.md 中的“症状 → 可能原因 → 修复”表，再尝试随机修复——该表涵盖 ModuleNotFoundError、BACKBONE_REGISTRY KeyError、形状不匹配、NaN 损失、ONNX/TRT 构建失败、TRT 与 PyTorch 精度差距、OOM、DDP 卡住、检查点加载失败，以及子模块配置过时等问题。

---

环境隔离策略

所有 Python 工作都在 Docker 容器内运行——不使用主机 venv，不向主机 Python 执行 pip install（主机只需安装 tao-setup-nvidia-gpu-host 提供的 Docker）。共有三种上下文：A（阶段 1 在 tao-hf-inspect 中进行 HF 检查，回退方案为 python:3.12-slim），B（阶段 3/4/6 在准备好的容器中进行冒烟测试/L0/端到端测试，源代码通过 pip install /workspace/tao-core && python setup.py develop 安装），C（主机绑定挂载的临时工作区）。完整上下文及原文列出的四条规则（--check-only 主机软件包；阶段 1 使用 --user $(id -u):$(id -g) 与 root 的区别；HOME=/workspace/PIP_USER=1 回退方案；发行版软件包管理器清单；root:root 权衡；tao-hf-inspect 清理）见 references/cross-cutting.md。

---

阶段 0 — 前置条件检查

目标： 验证 Python 3.10+ 和 git；将驱动程序 / CUDA / Docker / NVIDIA Container Toolkit 主机检查委托给 tao-setup-nvidia-gpu-host；验证 NGC docker login 是否可用于 nvcr.io。然后询问用户 TAO Toolkit 镜像引用（tao-pytorch、tao-deploy，以及可选的 tao-dataservices），拉取镜像，并准备本地标签 tao-pytorch-base:latest、tao-deploy-base:latest、tao-dataservices-base:latest，供后续阶段使用——准备过程会移除预装的已发布 TAO 软件包，以便用户的 /workspace/... 克隆通过 pip install /workspace/tao-core && python setup.py develop 安装 / 加载。任何检查失败都必须立即停止。所需用户输入：镜像引用和凭据（NGC 登录、HF_TOKEN）。完整命令、提示词措辞和每个镜像的 Dockerfile 代码片段：参见阶段 0 参考资料。

关卡： 所有前置条件检查均通过；用户已提供所需镜像引用；本地存在 tao-pytorch-base:latest 和 tao-deploy-base:latest；如果预计会开展 dataservices 工作，则本地还存在 tao-dataservices-base:latest。

---

阶段 1 — 信息收集与验证

目标： 决定是否继续。收集凭据，定位 / 克隆 4 个 TAO 仓库，创建一致的工作分支，启动 tao-hf-inspect 容器（上下文 A），验证 HF 模型属于 CV 且具有受支持的 pipeline_tag，提取配置和状态字典架构，进行 ONNX 导出健全性检查，然后清理。完整步骤：参见阶段 1 参考资料。

拒绝条件： pipeline_tag 属于 NLP / 音频 / LLM（非 CV）；AutoConfig 抛出异常；或 ONNX 导出在根本上无法实现（且没有重写路径）。

关卡： 已定位 / 克隆全部 4 个 TAO 仓库，且分支一致；已确认 pipeline_tag 属于 CV；已提取 model_type、image_size、hidden_size、num_labels；已记录状态字典键，并起草 HF→TAO 映射方案；ONNX 导出健全性检查已通过（或已了解失败原因）；用户已确认 model_short_name 和任务类型。（完整检查清单：phase-1-inspection.md。）先展示调查结果并取得用户确认。

---

阶段 2 — 代码库探索

目标： 为检测到的 pipeline_tag 找到最接近的现有 TAO 参考模型，阅读其在 tao-core / tao-pytorch / tao-deploy 中的实现，并决定骨干网络是否已存在于 backbone_v2/ 中，还是需要新建。

HF pipeline_tag → TAO 参考模型的映射（分类 → classification_pyt，检测 → dino / rtdetr，分割 → segformer，实例 → mask2former，全景 → oneformer，零样本 → grounding_dino，深度 → mono_depth）会影响所有后续工作（配置、架构、损失、ONNX 形状、TRT 构建器、部署类、指标、数据集格式）。完整参考列表（每个模型 12 个文件）、backbone_v2/ 和 tao-dataservices 覆盖范围检查，以及各任务架构，请参阅阶段 2 参考资料。

如果需要新的骨干网络，必须在阶段 3 之前决定策略（封装 timm > 重新实现 > HF 黑盒封装）——这会改变权重加载、ONNX 导出和部署方式。切勿同时继承 transformers.PreTrainedModel 和 BackboneBase（会发生元类冲突——应改用组合）。

关卡： 已确定参考 TAO 模型，并阅读全部 12 个参考位置；已了解任务类型的影响（架构、损失、ONNX 输出、部署类、指标、数据集）；已决定骨干网络覆盖方案（复用 / 封装 timm / 新建）；已检查 dataservices 覆盖情况。（完整检查清单：phase-2-codebase.md。）

第 3 阶段 — TAO Core 配置与原生实现

**目标：**编写 tao-core 配置架构，以及 tao-pytorch 训练器、原生推理和评估，并在各步骤之间进行冒烟测试。（<model_name> = snake_case 短名称；<ModelName> = PascalCase。）

步骤 1–7（每步都基于上一步，并在步骤之间进行冒烟测试）：tao-core 配置（1）、tao-pytorch 训练器（2）、多 GPU／多节点（3）、原生推理 → result.csv（4）、原生评估 → results.json（5）、用于训练和评估／推理的 MLOps → status.json（6–7）。ExperimentConfig(CommonExperimentConfig) 必须包含 model、dataset、train、evaluate、inference、export、gen_trt_engine、quantize。所有 ??? 字段均为 MISSING（由用户通过 YAML／CLI 提供）；augmentation.mean／std、model.head.in_channels、检查点名称以及 onnx_file 的匹配项见下方清单。

各步骤的完整内容、代码、规范的 experiment_spec.yaml 和冒烟测试命令：请参阅第 3 阶段参考资料。

**关卡：**步骤 1 — ExperimentConfig 可在容器中正常导入；步骤 2 — build_model(cfg) 可运行，且 PLModel 可在容器中实例化；第 3 阶段 — 7 个步骤全部完成，冒烟测试通过，且没有缺失的 __init__.py。

---

第 4 阶段 — 导出、部署与 TensorRT 集成

**目标：**从 tao-pytorch 导出 ONNX，然后在 tao-deploy 中构建 TRT 引擎、进行推理和评估，并复用 tao-core 的 ExperimentConfig。

步骤 8–11：ONNX 导出器（8 — 任务专用的输入／输出名称，batch_size=-1 ⇒ 动态批次）；TRT 引擎构建器（9 — 继承 EngineBuilder 或复用 ClassificationEngineBuilder；编写 specs/{gen_trt_engine,inference,evaluate}.yaml，使用相同的 ExperimentConfig 架构，augmentation.mean／std 必须与训练一致）；TRT 推理 → result.csv（10）；TRT 评估 → results.json（11）。完整代码以及第 3+4 阶段关卡（3 项容器内检查：导入、模型构建 + 前向传播、ONNX 往返测试）请参阅第 4 阶段参考资料。

模块注意事项：tao-pytorch 和 tao-deploy 使用各自独立的 hydra_runner 和 monitor_status——在部署脚本中使用 deploy 版本。两者的 ExperimentConfig 均来自 nvidia_tao_core（架构／字段路径相同）。

**第 3+4 阶段关卡：**全部 3 项容器内检查均通过（tao-pytorch 导入 + 模型 + ONNX 导出；tao-deploy 导入）。

---

第 5 阶段 — 打包与 L0 测试

**目标：**在两个代码库中将模型注册为 console_script，并添加单元测试。

步骤 12–15：在 tao-pytorch/setup.py（12）和 tao-deploy/setup.py（13）的 console_scripts 中注册 '<model_name>=...:main'（通过 entrypoint_hydra 创建 deploy 的 entrypoint/<model_name>.py）；deploy L0 测试（14）；训练器 L0 测试——Trainer(..., fast_dev_run=True) + @pytest.mark.cv_unit @pytest.mark.<model_name>（15）。具体的入口点字符串、代码和 L0 测试文件列表请参阅第 5 阶段参考资料。

**关卡：**入口点已注册；pytest 文件已创建并遵循标记约定。不要停止——直接进入第 6 阶段。

跨阶段数据流与一致性验证

Docker 测试前，请验证 train → export → gen_trt_engine → inference / evaluate 链路（*_model_latest.pth → .onnx → .engine 工件流，以及各阶段读写的配置字段——完整示意图见 references/cross-cutting.md）。

一致性检查清单（继续前请验证）：self.checkpoint_filename → evaluate.checkpoint / export.checkpoint 引用的 *_latest.pth 名称；训练规范、inference.yaml、evaluate.yaml 和引擎构建器 preprocess_mode 中的 augmentation.mean/std 完全一致；ONNX input_names=['input'] / output_names=['output']（检测/实例分割使用任务专属名称）；export.input_width/input_height 与 dataset.img_size 匹配；model.head.in_channels 与 model_params_mapping.py 匹配；dataset.root_dir 下的 classes.txt 可由两个仓库读取；所有 __init__.py 均存在（包括 scripts/__init__.py，供 pkgutil 调用 get_subtasks()）。完整路径：workflow-consistency.md。

---

阶段 6 — 容器测试与端到端验证

强制要求——阶段 5 结束后立即开始。 所有 TAO 模型均以 Docker 镜像形式发布；只能在容器外运行的代码是不完整的。测试直接在 TAO Toolkit 容器内运行——不涉及镜像构建：挂载 → 安装源代码（setup.py develop）→ 直接运行 pytest / pylint / pydocstyle / flake8。使用原生命令，切勿使用 ci/run_functional_tests.py / ci/run_static_tests.py 包装脚本（仅适用于内部镜像；公开的 github.com/NVIDIA-TAO/ 镜像没有 ci/ 目录）。

步骤 16–25：验证本地镜像标签是否存在（16）；对 tao-core / tao-pytorch（-m cv_unit、--shm-size=16G）/ tao-deploy 运行单元测试（17–19）；lint 检查（20）；构建 wheel（21）；端到端测试——在一个 tao-pytorch 会话中进行训练试运行 + 导出，然后在一个 tao-deploy 会话中运行 gen_trt_engine + inference + evaluate（同一会话至关重要——--rm 会丢弃安装内容）（22）；对比原生与 TRT（23）；调试 shell（24）；可选的发布镜像（25）。

完整命令（每个 docker run、每个容器的环境变量、精确的 pytest / lint 调用 + 完整套件变体、包含所有 CLI 覆盖项的 train/export/gen_trt_engine/inference/evaluate 单行命令、ci/ 说明、修复并重新测试的循环），以及构建脚本 / 运行器模式：请参阅阶段 6 参考资料。

阶段 6 门槛（完成标准）： tao-core / tao-pytorch / tao-deploy 容器中的单元测试通过；静态测试通过（或仅有旧版 lint 警告）；wheel 构建成功；端到端流程完成 <model_name>_model_latest.pth → model.onnx → model.engine → 非空的 result.csv + results.json；原生与 TRT 在容差范围内一致。

---

阶段 7 — 优化与调优（条件性）

只有在阶段 6 通过，但准确率 / 延迟 / 大小仍需改进时才进入。首先询问用户的目标指标。

诊断类别：准确率过低；TRT 与原生结果差异过大；训练过慢；推理过慢。技术：步骤 27 — 超参数调优；步骤 28 — INT8 量化（通过 torchao / modelopt 进行 PTQ，或使用 TRT INT8 + 校准）；步骤 29 — 通道剪枝 + 重新训练；步骤 30 — 知识蒸馏；步骤 31 — 分辨率调优（TAO 会自动插值 ViT 位置嵌入）。每个类别的检查项、配置块、YAML 覆盖项、决策树和原理，均请参阅阶段 7 参考资料。

---

参数

$ARGUMENTS

如果提供了 $ARGUMENTS，则将其视为 HuggingFace 模型 ID 或 URL，并从阶段 1 开始。如果未提供凭据或模型简称，请先向用户询问，然后再继续。