omniverse-usd-performance-tuning

Omniverse USD のパフォーマンス調整

対象範囲

読み込みが遅い、FPS／インタラクティブ性が低い、GPU またはシステムメモリの使用量が多い、GPU クラッシュ／デバイス喪失、検証エラー、CAD／変換品質のトリアージ、プロファイリング、シーンの最適化依頼など、幅広い USD のパフォーマンス改善に使用します。このスキルはユーザー向けワークフローを担当します。セットアップ、認証、プロファイリング、検証、変更、レポート作成は、該当する段階に進んだ時点で参照先に従って実行します。

エージェントスキルの互換性のため、フロントマターでは version と tools をトップレベルに配置し、NVCARPS のフィールドは metadata の下に配置します。

セッション開始時の必須ゲート

静的な分類のみの回答を除き、調整に関する出力を行う前に、skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md に従ってください。この参照先では、output_path、setup-preflight.json、Format A／Format B を規定し、無断で場当たり的な調査を行うことを禁止しています。

必須の動作：

• プリフライトが存在しない、または読み取れない場合：setup-usd-performance-tuning を呼び出します。
• プリフライトが存在する場合：Format A を出力し、ユーザーの回答を待ちます。選択肢は参照先で定義されています。ここで選択肢を再掲したり、新たに作ったりしないでください。
• ランタイムがこのセッションですでに確認済みの場合：簡潔な Format B を使用します。

[Kit: {runtime_context.kit.application} {runtime_context.kit.version}  |  SO: {runtime_context.usdOptimize.version}  |  AV: {runtime_context.assetValidator.version}]

スタンドアロン／usd-optimize パッケージでは、ランタイムの証拠にパッケージ／センチネルの確認に加えて、共有ライブラリまたはインポート／読み込みの検証を含める必要があります。Python 実行ファイル／バージョンの確認だけでは不十分です。omniverse:// アセットの場合は、セットアップ、トリアージ、または最初のオープンの前に、omniverse-authentication を経由してください。

エントリースキルと判断ルール

• Kit、スタンドアロン、または usd-validation-nvidia のみの部分スタックなど、いずれかのランタイム経路が確認された場合は、エントリースキルとして omniverse-usd-performance-tuning を指定してください。要求されたツールまたは操作がない場合は、blocked_missing_usd_optimize や blocked_missing_usd_optimize_operation など、該当する具体的なブロッカーコードを返してください。別のワークフローで代用しないでください。
• ランタイム経路が確認されておらず、ランタイムの選択またはセットアップが最初に未解決となる問題である場合に限り、エントリーとして setup-usd-performance-tuning を指定してください。
• これは担当範囲のルールであり、フェーズの順序ではありません。認証、セットアップ、トリアージは通常の順序で実行します。

計画判断 — decision は、リクエストで破壊的操作が指定されたかどうかではなく、レスポンスの形式から導出してください（ハーネスが形式の不変条件を適用します）。

• ready_to_plan — このレスポンスでユーザーの対応を待つ項目がなく、committed_milestones が planned_phases と一致する場合です。一般的な最適化では、ロスレスの標準チェーンに加えて、積極的な auto-within-tolerance 有界損失パスを実行するのがデフォルトです（過剰にテッセレーションされた、視覚的許容範囲内のターゲットを、ターゲットごとの保守的な範囲まで削減します。プロンプトではなく、1行の通知を添えて適用します）。
• approval_required — このレスポンスが、今提示しているゲートで停止する場合です。committed_milestones は planned_phases の厳密な接頭辞であり、approval_required_reason にゲートを記載します。きっかけとなるのは、操作を計画する前にエージェントが提示しなければならない未解決の判断であり、操作が破壊的であるという事実ではありません。プリミティブフィッティング候補となるシーン（例：BIM/CAD の配管やダクトの配列）に対するデフォルト引数での fitPrimitives は、標準的で期待される有効な処理であり、実行時にゲートを設ける形で ready_to_plan を維持します。有界損失操作（decimateMeshes、fitPrimitives）がその場での確認が必要になるのは、保守的な範囲を超えて実行される場合、機能精度が必要なターゲット（articulated／物理演算／シミュレーション対応／計測／バリアントを含む）に対して実行される場合、または保持の意図が明示されている場合（ユーザーが UV、displayColors、サブセットの保持を求めている場合）のみです。許容値が指定されていない decimateMeshes リクエストでは、最初に1回だけ mm_tolerance を質問することで、その場での確認を行います。レスポンスが今提示する restructure-decision も、同じ理由で approval_required です。適用権限の分類については、usd-optimize-run-operations/references/operation-safety.md を参照してください。
• blocked — blocked_code が該当する場合です。
• 後の段階で実際に発生する将来のゲート — まだ到達していない下流の restructure-decision や、Phase 7 のオプトインメニューにまとめられた ID ゲート付き操作など — は、decision ではなく gates_observed に記載してください。

標準プランの契約

広範な最適化では、構造化されたプラン／ステータスの要約は、次の条件を満たす必要があります。

• マイルストーンのリストは omniverse-usd-performance-tuning から開始してください。関連する場合に限り、Phase 0 のコンテキストとして setup-usd-performance-tuning を含めてください。
• 一般的な最適化では、トップレベルの decision を ready_to_plan に設定してください。
• committed_milestones と planned_phases の両方に、optimization-report までの一連の項目を含めてください。
• プロファイルラベルには正確に profile-stage:baseline と profile-stage:after を使用してください。profile-stage のみを出力してはいけません。
• 次のサブシーケンスを正確に保持してください。順序を変えない範囲でのみ、任意の分析項目を挿入できます。

omniverse-usd-performance-tuning -> profile-stage:baseline -> usd-structure-assessment -> usd-validation-runner -> restructure-decision -> apply-restructure -> usd-optimize-run-validators -> usd-optimize-interpret-validators -> usd-optimize-run-operations -> profile-stage:after -> compare-profiles -> optimization-report

2 つのマイルストーンは条件付きで必須です。該当条件を満たす場合、単に振り分けるのではなく、次の位置にコミット済みマイルストーンとして含める必要があります。

• usd-hierarchy-dedupe-candidates — ステージで階層構造のコピーが繰り返されている、インスタンス化がほとんどない、またはまったくないのにメッシュ数が多い、あるいはモノリシックなルートが確認された場合は、usd-structure-assessment の後、restructure-decision の前に含めてください。この項目なしに hierarchy_dedupe.recommended: false と結論づけてはいけません。
• usd-edit-target-planner — ステージが合成されており（参照またはペイロードを使用）、各ターゲットを独自のルートレイヤーとして最適化する必要がある場合は、apply-restructure の後、Usd Optimize のバリデーター／操作の一連の処理の前に含めてください。

広範な最適化のマイルストーン要約では、usd-optimize-run-validators または usd-optimize-interpret-validators を restructure-decision より前に記載してはいけません。フェーズを考慮したバリデーターの振り分けは、引き続き usd-validation-runner 内で行います。

ユーザーがオプトアウトする場合、簡易処理を求める場合、または停止条件に該当する場合を除き、広範な最適化では、範囲を絞った反復処理をデフォルトで 3 回行ってください。各反復で中間レポート／更新を書き出します。後続の処理では、ワークフロー全体を最初からやり直すのではなく、前の証拠を再利用してください。

実行上の規律

• エンドツーエンドの実行前に references/workflow.md を読み込んでください。Phase 0～7 のフロー、Kit／スタンドアロンの分岐、バリデーターの振り分け、操作の順序、終了基準、所要時間の目安、デフォルトの 3 回反復パターンは、このファイルを参照してください。
• 入れ子になったフェーズ名をチェックリストのラベルとして扱ってはいけません。フェーズを実行する前に、そのフェーズの入れ子になった README.md またはリファレンスを読み込み、それに従ってください。後続のスキル本体は、そのフェーズに到達した場合にのみ呼び出してください。
• ローカルワークスペースの指示やヘルパーコマンドが提示されている場合は、それらを確認し、必要な成果物の作成、検証、またはレンダリングに使用してください。ファイルやツールを利用できない場合は、完了したことを捏造せず、確認できた阻害要因を報告してください。
• バイナリや大容量のアセットについて、生の内容を出力してはいけません。範囲を限定したメタデータ、チェックサム、サイズ、検証／プロファイルの要約、簡潔な事実、またはツールのレポートを使用してください。
• Kit のログ、usd-validation-nvidia の CSV、Usd Optimize のログ、Tracy の CSV、その他のランタイム出力を読む前に、references/runtime-artifact-token-budget.md に従ってください。生のアーティファクトはディスク上に保持し、まず要約 JSON を読み、全体のダンプやライブストリームではなく、範囲を限定したスナップショットを使用してください。

収集する最低限のコンテキストは、対象ステージ、問題／目標、ローカル／マウント済み／リモートの場所、ランタイム、判明している場合はワークロードの種類、診断のみか変更を行うか、書き込みの許可と出力先です。明示的に許可されていない限り、ソースを上書きしてはいけません。変更を行う場合は、最適化済みの出力先を別にすることを優先してください。しきい値、改善率、メトリクス、ランタイムの証拠を捏造してはいけません。

ルーティングマップ

• コンポジション、構造、レイヤーの健全性、インスタンス化の準備状況：usd-structure-assessment。
• 検証／コンテンツの問題：usd-validation-runner。必要に応じて validate-* または Usd Optimize のバリデーターにルーティングします。
• 編集対象、バリアント、ペイロード、出力に関する判断：usd-edit-target-planner。
• インスタンス化されていない、コピー済み階層の繰り返し／高いメッシュ数：usd-hierarchy-dedupe-candidates。
• モノリシックなステージ、またはアセット境界の具体化：restructure-decision、承認後に apply-restructure。
• CAD コンバーターの設定：references/cad-conversion/README.md。
• Usd Optimize の実行：usd-optimize-run-validators、usd-optimize-interpret-validators、usd-optimize-run-operations。
• FPS、フレーム時間、Hydra／RTX メトリクスなど、Kit ランタイム全体のプロファイリング：外部の NVIDIA／omniperf プロファイリングスキル。

広範な作業をルーティングする前に、パイプラインのフェーズやファクトリーレベルの構造化が判断に関係する場合は、usd-structure-assessment のトレードオフに関するリファレンスを読みます。

ミューテーションと操作のルール

references/workflow.md#operation-ordering-invariants に従ってください。大まかな不変条件は、プロトタイプを最初に処理し、次にアセットごとに検証し、最後にステージレベルの操作を行うことです。

常に次のことを行います。

• ミューテーションの前にコンポジション監査を実行します。
• プロセッサーの実行前後に検証します。
• アセットごとの検証前にプロトタイプを最適化します。
• 非常に大規模な CAD シーンでは、ステージ全体のメッシュ重複排除を行う前に、階層レベルでの再利用を確認します。
• ボトルネックの根拠に基づいて推奨事項を提示します。調査結果なしに固定のスタックを推奨してはいけません。
• 書き込みが許可されていない場合は、ミューテーションを承認しません。

Usd Optimize の選定方針：

• 複数の操作で同じ調査結果に対処できる場合は、references/operations/operations.json の canonical 操作を優先します。
• 頂点の溶接：単独の mergeVertices より、明示的なフラグを指定した canonical の meshCleanup を優先します。ミューテーションの前に、上流の usd-optimize の仕組みとローカルの承認ポリシーに従ってください。
• 階層の重複排除：Phase 2 の降下では、usd-hierarchy-dedupe-candidates と apply-restructure を優先します（これらがマニフェスト／ID の契約を担います）。単独で承認されたチェーンの重複排除実行では deduplicateHierarchies を直接実行し、フロンティア領域ごとに呼び出します（paths と領域ごとの maxDepth）。
• メッシュごとの重複排除：canonical の deduplicateGeometry を優先します。findCoincidingGeometry は分析／レポート専用です。
• 明示的に依頼されない限り、boxClip、deletePrims、removeAttributes、removeUntypedPrims などの documentary 操作や、狭義の非インスタンス化ケースを除く広範な merge を、エージェントから開始してはいけません。
• バリデーターの根拠により usd-optimize-interpret-validators に組み込まれている場合や、後続のコンテキストで必要な場合は、sparseMeshes、optimizePrimvars、primitivesToMeshes、utilityFunction、pythonScript のレシピなどの specialty 操作を使用できます。

成果物と最終レスポンス

エンドツーエンドの最適化では、ミューテーションを実行した場合、最適化済みの USD ステージと optimization-report レポートを生成する必要があります。診断のみを行う場合も、最適化済みのステージが書き出されていないことを示すレポートまたは概要で締めくくる必要があります。

レポートの要件：

• 構造化 JSON は、optimization-report の scripts/optimization-report.schema.json に準拠する必要があります。
• 生成された Markdown の概要を保存します。
• render_preview.py を使って references/report-templates/optimization-report.html.template から HTML をレンダリングします。HTML を手書きしてはいけません。
• レポート成果物の代わりに、場当たり的な概要ファイルやチャットだけでの振り返りを使用してはいけません。

最終ランタイムレスポンスでは、次の内容を明示する必要があります。

• 選択したエントリースキルと選択したランタイム／プリフライトの状態。該当する場合は、スタンドアロンパッケージのセンチネル／ロードの証拠を含めます。
• 最適化済み USD の出力先パス。書き出していない場合は、ミューテーションを実行していないこと。
• ソースを上書きしていないか／インプレースでミューテーションしたかの状態。
• 実行した操作の正確なチェーン。特に、安全／ロスレスなチェーンを主張する場合は、その内容。
• 証拠から確認できる、最適化前後の検証結果とプロファイル指標。
• 検証済みのレポート JSON、生成された Markdown、レンダリング済み HTML、スキーマ／検証の判定、存在する場合はスコア、および workflow_mode。

プリフライトが存在しない場合、検証／レンダリングに失敗した場合、レポート成果物がない場合、またはミューテーションを実行していない場合は、その事実を明確に伝え、欠落した成果物をチャットだけでの振り返りで置き換えてはいけません。

制限事項と参考資料

このスキルは、ランタイムのインストール、後続の参考手順の置き換え、リモートアセットの認証、依頼されていない破壊的な書き込みの承認を行うものではなく、証拠なしにパフォーマンス向上を保証するものでもありません。ランタイムの状態が不明確な場合はセットアップゲートに戻ってください。証拠を得る前にミューテーションが行われたように見える場合は、まずベースラインのプロファイリングとコンポジション監査に戻ってください。

主な参考資料：

• references/workflow.md
• references/briefing-the-skill.md — 依頼で明示すべき内容と、その理由について説明しています。依頼内容が簡素な場合は参照してください。方針を決める4つの要素と、明示された三角形数やメッシュ数など、品質を意図せず損なう表現について説明しています。
• references/runtime-artifact-token-budget.md
• references/skill-map.md
• skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md
• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/optimization-tradeoffs.md
• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md
• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md
• skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md
• skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md
• references/upstreams/usd-optimize.md

ネットワークアクセスが可能で、現在の上流の動作が重要な場合は、参考ファイルに記載されているライブ URL を使用してください。