Jetson AI Lab : configuration des pages du catalogue de modèles

Que fait Jetson AI Lab : configuration des pages du catalogue de modèles ?

Rappel important

• Jetson AI Lab est un site Astro statique. Il n'héberge pas d'API d'inférence. Les utilisateur·rices copient les commandes depuis le site et les exécutent sur un Jetson (ou une autre machine).
• Les pages de modèles sont des fichiers Markdown dans la collection de contenu Astro models : src/content/models/<slug>.md.
• Le slug du fichier (nom du fichier sans l'extension .md) devient le segment d'URL : la route publiée est /models/<slug> (voir src/pages/models/[slug].astro).
• Presque tous les éléments visibles d'une page de modèle sont pilotés par le frontmatter YAML de ce fichier (Hero, barre latérale des détails du modèle, onglets Run on Jetson, extraits Call, onglets one-shot, graphique des benchmarks). Le corps Markdown ne remplit que la section de texte Model Details en bas de page.

N'inventez pas d'URL de base pour « l'API d'inférence du Jetson AI Lab » — elle n'existe pas.

---

Anatomie de la page (de haut en bas)

Section	Pilotée par	Composant / fichier
Hero (titre, badges, puces « Command to Run on Jetson » / « Benchmark » / « Model Details »)	title, is_new, type, short_description, présence des moteurs et de benchmark_key	src/pages/models/[slug].astro
Barre latérale des spécs (Paramètres, Modalités, Longueur de contexte, Licence, badges de Précision)	parameters (ou model_size), modalities (ou vision_capable), context_length, license, precision (par jeton)	src/pages/models/[slug].astro L137–193
Run on Jetson → Matrice Serve	serving.entries (recommandé) ou supported_inference_engines, plus matrix_modules_disabled	ModelServeSection.astro
Call the model	client_call.{shell,python,intro} (ou généré automatiquement à partir des moteurs + hf_checkpoint)	ModelCallSection.astro
Inférence one-shot (onglets par module)	one_shot_inference.*	ModelOneShotSection.astro + src/lib/evalRunModal.ts
Graphique des benchmarks	benchmark_key (+ benchmark_series optionnel) → jointure avec src/data/benchmarks.json	ModelBenchmarkSection.astro
Texte des détails du modèle + liens externes (Try on build.nvidia.com, View on HuggingFace)	Corps Markdown + build_nvidia_url, huggingface_url (ou hf_checkpoint)	src/pages/models/[slug].astro L242–289

---

Référence du frontmatter

Chaque page de modèle est pilotée par son frontmatter YAML. La validation se trouve dans src/content/config.ts (modelsSchema).

Balises toujours incluses

Soit elles sont requises par le schéma (la construction échoue sans elles), soit elles sont utilisées par tous les modèles du dépôt. Incluez-les toutes lors de l'ajout d'un nouveau modèle.

Balise	Schéma	Rôle
title	requis	Nom affiché sur la page du modèle et les cartes du catalogue.
short_description	requis	Résumé d'une ligne dans la grille du catalogue et le sous-titre du Hero.
precision	requis	Jetons de quantification séparés par des barres obliques ou des virgules (ex. "NVFP4 / FP8 / Q4_K_M GGUF"). Chaque jeton s'affiche sous forme de pilule colorée dans la barre latérale (precisionPill dans [slug].astro).
family	optionnel mais omniprésent	Regroupe les modèles dans le catalogue. La valeur spéciale "Google Gemma4" déclenche la bannière CTA du tutoriel Gemma 4 au-dessus du texte.
model_id, icon, is_new, order, type, hf_checkpoint, huggingface_url, minimum_jetson	optionnel mais omniprésent	Carte du catalogue / Hero / liens externes. huggingface_url utilise par défaut https://huggingface.co/${hf_checkpoint} si omis.

Balises de la barre latérale des détails du modèle (pilote la carte de spécifications sombre à droite du Hero)

Si vous sautez ces balises, la ligne disparaît de la barre latérale (pas d'erreur, juste moins de raffinement).

Balise	Ligne de la barre latérale	Remarques
parameters (ou fallback model_size)	« Parameters »	Texte libre, ex. "~9B" ou "30B total / 3B active".
modalities: [...]	« Modalities »	Tableau de `"Text"
vision_capable (booléen)	(fallback pour Modalities)	Définissez-le explicitement même lorsque modalities est présent — utilisé ailleurs pour les filtres du catalogue.
context_length	« Context Length »	Texte libre, ex. "128K", "262K".
license	« License »	Texte libre, ex. "Apache 2.0", "NVIDIA Open Model License".
model_size	(fallback pour Parameters)	ex. "12GB".
memory_requirements	non affiché dans la barre latérale mais utilisé par d'autres IU	ex. "16GB RAM".

Balises situationnelles

N'ajoutez ces balises que lorsque le modèle en a besoin.

Balise	Quand l'utiliser	Utilisation dans le dépôt
build_nvidia_url	Le modèle a une page NVIDIA Build → ajoute le bouton Try on build.nvidia.com.	~67% des modèles
matrix_modules_disabled	Certains onglets de modules de la matrice doivent être grisés / non cliquables pour tous les moteurs de ce modèle.	~10% des modèles
hide_run_button	Masque toute l'interface Run on Jetson (Serve + Call + one-shot) même si les données du moteur sont présentes.	~5% des modèles
benchmark_key	Le modèle a des performances mesurées dans src/data/benchmarks.json. La valeur doit correspondre au champ name de cette entrée de benchmarks.	~30% des modèles
benchmark_series: [...]	Affiche des barres de comparaison côte à côte supplémentaires (ex. comparer avec la génération précédente de la même famille). Chaque valeur est un autre name de benchmarks.json.	Quelques modèles

Blocs d'inférence (au moins un requis sauf si hide_run_button: true)

Bloc	Objectif
serving.entries	Liste de moteurs de nouvelle génération — recommandé pour les nouveaux modèles. Remplace supported_inference_engines dans l'IU lorsqu'il n'est pas vide.
supported_inference_engines	Tableau de moteurs hérité. Fonctionne toujours et est la forme la plus courante aujourd'hui.
one_shot_inference	Commandes d'exécution one-shot (variantes shell/python/par module). Affiche une section à onglets séparée « One-shot inference » sous Call.
client_call.{shell,python,intro}	Remplacement optionnel pour l'extrait Call the model. S'il est omis, la page construit automatiquement un exemple curl à partir des commandes du moteur et de hf_checkpoint.

---

Run on Jetson : les trois leviers de « bloc » (quand OOM vs masquer vs griser)

Ces leviers sont superposés. La matrice Serve les évalue dans cet ordre :

1. hide_run_button: true (frontmatter, niveau supérieur)

   • Masque toute la section Run on Jetson (Serve + Call + one-shot).
   • Utilisez-le lorsque le modèle existe dans le catalogue mais n'est pas encore utilisable depuis le site (ex. téléchargement NGC requis, point de contrôle verrouillé, validation en attente).
   • Exemple : src/content/models/cosmos-reason2-8b.md — conserve les données du moteur pour la documentation, mais l'IU d'exécution reste masquée.

2. matrix_modules_disabled: [moduleId, ...] (frontmatter, niveau supérieur)

   • Grise les onglets de modules listés sur tous les moteurs pour ce modèle. L'onglet est affiché mais n'est pas cliquable.
   • Utilisez-le lorsqu'un module Jetson est théoriquement possible mais pas encore validé pour ce modèle.

3. engines[].modules_supported: [moduleId, ...] (par moteur, dans serving.entries[] ou supported_inference_engines[])

   • Liste d'autorisation : seuls les identifiants de modules listés sont activés pour ce moteur. Les cellules en dehors de la liste sont grisées pour cette ligne de moteur.
   • Omettez complètement le champ → le moteur prend en charge tous les modules de la matrice. Un tableau vide signifie que le moteur ne prend rien en charge (rare).
   • Utilisez-le lorsque le modèle s'exécute partout mais qu'un moteur spécifique ne fonctionne que sur un sous-ensemble (ex. vLLM Thor uniquement, Ollama Orin+Thor).

OOM est un concept différent et réside dans src/data/benchmarks.json — voir Benchmarks ci-dessous.

Vous voulez exprimer…	Utilisez…
« Ce modèle n'est pas prêt à être exécuté depuis le site du tout »	hide_run_button: true
« Ce modèle ne peut pas fonctionner sur Orin Nano (quel que soit le moteur) »	matrix_modules_disabled: [orin_nano_8]
« vLLM ne fonctionne que sur Thor pour ce modèle ; llama.cpp fonctionne partout »	Entrée vLLM : modules_supported: [thor_t5000, thor_t4000] ; omettez sur llama.cpp
« Nous avons fait un benchmark et cela a manqué de mémoire sur T4000 »	Ajoutez "oom": ["t4000"] à cette quantification dans benchmarks.json (n'appartient pas au frontmatter du modèle)
« Nous avons fait un benchmark et le modèle ne fonctionne tout simplement pas sur Orin Nano »	Ajoutez "dnr": ["orin_nano_8gb"] à cette quantification dans benchmarks.json
« Nous n'avons pas encore mesuré cette combinaison »	Définissez la valeur sur null dans benchmarks.json. Aucun marqueur n'est dessiné ; la barre est simplement absente.

---

Données d'inférence : matrice Serve (moteurs)

La liste des moteurs est construite par getSupportedInferenceEngines dans src/lib/modelFrontmatterAdapter.ts :

• Si serving.entries est présent et non vide → ces entrées sont utilisées (recommandé pour les nouveaux travaux).
• Sinon supported_inference_engines (tableau hérité) est utilisé.

Chaque ligne de moteur correspond à SupportedEngineEntry dans src/lib/inferenceCommands.ts. Préférez :

• serve_command_orin / serve_command_thor pour les commandes de service à longue durée (vLLM, Ollama, etc.).
• Les run_command_orin / run_command_thor hérités sont obsolètes mais toujours acceptés comme solutions de repli.

Champs optionnels :

• modules_supported — voir levier de bloc n°3 ci-dessus.
• run_commands_by_module : carte de remplacement par cellule { moduleId: command } pour les cellules de la matrice Run.
• install_command / install_command_orin / install_command_thor : préfixé comme bloc # Installation au-dessus de la commande serve.

L'ordre d'affichage des moteurs est fixe, défini par sortEnginesForUi dans modelFrontmatterAdapter.ts : vLLM → SGLang → llama.cpp → Ollama → Edge-LLM → tout le reste (alphabétique). N'essayez pas de contrôler l'ordre depuis le frontmatter.

Identifiants canoniques des modules Jetson

Définis dans JETSON_MATRIX_MODULES dans src/lib/inferenceCommands.ts. Utilisez ces identifiants exacts dans modules_supported / matrix_modules_disabled / one_shot_inference.modules_supported.

Identifiant du module	Onglet Matrice ?	Plateforme
thor_t5000	Oui	thor
thor_t4000	Oui	thor
orin_agx_64	Oui	orin
orin_nx_16	Oui	orin
orin_nano_8	Oui	orin
orin_agx_32	données uniquement (pas d'onglet)	orin
orin_nx_8	données uniquement (pas d'onglet)	orin
orin_nano_4	données uniquement (pas d'onglet)	orin

Les identifiants « données uniquement » (showInMatrixUi: false) sont valides dans le frontmatter et résolvent les commandes via platformKey, mais aucun onglet de matrice Serve/Run n'est affiché. N'inventez pas de nouveaux identifiants — l'extension de la liste nécessite une modification de code dans JETSON_MATRIX_MODULES.

Exemples dans le dépôt :

• serving.entries (nouveau style) : src/content/models/ministral3-8b-reasoning.md
• supported_inference_engines hérité avec modules_supported riche par moteur : src/content/models/nemotron-3-nano-omni.md
• hide_run_button: true : src/content/models/cosmos-reason2-8b.md

---

Inférence one-shot

Bloc de frontmatter optionnel one_shot_inference (schéma dans src/content/config.ts). Champs :

• run_command_orin, run_command_thor — commande d'exécution unique par plateforme.
• shell, python — extraits non spécifiques à une plateforme.
• shell_by_module, python_by_module — cartes de remplacement par module, indexées par identifiant de module canonique.
• modules_supported — restreint les onglets de modules qui apparaissent.
• intro — introduction Markdown optionnelle affichée au-dessus des onglets.

Visibilité : ModelOneShotSection.astro affiche la section lorsqu'au moins un des champs de commande ci-dessus est non vide (vérification hasContent).

La résolution des extraits/modules se trouve dans src/lib/evalRunModal.ts (voir evalSnippetByModule, evalMatrixModuleSpecs).

---

Call the model (client_call)

Bloc de frontmatter optionnel — remplace l'exemple curl généré automatiquement affiché dans Call the model.

client_call:
  intro: "Une fois le serveur démarré :"
  shell: |-
    curl -s http://${JETSON_HOST}:8080/v1/chat/completions \
      -H "Content-Type: application/json" \
      -d '{ "model": "my_model", "messages": [{"role":"user","content":"salut"}] }'
  python: |-
    import openai
    ...

Omettez complètement client_call pour laisser ModelCallSection.astro synthétiser un exemple à partir de hf_checkpoint et de la commande serve du premier moteur.

---

Données de benchmarks

Les chiffres des benchmarks ne vivent pas dans le frontmatter du modèle. Ils résident dans src/data/benchmarks.json sous models[]. La page du modèle fait la jointure via le champ benchmark_key du frontmatter, qui doit correspondre exactement à models[].name.

Ajout de données de benchmarks

1. Ajoutez une entrée à models[] dans src/data/benchmarks.json :

{
  "family": "Nom de la famille",
  "name": "Nom exact (c'est la clé de jointure)",
  "releaseDate": "YYYY-MM-DD",
  "capabilities": { "language": true, "vision": false, "audio": false, "vla": false },
  "isl": 2048,
  "osl": 128,
  "engines": {
    "vLLM": {
      "NVFP4": {
        "concurrency1": { "t5000": 63.3, "t4000": 51.8, "agx_orin_64gb": null, "orin_nx_16gb": null, "orin_nano_8gb": null, "dgx_spark": 59.6 },
        "concurrency8": { "t5000": 181.2, "t4000": 147.4, "agx_orin_64gb": null, "orin_nx_16gb": null, "orin_nano_8gb": null, "dgx_spark": 191.2 }
      },
      "FP8": {
        "concurrency1": { "t5000": 54.7, "t4000": null, "agx_orin_64gb": null, "orin_nx_16gb": null, "orin_nano_8gb": null, "dgx_spark": 52.3 },
        "concurrency8": { "t5000": 129.8, "t4000": null, "agx_orin_64gb": null, "orin_nx_16gb": null, "orin_nano_8gb": null, "dgx_spark": 138.6 },
        "oom": ["t4000"]
      }
    },
    "Ollama": {
      "Q4_K_M": {
        "concurrency1": { "t5000": 27, "t4000": null, "agx_orin_64gb": 17, "orin_nx_16gb": null, "orin_nano_8gb": null, "dgx_spark": null },
        "concurrency8": { "t5000": 28, "t4000": null, "agx_orin_64gb": 17, "orin_nx_16gb": null, "orin_nano_8gb": null, "dgx_spark": null },
        "oom": ["orin_nx_16gb", "orin_nano_8gb"]
      }
    }
  }
}

2. Dans le frontmatter du modèle, ajoutez :

benchmark_key: "Nom exact (c'est la clé de jointure)"
benchmark_series:
  - "Nom de la famille prédécesseur"   # optionnel — superpose des barres de comparaison

Identifiants de produits de benchmarks ≠ identifiants de modules de matrice (piège critique)

L'axe des benchmarks utilise des identifiants différents de ceux de la matrice Run/Serve :

Matériel	Identifiant de module matrice (frontmatter)	Identifiant de produit de benchmark (benchmarks.json)
Jetson Thor T5000	thor_t5000	t5000
Jetson Thor T4000	thor_t4000	t4000
Jetson AGX Orin 64 Go	orin_agx_64	agx_orin_64gb
Jetson Orin NX 16 Go	orin_nx_16	orin_nx_16gb
Jetson Orin Nano 8 Go	orin_nano_8	orin_nano_8gb
DGX Spark	dgx_spark	dgx_spark

Résumé visuel du comportement d'affichage des benchmarks

Valeur dans benchmarks.json	Affichée dans le graphique ?	Info-bulle / marqueur
null	Non (barre absente)	Aucun
Nombre	Oui	Barre avec la valeur en haut
"oom" (clé au niveau de la quantification)	Non ; les lignes OOM ne sont pas dessinées	Légende en bas : ligne barrée, texte « Out of Memory »
"dnr" (clé au niveau de la quantification)	Non ; les lignes DNR ne sont pas dessinées	Légende en bas : ligne barrée, texte « Does Not Run »

Note importante : oom et dnr ne sont pas des valeurs d'une cellule de performance — ce sont des listes d'identifiants de produits sous la quantification (même niveau que concurrency1 / concurrency8). Le code du graphique filtre les entrées de cette liste et ne dessine pas de barre pour les produits concernés.

---

Guide pas à pas pour ajouter un modèle

1. Créez src/content/models/<mon-slug>.md.
2. Remplissez le frontmatter obligatoire (title, short_description, precision).
3. Ajoutez les balises de la barre latérale : parameters, modalities (ou vision_capable), context_length, license.
4. Ajoutez au moins un bloc d'inférence :
   • Nouveau style : serving.entries (recommandé).
   • Style hérité : supported_inference_engines.
   • Pour les commandes rapides : one_shot_inference.
   • Si le modèle n'est pas encore utilisable : définissez hide_run_button: true.
5. Ajoutez un bloc client_call (optionnel ; s'il est omis, un exemple curl automatique sera généré).
6. Liez les données de performance : si des benchmarks existent, ajoutez benchmark_key. Si vous comparez avec son prédécesseur, ajoutez benchmark_series.
7. Ajoutez le corps du texte : rédigez la section « Model Details » en Markdown en dessous du frontmatter.
8. Validez : exécutez npm run build ou npm run astro check pour détecter les erreurs de schéma dans le frontmatter.

---

Pièges courants

• Ne pas confondre hide_run_button avec matrix_modules_disabled : hide_run_button masque toute la section, tandis que matrix_modules_disabled grise des onglets individuels.
• L'ordre d'affichage des moteurs ne peut pas être modifié via le frontmatter : il est codé en dur (vLLM → SGLang → llama.cpp → Ollama → Edge-LLM → alphabétique).
• Les identifiants des benchmarks sont différents des identifiants de la matrice : voir le tableau benchmarks.json ci-dessus. Une faute de frappe ici conduira à une absence de données de performance sur la page.
• Les identifiants de module doivent correspondre exactement : thor_t5000 (valide) vs thor-t5000 (invalide).