physical-ai-people-attribute-search

Physical AI People Attribute Search Workflow Orchestrator

OSMO で PAS を実行するためのデフォルトのワークフロースキルです。フロー選択、事前チェック、送信時の補間、監視、出力の取得を担います。

目的

事前チェックから出力のダウンロードまで、PAS の画像拡張と自動ラベリングのパイプラインを安全かつ再現可能な方法で実行します。

PAS パイプラインは、制御された衣服・外見のバリエーション（画像ドメイン）と同義語による属性キャプション（テキストドメイン）を生成し、既存の人物クロップデータセットを拡張します。画像編集拡張と MCQ 検証には paidf-augmentation コンテナを、人物属性のキャプション生成には 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 に少なくとも 1 つの ONLINE プールがあること	セットアップとワーカータスクのスケジューリング
Image Edit エンドポイント	クラスター内の NIM qwen-image-edit-2511（正常な場合は再利用し、そうでない場合は NIM オペレーター経由でデプロイ）。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

あいまいなリクエストの明確化：確定前に対応する

自律的に進めることを基本とします。不足情報によって実行が妨げられる場合に限り、質問してください。

自律的な既定値（質問しないでください）

• フローが明示的に指定されていない場合は、e2e を既定とします。
• cookbook が指定されていない場合は、default を既定とします。
• n_augmentations が指定されていない場合は、3 を既定とします。
• いずれかの段階が正常に完了したら、直ちに次の段階へ進んでください。

明確化のために一時停止すべき条件

不足している入力	重要な理由	質問
preflight の結果が USER_INPUT_REQUIRED	必須シークレットが不足しています	実行を妨げている点を解消するため、簡潔な質問を1つしてください
ストレージバックエンドのプレフィックスを導出できない	スキームが誤っていると、実行時にストレージ認証の不一致が発生します	"この実行で使うバックエンド固有のルートプレフィックスは何ですか？"
ONLINE GPU プール／プラットフォームがない	ワークフローをスケジュールできません	"この実行の対象とする GPU プール／プラットフォームを指定してください。"
NIM のデプロイに失敗し、外部 URL も指定されていない	ワーカーがモデルに接続できません	"Image Edit／VLM／LLM のエンドポイント URL を指定するか、NIM オペレーターのデプロイに GPU 容量を割り当ててください。"

ステップ 0：フローを選択して入力を収集する

入力データのポリシー

• PAS では、<person_id>/<view>.jpg のサブディレクトリに整理された人物クロップ画像が必要です。
• ユーザーが提供したデータセット入力は、常に第一級の入力として保持してください。
• 明示的に指定されたユーザーデータセットを、デモ用アセットに置き換えないでください。
• データセットが指定されていない場合は、データセットの提供を求めてください（PAS には組み込みのデモデータセットはありません）。

不足している値だけを収集します。

1. データセットのソース（storage_url + dataset 名）。
2. フロー（e2e、augmentation、auto_labeling）。既定値は e2e です。
3. OSMO の gpu_platform（一意に判断できる場合は自動選択します）。
4. Image Edit、VLM、LLM のエンドポイント URL（任意。既定ではクラスター内の NIM を使用し、外部エンドポイントの場合のみ設定します）。
5. person ID ごとの拡張数（既定値：3）。

送信の前に毎回、実行スタンプを生成します。

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

実行時間の概要（実行前に必須）

変更を伴うコマンドを実行する前に、簡潔な ETA の概要を提示してください。

標準的な所要時間：

フェーズ	典型的な所要時間
認証情報 + preflight	約1～2分
ワークフローの送信 + キュー投入／開始	約1～3分

ワークフローの実行時間（データセットのサイズとエンドポイントのレイテンシによって異なります）：

フロー	画像あたりの時間	典型的なデータセット（100枚、3回の拡張）
augmentation	画像あたり約2.5～3分	約4～5時間
auto_labeling	画像あたり約1～2分	約2～3時間
e2e	画像あたり約3.5～5分	約6～8時間

共通の前提条件（すべてのフロー）

1. 認証情報とコントロールプレーンの preflight

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

   出力に USER_INPUT_REQUIRED: が含まれている場合は、実行を妨げている点を解消するため、簡潔な質問を1つしてください。

2. ストレージの補間ポリシー

   storage_url は、実際のデータセット／アップロードのバックエンドから導出する必要があります。 バックエンドが一致しない場合に、古い値を暗黙的に既定値として使用しないでください。

3. 推論ポリシー（必須）

   • 正常なクラスター内の永続 NIM エンドポイント（qwen-image-edit-2511、qwen3-vl、qwen25-14b）を既定で再利用してください。
   • エンドポイントがない、または正常でない場合は、自動的にデプロイしてください。これは前提条件であり、ユーザーが判断することではありません。質問するために一時停止しないでください。Image Edit の NIMService マニフェストと VLM／LLM の NIM オペレーターのインストールについては、references/nim/README.md を参照してください。
   • PAS は OSMO ワークフロー内で推論サーバーを起動しません。ワーカーは 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 フラグは 1 つだけ使用し、すべてのキーと値のペアをその後に渡してください。
• 同じコマンド内で --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>/

2 分を超えると予想される実行では、少なくとも 2 分ごとにハートビートを送信してください。

実行後の出力

正常に完了すると、出力ディレクトリには次の内容が含まれます。

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
• クックブックの調整：assets/cookbooks/default/README.md