physical-ai-people-attribute-search

Physical AI 人员属性搜索工作流编排器

PAS 在 OSMO 上执行的默认工作流技能。负责流程选择、 预检、提交时插值、监控和输出检索。

目的

安全且可复现地运行 PAS 图像增强和自动标注流水线， 从预检一直到输出下载。

PAS 流水线通过生成受控的服装／外观变化（图像域）和同义属性描述（文本域）， 增强现有的人员裁剪数据集。它使用 paidf-augmentation 容器进行图像编辑增强并进行 MCQ 验证， 使用 paidf-auto-labeling 容器生成描述人员属性的文本。

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

先决条件

在运行预检或任何提交之前，请确认以下各项。缺少必需的密钥时， scripts/preflight_credentials.sh 会提示 USER_INPUT_REQUIRED:。

要求	满足方式	用途
NGC API 密钥（可选）	NGC_API_KEY、NGC_CLI_API_KEY 或兼容的 nvapi-* 令牌	可选，用于刷新 nvcr_io 凭据；默认 PAS 镜像引用是公开的
Hugging Face 令牌	HF_TOKEN（或 HUGGING_FACE_HUB_TOKEN），或缓存在 ~/.cache/huggingface/token 中的令牌	创建 OSMO hf_token 凭据
OSMO CLI 访问权限	PATH 中存在 osmo，已登录且具有默认配置，以及与 storage_url 匹配的已注册 DATA 凭据配置	提交／监控工作流，以及列出／下载对象
GPU 池	osmo pool list --mode free 中至少有一个 ONLINE 池	安排设置任务和工作进程任务
图像编辑端点	集群内 NIM qwen-image-edit-2511（若健康则复用，否则通过 NIM operator 部署）；通过 image_edit_url 可选择使用外部端点	图像域增强
VLM 端点	集群内 NIM qwen3-vl（与 VDA 共享）；通过 vlm_url 可选择使用外部端点	MCQ 验证和人员属性描述生成
LLM 端点	集群内 NIM qwen25-14b（与 VDA 共享）；通过 llm_url 可选择使用外部端点	MCQ 问题生成

说明

1. 根据用户意图选择工作流（e2e、augmentation、auto_labeling）。
2. 开始运行操作前，先提供预计执行时间概览。
3. 提交前运行预检和就绪状态检查。
4. 根据当前数据集后端推导提交时所需的值（切勿猜测 storage_url）。
5. 使用明确的插值值提交工作流，并监控直至完成。
6. 检索输出并总结任务结果。

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

run_script("bash scripts/preflight_credentials.sh --workflow assets/configs/osmo/e2e.yaml")

可用脚本

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

脚本	作用
scripts/preflight_credentials.sh	密钥／控制平面预检和工作流镜像访问检查
scripts/augmentation_worker.sh	图像编辑增强工作进程（预处理、配置生成、增强、后处理）
scripts/auto_labeling_worker.sh	人员属性描述生成工作进程
scripts/endpoint_common.sh	共享的端点健康状态／身份验证辅助功能

支持的流程

流程	OSMO YAML	组序列	典型用途
e2e	assets/configs/osmo/e2e.yaml	setup -> augmentation -> auto_labeling	完整流水线：增强人员裁剪图像，然后生成描述
augmentation	assets/configs/osmo/augmentation.yaml	setup -> augmentation	仅进行图像编辑增强，不生成描述
auto_labeling	assets/configs/osmo/auto_labeling.yaml	setup -> auto_labeling	仅对预先增强的人员裁剪图像生成描述

根据用户请求选择正确的工作流

用户意图	工作流
“增强人员裁剪图像并生成描述”／“完整 PAS 流水线”	e2e
“生成服装变化”／“仅增强”／“图像编辑”	augmentation
“为增强后的图像生成描述”／“生成搜索查询”／“仅标注”	auto_labeling

消歧：在确认执行前处理模糊请求

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

自主默认值（不要提问）

• 如果未明确指定 flow，默认使用 e2e。
• 如果未指定 cookbook，默认使用 default。
• 如果未指定 n_augmentations，默认使用 3。
• 任何阶段成功完成后，立即继续下一阶段。

需要暂停以进行消歧的触发条件

缺失的输入	重要原因	提问
预检返回 USER_INPUT_REQUIRED	缺少必需的密钥	提出一个简洁的解阻问题
无法推导出存储后端前缀	错误的方案会导致运行时存储身份验证不匹配	“这次运行的后端原生根前缀是什么？”
没有 ONLINE GPU 池/平台	工作流无法调度	“这次运行应使用哪个 GPU 池/平台？”
NIM 部署失败且未提供外部 URL	Worker 无法连接到模型	“请提供 Image Edit / VLM / LLM 端点 URL，或为 NIM operator 部署提供 GPU 容量。”

步骤 0：选择 Flow 并收集输入

输入数据政策

• PAS 要求人员裁剪图像按 <person_id>/<view>.jpg 子目录组织。
• 始终将用户提供的数据集输入作为一等输入保留。
• 绝不使用演示资源替换明确指定的用户数据集。
• 如果未提供数据集，请索要一个（PAS 没有内置演示数据集）。

仅收集缺失的值：

1. 数据集来源（storage_url + dataset 名称）。
2. Flow（e2e、augmentation、auto_labeling）；默认为 e2e。
3. OSMO gpu_platform（在没有歧义时自动选择）。
4. Image Edit、VLM 和 LLM 的端点 URL——可选；默认使用集群内的 NIM，仅在使用外部端点时设置。
5. 每个人员 ID 的增强数量（默认值：3）。

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

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

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

在运行任何会产生变更的命令之前，提供简短的预计耗时概览。

基准耗时范围：

阶段	典型耗时
凭据 + 预检	~1-2 分钟
工作流提交 + 排队/启动	~1-3 分钟

工作流运行时间（取决于数据集大小和端点延迟）：

Flow	每张图像耗时	典型数据集（100 张图像，3 次增强）
augmentation	~2.5-3 分钟/张图像	~4-5 小时
auto_labeling	~1-2 分钟/张图像	~2-3 小时
e2e	~3.5-5 分钟/张图像	~6-8 小时

通用前置条件（所有 flow）

1. 凭据和控制平面预检

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

   如果输出包含 USER_INPUT_REQUIRED:，提出一个简洁的解阻问题。

2. 存储插值政策

   storage_url 必须根据实际数据集/上传后端推导。 后端不匹配时，绝不要默默使用过时的默认值。

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

   • 默认重用健康的集群内持久化 NIM 端点 （qwen-image-edit-2511、qwen3-vl、qwen25-14b）。
   • 如果缺失/不健康，自动部署——这是前置条件，不由用户决定。不要暂停询问。有关 image-edit NIMService 清单以及 VLM/LLM NIM operator 安装，请参阅 references/nim/README.md。
   • PAS 不会在 OSMO 工作流内部启动推理服务器；Worker 会使用 image_edit_url / vlm_url / llm_url 端点。
   • 外部端点仅在选择启用时使用（明确请求或明确提供 URL）；只有在这种情况下，才在提交时覆盖 *_url 值。
   • 绝不要为了释放 GPU 而缩减现有 NIM 的规模或删除它们。

提交（所有流程）

每个流程都使用相同的提交格式；只有工作流 YAML 会变化。

SKILLS_DIR="$(cd "$(git rev-parse --show-toplevel)/skills/physical-ai-people-attribute-search" && 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> \
    skills_dir="$SKILLS_DIR"

端点默认使用集群内的 NIM（image_edit_url / vlm_url / llm_url）；请按照上文的推理策略部署或复用它们。除非使用外部端点，否则不要传入这些参数。

兼容性说明：

• 只使用一个 --set-string 标志，并在其后传入所有键值对。
• 同一条命令中不要重复使用 --set / --set-string 标志。

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

cookbook=<cookbook_name> \
n_augmentations=<count> \
image_edit_url=<image-edit-endpoint> \
vlm_url=<vlm-endpoint> \
llm_url=<llm-endpoint>

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>/

对于预计运行时间超过两分钟的任务，至少每两分钟发送一次心跳更新。

运行后输出

成功完成后，输出目录包含：

对于 augmentation / e2e：

• <person_id>/aug_<n>/output.jpg — 增强后的多面板图像
• <person_id>/aug_<n>/output.txt — 自然语言描述
• <person_id>/aug_<n>/output_metadata.json — 验证结果
• dataset/augmented_data.json — 包含属性和查询的结构化数据集
• dataset/augmented_imgs/ — 按视图拆分的裁剪图像

对于 auto_labeling：

• caption_<id>/task/open_qa.json — 按问题库分组的人员属性描述

支持文件

请使用以下规范位置：

• 工作流：assets/configs/osmo/*.yaml
• 运行时脚本：scripts/*.sh
• 流程指南：references/flows/*.md
• 设置和问题排查：references/setup.md、references/troubleshooting.md
• 图像：references/container-images.md
• Cookbook 调优：assets/cookbooks/default/README.md