
名称	paidf-augmentation
描述	>- 用于编写或验证PAIDF增强YAML配置，或运行远程Cosmos Transfer/Predict、图像编辑或图像到视频推理。
开源协议	Apache-2.0 metadata: owner: NVIDIA service: physical-ai-data-factory
版本	1.1.0 reviewed: ‘2026-08-31’
作者	NVIDIA tags: - physical-ai - augmentation - cosmos - image-edit

PAIDF增强管线技能

通过NVIDIA生成式AI模型自动化字幕生成、生成和质量评估，统一增强相机数据的管线。BYOM（自带模型）： 每个模型都通过远程HTTP端点访问，该端点由配置中的endpoints:列表中的一个条目描述；添加模型通常是配置变更，而不是代码变更。

目的

使用此技能端到端驱动PAIDF增强管线：

选择正确的模型 — Cosmos Transfer 2.5（转换视频）、Cosmos Predict 2.5（生成/扩展视频）、image-edit（编辑图像）或image-to-video（动画化首帧：Cosmos3或Veo 3.1）。
编写并验证YAML配置，使其符合PipelineConfig Pydantic模式。
配置字幕生成（VLM、LLM、确定性VLM模板、文本或文件）以及评估器（幻觉检查、属性验证、VLM验证）。
在paidf-augmentation:1.1.0 Docker容器内启动并运行推理（仅远程API——无本地模型权重）。

当运行推理、编写或编辑配置、调试验证或运行时错误、添加数据样本、配置字幕生成、调整生成参数、注册BYOM端点/适配器或设置评估器时，使用此技能。触发关键词：增强、cosmos transfer、cosmos predict、图像编辑、图像到视频、veo、图像属性增强、缺陷图像生成、字幕生成、属性验证、配置验证。

不要将此技能用于训练或微调模型、部署集群或NIM端点，或无关的应用/数据库开发。

前提条件

要求	详情
Docker	`docker --version`。该镜像是仅远程API——它不包含Cosmos/torch权重，因此纯远程推理不需要GPU和`HF_TOKEN`。
NVIDIA GPU（条件性）	仅用于`data_processing.alignment`后处理器（cupy）和H.264解码（评估器，`data_processing.transcode`）。见限制。
端点URL	配置使用的每个角色各有一个可达URL：模型角色（`video_transfer`/`video_predict`/`image_edit`/`image2video`）以及用于字幕生成和评估的`vlm`/`llm`。默认是本地Qwen vLLM服务器（`Qwen/Qwen3.6-27B-FP8`在`vlm`上，`Qwen/Qwen2.5-14B-Instruct`在`llm`上）。如果用户没有运行任何服务器，请询问URL。
API密钥（条件性）	仅用于需要认证的端点。通过每个端点`api_key_env`命名的环境变量传递——绝不硬编码在YAML中。常见：`VLM_API_KEY`、`LLM_API_KEY`、`VEO_API_KEY`、`BUILD_NVIDIA_API_KEY`。本地端点不需要。
输入媒体	由`multistorageclient`可达的视频（传输/预测）或图像（编辑/图像到视频）——本地路径、`s3://`、`gs://`、`az://`或HTTP。

输入

按此优先级解析每个值：状态文件 → 显式提示参数 → 代理上下文 → 用户提示。 仅询问用户剩余未解决的内容。

输入	必需	描述
`config_path`	是	管线YAML的路径，例如`configs/cookbook/video-data-augmentation/config_video_transfer_CT25_nim.yaml`。如果缺失，从支持的模型中选择一个起始配置并与用户确认。
`input_media`	是	源视频/图像→`data[].inputs.rgb`。运行时可通过`data.0.inputs.rgb=...`覆盖。
`output_paths`	是	`data[].output.{video,caption,metadata}`；`evaluation`可选。
`model_name`	是	`augmentation.model.name`——一个端点`id`、角色或已知模型名称。自由格式字符串，不是枚举。
`endpoint_urls`	是	`endpoints[]`中每个使用中的角色对应一个条目。
`api_key_env`	如果认证	每个端点的环境变量名称；值来自环境。
`target_attributes`	否	`captioning.llm.variables`（例如`weather_condition`、`lighting_condition`）。
`generation_params`	否	`augmentation.parameters`——透传；仅发送已设置的旋钮。
`seed`	否	在`augmentation.parameters`下；`null`=随机，重试时重新滚动。

BYOM模型：端点、适配器、角色

管线从不针对每个模型嵌入SDK。而是：

endpoints:是列表。 每个条目有role、url、model（线上的模型字符串）、可选的id（仅用于区分共享角色的2个以上端点）、可选的adapter（API契约；默认来自角色）、api_key_env和timeout。
角色：vlm、llm（字幕生成+评估器）、image_edit、video_transfer（Cosmos Transfer）、video_predict（Cosmos Predict）、image2video（Cosmos3 / Veo）。
适配器（API契约）：openai.chat.completions、openai.images.edits、openai.video.sync、openai.video.async、nim、passthrough。同一个模型可以通过仅更改端点的adapter字段来通过不同契约提供服务。
模型选择：augmentation.model.name按id、否则按role、否则按模型名→角色映射解析端点（image-edit→image_edit、cosmos-transfer2.5→video_transfer、cosmos-predict→video_predict、cosmos3-image2video→image2video）。

支持的模型

当用户未指定模型时，根据其输入类型和目标选择：

输入类型 → 目标	`model.name`	角色 / 默认适配器	输入 → 输出
视频 — 更改场景属性（天气、光照、风格）	`cosmos-transfer2.5`	`video_transfer` / `nim`	视频（+控制）→ 视频
视频 + 文本 — 扩展或预测延续	`cosmos-predict`	`video_predict` / `nim`	视频+文本 → 视频
仅文本 — 从头生成视频	`cosmos-predict`（`inference_type: text2world`）	`video_predict` / `nim`	文本 → 视频
图像 — 编辑特定属性	`image-edit`	`image_edit` / `nim`（或`openai.chat.completions`、`openai.images.edits`）	图像 → 图像
图像 — 动画化首帧	`cosmos3-image2video`（或您的Veo端点id）	`image2video` / `openai.video.sync`（Veo：`openai.video.async`）	图像 + 提示 → 视频

关键规则：视频输入 + 场景属性更改 → Cosmos Transfer。从文本/图像/视频条件生成新视频 → Cosmos Predict。单图像编辑 → 图像编辑。静态图像 → 动态片段 → 图像到视频。

所有模型通过一个BaseExecutor经由远程HTTP运行；没有本地torchrun，也没有executor_type字段。

使用方法

第1步：启动Docker容器

将PAIDF_IMAGE_ID设置为从受信任的本地构建（或受信任的发布元数据中提供）记录的不可变sha256:镜像ID。镜像ID特定于构建和架构，因此此仓库无法提供一个通用值。验证可变便捷标签仍解析到预期ID，然后直接运行该ID：

set -e

PAIDF_IMAGE_ID="sha256:<expected-image-id>"
test "$(docker image inspect --format '{{.Id}}' paidf-augmentation:1.1.0)" = "$PAIDF_IMAGE_ID"
docker network inspect paidf >/dev/null 2>&1 || \
  docker network create paidf

docker run -it --rm \
  --network paidf \
  -v "$(pwd)/modules:/workspace/modules" \
  -v "$(pwd)/configs:/workspace/configs" \
  -v "$(pwd)/data:/workspace/data" \
  --entrypoint /bin/bash \
  "$PAIDF_IMAGE_ID"

不要从标签推导出PAIDF_IMAGE_ID并立即信任它；将标签与构建或发布时记录的摘要进行比较。如果注册表发布提供了签名清单，请在拉取前验证该签名，并使用其name:tag@sha256:<manifest-digest>引用。

网络： 增强仅进行出站请求，因此不需要-p/--publish端口。保留上述共享的paidf桥接以供远程端点使用。对于另一个模型容器，将其连接到同一桥接，并在端点URL中使用其容器名称。在桥接上的容器中运行主机本地的模型，或使用远程端点；不要授予增强容器访问主机网络的权限。
API密钥： 更倾向于使用平台机密管理器来注入所需的环境变量。否则，仅导出所需密钥并转发其名称-e VAR_NAME；绝不挂载或加载宽泛的凭据文件。
远程推理无需GPU — 为data_processing.alignment和任何H.264解码添加--gpus；选择一个不与忙碌的模型服务器共享的GPU。容器以uid 10000运行；确保data/可写（或--user "$(id -u):$(id -g)"）。

安全： 此工作流禁止主机网络，尤其当存在API密钥时。请查看pipeline-operations.md。

第2步：在容器内运行管线

uv run --no-sync modules/cli.py --config configs/<config_file>.yaml

# 使用OmegaConf CLI覆盖（点列表语法）
uv run --no-sync modules/cli.py --config configs/cookbook/video-data-augmentation/config_video_transfer_CT25_nim.yaml \
  data.0.inputs.rgb=/workspace/data/input.mp4 \
  augmentation.parameters.seed=42

环境变量：密钥按api_key_env变量→角色的默认环境变量解析。如果api_key_env命名了一个未设置的变量，则回退到角色默认值；对未认证端点留空。LOG_LEVEL设置日志级别。

配置模式

配置根据PipelineConfig（modules/aug_utils/schema/）验证，且有七个顶级部分：data、endpoints（一个列表）、pipeline、captioning、augmentation、data_processing和evaluators。每个部分的完整YAML见configuration-schema.md；运行时流程和常见的编辑任务见pipeline-operations.md。

示例

配置位于configs/cookbook/<用例>/下。有关文件夹布局，请参见食谱索引。

用例	配置
视频场景属性传输（CT2.5，`nim`）	`config_video_transfer_CT25_nim.yaml`
图像 → 视频	`config_image2video_cosmos3.yaml`（VLM→LLM）· `config_image2video_cosmos3_vlm_template.yaml`（VLM→模板）· `config_image2video_veo31.yaml`（Veo 3.1，异步）
图像属性增强	`config_image_edit_attribute_{chat_api,images_api,nim}.yaml` · `…_gemma_llm.yaml`（托管Gemma LLM交换）
缺陷图像生成 + MI对齐	`config_image_edit_defect_{chat_api,images_api}.yaml`
批量配置生成	`workflow_example.yaml` · `attribute_distribution_1000_v1.yaml`
智能空间种子图像 / 事件视频	`config_seed_image_gen_cosmos3_super_t2i_smart_spaces.yaml` · `config_event_video_gen_cosmos3_smart_spaces.yaml`

每个配置的字幕生成/评估器/适配器详情见config-decision-tree.md。

故障排除

在Docker容器内部运行所有推理和模式验证以获得一致的环境。对于配置验证错误、运行时/端点错误和典型的每阶段时序，请参阅troubleshooting.md。

限制

仅远程推理。 所有模型都在远程HTTP端点后面运行；没有本地权重，没有torchrun，没有executor_type，没有Gradio执行器。
GPU用于对齐和H.264解码。 远程推理不需要GPU。data_processing.alignment（cupy）和解码H.264的任何内容——评估器和data_processing.transcode——需要CUDA GPU，因为镜像仅附带硬件h264_cuvid解码器（软件AVC解码因许可而关闭）。VP9在软件中解码。视频输出仅VP9。
仅推理。 此管线增强并生成媒体——它不训练或微调模型。
认证因端点而异。 托管端点（例如Veo）需要通过api_key_env的密钥；本地端点（例如vLLM）不需要。

参考文件

configuration-schema.md — 每个配置部分的完整YAML。
config-decision-tree.md — 从哪个配置开始、模型/字幕选择、对齐覆盖规则。
pipeline-operations.md — 管线流程、工作示例、常见任务、存储、安全注意事项。
captioning-strategy-guide.md — 全部6种字幕模式及完整YAML。
evaluator-setup-guide.md — 幻觉调优、属性验证、MCQ布线。
troubleshooting.md — 验证/运行时错误和每阶段时序。
image-attribute-augmentation.md — 图像属性增强图像编辑工作流和数据集打包。
event-video-gen.md — 智能空间图像到视频事件生成。