Accord de performance Omniverse USD

Quand utiliser

Utilisez ce workflow pour les demandes de performance générales telles que chargement lent, mémoire élevée, FPS bas, plantages GPU, triage de qualité de conversion, ou demandes génériques d'optimisation d'une scène USD.

Instructions

Commencez par la porte de contexte runtime obligatoire avant de produire une sortie de tuning, sauf si l'invite demande uniquement un test de classification statique.
Classifiez les demandes d'optimisation générales comme ready_to_plan ; réservez approval_required aux invites qui nomment explicitement une opération destructrice à exécuter avant la planification.
Planifiez la chaîne canonique complète jusqu'à optimization-report, en préservant l'ordre structuré des jalons et les libellés profile-stage:baseline / profile-stage:after lors de l'énumération des jalons. Pour l'optimisation générale, prévoyez 3 itérations avec portée limitée par défaut, sauf si l'utilisateur se désabonne, demande un passage rapide, ou si les critères d'arrêt s'appliquent.
Invoquez les corps de skill en aval uniquement quand leur phase est atteinte, et conservez les artefacts runtime bruts sur disque tout en lisant des résumés compacts.

Le frontmatter conserve version et tools au niveau supérieur pour la compatibilité runtime agentskills.io. Les champs de découvrabilité NVCARPS se trouvent sous metadata.

Format de sortie

Retournez un plan ou résumé d'état qui nomme le skill d'entrée sélectionné, utilise ready_to_plan pour les demandes d'optimisation génériques, inclut la chaîne de jalons complète jusqu'à optimization-report, et libelle les phases de profil comme profile-stage:baseline et profile-stage:after. Pour les sorties structurées, la sous-séquence de jalon d'optimisation générale est 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. L'exécution de bout en bout doit produire une étape optimisée lorsque la mutation s'exécute et un rapport conforme au schéma de la référence optimization-report (scripts/optimization-report.schema.json au sein de cette référence). L'optimisation générale doit planifier 3 itérations avec portée limitée par défaut ; chaque itération écrit un rapport/mise à jour intermédiaire et les passages ultérieurs réutilisent des preuves antérieures au lieu de redémarrer le workflow complet.

Utilisez ce workflow pour les demandes de performance générales telles que chargement lent, FPS bas, mémoire élevée, plantages GPU, qualité de conversion, ou « optimisez ma scène ».

Règle du skill d'entrée

Ce skill est le point d'entrée nommé pour le travail de performance générale chaque fois que l'agent a une méthode vérifiée pour faire ce travail. Les détails de sondage runtime vivent dans setup-usd-performance-tuning ; cette règle décide uniquement quel skill possède la demande de performance visible par l'utilisateur.

Si la sonde de configuration montre un seul chemin runtime vérifié - Kit, standalone, ou même une pile partielle telle que Asset Validator uniquement - entrez ici. Si l'outil demandé par l'utilisateur est manquant, retournez le blocked_code spécifique (blocked_missing_scene_optimizer, blocked_missing_so_operation, etc.) au lieu de substituer un autre workflow.
Entrez à setup-usd-performance-tuning uniquement quand aucun chemin runtime n'est vérifié et que le choix/configuration du runtime est le premier problème non résolu.
Pour les ressources omniverse://, entrez d'abord à omniverse-authentication. L'authentification précède la configuration et le triage pour les ressources distantes.

La décision concerne la propriété, pas l'ordre. Configuration, authentification et triage s'exécutent tous dans leur ordre de phase normal ; cette règle fixe uniquement quel skill l'agent nomme comme skill d'entrée dans sa réponse.

Contexte runtime — porte de session-start (obligatoire)

Avant tout autre résultat de tuning, suivez la porte obligatoire de session-start dans skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md. Cette référence possède output_path, l'emplacement canonique setup-preflight.json, Format A/Format B, et l'anti-pattern « ne pas improviser une sonde silencieuse ».

Résultats requis :

Preflight manquant ou illisible : invoquez setup-usd-performance-tuning.
Preflight présent : imprimez Format A et attendez que l'utilisateur choisisse Continuer, Changer Kit, Passer à standalone, ou Relancer la sonde.
Runtime confirmé dans la même session : utilisez Format B compact pour le suivi du statut.

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

Budget de jetons des artefacts runtime

Avant de lire les journaux Kit, les CSV Asset Validator, les journaux Scene Optimizer, les CSV Tracy, ou autre sortie runtime, suivez references/runtime-artifact-token-budget.md. Conservez les artefacts bruts sur disque, lisez d'abord le JSON résumé, et utilisez des instantanés de journal limités au lieu de dumps complets ou de flux en direct.

Approbation au moment de la planification vs au moment de l'exécution

approval_required au moment de la planification est réservé aux demandes qui nomment explicitement une opération destructrice. Utilisez la règle suivante quand vous décidez entre ready_to_plan et approval_required :

approval_required au moment de la planification — la demande de l'utilisateur elle-même nomme une opération destructrice : « aplatir cette étape », « décimer les maillages », « fusionner les prototypes », « supprimer les prims inutilisés », ou toute mutation nommée spécifique qui ne peut pas être annulée au sein du même workflow. Dans ce cas, la première réponse de l'agent doit être une demande d'approbation qui nomme l'opération, avant que l'agent ne s'engage sur un plan qui l'exécute.
ready_to_plan au moment de la planification — la demande de l'utilisateur est générale : « optimisez cette scène », « accélérez son chargement », « réduisez la mémoire GPU », « améliorez l'interactivité ». L'agent expose le plan complet, incluant toute opération destructrice que le plan invoquerait (par exemple so-run-operations avec mergeMaterials), sans retenir le plan lui-même. L'approbation pour chaque opération destructrice est demandée aux côtés de l'approbation du plan.

La distinction se fait entre autoriser un plan et autoriser une action destructrice. Une demande d'optimisation générale autorise la planification ; elle n'autorise pas l'exécution d'opérations destructrices spécifiques.

Pour les réponses de test runtime structurées et les résumés de planification similaires :

Un futur invite restructure-decision est une porte de décision utilisateur planifiée, pas une raison de définir le decision de réponse de niveau supérieur à approval_required pour une demande d'optimisation générique.
Pour une demande d'optimisation générique, définissez decision: "ready_to_plan" et incluez la chaîne complète prévue dans à la fois committed_milestones et planned_phases, jusqu'à optimization-report.
Il est valide que gates_observed inclue asks_user_for_restructure_decision tandis que le decision de niveau supérieur reste ready_to_plan.
Chaque fois qu'une chaîne nomme des phases de profil, utilisez les libellés exacts profile-stage:baseline et profile-stage:after ; ne émettez pas le jeton ambigu profile-stage nu.
Commencez les listes structurées de jalons avec omniverse-usd-performance-tuning comme skill d'entrée propriétaire. Incluez setup-usd-performance-tuning uniquement comme contexte additionnel Phase 0, pas comme remplacement du jalon du skill d'entrée.
Pour les demandes d'optimisation générale, préservez exactement la sous-séquence de jalons de la section Format de sortie ci-dessus, avec des étapes d'analyse supplémentaires optionnelles insérées uniquement où elles ne la réordonnent pas.
Ne listez pas so-run-validators ou so-interpret-validators avant restructure-decision dans les résumés structurés de jalons d'optimisation générale. Le routage de validateurs conscient de la phase se produit toujours via usd-validation-runner ; les jalons d'exécuteur/interprète de validateur SO apparaissent après le chemin de décision de restructure dans le contrat du plan structuré.

Attente de sortie

Le travail d'optimisation de bout en bout doit produire à la fois une étape USD optimisée, lorsque la mutation est exécutée, et un rapport d'optimisation structuré conforme au scripts/optimization-report.schema.json de la référence optimization-report. Le rapport HTML doit être rendu à partir de references/report-templates/optimization-report.html.template via render_preview.py — ne jamais écrire manuellement du HTML. Le travail de diagnostic uniquement doit se terminer avec un rapport ou résumé qui indique qu'aucune étape optimisée n'a été écrite.

Objectif

Acheminez les demandes de performance USD de jumeau numérique vers le workflow de diagnostic et d'optimisation approprié tout en préservant les preuves avant la mutation.

Prérequis

Chemin de scène ou contexte suffisant pour identifier l'élément multimédia cible.
Objectif utilisateur : diagnostic uniquement, validation, profilage, ou exécution de processeur.
État de disponibilité runtime de setup-usd-performance-tuning si pas déjà connu.
État de permission pour mutation sur place vs écriture d'une sortie optimisée séparée.

Exemples

« Cet USD se charge lentement ; triez ce qu'il faut vérifier en premier. »
« Acheminez une scène CAO avec FPS bas à travers le workflow de performance. »

Ordre de triage

Porte runtime. Suivez la porte obligatoire de session-start ci-dessus avant la validation, le profilage ou l'optimisation. Ne scannez pas, ne sondez pas, n'installez pas, et ne choisissez pas directement les runtimes Kit/standalone dans ce skill ; setup-usd-performance-tuning possède la dispatch de probe/chooser/install et écrit le preflight consommé ici.
Identifiez le problème cible :
- Temps de chargement.
- FPS ou interactivité.
- Mémoire GPU ou système.
- Plantage ou perte d'appareil.
- Qualité de conversion CAO.
- Échec de validation.
Rassemblez le contexte minimum :
- Chemin de scène et taille.
- Indique si la scène est locale, montée, ou omniverse:// distante. Pour les ressources distantes, acheminez via omniverse-authentication avant la première ouverture.
- Runtime Kit ou USD.
- Indique si la charge de travail est CAO, VFI, AIF, Isaac, ou OpenUSD générique.
- Indique si la mutation sur place est autorisée.
- Indique si l'utilisateur souhaite un diagnostic uniquement ou l'exécution du processeur.
Acheminez :
- Questions de composition USD : usd-structure-assessment (la composition fait maintenant partie de l'ombrage SA ; détails approfondis dans skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md).
- Validation et problèmes de contenu : usd-validation-runner (routeur maître ; achemine vers la famille validate-* ou so-run-validators selon l'intention).
- Décisions d'édition/sortie : usd-edit-target-planner (possède également les portes variant/payload).
- Hiérarchie copiée répétée ou nombre élevé de maillages sans instancing : usd-hierarchy-dedupe-candidates.
- Décision de restructure (étape monolithique, matérialisation des limites des éléments multimédias) : restructure-decision.
- Paramètres du convertisseur CAO : lisez references/cad-conversion/README.md (préoccupation pré-USD de niche ; voir la référence pour les détails).
- Scene Optimizer : so-run-validators, so-interpret-validators, so-run-operations.

Ordre d'optimisation

Suivez l'ordre canonique dans workflow.md § Invariants d'ordre d'opération. La règle de haut niveau : prototypes d'abord → validation par ressource → opérations au niveau de l'étape en dernier. La référence du workflow possède la liste complète des invariants (meshCleanup avant decimateMeshes, déduplication avant décimation, ne jamais fusionner si instancié, etc.) et le catalogue d'ops d'analyse uniquement.

Règles

Exécutez toujours l'audit de composition avant la mutation.
Validez toujours avant et après l'exécution du processeur.
Optimisez les prototypes avant la validation par ressource.
N'exécutez pas la déduplication de maillage au niveau de l'étape complète sur de très grandes scènes CAO avant de vérifier la réutilisation au niveau de la hiérarchie.
Ne recommandez pas une pile d'optimisation fixe sans preuves de goulot d'étranglement.
N'inventez pas de seuils numériques ou de gains en pourcentage attendus.
Préférez les ops SO canoniques aux ops spécialisés/documentaires. La curation op dans references/operations/_curation.json classifie chaque op comme canonical, specialty, analysis, documentary, ou deprecated. Quand plus d'une op pourrait résoudre la même découverte, recommandez d'abord la canonique et ne recourez à une op spécialisée que lorsque l'utilisateur le demande explicitement ou que la justification le justifie. Précisément :
- Pour la soudure de sommet, préférez canonical meshCleanup avec drapeaux explicites à l'op autonome mergeVertices. L'op autonome est une surface héritage/spécialisée ; utilisez l'amont usd-optimize pour la mécanique d'opération et la politique d'approbation locale avant de muter.
- Pour la déduplication de hiérarchie, recommandez usd-hierarchy-dedupe-candidates + apply-restructure (le chemin de réécriture rédigé en USD).
- Pour la déduplication par maillage, recommandez deduplicateGeometry (canonique) plutôt que findCoincidingGeometry (analyse — produit un rapport, pas un changement).
- Ne recommandez pas les ops de statut documentary (par ex., boxClip, deletePrims, removeAttributes, removeUntypedPrims, merge en dehors de son cas étroit non-instancié) sans une demande utilisateur explicite. Les ops documentaires survivent dans les stubs de routage par op references/operations/<key>.md pour la complétude mais sont exclus des recommandations initiées par agent.
- Spécialisé ≠ documentaire. Les ops classifiées comme specialty dans _curation.json soit (a) ont des preuves de découverte de validateur qui les câblent dans la chaîne so-interpret-validators (par ex. sparseMeshes, optimizePrimvars), soit (b) sont des trappes de sortie essentielles nécessaires pour des contextes en aval spécifiques (par ex. primitivesToMeshes quand la sortie doit être UsdGeomMesh, utilityFunction pour les bascules d'instancing et la reliure de matériau, pythonScript pour les recettes so-create-proxy). Recommandez les ops spécialisées quand leur validateur se déclenche OU quand leur contexte aval s'applique — la suppression ci-dessus cible uniquement les ops documentary.

Limitations

Ne remplace pas les instructions de référence en aval ; chargez chaque référence requise avant l'exécuter.
N'installe pas les runtimes directement ; suivez les références de configuration ou d'installation lorsque les exigences manquent.
N'autorise pas la mutation quand l'utilisateur n'a pas autorisé les écritures.

Dépannage

Si le statut du runtime est peu clair, exécutez setup-usd-performance-tuning avant le profilage ou la validation.
Si le problème rapporté est vague, rassemblez le chemin de scène, le type de charge de travail, et si un diagnostic ou une exécution est demandée.
Si le workflow suggère une mutation avant la preuve, retournez au profilage de base et à l'audit de composition en premier.

Références

Avant d'acheminer, lisez :

skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/optimization-tradeoffs.md — identifiez la phase de pipeline dans laquelle se trouve la scène (extraction, structuration, ou optimisation). L'action appropriée dépend de la phase.
skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md — comprenez les trois piliers (ressources, agrégation, animation) et le motif de structuration en sept étapes.

Si vous avez accès au réseau, privilégiez les URL en direct (notées dans chaque fichier de référence) pour la version la plus actuelle.

Flux d'exécution requis

Lisez references/workflow.md pour le flux canonique Phase 0-7, incluant les branches Kit/standalone, le routage de pile de validateur, l'ordre d'opération, les conditions de terminaison, les indices de durée, et le motif d'itération avec portée limitée par défaut à trois passes. La carte racine compacte à references/skill-map.md achemine uniquement les agents dans ce workflow.

Ne traitez pas les noms de phase en aval comme des libellés de simple checklist. Avant d'exécuter chaque étape, chargez la référence README.md imbriquée de cette phase et suivez ses instructions. Claude Code expose uniquement le skill de catalogue public ; il n'injecte pas récursivement profile-stage, usd-structure-assessment, ou d'autres références imbriquées.

Le livrable final doit provenir de optimization-report : enregistrez à la fois le rapport JSON structuré et le résumé Markdown généré. Ne substituez pas un SUMMARY.md ad hoc ou un récapitulatif de chat uniquement au rapport d'optimisation.

Pour des conseils sur des sous-thèmes plus approfondis, consultez les références :

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 - détail de sous-thème pour la checklist Phase 1 de SA.
skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md - sécurité de fusion, arbre de décision pour les choix d'instancing.
skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md - compromis variant/payload plus approfondis (les portes sont en ligne dans usd-edit-target-planner).
references/cad-conversion/README.md - paramètres du convertisseur CAO.
references/upstreams/usd-optimize.md - mécanique upstream SO et résolution de paquets pré-construits.
skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md - remise locale pour l'infrastructure du validateur SO.
skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md - plan de sonde sélectionnée tier 1/2/3, garde-fous de grande étape, approbation de balayage complet, et ajustement conscient de la scène.
skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md - le contrat de données que chaque phase remplit.

Pour le profilage runtime Kit complet (FPS, temps de trame, métriques Hydra/RTX), consultez les skills de profilage externes à NVIDIA/omniperf.