tao-train-action-recognition

动作识别

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

从视频序列中识别动作。支持 RGB、光流和联合（多流）输入类型，用于对视频片段中的时序动作进行分类。

设置 model.pretrained_model_path 以指定预训练骨干网络权重。

快速开始（docker run）

Docker 原生启动——主机上无需 TAO SDK 或 Python。如果本地 Docker/平台技能提供了更严格的环境专用命令（非 root UID 映射、缓存重定向、远程守护进程）， 请改用该命令。

TAO_PYT_IMAGE_DEFAULT=nvcr.io/nvidia/tao/tao-toolkit:7.3.0-pyt  # versions-key: images.tao_toolkit.pyt
TAO_PYT_IMAGE="${TAO_PYT_IMAGE:-$TAO_PYT_IMAGE_DEFAULT}"
RUN_ROOT="${RUN_ROOT:-$PWD}"
DOCKER_COMMON=(
  --rm --gpus all --shm-size=8g
  --shm-size=8g
  --ulimit memlock=-1
  --ulimit stack=67108864
  -v "$RUN_ROOT/data:/data:ro"
  -v "$RUN_ROOT/specs:/specs:ro"
  -v "$RUN_ROOT/results:/results"
)

训练：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  action_recognition train -e /specs/train.yaml

评估：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  action_recognition evaluate -e /specs/evaluate.yaml

推理：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  action_recognition inference -e /specs/inference.yaml

导出：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  action_recognition export -e /specs/export.yaml

每个操作都通过 -e 接收其配置文件；results_dir 在配置文件中设置，也可 在命令行中覆盖。挂载配置文件引用的任何预训练权重目录，并确保所有容器内路径 在各个操作中保持一致。

Dataclass 架构

生成的 TAO Core 架构以 schemas/<action>.schema.json 的形式打包，schemas/manifest.json 列出可用操作。每个生成的架构还会根据架构顶层的 default 字段生成 references/spec_template_<action>.yaml。AutoML 是否启用由 references/skill_info.yaml 中模型层级的 automl_enabled 声明。某个操作要能运行 AutoML，必须存在并且可解析 schemas/<action>.schema.json 和 references/spec_template_<action>.yaml。请使用已打包的所选操作架构，获取 automl_default_parameters、automl_disabled_parameters、默认值、最小值/最大值边界、枚举、选项权重、数学条件、依赖项和常用参数。运行时不要假定 ~/tao-core 存在；维护者会在打包技能库前重新生成架构/模板。

训练操作策略

此模型在模型层级启用了 AutoML。处理任何训练阶段请求前，请阅读 references/skill_info.yaml，并根据明确指定的 automl_policy 值或用户的工作流请求，确定本次运行的策略。默认使用 automl_policy: on，并且在新的启动提示中仅提供 on / off 选项。对于“关闭 AutoML”“禁用 AutoML”“不进行 HPO”或“普通训练”等表达，本次运行应视为 automl_policy: off。当 automl_policy: on、automl_enabled: true，且已打包 schemas/train.schema.json 和 references/spec_template_train.yaml 时，默认通过 tao-skill-bank:tao-run-automl 执行训练操作，并使用此模型的 skill_dir。保留工作流/应用对数据集、配置文件、输出目录、GPU/平台设置、父检查点和 automl_policy 的覆盖设置。仅当 automl_policy: off 或缺少已打包的训练架构/模板时，才直接训练模型；若缺少架构/模板，请说明 AutoML 已启用，但在生成架构前，此模型无法运行 AutoML。

evaluate、inference、export 等非训练操作以及部署流程仍由此模型技能处理。单次运行的 automl_policy 覆盖设置不会更改模型元数据。

训练要求

• 数据集类型： action_recognition
• 格式： default
• 训练监控指标： val_loss、val_acc
• 评估任务指标： accuracy、m_accuracy
• AutoML 指标约定： 对于必需的、基于评估的基线和最终比较，请使用最大化方向的 accuracy，并对每项建议通过 eval_fn 运行 evaluate。val_loss 仅适用于明确接受的训练代理运行，因为 evaluate 不会输出该指标。从头开始且没有初始检查点的运行，需要先执行最小默认训练作业，然后评估其精确的 epoch/step 检查点以建立基线。

各操作的数据集要求

操作	规范键	来源	文件	是否为列表
evaluate	evaluate.test_dataset_dir	train_datasets	从 test.tar.gz 解压得到的 test/	否
inference	inference.inference_dataset_dir	train_datasets	从 test/smile.tar.gz 解压得到的 test/smile/	否
train	dataset.train_dataset_dir	train_datasets	从 train.tar.gz 解压得到的 train/	否
train	dataset.val_dataset_dir	train_datasets	从 test.tar.gz 解压得到的 test/	否

常见规范覆盖项

每个操作都必须覆盖数据源——Agent 必须根据上面的各操作数据集要求表构建数据源路径，并将其包含在 spec_overrides 中。

LOCAL_DATA = "/workspace/data/extracted"

如果源数据集以 TAO 示例归档文件 train.tar.gz、test.tar.gz 或 test/smile.tar.gz 的形式提供，请在启动 TAO 容器之前下载并解压。 动作识别入口需要目录路径；如果这些规范键指向 .tar.gz 文件，则会因 NotADirectoryError 而失败。

train（必须的数据源）：

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.label_map": {
        "catch": 0,
        "smile": 1
    },
    "dataset.batch_size": 2,
    "dataset.train_dataset_dir": f"{LOCAL_DATA}/train",
    "dataset.val_dataset_dir": f"{LOCAL_DATA}/test",
}

evaluate（必须的数据源）：

{
    "dataset.label_map": {
        "catch": 0,
        "smile": 1
    },
    "evaluate.test_dataset_dir": f"{LOCAL_DATA}/test",
}

inference（必须的数据源）：

{
    "dataset.label_map": {
        "catch": 0,
        "smile": 1
    },
    "inference.inference_dataset_dir": f"{LOCAL_DATA}/smile_infer/smile",
}

export（必须的检查点 + 输出路径）：

{
    "export.checkpoint": "<selected train checkpoint>",
    "export.onnx_file": "<results_dir>/action_recognition.onnx",
}

若要在不使用 SDK 解析器的情况下直接通过本地 Docker 串接操作，请选择训练生成的具体检查点，例如 model_epoch_000_step_00005.pth，并将该确切文件传递给 evaluate、 inference 和 export。除非用户明确要求使用最新检查点行为，否则不要使用 ar_model_latest.pth 符号链接。恢复训练时，将 train.resume_training_checkpoint_path 设为要恢复的确切 epoch/step 检查点。

Eval 数据集

可选。测试数据集可能与训练数据分开，以 test.tar.gz 的形式分发；请将其解压，并将规范指向解压后的 test/ 目录。 对于打包的示例数据，TAO 训练会生成 val_loss 和 val_acc，而 evaluate 操作会生成 accuracy 和 m_accuracy。对于常规的、由评估结果驱动的 AutoML 工作流，请使用最大化方向的 accuracy。只有在用户明确接受不使用所需影响基准、仅以训练结果作为代理指标时，才使用最小化方向的 val_loss。

重要参数

• model.model_type：输入类型：rgb、of（光流）或 joint（多流）。
• model.backbone：默认为 resnet_18。用作空间特征提取器。
• dataset.label_map：将类别名称映射到索引的字典。
• model.rgb_seq_length：RGB 输入的每个片段所含帧数。
• model.of_seq_length：光流输入的帧数。
• train.optim.lr：学习率。默认为 5e-4。

多 GPU / 多节点

**启动方式：**由 Lightning 管理（单个 python 进程，由 Lightning 启动工作进程）。

规范键	描述	默认值
train.num_gpus	GPU 数量	1
train.gpu_ids	GPU 设备索引	[0]

• 策略：auto（Lightning 自动选择最佳策略）
• 没有显式的 num_nodes 或 distributed_strategy 配置——面向单节点

硬件

最低需要 1 块 GPU，建议使用 2 块 GPU。每块 GPU 显存需为 16GB 或以上。内存需求取决于序列长度和输入分辨率。对于视频数据，batch_size=2 是较为保守的设置。

错误模式

序列长度不匹配：确保视频片段包含的帧数足以满足配置的 rgb_seq_length 或 of_seq_length。

evaluate/inference 缺少标签映射：下游操作会在加载检查点之前重新构建 ActionRecognitionModel，因此需要使用与训练时相同的 dataset.label_map。请在每个 evaluate 或 inference 规范中都包含该项；否则模型构建会在检查点验证之前失败。

规范参数／父模型推断

特定模型的推断映射应放在此 MD 文件中，而不是 config.json 中。生成的运行器应读取本节，并在调用 create_job() 前通过 SDK 辅助函数应用这些映射。这与旧版微服务的 infer_params.py 流程一致。

TAO Core action_recognition.config.json 中的推断映射：

操作	规范字段	推断函数	含义
evaluate	encryption_key	key	加密密钥
evaluate	evaluate.checkpoint	parent_model	从父作业结果文件夹推断出的模型文件
evaluate	results_dir	output_dir	当前作业结果目录
export	encryption_key	key	加密密钥
export	export.checkpoint	parent_model	从父作业结果文件夹推断出的模型文件
export	export.onnx_file	create_onnx_file	输出 ONNX 路径
export	results_dir	output_dir	当前作业结果目录
inference	encryption_key	key	加密密钥
inference	inference.checkpoint	parent_model	从父作业结果文件夹推断出的模型文件
inference	results_dir	output_dir	当前作业结果目录
train	encryption_key	key	加密密钥
train	model.of_pretrained_model_path	ptm_if_no_resume_model	不存在恢复检查点时使用的 PTM
train	model.rgb_pretrained_model_path	ptm_if_no_resume_model	不存在恢复检查点时使用的 PTM
train	results_dir	output_dir	当前作业结果目录
train	train.resume_training_checkpoint_path	resume_model	从当前作业结果文件夹推断出的模型文件

对于 parent_model 或 parent_model_folder，请将上游 train/export/AutoML 子作业 ID 作为 parent_job_id 传入。SDK 会列出父作业结果文件夹、筛选检查点产物，并返回选定的模型文件或文件夹。不要将这些映射重新添加到 config.json 中，也不要修改生成的运行器脚本来猜测检查点路径。