tao-port-huggingface-model

TAO-HF 集成技能

将 HuggingFace（HF）计算机视觉模型集成到 NVIDIA TAO Toolkit 生态系统中。迭代推进各个阶段，而不是单纯按线性顺序执行；在每一步都遵循 构建 → 测试 → 调试 → 修复 → 重新测试 的循环。

此 SKILL.md 是工作流协调文档。每个阶段都有对应的参考文件，位于 references/ 下，其中包含完整的分步说明、代码块、Docker 调用和关卡要求。每个阶段开始时都要阅读对应的参考文件；仅凭下方的概要并不足以完成工作。

---

仅限本地规则

所有工作都严格限于本地。你只能从远程仓库读取或克隆内容；所有文件编辑、Docker 构建和测试运行都必须在本地机器上进行。不得执行 git commit、git push 或创建远程分支（GitLab、GitHub、HuggingFace），不得创建合并请求 / 拉取请求 / 问题，也不得将 Docker 镜像上传、发布或推送到任何镜像仓库或制品库。这是由 references/execution-and-debugging.md 中绑定挂载的本地克隆布局所决定的。

---

子模块覆盖与执行平台

local-docker 是默认平台。用户将四个 TAO 仓库（tao-core、tao-pytorch、tao-deploy、tao-dataservices）分别克隆到同一个工作目录中；每个仓库还包含嵌套的 tao-core/（以及 tao-pytorch/）子模块，固定在原始未修改的提交版本，这些子模块已过时——修改内容仅存在于顶层 tao-core/ 中。始终从顶层 tao-core/ 安装，绝不要从 <repo>/tao-core/ 安装（嵌套子模块会悄无声息地丢弃所有修改）。覆盖 CI 中 pip install tao-core/ 的规则有三条：挂载整个工作目录（-v $(pwd):/workspace）；先执行 pip install /workspace/tao-core，确保修改后的 schema 生效；将顶层 tao-core 放在 PYTHONPATH 的首位（-e PYTHONPATH=/workspace/tao-core:/workspace/tao-pytorch）。

每项测试、冒烟运行和端到端验证都必须在本地准备的 TAO Toolkit 容器内运行（tao-pytorch-base:latest、tao-deploy-base:latest，可选的 tao-dataservices-base:latest，均来自阶段 0）；本地克隆通过绑定挂载方式挂载到 /workspace，并使用 pip install /workspace/tao-core 和 setup.py develop 安装。所有 Python 工作都在容器中运行——不得使用主机 venv，也不得在主机上执行 pip install。平台技能规定容器的运行方式——主机 GPU 运行时通过 tao-setup-nvidia-gpu-host 配置；docker run 标志 / NGC 身份验证 / 挂载 / 环境变量透传 / --ipc=host/--shm-size / 检查 / 错误模式，通过 tao-run-on-docker 和 tao-run-on-local-docker 配置。本工作流只规定在容器内 运行什么，绝不另行定义这些约定。带注释的工作目录树、规范的 docker run 标志集合及工作流专用的 -w/PYTHONPATH/安装命令补充项、三个隔离上下文、四条隔离规则、开发循环以及调试手册表格：references/execution-and-debugging.md。

---

阶段地图

七个阶段（完整目标和关卡如下；各阶段的参考资料）：

• 阶段 0 — 前置条件 + TAO Toolkit 镜像 + 本地镜像标签：phase-0-prereqs.md
• 阶段 1 — HF 检查环境，验证 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 — 打包（setup.py console_scripts）+ L0 测试：phase-5-packaging.md
• 阶段 6 — 基于容器的测试 + 端到端流水线验证：phase-6-container-tests.md、docker-patterns.md
• 阶段 7 —（有条件时）精度 / 延迟 / 大小调优：phase-7-optimization.md

**重要 — 持续执行至阶段 6：**实现完成后（阶段 3–5）不要停下来等用户运行测试；应立即继续执行必需的阶段 6。只有在 TAO Toolkit 容器内测试通过且端到端流水线经过验证后，实现才算完成。每一步都要执行构建-测试-调试循环——编写后立即测试，失败时修复，切勿累积未经测试的代码。

---

阶段 0 — 前置条件检查

目标：验证 Python 3.10+ 和 git；将 NVIDIA 驱动 / 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，供阶段 3–6 使用。准备过程会移除这些镜像中已发布的 TAO 软件包，以便安装用户的本地克隆（挂载在 /workspace/...），并在运行时使用。任何检查失败都必须立即停止。完整命令、向用户提问的措辞，以及每个镜像的准备 Dockerfile 代码片段：phase-0-prereqs.md。

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

---

阶段 1 — 信息收集与验证

**目标：**确定是否继续。收集凭据，定位（或克隆）四个 TAO 仓库，并在这些仓库中创建一致的本地工作分支；启动长期运行的 tao-hf-inspect 容器（隔离上下文 A）；验证 HF 模型是具有受支持 pipeline_tag 的 CV 模型；提取配置 + state-dict 结构；对 ONNX 导出进行合理性检查，然后清理。完整逐步流程（1.1–1.7）：phase-1-inspection.md；通用模式：hf-inspection.md。

以下情况应拒绝：pipeline_tag 属于 NLP / 音频 / LLM（不在 CV 范围内）、AutoConfig 抛出异常，或者 ONNX 导出根本无法实现且没有重写方案。

**关卡：**已定位 / 克隆全部 4 个 TAO 仓库，并创建了一致的工作分支；已确认 pipeline_tag 属于 CV；已提取 model_type、image_size、hidden_size、num_labels；已记录 state-dict 键并起草 HF→TAO 映射方案；ONNX 合理性检查已通过（或已了解失败模式）；用户已确认 model_short_name 和任务类型。展示检查结果并确认后再继续。

---

阶段 2 — 代码库探索

目标： 为检测到的 pipeline_tag 找到最接近的现有 TAO 参考模型（分类 → classification_pyt，检测 → dino/rtdetr，分割 → segformer，实例分割 → mask2former，全景分割 → oneformer，零样本 → grounding_dino，深度估计 → mono_depth），阅读它在 tao-core、tao-pytorch 和 tao-deploy 中的完整实现，并确认 backbone_v2/ 中是否已包含该骨干网络。选定的参考模型将决定后续所有内容——配置结构、架构、损失、ONNX 导出形状、TRT 构建器、部署推理器/加载器、指标、数据集格式。完整参考列表（每个模型 12 个文件）、backbone_v2/ 覆盖情况检查（其中已提供 vit、swin、resnet、dino_v2 等），以及 tao-dataservices 覆盖情况检查，请参见：phase-2-codebase.md；各任务类型的详情请参见：task-type-guide.md。

如果需要新的骨干网络，请在阶段 3 之前确定策略（封装 timm > 从头重新实现 > 封装 HF 黑盒），因为这会影响权重加载、ONNX 导出和部署流水线。绝不能同时继承 transformers.PreTrainedModel 和 BackboneBase（元类冲突）。

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

---

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

目标： 编写 tao-core 配置模式，以及 tao-pytorch 训练器、原生推理和原生评估，并在各步骤之间进行冒烟测试。使用 <model_name>（阶段 1 中的 snake_case）和 <ModelName>（PascalCase）。共七个步骤：（1）在 config/<model_name>/ 下编写 tao-core 配置——ExperimentConfig(CommonExperimentConfig) 必须包含 model、dataset、train、evaluate、inference、export、gen_trt_engine、quantize；（2）在 cv/<model_name>/ 下编写 tao-pytorch 训练器（build_model()、<ModelName>PlModel(TAOLightningModule)、train.py、入口点、experiment_spec.yaml；新增骨干网络时 → 添加并注册 cv/backbone_v2/<backbone_name>.py）；（3）通过入口点的 launch() 实现多 GPU / 多节点训练；（4）原生推理 → result.csv；（5）原生评估 → results.json；（6–7）接入 MLOps（@monitor_status → status.json）。下方的跨阶段检查清单会强制执行一致性规则（包括 export.onnx_file 与 gen_trt_engine.onnx_file，以及 ??? = 必填的 MISSING）。

各步骤的完整代码和规范的 experiment_spec.yaml 请参见：phase-3-implementation.md（代码片段见 tao-patterns.md，目录布局见 repo-structure.md，各任务类型见 task-type-guide.md）。

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

---

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

目标： 从 tao-pytorch 导出 ONNX，然后在 tao-deploy 中构建 TRT 引擎、执行 TRT 推理和 TRT 评估，并复用 tao-core 的 ExperimentConfig。共四个步骤（8–11）：导出 ONNX（scripts/export.py，按任务指定输入和输出名称，batch_size=-1 ⇒ 动态批次）；构建 TRT 引擎（gen_trt_engine.py，继承 EngineBuilder 或复用 ClassificationEngineBuilder，写入 specs/{gen_trt_engine,inference,evaluate}.yaml）；TRT 推理（仅使用 NumPy 的 ClassificationLoader → result.csv）；TRT 评估（sklearn/pycocotools → results.json）。完整代码和阶段 3+4 的门槛：phase-4-deploy.md。

模块注意事项：tao-pytorch 和 tao-deploy 有各自独立的 hydra_runner 和 monitor_status 实现——在部署脚本中使用 deploy 版本；两个仓库中的 ExperimentConfig 都从 nvidia_tao_core 导入（架构相同，字段路径相同）。

阶段 3+4 的门槛： 容器内的三项检查全部通过——tao-pytorch 导入 + 模型 + ONNX 导出，以及 tao-deploy 导入。

---

阶段 5 — 打包与 L0 测试

目标： 在 tao-pytorch/setup.py 和 tao-deploy/setup.py 中都将模型注册为 '<model_name>=...entrypoint.<model_name>:main' console_script（deploy 入口点使用 nvidia_tao_deploy.cv.common.entrypoint.entrypoint_hydra），并添加 L0 测试——deploy 测试（tao-deploy/tests/<model_name>/，subprocess + --buildOnly trtexec）和训练器测试（tao-pytorch/tests/cv_unit_test/<model_name>/，Trainer(..., fast_dev_run=True)，标记 @pytest.mark.cv_unit @pytest.mark.<model_name>）。完整代码和测试布局：phase-5-packaging.md。

门槛： 已注册入口点；pytest 文件已创建并遵循标记约定。不要止步于此——直接进入阶段 6。

---

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

Docker 测试前，先验证产物链：train 生成 <results_dir>/train/<model_name>_model_latest.pth → export.checkpoint → <results_dir>/export/<model_name>.onnx → gen_trt_engine → <results_dir>/trt/<model_name>.engine → inference.trt_engine / evaluate.trt_engine。然后确认一致性检查清单：*_latest.pth 名称；训练 spec、inference.yaml、evaluate.yaml 与构建器 preprocess_mode 中的 augmentation.mean/std 一致；ONNX input_names/output_names；export.input_width/input_height 与 dataset.img_size；model.head.in_channels 与 model_params_mapping.py；共享的 classes.txt；以及每个包目录中都有 __init__.py（包括用于 get_subtasks() pkgutil 发现的 scripts/__init__.py）。完整插值路径、逐项检查清单和配置字段路径：workflow-consistency.md。

---

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

必须在阶段 5 之后立即开始。 所有 TAO 模型都以 Docker 镜像形式发布；只能在容器外运行的代码是不完整的。测试直接在 TAO Toolkit 容器内运行（测试循环中不构建 Docker 镜像）：将本地源代码挂载到阶段 0 的镜像标签中，通过 setup.py develop 安装，并直接调用 pytest / pylint / pydocstyle / flake8——使用原生 pytest 和 lint 二进制文件，不要使用任何 ci/run_functional_tests.py / ci/run_static_tests.py 包装脚本（这些脚本仅存在于 NVIDIA 的内部镜像中；公开的 github.com/NVIDIA-TAO/ 镜像没有 ci/ 目录）。

按顺序执行步骤 16–25：验证本地镜像标签（16）；在容器中运行 tao-core 的 pytest（17）、tao-pytorch 的 pytest（18，-m cv_unit、--shm-size=16G）和 tao-deploy 的 pytest（19）；静态检查 / lint 测试（20，pylint --errors-only，以及可选的 pydocstyle / flake8）；构建 wheel（21）；运行端到端流水线（22——在同一个 tao-pytorch 会话中执行训练 dry-run 和导出，然后在同一个 tao-deploy 会话中执行 gen_trt_engine、推理和评估，因为 --rm 会丢弃已安装的软件包）；原生与 TRT 交叉检查（23——FP32 应近乎完全一致，FP16 应只有微小偏差，出现明显差异表示存在 ONNX/TRT 问题）；交互式调试 shell（24）；可选的发布版 Docker 镜像构建（25，仅用于分发）。各步骤的完整命令和修复后重新测试的循环见：phase-6-container-tests.md；构建脚本、运行器模式、依赖要求和 CI 约定见：docker-patterns.md。

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

---

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

仅在阶段 6 通过，但准确率 / 延迟 / 模型大小仍需改进时进入。首先询问用户的目标指标。 从四个类别进行诊断（步骤 26）——准确率过低、TRT 与原生结果存在差异、训练过慢、推理过慢——然后应用相应技术：超参数调优（27）、INT8 量化（28）、通道剪枝并重新训练（29）、知识蒸馏（30）或分辨率调优（31）。完整的诊断、配置块、YAML 覆盖项和决策树见：phase-7-optimization.md。

---

参数

$ARGUMENTS

如果提供了 $ARGUMENTS，则将其视为 HuggingFace 模型 ID 或 URL，作为阶段 1 的起点。如果未包含凭据或模型短名称，请在继续之前向用户询问。