NVIDIA-AI-IOT/jetson-ai-lab

Jetson AI Lab: Konfiguration des Modellkatalogseiten

Realitätscheck

• Jetson AI Lab ist eine statische Astro-Website. Sie hostet keine Inferenz-APIs. Benutzer kopieren Befehle von der Website und führen sie auf einem Jetson (oder einem anderen Rechner) aus.
• Modellseiten sind Markdown-Dateien in der Astro-Content-Collection models: src/content/models/<slug>.md.
• Der Dateiname slug (ohne .md) wird zum URL-Segment: veröffentlichte Route /models/<slug> (siehe src/pages/models/[slug].astro).
• Fast jedes sichtbare Element auf einer Modellseite wird durch YAML-Frontmatter in dieser Datei gesteuert (Hero, Modelldetails-Seitenleiste, „Run on Jetson“-Tabs, Call-Schnipsel, One-Shot-Tabs, Benchmark-Diagramm). Der Body-Markdown füllt nur den unteren Modelldetails-Prosaabschnitt.

Erfinden Sie keine Basis-URL für „die Jetson AI Lab Inferenz-API“ — es gibt keine.

---

Seitenanatomie (von oben nach unten)

Abschnitt	Gesteuert durch	Komponente / Datei
Hero (Titel, Badges, „Command to Run on Jetson“ / „Benchmark“ / „Model Details“-Chips)	title, is_new, type, short_description, Vorhandensein von Engines und benchmark_key	src/pages/models/[slug].astro
Spezifikationen-Seitenleiste (Parameter, Modalitäten, Kontextlänge, Lizenz, Präzisionspillen)	parameters (oder model_size), modalities (oder vision_capable), context_length, license, precision (pro Token)	src/pages/models/[slug].astro L137–193
Run on Jetson → Serve-Matrix	serving.entries (bevorzugt) oder supported_inference_engines, plus matrix_modules_disabled	ModelServeSection.astro
Call the model	client_call.{shell,python,intro} (oder automatisch aus Engines + hf_checkpoint erstellt)	ModelCallSection.astro
One-Shot-Inferenz (pro-Modul-Reiter)	one_shot_inference.*	ModelOneShotSection.astro + src/lib/evalRunModal.ts
Benchmark-Diagramm	benchmark_key (+ optional benchmark_series) → verbindet src/data/benchmarks.json	ModelBenchmarkSection.astro
Modelldetails-Prosa + externe Links (Try on build.nvidia.com, View on HuggingFace)	Body-Markdown + build_nvidia_url, huggingface_url (oder hf_checkpoint)	src/pages/models/[slug].astro L242–289

---

Frontmatter-Referenz

Jede Modellseite wird durch ihr YAML-Frontmatter gesteuert. Die Validierung befindet sich in src/content/config.ts (modelsSchema).

Immer einzufügende Tags

Entweder schema-erforderlich (Build schlägt ohne sie fehl) oder von jedem Modell im Repository verwendet. Fügen Sie alle ein, wenn Sie ein neues Modell hinzufügen.

Tag	Schema	Funktion
title	erforderlich	Anzeigename auf der Modellseite und den Katalogkarten.
short_description	erforderlich	Einzeilige Zusammenfassung im Katalograster und Hero-Untertitel.
precision	erforderlich	Schrägstrich- oder Komma-getrennte Quant-Tokens (z. B. "NVFP4 / FP8 / Q4_K_M GGUF"). Jedes Token wird als farbige Pille in der Seitenleiste gerendert (precisionPill in [slug].astro).
family	optional, aber allgegenwärtig	Gruppiert Modelle im Katalog. Sonderwert "Google Gemma4" löst das Gemma 4-Tutorial-CTA-Banner oberhalb der Prosa aus.
model_id, icon, is_new, order, type, hf_checkpoint, huggingface_url, minimum_jetson	optional, aber allgegenwärtig	Katalogkarte / Hero / externe Links. huggingface_url fällt auf https://huggingface.co/${hf_checkpoint} zurück, wenn nicht angegeben.

Tags der Modelldetails-Seitenleiste (steuern die dunkle Spezifikationskarte rechts neben dem Hero)

Das Weglassen dieser Tags führt dazu, dass die Zeile in der Seitenleiste verschwindet (kein Fehler, nur weniger Details).

Tag	Zeile in der Seitenleiste	Hinweise
parameters (oder Rückfall auf model_size)	„Parameter“	Freitext, z. B. "~9B" oder "30B total / 3B active".
modalities: [...]	„Modalitäten“	Array von "Text" | "Image" | "Audio" | "Video" – jedes wird mit einem Icon gerendert. Wenn nicht angegeben, Rückfall auf vision_capable (Ja → „Text, Image“, Nein → „Text“).
vision_capable (boolean)	(Rückfall für Modalitäten)	Auch explizit setzen, wenn modalities vorhanden ist – wird anderswo für Katalogfilter verwendet.
context_length	„Context Length“	Freitext, z. B. "128K", "262K".
license	„License“	Freitext, z. B. "Apache 2.0", "NVIDIA Open Model License".
model_size	(Rückfall für Parameter)	z. B. "12GB".
memory_requirements	nicht in der Seitenleiste angezeigt, aber von anderer UI verwendet	z. B. "16GB RAM".

Situative Tags

Fügen Sie diese nur hinzu, wenn das Modell sie benötigt.

Tag	Wann verwenden	Verwendung im Repository
build_nvidia_url	Modell hat eine NVIDIA Build-Seite → fügt den Button Try on build.nvidia.com hinzu.	~67 % der Modelle
matrix_modules_disabled	Einige Matrix-Modul-Reiter sollten für jede Engine dieses Modells ausgegraut / nicht anklickbar sein.	~10 % der Modelle
hide_run_button	Die gesamte Run-on-Jetson-UI (Serve + Call + One-Shot) ausblenden, auch wenn Engine-Daten vorhanden sind.	~5 % der Modelle
benchmark_key	Modell hat gemessene Leistung in src/data/benchmarks.json. Der Wert muss mit dem name-Feld dieses Benchmark-Eintrags übereinstimmen.	~30 % der Modelle
benchmark_series: [...]	Zusätzliche Vergleichsbalken nebeneinander anzeigen (z. B. Vergleich mit der Vorgängergeneration derselben Familie). Jeder Wert ist ein weiterer name aus benchmarks.json.	Eine Handvoll

Inferenzblöcke (mindestens einer erforderlich, es sei denn, hide_run_button: true)

Block	Zweck
serving.entries	Neuartige Engine-Liste – bevorzugt für neue Modelle. Überschreibt supported_inference_engines in der UI, wenn nicht leer.
supported_inference_engines	Legacy-Engine-Array. Funktioniert noch und ist heute die gebräuchlichste Form.
one_shot_inference	One-Shot-Ausführungsbefehle (Shell/Python/pro-Modul-Varianten). Rendert einen separaten Bereich „One-shot inference“ mit Reitern unterhalb von Call.
client_call.{shell,python,intro}	Optionale Überschreibung für das Call the model-Snippet. Wenn nicht angegeben, erstellt die Seite automatisch ein curl-Beispiel aus Engine-Befehlen und hf_checkpoint.

---

Run on Jetson: Die drei „Block“-Hebel (wann OOM vs. ausblenden vs. ausgrauen)

Diese sind geschichtet. Die Serve-Matrix wertet sie in dieser Reihenfolge aus:

1. hide_run_button: true (Frontmatter, oberste Ebene)

   • Blendet den gesamten Run-on-Jetson-Abschnitt aus (Serve + Call + One-Shot).
   • Verwenden, wenn das Modell im Katalog existiert, aber noch nicht von der Website aus startbar ist (z. B. NGC-Download erforderlich, gesperrter Checkpoint, ausstehende Validierung).
   • Beispiel: src/content/models/cosmos-reason2-8b.md – behält Engine-Daten für die Dokumentation, aber die Run-UI bleibt ausgeblendet.

2. matrix_modules_disabled: [moduleId, ...] (Frontmatter, oberste Ebene)

   • Blendet die aufgeführten Modul-Reiter für alle Engines dieses Modells aus. Der Reiter wird angezeigt, ist aber nicht anklickbar.
   • Verwenden, wenn ein Jetson-Modul theoretisch möglich, aber noch nicht validiert für dieses Modell ist.

3. engines[].modules_supported: [moduleId, ...] (pro Engine, innerhalb von serving.entries[] oder supported_inference_engines[])

   • Whitelist: Nur die aufgeführten Modul-IDs sind für diese Engine aktiviert. Zellen außerhalb der Liste werden für diese Engine-Zeile ausgegraut.
   • Das Feld vollständig weglassen → Engine unterstützt alle Matrix-Module. Ein leeres Array bedeutet, dass die Engine nichts unterstützt (selten).
   • Verwenden, wenn das Modell überall läuft, aber eine bestimmte Engine nur auf einer Teilmenge funktioniert (z. B. vLLM Thor-only, Ollama Orin+Thor).

OOM ist ein anderes Konzept und lebt in src/data/benchmarks.json – siehe Benchmarks unten.

Sie möchten ausdrücken…	Verwenden Sie…
„Dieses Modell ist nicht bereit, von der Website aus ausgeführt zu werden“	hide_run_button: true
„Dieses Modell kann nicht auf Orin Nano laufen (keine Engine)“	matrix_modules_disabled: [orin_nano_8]
„vLLM funktioniert für dieses Modell nur auf Thor; llama.cpp funktioniert überall“	vLLM-Eintrag: modules_supported: [thor_t5000, thor_t4000]; bei llama.cpp weglassen
„Wir haben das benchmarkt und es gab einen Speicherüberlauf auf T4000“	Fügen Sie "oom": ["t4000"] zu diesem Quant in benchmarks.json hinzu (gehört nicht ins Modell-Frontmatter)
„Wir haben das benchmarkt und das Modell läuft einfach nicht auf Orin Nano“	Fügen Sie "dnr": ["orin_nano_8gb"] zu diesem Quant in benchmarks.json hinzu
„Wir haben diese Kombination noch nicht gemessen“	Setzen Sie den Wert auf null in benchmarks.json. Es wird kein Marker gezeichnet; der Balken fehlt einfach.

---

Inferenzdaten: Serve-Matrix (Engines)

Die Engine-Liste wird von getSupportedInferenceEngines in src/lib/modelFrontmatterAdapter.ts erstellt:

• Wenn serving.entries vorhanden und nicht leer ist → werden diese Einträge verwendet (bevorzugt für neue Arbeiten).
• Andernfalls wird supported_inference_engines (Legacy-Array) verwendet.

Jede Engine-Zeile bildet auf SupportedEngineEntry in src/lib/inferenceCommands.ts ab. Bevorzugen Sie:

• serve_command_orin / serve_command_thor für langlebige Serve-Befehle (vLLM, Ollama usw.).
• Legacy-Befehle run_command_orin / run_command_thor sind veraltet, werden aber weiterhin als Fallbacks akzeptiert.

Optionale Felder:

• modules_supported – siehe Block-Hebel #3 oben.
• run_commands_by_module: pro-Zell-Überschreibungskarte { moduleId: command } für Run-Matrix-Zellen.
• install_command / install_command_orin / install_command_thor: wird als # Installation-Block oberhalb des Serve-Befehls vorangestellt.

Die Anzeigereihenfolge der Engines ist festgelegt durch sortEnginesForUi in modelFrontmatterAdapter.ts: vLLM → SGLang → llama.cpp → Ollama → Edge-LLM → alles andere (alphabetisch). Versuchen Sie nicht, die Reihenfolge über das Frontmatter zu steuern.

Kanonische Jetson-Modul-IDs

Definiert in JETSON_MATRIX_MODULES in src/lib/inferenceCommands.ts. Verwenden Sie diese genauen IDs in modules_supported / matrix_modules_disabled / one_shot_inference.modules_supported.

Modul-ID	Matrix-Reiter?	Plattform
thor_t5000	Ja	thor
thor_t4000	Ja	thor
orin_agx_64	Ja	orin
orin_nx_16	Ja	orin
orin_nano_8	Ja	orin
orin_agx_32	nur Daten (kein Reiter)	orin
orin_nx_8	nur Daten (kein Reiter)	orin
orin_nano_4	nur Daten (kein Reiter)	orin

„Nur Daten“-IDs (showInMatrixUi: false) sind gültiges Frontmatter und lösen Befehle über platformKey auf, aber es wird kein Serve/Run-Matrix-Reiter angezeigt. Erfinden Sie keine neuen IDs – die Erweiterung der Liste erfordert eine Codeänderung in JETSON_MATRIX_MODULES.

Beispiele im Repository:

• serving.entries (neuer Stil): src/content/models/ministral3-8b-reasoning.md
• Legacy supported_inference_engines mit umfangreichem pro-Engine-modules_supported: src/content/models/nemotron-3-nano-omni.md
• hide_run_button: true: src/content/models/cosmos-reason2-8b.md

---

One-Shot-Inferenz

Optionaler Frontmatter-Block one_shot_inference (Schema in src/content/config.ts). Felder:

• run_command_orin, run_command_thor – Einzelbefehlsausführung pro Plattform.
• shell, python – nicht plattformspezifische Schnipsel.
• shell_by_module, python_by_module – pro-Modul-Überschreibungskarten, die nach kanonischer Modul-ID indiziert sind.
• modules_supported – einschränken, welche Modul-Reiter erscheinen.
• intro – optionaler Markdown-Text, der oberhalb der Reiter angezeigt wird.

Sichtbarkeit: ModelOneShotSection.astro zeigt den Abschnitt an, wenn mindestens eines der obigen Befehlsfelder nicht leer ist (hasContent-Prüfung).

Die Auflösung von Schnipseln/Modulen befindet sich in src/lib/evalRunModal.ts (siehe evalSnippetByModule, evalMatrixModuleSpecs).

---

Call the model (client_call)

Optionaler Frontmatter-Block – überschreibt das automatisch generierte curl-Beispiel, das in Call the model angezeigt wird.

client_call:
  intro: "Sobald der Server läuft:"
  shell: |-
    curl -s http://${JETSON_HOST}:8080/v1/chat/completions \
      -H "Content-Type: application/json" \
      -d '{ "model": "my_model", "messages": [{"role":"user","content":"hi"}] }'
  python: |-
    import openai
    ...

Lassen Sie client_call vollständig weg, damit ModelCallSection.astro ein Beispiel aus hf_checkpoint und dem ersten Serve-Befehl der Engine synthetisiert.

---

Benchmarks-Daten

Benchmark-Zahlen leben nicht im Modell-Frontmatter. Sie leben in src/data/benchmarks.json unter models[]. Die Modellseite verknüpft über das Frontmatter-Feld benchmark_key, das exakt mit models[].name übereinstimmen muss.

Hinzufügen von Benchmark-Daten

1. Fügen Sie einen Eintrag zu models[] in src/data/benchmarks.json hinzu:

{
  "family": "Familienname",
  "name": "Exakter Name (dies ist der Verbindungsschlüssel)",
  "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. Fügen Sie im Modell-Frontmatter hinzu:

benchmark_key: "Exakter Name (dies ist der Verbindungsschlüssel)"
benchmark_series:
  - "Name der Vorgängerfamilie"   # optional – überlagert Vergleichsbalken

Benchmark-Produkt-IDs ≠ Matrix-Modul-IDs (kritische Falle)

Die Benchmark-Achse verwendet andere IDs als die Run/Serve-Matrix:

Hardware	Matrix-Modul-ID (Frontmatter)	Benchmark-Produkt-ID (benchmarks.json)
Jetson Thor T5000	thor_t5000	t5000
Jetson Thor T4000	thor_t4000	t4000
Jetson Orin AGX 64 GB	orin_agx_64	agx_orin_64gb
Jetson Orin NX 16 GB	orin_nx_16	orin_nx_16gb
Jetson Orin Nano 8 GB	orin_nano_8	orin_nano_8gb
DGX Spark	(kein Matrix-Reiter)	dgx_spark

Übersetzen Sie nicht eine in die andere. Die Benchmark-Konfiguration ist unabhängig vom Frontmatter. Das Verknüpfungssystem (in src/lib/modelBenchmarks.ts) behandelt die Übersetzung zwischen den beiden Namensräumen. Wenn Sie eine neue Hardware-Plattform hinzufügen, müssen Sie BENCHMARK_PRODUCT_IDS in modelBenchmarks.ts aktualisieren, um den Matrix-Modul-ID auf den Benchmark-Produkt-ID abzubilden.

Was die Symbole bedeuten

Symbol	Bedeutung
null	Nicht getestet – kein Balken eingezeichnet
"oom" (Out of Memory)	Benchmark schlug mit Speichermangel fehl – roter Blitz
"dnr" (Does Not Run)	Modell läuft auf diesem Gerät überhaupt nicht (Inkompatibilität) – graues "–"
Zahl	Gemessener Durchsatz in Tokens pro Sekunde

---

Modellseiten-Assets (Bilder / Diagramme)

Modellseiten können Bilder im Hero-Bereich oder eingebettete Bilder im Body-Markdown enthalten:

• Hero-Icon: icon: "models/example-icon.svg" – relativ zu src/assets/ (Astro-Bildoptimierung).
• Eingebettete Bilder im Body-Markdown: Relative Pfade ./images/my-diagram.png innerhalb desselben Ordners (z. B. src/content/models/images/).

Images in src/content/models/images/ werden automatisch von Astro optimiert, wenn sie über den ![](...)-Markdown-Referenzpfad verlinkt sind.

---

Validierung und Fehlerbehebung

1. Frontmatter-Schema nicht eingehalten: Der Build schlägt mit einem Fehler wie Frontmatter does not match schema fehl. Jeder Tag-Typ (Zeichenkette, Zahl, Array, Boolean) wird in src/content/config.ts geprüft.
2. Benchmark-Key stimmt nicht überein: Wenn benchmark_key in der Modellseite gesetzt ist, aber kein passender Eintrag in benchmarks.json existiert, wird die Seite ohne Fehler erstellt, das Benchmark-Diagramm zeigt aber einen leeren Zustand.
3. Engine-IDs für modules_supported: Die Liste muss kanonische Jetson-Modul-IDs aus JETSON_MATRIX_MODULES verwenden. Falsche IDs werden ignoriert (keine Engine-Zelle ist dann sichtbar).

Zusätzliche Hinweise:

• Sie können die Modellseiten-Platzhalter('Stubs') über das Astro-Content-API prüfen: npx astro check validiert Frontmatter-Schemata ohne vollständigen Build.
• Obsolete Felder (z. B. run_command_orin außerhalb von serving.entries) werden von der UI nicht mehr erkannt. Verwenden Sie run_commands_by_module für pro-Zoll-Überschreibungen.

Anhänge: Referenz für schnelles Nachschlagen

Schema-Referenz (aus src/content/config.ts)

// Ausschnitt aus modelsSchema
{
  title: z.string(),
  short_description: z.string(),
  precision: z.string(),
  family: z.string().optional(),
  model_id: z.string().optional(),
  icon: z.string().optional(),
  is_new: z.boolean().optional(),
  order: z.number().optional(),
  type: z.string().optional(),
  hf_checkpoint: z.string().optional(),
  huggingface_url: z.string().optional(),
  minimum_jetson: z.string().optional(),
  parameters: z.string().optional(),
  model_size: z.string().optional(),
  modalities: z.array(z.enum(['Text', 'Image', 'Audio', 'Video'])).optional(),
  vision_capable: z.boolean().optional(),
  context_length: z.string().optional(),
  license: z.string().optional(),
  memory_requirements: z.string().optional(),
  build_nvidia_url: z.string().optional(),
  matrix_modules_disabled: z.array(z.string()).optional(),
  hide_run_button: z.boolean().optional(),
  benchmark_key: z.string().optional(),
  benchmark_series: z.array(z.string()).optional(),
  serving: z.object({
    entries: z.array(SupportedEngineEntrySchema).optional()
  }).optional(),
  supported_inference_engines: z.array(SupportedEngineEntrySchema).optional(),
  one_shot_inference: OneShotInferenceSchema.optional(),
  client_call: z.object({
    intro: z.string().optional(),
    shell: z.string().optional(),
    python: z.string().optional()
  }).optional()
}

Liste der Engine-IDs (für modules_supported)

Aktuelle Liste (möglicherweise nicht erschöpfend, prüfen Sie inferenceCommands.ts): [vllm, sglang, llama.cpp, ollama, edge_llm, ...]

Dateipfade

Zweck	Pfad
Modellseiten (Frontmatter)	src/content/models/<slug>.md
Benchmark-Daten	src/data/benchmarks.json
Schema-Validierung	src/content/config.ts (modelsSchema)
Engine-Befehlslogik	src/lib/inferenceCommands.ts
Benchmark-Brücke (Produkt-IDs)	src/lib/modelBenchmarks.ts
Run/Serve-Komponente	src/components/ModelServeSection.astro
Call-Komponente	src/components/ModelCallSection.astro
One-Shot-Komponente	src/components/ModelOneShotSection.astro
Benchmark-Komponente	src/components/ModelBenchmarkSection.astro