omniverse-usd-performance-tuning

Omniverse USD パフォーマンスチューニング

使用するタイミング

読み込みの遅さ、メモリ使用量の多さ、低い FPS、GPU クラッシュ、変換品質のトリアージ、USD シーンの最適化に関する一般的なリクエストなど、幅広いパフォーマンス関連の依頼には、このワークフローを使用してください。

手順

1. 静的な分類テストのみを求めるプロンプトでない限り、チューニング結果を出す前に、必須のランタイムコンテキスト確認から始めます。
2. 幅広い最適化のリクエストは ready_to_plan に分類し、approval_required は計画前に実行する破壊的操作を明示的に指定するプロンプトにのみ使用します。
3. 構造化されたマイルストーンの順序を維持し、マイルストーンを列挙する際は profile-stage:baseline / profile-stage:after のラベルを付けて、optimization-report までの標準的な全工程を計画します。幅広い最適化では、ユーザーが対象外とする場合、迅速な対応を求める場合、または停止条件に該当する場合を除き、範囲を絞った反復をデフォルトで3回計画します。
4. 下流のスキル本文は該当するフェーズに達した場合にのみ呼び出し、読み込む際は、コンパクトな概要を参照しつつ、ランタイムの生のアーティファクトをディスク上に保持します。

agentskills.io のランタイム互換性のため、Frontmatter の version と tools はトップレベルに配置します。NVCARPS の検出用フィールドは metadata の下に配置します。

出力形式

選択したエントリースキルを明記した計画またはステータス概要を返します。一般的な最適化のリクエストには ready_to_plan を使用し、optimization-report までの全マイルストーンを含め、プロファイルフェーズには profile-stage:baseline と profile-stage:after のラベルを付けます。構造化された出力では、幅広い最適化におけるマイルストーンの順序は、omniverse-usd-performance-tuning -> profile-stage:baseline -> usd-structure-assessment -> usd-validation-runner -> restructure-decision -> apply-restructure -> so-run-validators -> so-interpret-validators -> so-run-operations -> profile-stage:after -> compare-profiles -> optimization-report です。エンドツーエンドの実行では、変更処理を実行した場合に最適化されたステージを生成し、optimization-report のリファレンスのスキーマ（そのリファレンス内の scripts/optimization-report.schema.json）に準拠したレポートを生成します。幅広い最適化では、範囲を絞った反復をデフォルトで3回計画します。各反復で中間レポートまたは更新を作成し、後続のパスではワークフロー全体を最初からやり直さず、以前のエビデンスを再利用します。

読み込みの遅さ、低い FPS、メモリ使用量の多さ、GPU クラッシュ、変換品質、または「シーンを最適化して」といった幅広いパフォーマンス関連の依頼には、このワークフローを使用してください。

エントリースキルのルール

エージェントがその作業を実行するための検証済みの方法を少しでも持っている場合、このスキルは幅広いパフォーマンス関連作業の名前付きエントリーポイントになります。ランタイムの確認手順の詳細は setup-usd-performance-tuning に記載されています。このルールでは、ユーザー向けのパフォーマンス関連リクエストをどのスキルが担当するかのみを決定します。

• セットアップ時の確認で、Kit、スタンドアロン、または Asset Validator のみといった部分的なスタックを含む、検証済みのランタイムパスが1つでも示された場合は、ここから開始します。ユーザーが要求したツールがない場合は、別のワークフローに置き換えるのではなく、具体的な blocked_code（blocked_missing_scene_optimizer、blocked_missing_so_operation など）を返します。
• ランタイムパスが1つも検証されておらず、ランタイムの選択またはセットアップが最初に解決すべき問題である場合にのみ、setup-usd-performance-tuning から開始します。
• omniverse:// アセットの場合は、まず omniverse-authentication から開始します。リモートアセットでは、認証をセットアップとトリアージより先に行います。

この判断で決めるのは担当スキルであり、実行順序ではありません。セットアップ、認証、トリアージはすべて通常のフェーズ順に実行されます。このルールで定めるのは、応答でエージェントがエントリースキルとして名前を挙げるスキルのみです。

ランタイムコンテキスト — セッション開始ゲート（必須）

他のチューニング出力を行う前に、 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 を出力し、ユーザーが Continue、 Change Kit、Switch to standalone、または Re-run probe を選択するまで待ちます。
• 同じセッション内でランタイムが確認済みの場合：後続の状況確認には簡潔な Format B を使用します。

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

ランタイムアーティファクトのトークン予算

Kit のログ、Asset Validator の CSV、Scene Optimizer のログ、Tracy の CSV、 その他のランタイム出力を読む前に、 references/runtime-artifact-token-budget.md に従ってください。生のアーティファクトはディスク上に保持し、 まず概要 JSON を読み、ログ全体のダンプやライブストリームではなく、範囲を限定したログスナップショットを使用します。

計画時の承認と実行時の承認

計画時の approval_required は、破壊的な操作を明示的に指定したリクエストに限られます。ready_to_plan と approval_required のどちらにするかを判断する際は、次のルールに従ってください。

• 計画時の approval_required — ユーザーのリクエスト自体が、「このステージをフラット化する」「メッシュをデシメートする」「プロトタイプを結合する」「未使用のプリムを削除する」など、同じワークフロー内では元に戻せない、特定の破壊的な操作を指定している場合です。この場合、エージェントの最初の応答では、その操作を実行する計画を確定する前に、操作名を明示して承認を求める必要があります。
• 計画時の ready_to_plan — ユーザーのリクエストが「このシーンを最適化する」「読み込みを速くする」「GPU メモリを削減する」「インタラクティブ性を向上させる」など、一般的な場合です。エージェントは、計画で実行する破壊的な操作（たとえば mergeMaterials を指定した so-run-operations）も含め、計画全体を提示します。計画そのものを伏せてはいけません。各破壊的な操作への承認は、計画の承認を求める際に併せて求めます。

ここでの区別は、計画を承認することと破壊的な操作を承認することです。一般的な最適化リクエストは計画を立てることを許可しますが、特定の破壊的な操作の実行を許可するものではありません。

構造化されたランタイムテストへの応答や、同様の計画概要では、次のようにします。

• 将来の restructure-decision プロンプトは、計画されたユーザー判断ゲートです。一般的な最適化リクエストに対して、最上位の応答 decision を approval_required にする理由にはなりません。
• 一般的な最適化リクエストでは、decision: "ready_to_plan" を設定し、optimization-report までの予定された一連の流れ全体を committed_milestones と planned_phases の両方に含めます。
• 最上位の decision が ready_to_plan のままでも、gates_observed に asks_user_for_restructure_decision を含めることは有効です。
• 一連の流れでプロファイルフェーズを指定する場合は、正確なラベル profile-stage:baseline と profile-stage:after を使用してください。曖昧な単独の profile-stage トークンは出力しないでください。
• 構造化されたマイルストーン一覧は、所有するエントリスキルである omniverse-usd-performance-tuning から始めてください。setup-usd-performance-tuning は Phase 0 の追加コンテキストとしてのみ含め、エントリスキルのマイルストーンの代わりにしてはいけません。
• 幅広い最適化リクエストでは、順序を変えない範囲で追加の分析ステップを挿入する場合を除き、上記の Output Format に記載されたマイルストーンの部分列をそのまま維持してください。
• 幅広い最適化のマイルストーン概要では、restructure-decision より前に so-run-validators または so-interpret-validators を列挙しないでください。フェーズに応じたバリデーターの振り分けは引き続き usd-validation-runner を通じて行います。SO バリデーターの実行／解釈マイルストーンは、構造化された計画の契約に従い、再構成の判断後に配置します。

出力要件

エンドツーエンドの最適化作業では、ミューテーションを実行した場合に、最適化済み USD ステージと、optimization-report リファレンスの scripts/optimization-report.schema.json に準拠した構造化最適化レポートの両方を作成する必要があります。HTML レポートは、render_preview.py を介して references/report-templates/optimization-report.html.template からレンダリングしてください。HTML を手書きしてはいけません。診断のみの作業でも、最適化済みステージは書き込まれていないことを明記したレポートまたはサマリーで締めくくる必要があります。

目的

デジタルツインの USD パフォーマンスに関する依頼を、変更前の証拠を保持しながら、適切な診断および最適化ワークフローに振り分けます。

前提条件

• ステージのパス、または対象アセットを特定できるだけの情報。
• ユーザーの目的：診断のみ、検証、プロファイリング、またはプロセッサの実行。
• まだ判明していない場合は、setup-usd-performance-tuning で確認したランタイムの利用可能状況。
• その場での変更と、別の最適化済み出力の書き込みのどちらが許可されているか。

例

• 「この USD の読み込みが遅いです。まず何を確認すべきか、トリアージしてください。」
• 「低 FPS の CAD シーンをパフォーマンスワークフローに振り分けてください。」

トリアージの順序

0. ランタイムゲート。 検証、プロファイリング、最適化の前に、上記の必須セッション開始ゲートに従ってください。このスキル内でランタイムを直接スキャン、プローブ、インストール、選択してはいけません。プローブ／選択／インストールの振り分けを担当するのは setup-usd-performance-tuning であり、ここで使用するプリフライト情報も同スキルが書き込みます。

1. 対象となる問題を特定します。

   • 読み込み時間。
   • FPS または操作性。
   • GPU またはシステムメモリ。
   • クラッシュまたはデバイスの切断。
   • CAD 変換の品質。
   • 検証の失敗。

2. 必要最小限の情報を収集します。

   • ステージのパスとサイズ。
   • ステージがローカル、マウント済み、または omniverse:// のリモートのいずれか。リモートアセットの場合、初回オープンの前に omniverse-authentication を経由してください。
   • Kit または USD ランタイム。
   • ワークロードが CAD、VFI、AIF、Isaac、汎用 OpenUSD のいずれか。
   • その場での変更が許可されているか。
   • ユーザーが診断のみを希望しているか、プロセッサの実行を希望しているか。

3. 振り分けます。

   • USD の構成に関する質問：usd-structure-assessment（構成は現在 SA の包括的な範囲に含まれます。詳細は skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md を参照してください）。
   • 検証とコンテンツに関する問題：usd-validation-runner（マスタールーター。目的に応じて validate-* ファミリーまたは so-run-validators に振り分けます）。
   • 編集／出力の判断：usd-edit-target-planner（バリアント／ペイロードのゲートも担当します）。
   • コピーされた階層が繰り返されている、またはインスタンス化されていないメッシュ数が多い場合： usd-hierarchy-dedupe-candidates。
   • 再構成の判断（モノリシックなステージ、アセット境界の具現化）：restructure-decision。
   • CAD コンバーターの設定：references/cad-conversion/README.md を読んでください（USD に取り込む前の特殊な考慮事項です。詳細はリファレンスを参照してください）。
   • Scene Optimizer：so-run-validators、so-interpret-validators、so-run-operations。

最適化の順序

workflow.md § 操作順序の不変条件 に記載された標準的な順序に従ってください。 大まかなルールは、まずプロトタイプ → アセットごとの検証 → 最後にステージレベルの操作です。ワークフローのリファレンスには、不変条件の全リスト（meshCleanup は decimateMeshes より前、間引きの前に重複排除、インスタンス化されている場合はマージしない、など）と、解析専用操作のカタログが記載されています。

ルール

• 変更を加える前に、必ずコンポジション監査を実行してください。
• プロセッサーの実行前と実行後に、必ず検証してください。
• アセットごとの検証を行う前に、プロトタイプを最適化してください。
• 階層レベルでの再利用を確認する前に、非常に大規模な CAD シーン全体に対してメッシュの重複排除を実行しないでください。
• ボトルネックを示す根拠なしに、固定の最適化手順を推奨しないでください。
• 数値のしきい値や、期待される改善率を作り出さないでください。
• 特殊用途や説明目的のものより、標準的な SO オペレーションを優先してください。 references/operations/_curation.json のオペレーション分類では、すべてのオペレーションが canonical、specialty、analysis、documentary、または deprecated に分類されています。同じ指摘を解決できるオペレーションが複数ある場合は、まず canonical のものを推奨し、ユーザーから明示的に依頼された場合、または根拠が妥当な場合に限り、specialty のものを使用してください。具体的には、次のとおりです。
  • 頂点の溶接には、単独の mergeVertices オペレーションより、明示的なフラグを指定した標準の meshCleanup を優先してください。単独のオペレーションはレガシーまたは特殊用途のインターフェースです。変更を加える前に、オペレーションの仕組みについては上流の usd-optimize を、またローカルの承認ポリシーを確認してください。
  • 階層の重複排除には、usd-hierarchy-dedupe-candidates と apply-restructure を推奨してください（USD 作成データを書き換える方法です）。
  • メッシュ単位の重複排除には、findCoincidingGeometry（分析用で、変更ではなくレポートを生成）より、deduplicateGeometry（標準）を推奨してください。
  • ユーザーから明示的に依頼されていない限り、documentary に分類されたオペレーション（例：boxClip、deletePrims、removeAttributes、removeUntypedPrims、限定的な非インスタンス化ケース以外での merge）を推奨しないでください。説明目的のオペレーションは、網羅性のためにオペレーションごとの references/operations/<key>.md ルーティング用スタブには残されていますが、エージェントからの推奨対象からは除外されています。
  • specialty は documentary とは異なります。 _curation.json で specialty に分類されたオペレーションは、（a）so-interpret-validators チェーンに組み込まれたバリデーター指摘の根拠があるもの（例：sparseMeshes、optimizePrimvars）、または（b）特定の後続処理コンテキストで必要となる、負荷を支えるための代替手段（例：出力を UsdGeomMesh にする必要がある場合の primitivesToMeshes、インスタンス化の切り替えやマテリアルの再バインドに使う utilityFunction、so-create-proxy のレシピに使う pythonScript）のいずれかです。バリデーターが検出した場合、または該当する後続処理コンテキストがある場合は、specialty のオペレーションを推奨してください。上記の除外ルールは documentary のオペレーションのみを対象としています。

制限事項

• 後続処理の参照手順に代わるものではありません。実行する前に、必要な参照をそれぞれ読み込んでください。
• ランタイムを直接インストールするものではありません。必要条件が不足している場合は、セットアップまたはインストールの参照手順に従ってください。
• ユーザーが書き込みを許可していない場合、変更を許可するものではありません。

トラブルシューティング

• ランタイムの状態が不明な場合は、プロファイリングまたは検証の前に setup-usd-performance-tuning を実行してください。
• 報告された問題が曖昧な場合は、ステージのパス、ワークロードの種類、診断と実行のどちらが求められているかを確認してください。
• ワークフローが根拠を得る前に変更を提案している場合は、まずベースラインのプロファイリングとコンポジション監査に戻ってください。

参照資料

ルーティングの前に、次を読んでください。

• 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 — 3 つの柱（アセット、集約、アニメーション）と、7 ステップの構造化パターンについて確認します。

ネットワークにアクセスできる場合は、最新の内容を確認するため、各参照ファイルに記載されているライブ URL を優先してください。

必須の実行フロー

正規の Phase 0～7 のフロー（Kit／スタンドアロンの分岐、バリデータースタックへのルーティング、操作の順序、終了条件、所要時間の目安、デフォルトの3パスのスコープ付き反復パターンを含む）については、references/workflow.md を参照してください。 ルートにある簡潔なマップ references/skill-map.md は、エージェントをこのワークフローに誘導するためだけのものです。

後続フェーズの名前を、単なるチェックリストの項目として扱わないでください。各ステップを実行する前に、そのフェーズのネストされた README.md リファレンスを読み込み、記載された指示に従ってください。Claude Code が公開カタログスキルから再帰的に読み込むのは、profile-stage、usd-structure-assessment、その他のネストされたリファレンスではありません。

最終成果物は optimization-report から作成する必要があります。構造化された JSON レポートと、生成された Markdown サマリーの両方を保存してください。最適化レポートの代わりに、その場しのぎの SUMMARY.md やチャットのみの要約を使わないでください。

より詳細なサブトピックのガイダンスについては、以下のリファレンスを参照してください。

• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md、skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/layer-health.md - SA の Phase 1 チェックリストのサブトピック詳細。
• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md - マージの安全性、インスタンシングの選択に関する決定木。
• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md - バリアント／ペイロードのトレードオフの詳細（ゲートは usd-edit-target-planner 内に記載）。
• references/cad-conversion/README.md - CAD コンバーターの設定。
• references/upstreams/usd-optimize.md - 上流 SO の仕組みと、ビルド済みパッケージの解決方法。
• skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md - SO バリデーターのインフラストラクチャに関するローカルでの引き継ぎ。
• skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md - Tier 1／2／3 の選択的プローブ計画、大規模ステージのガードレール、全件スイープの承認、シーンに応じた調整。
• skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md - 各フェーズで入力するデータ契約。

Kit ランタイムの完全なプロファイリング（FPS、フレーム時間、Hydra／RTX メトリクス）については、NVIDIA／omniperf の外部プロファイリングスキルを参照してください。