Réglage des performances USD Omniverse

Quand l'utiliser

Utilisez ce workflow pour les demandes de performance générales comme un chargement lent, une mémoire élevée, un FPS faible, des plantages GPU, un triage de qualité de conversion ou des demandes génériques pour optimiser une scène USD.

Instructions

Commencez par la porte de contexte d'exécution obligatoire avant de produire une sortie de réglage, sauf si la requête ne demande qu'un test de classification statique.
Classez les demandes d'optimisation générales comme ready_to_plan ; réservez approval_required aux requêtes qui nomment explicitement une opération destructrice à exécuter avant la planification.
Planifiez la chaîne canonique complète par optimization-report, en préservant l'ordre structuré des jalons et les étiquettes profile-stage:baseline / profile-stage:after lors de la liste des jalons.
Appelez les corps de compétence en aval uniquement quand leur phase est atteinte, et gardez les artefacts d'exécution bruts sur disque en lisant des résumés compacts.

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

Format de sortie

Retournez un plan ou un résumé de statut qui nomme la compétence d'entrée sélectionnée, utilise ready_to_plan pour les demandes d'optimisation génériques, inclut la chaîne complète de jalons par optimization-report, et étiquette les phases de profiling comme profile-stage:baseline et profile-stage:after. Pour les sorties structurées, la sous-séquence de jalon d'optimisation large 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 quand la mutation s'exécute et un rapport conforme au schéma de la référence optimization-report (scripts/optimization-report.schema.json dans cette référence).

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

Règle de compétence d'entrée

Cette compétence est le point d'entrée nommé pour les travaux de performance généraux chaque fois que l'agent a un moyen vérifié de faire ce travail. Les détails de sondage du runtime vivent dans setup-usd-performance-tuning ; cette règle décide seulement quelle compétence possède la demande de performance orientée utilisateur.

Si la sonde de configuration montre un quelconque chemin d'exécution vérifié - Kit, autonome, ou même une pile partielle comme Asset Validator seul - 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 d'exécution n'est vérifié et que le choix/la configuration du runtime est le premier problème non résolu.
Pour les actifs omniverse://, entrez d'abord à omniverse-authentication. L'authentification précède la configuration et le triage pour les actifs distants.

La décision porte sur la propriété, non sur l'ordre. Configuration, authentification et triage s'exécutent tous dans leur ordre de phase normal ; cette règle ne fait que fixer quelle compétence l'agent nomme comme compétence d'entrée dans sa réponse.

Contexte d'exécution — porte de démarrage de session (obligatoire)

Avant tout autre résultat de réglage, suivez la porte de démarrage de session obligatoire 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 : appelez setup-usd-performance-tuning.
Preflight présent : imprimez Format A et attendez que l'utilisateur choisisse Continuer, Changer Kit, Passer à autonome, ou Réexécuter la sonde.
Runtime confirmé dans la même session : utilisez Format B compact pour le suivi de statut.

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

Budget de tokens d'artefacts d'exécution

Avant de lire les journaux Kit, les CSV d'Asset Validator, les journaux Scene Optimizer, les CSV Tracy, ou autres sorties d'exécution, suivez references/runtime-artifact-token-budget.md. Gardez les artefacts bruts sur disque, lisez d'abord le JSON résumé, et utilisez des aperçus de journaux délimités au lieu de vidages complets ou de flux directs.

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 pour décider 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 mailles », « fusionner les prototypes », « supprimer les prims inutilisés », ou toute mutation nommée spécifique qui ne peut pas être annulée dans le 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 dans 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 », « faites-la charger plus vite », « réduisez la mémoire GPU », « améliorez l'interactivité ». L'agent expose le plan complet, y compris 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 parallèlement à l'approbation du plan.

La distinction est 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 d'exécution structurées et les résumés de planification similaires :

Une future requête restructure-decision est une porte de décision utilisateur planifiée, pas une raison de définir la réponse de niveau supérieur decision à 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 prévue complète à la fois dans committed_milestones et planned_phases, via optimization-report.
Il est valide que gates_observed inclue asks_user_for_restructure_decision tandis que decision de niveau supérieur reste ready_to_plan.
Chaque fois qu'une chaîne nomme des phases de profiling, utilisez les étiquettes exactes profile-stage:baseline et profile-stage:after ; n'émettez pas le jeton profile-stage nu ambigu.
Commencez les listes de jalons structurés avec omniverse-usd-performance-tuning comme compétence d'entrée propriétaire. Incluez setup-usd-performance-tuning uniquement comme contexte de Phase 0 supplémentaire, pas comme remplacement de la compétence d'entrée.
Pour les demandes d'optimisation large, préservez la sous-séquence de jalons du format de sortie Output Format ci-dessus exactement, avec des étapes d'analyse supplémentaires optionnelles insérées uniquement où elles ne la réorganisent pas.
Ne listez pas so-run-validators ou so-interpret-validators avant restructure-decision dans les résumés de jalons d'optimisation large. Le routage de validateur sensible à la phase se fait 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 de plan structuré.

Attente de sortie

Le travail d'optimisation de bout en bout doit produire à la fois une étape USD optimisée, quand la mutation est exécutée, et un rapport d'optimisation structuré conforme à la 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 HTML à la main. Le travail de diagnostic seul doit quand même se terminer par un rapport ou un résumé qui indique qu'aucune étape optimisée n'a été écrite.

Objectif

Acheminez les demandes de performance USD des jumeaux numériques dans le workflow de diagnostic et d'optimisation approprié tout en préservant les preuves avant mutation.

Prérequis

Chemin d'étape ou contexte suffisant pour identifier l'actif cible.
Objectif utilisateur : diagnostic seul, validation, profiling, ou exécution du processeur.
Statut de disponibilité du runtime de setup-usd-performance-tuning quand pas déjà connu.
Statut de permission pour mutation sur place vs écriture d'une sortie optimisée séparée.

Exemples

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

Ordre de triage

Porte du runtime. Suivez la porte de démarrage de session obligatoire ci-dessus avant validation, profiling ou optimisation. Ne scannez pas, ne sondez pas, n'installez pas, ou ne choisissez pas directement les runtimes Kit/autonome dans cette compétence ; setup-usd-performance-tuning possède le dispatch sonde/sélecteur/installation 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 appareil perdu.
- Qualité de conversion CAO.
- Échec de validation.
Rassemblez le contexte minimum :
- Chemin et taille de l'étape.
- Si l'étape est locale, montée, ou distante omniverse://. Pour les actifs distants, acheminez via omniverse-authentication avant la première ouverture.
- Runtime Kit ou USD.
- Si la charge de travail est CAO, VFI, AIF, Isaac, ou OpenUSD générique.
- Si la mutation sur place est autorisée.
- Si l'utilisateur veut un diagnostic seul ou une exécution du processeur.
Acheminement :
- Questions de composition USD : usd-structure-assessment (la composition fait maintenant partie du parapluie SA ; détail plus approfondi 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 aussi les portes variant/payload).
- Hiérarchie copiée répétée ou nombre de mailles élevé sans instanciation : usd-hierarchy-dedupe-candidates.
- Décision de restructure (étape monolithique, matérialisation de limite d'actif) : restructure-decision.
- Paramètres du convertisseur CAO : lisez references/cad-conversion/README.md (souci pré-USD de niche ; voir 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 § Operation ordering invariants. La règle haut niveau : prototypes d'abord → validation par actif → opérations au niveau étape en dernier. La référence workflow possède la liste invariante complète (meshCleanup avant decimateMeshes, déduplication avant décimation, ne jamais fusionner si instancié, etc.) et le catalogue des ops d'analyse seule.

Règles

Exécutez toujours l'audit de composition avant mutation.
Validez toujours avant et après l'exécution du processeur.
Optimisez les prototypes avant la validation par actif.
Ne lancez pas la déduplication de mailles au niveau étape entière sur très grandes scènes CAO avant de vérifier la réutilisation au niveau hiérarchie.
Ne recommandez pas une pile d'optimisation fixe sans preuve de goulot d'étranglement.
N'inveniez pas de seuils numériques ou de gains en pourcentage attendus.
Préférez les ops SO canoniques aux ops spécialisées / documentaires. La curation op dans references/operations/_curation.json classe chaque op comme canonical, specialty, analysis, documentary, ou deprecated. Quand plus d'un op pourrait résoudre la même découverte, recommandez d'abord le canonique et ne recourez à un op spécialisé que quand l'utilisateur le demande explicitement ou que la justification le justifie. Spécifiquement :
- Pour la soudure de sommets, préférez le meshCleanup canonique avec drapeaux explicites au-dessus de l'op autonome mergeVertices. L'op autonome est une surface héritée/spécialisée ; utilisez usd-optimize en amont pour la mécanique d'opération et la politique d'approbation locale avant mutation.
- Pour la dedupe hiérarchie, recommandez usd-hierarchy-dedupe-candidates + apply-restructure (le chemin de réécriture USD-authored).
- Pour la dedupe par maille, recommandez deduplicateGeometry (canonique) plutôt que findCoincidingGeometry (analyse — produit un rapport, pas un changement).
- Ne recommandez pas les ops au statut documentary (ex. boxClip, deletePrims, removeAttributes, removeUntypedPrims, merge en dehors de son cas étroit non-instancié) sans demande utilisateur explicite. Les ops documentaires survivent dans les stubs de routage references/operations/<key>.md par-op pour la complétude mais sont exclus des recommandations initiées par l'agent.
- Specialty ≠ documentary. Les ops classés comme specialty dans _curation.json soit (a) ont une preuve de détection de validateur qui les relie à la chaîne so-interpret-validators (ex. sparseMeshes, optimizePrimvars), soit (b) sont des échappatoires indispensables nécessaires pour des contextes aval spécifiques (ex. primitivesToMeshes quand la sortie doit être UsdGeomMesh, utilityFunction pour les bascules d'instanciation et la reliaison matérielle, pythonScript pour les recettes so-create-proxy). Recommandez les ops spécialisés quand leur détecteur 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 aval ; chargez chaque référence requise avant de l'exécuter.
N'installe pas les runtimes directement ; suivez la configuration ou les références d'installation quand les exigences manquent.
N'autorise pas la mutation quand l'utilisateur n'a pas permis les écritures.

Dépannage

Si le statut du runtime est flou, exécutez setup-usd-performance-tuning avant profiling ou validation.
Si le problème signalé est vague, rassemblez le chemin d'étape, le type de charge de travail, et si le diagnostic ou l'exécution est demandée.
Si le workflow suggère mutation avant preuve, revenez au profiling de base et à l'audit de composition d'abord.

Références

Avant de router, lisez :

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

Si vous avez un accès réseau, préférez les URLs directs (notés 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 Phase 0-7 canonique, incluant les branches Kit/autonome, le routage de pile de validateur, l'ordre d'opération, les conditions de terminaison, les indices de durée, et le pattern d'itération optionnel. La carte racine compacte à references/skill-map.md ne fait que router les agents dans ce workflow.

Ne traitez pas les noms de phase aval comme des étiquettes simples de liste de contrôle. 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 seulement le catalogue de compétences publiques ; il n'injecte pas récursivement profile-stage, usd-structure-assessment, ou d'autres références imbriquées.

Le livrable final doit venir 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 basé sur la conversation au rapport d'optimisation.

Pour un guide sur les sous-thèmes plus profonds, 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'instanciation.
skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md - compromis variant/payload plus profonds (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 SO en amont et résolution de paquet prédélabéré.
skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md - remise locale pour l'infrastructure validateur SO.
skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validation-scoping.md - plan tier 1/2/3 + ajustement sensible à 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 profiling complet du runtime Kit (FPS, temps de trame, métriques Hydra/RTX), reportez-vous aux compétences de profiling externes à NVIDIA/omniperf.