physical-ai-video-data-augmentation

Physical AI 视频数据增强工作流编排器

用于在 OSMO 上执行 VDA 的默认工作流技能。负责流程选择、 预检、缓存就绪状态、推理路径决策、提交时插值、 监控和输出检索。组件技能仅供咨询。

目的

从预检到输出下载，安全且可复现地运行端到端 VDA 工作流。

请勿将此技能用于仅涉及容器内部调优的问题。

前提条件

运行预检或提交任何任务前，请确认以下条件。缺少必需密钥时， scripts/preflight_credentials.sh 会返回 USER_INPUT_REQUIRED:。

要求	满足方式	用途
NGC API 密钥（可选）	NGC_API_KEY、NGC_CLI_API_KEY，或 NVIDIA_API_KEY/OPENAI_API_KEY/VLM_API_KEY/LLM_API_KEY 中兼容的 nvapi-* 令牌	可选，用于刷新 nvcr_io 凭据和进行 NGC REST 范围探测；默认 VDA 镜像引用通过工作流注册表探测进行验证
Hugging Face 令牌	HF_TOKEN（或 HUGGING_FACE_HUB_TOKEN），或位于 ~/.cache/huggingface/token 的缓存令牌	创建 OSMO hf_token 凭据；拉取受限的 Cosmos/SeedVR 权重
OSMO CLI 访问权限	PATH 中有 osmo，已登录，具有默认配置文件，以及与 storage_url 匹配的已注册 DATA 凭据配置文件	提交/监控工作流以及列出/下载对象
GPU 池	osmo pool list --mode free 中至少有一个 ONLINE 池；POD_TEMPLATE 包含 GPU 容忍度/选择器	调度设置 + 工作器任务

可选（仅用于严格的 NGC 组织/团队探测）：NGC_ORG + NGC_TEAM （或 NGC_CLI_ORG / NGC_CLI_TEAM）。外部 VLM/LLM 端点密钥会单独验证， 不会由预检验证。

密钥处理规则：nvapi-* 令牌是 nvcr_io 的有效输入。 切勿仅凭令牌前缀拒绝；以工作流注册表探测结果为准。

说明

1. 根据用户意图选择工作流（auto_labeling、augmentation_and_al、e2e、 e2e_super_resolution）。
2. 开始运行操作前，提供暂定的执行时间概览。
3. 提交前运行预检和就绪状态检查。
4. 根据当前数据集后端推导提交时所需的值（绝不可猜测 storage_url）。
5. 使用明确的插值值提交工作流，并监控直至完成。
6. 检索输出；对于增强流程，提供并排对比证据，并总结任务结果。

使用 run_script(...) 执行脚本。规范示例：

run_script("bash scripts/preflight_credentials.sh --workflow assets/configs/osmo/augmentation_and_al.yaml")
run_script("python3 scripts/pre_submit_guard.py --workflow assets/configs/osmo/auto_labeling.yaml")
run_script("bash scripts/prepare_demo_assets.sh /srv/sdg/data/vda_inputs")

可用脚本

使用脚本级 --help 查看准确参数。

脚本	用途
scripts/preflight_credentials.sh	密钥/控制平面预检和工作流镜像访问检查
scripts/pre_submit_guard.py	提交时插值、缓存和数据集安全检查
scripts/prepare_demo_assets.sh	拉取演示视频并为默认演示路径进行扁平化处理
scripts/generate_configs.py	生成设置阶段的配置和操作指南投影
scripts/cosmos_worker.sh	执行增强工作器
scripts/pl_original_worker.sh	执行原始视频自动标注工作器
scripts/pl_augmented_worker.sh	执行增强视频自动标注工作器
scripts/osmo_barrier.py	多节点屏障同步
scripts/stage_run_artifacts.sh	将完整运行输出和输入视频镜像到本地
scripts/render_side_by_side.sh	根据本地制品渲染并排对比

支持的流程

流程	OSMO YAML	组序列	典型用途
augmentation_and_al	assets/configs/osmo/augmentation_and_al.yaml	setup -> augmentation -> auto_labeling_augmented	增强一个或多个视频，然后自动标注增强后的输出
auto_labeling	assets/configs/osmo/auto_labeling.yaml	setup -> auto_labeling	仅标注原始视频
e2e	assets/configs/osmo/e2e.yaml	setup -> (auto_labeling_original + augmentation) -> auto_labeling_augmented	优先考虑吞吐量的路径
e2e_super_resolution	assets/configs/osmo/e2e_super_resolution.yaml	setup -> auto_labeling_original -> augmentation -> auto_labeling_augmented	先通过 SR 门控，再进行增强的顺序路径

为保持向后兼容，仍保留旧别名 assets/configs/osmo/augmentation_and_pl.yaml。

根据用户请求选择合适的工作流

用户意图	工作流
“标注我的源视频” / “仅 PL” / “不进行增强”	auto_labeling
“创建增强视频并进行标注”	augmentation_and_al
“快速运行完整流水线”	e2e
“运行完整流水线，但先对经 SR 增强的原视频进行门控”	e2e_super_resolution

消除歧义：在确定方案前处理含糊请求

默认自主执行：只有缺少的信息会阻碍执行时才提问。

自主执行的默认设置（不要提问）

• 如果未提供数据集来源，则运行 VDA 演示路径（scripts/prepare_demo_assets.sh）， 并继续使用 dataset=vda-demo。
• 如果未明确指定流程，则默认使用 augmentation_and_al。
• 如果未指定端点模式，则默认复用集群内的持久化 NIM，并在 NIM 不健康时自动部署/修复。
• 如果缺少缓存，则运行 setup_model_cache.yaml，重新运行提交前检查，并在成功后自动继续。
• 任一阶段成功完成后，立即继续下一阶段。 不要暂停并询问“准备好后告诉我”或类似的确认问题。

需要暂停并消除歧义的情形

缺少的输入	重要原因	提问
预检返回 USER_INPUT_REQUIRED	缺少必需的密钥	针对确切缺少的值，简洁地询问一个能解除阻碍的问题
无法从活动数据集/上传根目录推导出存储后端前缀	错误的方案会导致运行时存储认证不匹配	“本次运行的后端原生根前缀是什么？”
无法选择 ONLINE GPU 池/平台	工作流无法调度设置/工作节点	“本次运行应使用哪个 GPU 池/平台？”

不要消除歧义的情形

• 除非用户明确要求更改场景配置，否则不要询问 cookbook。
• 默认不要提供外部端点。
• 不要询问 A/B 缓存策略问题；默认自动设置缓存。
• 不要询问是否缩减现有 NIM；这是禁止的。
• 输入缺失时，不要虚构、抓取或随机生成视频。
• 除非用户明确要求使用其他数据集，否则不要使用非 VDA 演示来源（例如 Carline adaptation 资源）。

步骤 0：选择流程并收集输入

输入视频策略（不可妥协）

• 始终将用户提供的视频输入（数据集 URL、本地路径或上传文件夹）作为首选，并将其视为一等输入。
• 绝不使用演示资源或任何其他来源替换用户明确指定的视频。
• 如果未提供视频输入，则默认通过 scripts/prepare_demo_assets.sh 使用 VDA 演示资源（HF 数据集流程），无需额外询问用户选择来源。
• 如果用户明确提及输入视频或数据集，则优先使用该输入，而非演示资源。
• 默认演示流程仅使用 VDA 演示资源（nvidia/video-data-augmentation-demo）。
• 除非用户明确要求，否则绝不建议下载任意网页视频片段或使用占位视频。

仅收集缺失的值：

1. 数据集来源（优先使用用户明确提供的 dataset_url 或本地上传文件夹；否则默认使用 VDA 演示资源并继续）。
2. 流程（auto_labeling、augmentation_and_al、e2e、e2e_super_resolution）；未指定时默认使用 augmentation_and_al。
3. 所有 VDA 资源的 OSMO gpu_platform（选项明确时自动选择一个 ONLINE 平台；仅在不存在有效选项时才询问）。
4. 端点模式（除非明确覆盖，否则默认在集群内复用/部署 NIM）。

不要猜测 gpu_platform（例如 microk8s）。请使用 osmo pool list --mode free 显示的当前确切平台标签（例如 gpu）。

每次提交前生成运行标记：

STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8)
RUN_ID="run-$STAMP"

执行时间概览（运行前必需）

运行任何会更改状态的命令（osmo credential set、NIM 安装/修复、缓存工作流提交或目标 VDA 工作流提交）之前，先向用户提供简短的预计耗时概览。

保持简洁（一小段话或 4-6 个要点），并包括：

• 当前属于冷启动（缺少 NIM/缓存）还是热启动（NIM/缓存已正常就绪），
• 主要阶段及其预计耗时，
• 所选工作流的预计总耗时范围。

基准耗时范围（根据已观察到的 MicroK8s + OSMO 运行情况）：

阶段	典型耗时
凭据 + 预检	~1-2 分钟
NIM 部署/下载/预热（如有需要）	~10-15 分钟
演示资源下载/上传（演示流程）	~1-3 分钟
模型缓存填充（如有需要）	~15-25 分钟
工作流提交 + 排队/启动	~1-3 分钟

提交后的工作流运行时间范围：

流程	典型运行时间
auto_labeling	~6-15 分钟
augmentation_and_al	~20-35 分钟
e2e	~22-40 分钟
e2e_super_resolution	~25-45 分钟

冷启动端到端运行通常需要 ~45-80 分钟；热启动运行通常需要 ~20-45 分钟，具体取决于流程和视频长度。

通用前置条件（适用于所有流程）

1. 凭据和控制平面预检

   bash scripts/preflight_credentials.sh --workflow assets/configs/osmo/<mode>.yaml
   

   出口受限：

   bash scripts/preflight_credentials.sh --no-probe --workflow assets/configs/osmo/<mode>.yaml
   

   预检不需要工作负载本地的 .env。运行时插值由提交时提供的值驱动（dataset、run_id、gpu_platform、video、storage_url、skills_dir），这些值统一放在一个 --set-string 列表中。

   传入 --workflow 会使用匿名 bearer 访问（在提供凭据时回退到凭据访问），验证当前工作流镜像引用（workflow.groups[].tasks[].image）是否可拉取。 如果在环境变量中提供了替换用的 NGC/HF 密钥，预检会在现有的 nvcr_io / hf_token 存在时自动刷新。若未提供新环境变量密钥，但仍要强制覆盖，请使用 --refresh：

   bash scripts/preflight_credentials.sh --workflow assets/configs/osmo/<mode>.yaml --refresh
   

   如果输出包含 USER_INPUT_REQUIRED:，请提出一个简短的阻塞问题，然后停止。

   如果工作流镜像返回 401/403，请在检查所列镜像引用后报告注册表访问失败；不要声称某类密钥（例如 nvapi-*）一概不受支持。

2. 存储插值策略

   storage_url 必须根据当前运行所使用的实际数据集/上传后端确定。

   dataset_url=azure://storiondevxah69/osmo-workflows/datasets/vda-demo
   storage_url=azure://storiondevxah69/osmo-workflows
   dataset=vda-demo
   

   对于非 S3 后端，绝不要静默回退到过时的 s3:// 值。

3. 推理策略（不可协商）

   • 默认复用集群中健康的持久化 NIM 端点。
   • 如果端点缺失或不健康，则自动部署——这是前置条件，不由用户决定。不要暂停询问；请使用 VDA 允许列表运行安装：

   export NIM_SERVICES="qwen3-vl qwen25-14b"
   skills/physical-ai-infrastructure-setup-and-resilient-scaling/components/inference-nim-operator/scripts/install.sh
   

   • 完整的端点文档和健康检查请参阅 references/nim/README.md。
   • 外部端点仅在主动选择时使用（明确请求或提供明确 URL）；仅在这种情况下跳过集群内部署。
   • 绝不要根据凭据是否存在来推断使用外部模式。
   • 绝不要为了释放 GPU 而缩减或删除现有 NIM。

4. 就绪状态检查

   osmo pool list --mode free
   osmo config show POD_TEMPLATE
   python3 scripts/pre_submit_guard.py --workflow assets/configs/osmo/<mode>.yaml
   

5. 缓存自动修复

   如果 pre_submit_guard.py 报告缓存失败，默认操作是运行：

   osmo workflow submit assets/configs/osmo/setup_model_cache.yaml \
     --set-string storage_url=<backend-prefix> path=data
   

   然后重新运行 pre_submit_guard.py，只有通过检查后才提交目标 VDA 流程。仅当后端/前缀不明确或缓存设置失败时才询问用户。

6. 调度策略

   VDA 模板会在 gpu_platform 上调度设置任务和工作进程（用户工作负载不依赖 system 池）。

提交（适用于所有流程）

所有流程使用相同的提交格式；只有工作流 YAML 不同。选择所需流程对应的 YAML，然后运行下面的命令。各流程的完整操作指南（阶段矩阵和流程详情）见链接中的参考文档。

流程	工作流 YAML	操作指南
增强 + 自动标注	assets/configs/osmo/augmentation_and_al.yaml	references/flows/augmentation_and_al.md
仅自动标注	assets/configs/osmo/auto_labeling.yaml	references/flows/auto_labeling.md
端到端（并行）	assets/configs/osmo/e2e.yaml	references/flows/e2e.md
端到端（超分辨率门控）	assets/configs/osmo/e2e_super_resolution.yaml	references/flows/e2e_super_resolution.md

SKILLS_DIR="$(cd "$(git rev-parse --show-toplevel)/skills/physical-ai-video-data-augmentation" && pwd)"
STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8)
osmo workflow submit assets/configs/osmo/<flow>.yaml \
  --pool <pool> \
  --set-string \
    dataset=<dataset> \
    run_id=run-$STAMP \
    storage_url=<backend-prefix> \
    gpu_platform=<gpu-platform> \
    video=<video-stem> \
    cosmos_model_cache_url=<backend-prefix>/data/models/cosmos_transfer \
    auto_labeling_model_cache_url=<backend-prefix>/data/models/auto_labeling \
    skills_dir="$SKILLS_DIR"

兼容性说明：

• 只使用一个 --set-string 标志，并在其后传入所有键值对。
• 同一条命令中不要重复使用 --set / --set-string 标志；某些 OSMO 版本只会采用最后一次出现的标志。
• 同一条提交命令中不要混用 --set 和 --set-string。
• 请显式传入 *_model_cache_url 值，以避免不同 OSMO 环境中的嵌套模板插值差异。
• 不要暴力尝试各种标志排列组合。直接使用此格式。

常见的可选覆盖项（将键值对追加到同一个 --set-string 列表中）：

cookbook=<scene_profile> \
vlm_url=<openai_base_url> \
llm_url=<openai_base_url> \
cosmos_model_cache_url=<url> \
auto_labeling_model_cache_url=<url>

仅自动标注流程没有增强阶段，因此运行时会省略 cosmos_model_cache_url；传入它不会有影响，并可让所有流程使用统一的提交格式。

OSMO 监控

# Workflow status + task states
osmo workflow query <workflow_id> --format-type json \
  | jq '{status, tasks: [.groups[].tasks[] | {name, status, exit_code}]}'

# Logs for a specific task
osmo workflow logs <workflow_id> --task <task_name> -n 200

# Output retrieval
osmo data list --no-pager <output_url>
osmo data download <output_url> <local_dir>/

对于完成产物，始终将完整运行输出复制到工作区：

ROOT="$(git rev-parse --show-toplevel)"
RUN_LOCAL_DIR="$ROOT/media/vda/runs/<run_id>"
mkdir -p "$RUN_LOCAL_DIR"
osmo data download "<storage_url>/datasets/<dataset>-outputs/<run_id>/" "$RUN_LOCAL_DIR/"

对于预计耗时超过两分钟的运行，至少每两分钟发送一次心跳更新。对于媒体证据，每个消息气泡单独输出一行 MEDIA:<absolute-path>。

执行连续性要求：

• 心跳必须在继续工作的同时报告进度；它们是状态更新，不是请求许可。
• 不要在阶段顺利完成后停下等待批准。
• 仅在遇到阻塞性故障，或用户明确要求停止／更改方向时暂停。
• 如果提交因插值失败，使用相同的规范单标志格式和修正后的值重新运行一次；不要反复尝试临时拼凑的标志。

MEDIA 格式要求严格：

• 只输出一行：MEDIA:/absolute/path/to/file.mp4
• 将 MEDIA: 保持在同一行中，不能拆分。
• 同一个气泡中不得包含其他文本。
• 不要在该指令周围添加代码围栏、项目符号或引号。
• 如果渲染失败：从稳定的工作区路径重试一次，然后输出 PNG 备用文件。

运行后对比证据（增强流程必需）

适用于成功运行后的 augmentation_and_al、e2e 和 e2e_super_resolution。

必需的完成输出（不要只提供原始输出 URL）：

1. 将完整输出和输入视频暂存到工作区本地路径：

   bash scripts/stage_run_artifacts.sh \
     --storage-url <storage_url> --dataset <dataset> --run-id <run_id> --video <video>
   

2. 从该本地运行副本渲染并排对比：

   bash scripts/render_side_by_side.sh \
     --run-local-dir "<repo>/media/vda/runs/<run_id>" --dataset <dataset> --video <video>
   

3. 从本地运行副本输出 MEDIA，并包含：

   • 来自 <run_local_dir>/setup_b0/configs/manifest.yaml 的增强摘要（<video>_aug0 的 sampled_vars）
   • 来自 <run_local_dir>/outputs/pseudo_labeled_augmented/<video>_aug0 的自动标注摘要
   • 对于 e2e／e2e_super_resolution，还需提供来自 <run_local_dir>/outputs/pseudo_labeled/<video> 的原始标签摘要

如果无法使用 ffmpeg，则从同一本地运行副本输出输入和增强后视频的 MEDIA，并仍然提供增强和自动标注摘要。

对于演示运行（未提供用户视频），请明确说明输入来自 nvidia/video-data-augmentation-demo。

支持文件

使用以下规范位置：

• 工作流：assets/configs/osmo/*.yaml
• 运行时脚本：scripts/*.sh、scripts/*.py
• 流程演练：references/flows/*.md
• 设置和故障排查：references/setup.md、references/troubleshooting.md
• 镜像和端点策略：references/container-images.md、references/nim/README.md
• 食谱调优：assets/cookbooks/TUNING_GUIDE.md