Jetson AI Lab: Configuración de Páginas del Catálogo de Modelos

¿Qué hace Jetson AI Lab: Configuración de Páginas del Catálogo de Modelos?

Verificación de la Realidad

• Jetson AI Lab es un sitio Astro estático. No aloja APIs de inferencia. Los usuarios copian comandos del sitio y los ejecutan en un Jetson (u otra máquina).
• Las páginas de modelos son archivos Markdown en la colección de contenido de Astro models: src/content/models/<slug>.md.
• El slug del archivo (nombre del archivo sin .md) se convierte en el segmento de URL: la ruta publicada es /models/<slug> (ver src/pages/models/[slug].astro).
• Casi todos los elementos visibles en una página de modelo están controlados por el frontmatter YAML de ese archivo (Héroe, Barra lateral de Detalles del Modelo, pestañas de Ejecutar en Jetson, fragmentos de Llamada, pestañas de disparo único, gráfico de Punto de Referencia). El Markdown del cuerpo solo llena la sección de prosa de Detalles del Modelo al final.

No inventes una URL base para "la API de inferencia de Jetson AI Lab" — no existe.

---

Anatomía de la Página (de arriba a abajo)

Sección	Controlado por	Componente/archivo
Héroe (título, insignias, tarjetas "Comando para Ejecutar en Jetson" / "Punto de Referencia" / "Detalles del Modelo")	title, is_new, type, short_description, presencia de motores y benchmark_key	src/pages/models/[slug].astro
Barra lateral de Especificaciones (Parámetros, Modalidades, Longitud de Contexto, Licencia, Píldoras de Precisión)	parameters (o model_size), modalities (o vision_capable), context_length, license, precision (por token)	src/pages/models/[slug].astro L137–193
Ejecutar en Jetson → Matriz de Servir	serving.entries (preferido) o supported_inference_engines, más matrix_modules_disabled	ModelServeSection.astro
Llamar al modelo	client_call.{shell,python,intro} (o auto-construido desde motores + hf_checkpoint)	ModelCallSection.astro
Inferencia de disparo único (pestañas por módulo)	one_shot_inference.*	ModelOneShotSection.astro + src/lib/evalRunModal.ts
Gráfico de Punto de Referencia	benchmark_key (+ benchmark_series opcional) → se une a src/data/benchmarks.json	ModelBenchmarkSection.astro
Prosa de Detalles del Modelo + enlaces externos (Probar en build.nvidia.com, Ver en HuggingFace)	Markdown del cuerpo + build_nvidia_url, huggingface_url (o hf_checkpoint)	src/pages/models/[slug].astro L242–289

---

Referencia del Frontmatter

Cada página de modelo está controlada por su frontmatter YAML. La validación vive en src/content/config.ts (modelsSchema).

Etiquetas de inclusión obligatoria

O son requeridas por el esquema (la compilación falla sin ellas) o son utilizadas por todos los modelos en el repositorio. Inclúyelas todas al añadir un nuevo modelo.

Etiqueta	Esquema	Qué hace
title	requerido	Nombre para mostrar en la página del modelo y tarjetas del catálogo.
short_description	requerido	Resumen de una línea en la cuadrícula del catálogo y subtítulo del Héroe.
precision	requerido	Tokens de cuantificación separados por barra o coma (ej. "NVFP4 / FP8 / Q4_K_M GGUF"). Cada token se renderiza como una píldora de color en la barra lateral (precisionPill en [slug].astro).
family	opcional pero ubicuo	Agrupa modelos en el catálogo. El valor especial "Google Gemma4" activa el banner de CTA del tutorial Gemma 4 sobre la prosa.
model_id, icon, is_new, order, type, hf_checkpoint, huggingface_url, minimum_jetson	opcional pero ubicuo	Tarjeta del catálogo / héroe / enlaces externos. huggingface_url recurre a https://huggingface.co/${hf_checkpoint} cuando se omite.

Etiquetas de la Barra Lateral de Detalles del Modelo (controlan la tarjeta de especificaciones oscura a la derecha del Héroe)

Omitir estas hace que la fila desaparezca de la barra lateral (sin error, solo menos pulido).

Etiqueta	Fila de la barra lateral	Notas
parameters (o recurrir a model_size)	"Parámetros"	Texto libre, ej. "~9B" o "30B total / 3B activos".
modalities: [...]	"Modalidades"	Array de `"Texto"
vision_capable (booleano)	(recurso para Modalidades)	Establécelo explícitamente incluso cuando modalities esté presente — se usa en otros lugares para filtros del catálogo.
context_length	"Longitud de Contexto"	Texto libre, ej. "128K", "262K".
license	"Licencia"	Texto libre, ej. "Apache 2.0", "Licencia de Modelo Abierto de NVIDIA".
model_size	(recurso para Parámetros)	ej. "12GB".
memory_requirements	no se muestra en la barra lateral pero utilizado por otra interfaz de usuario	ej. "16GB RAM".

Etiquetas Situacionales

Solo agrégalas cuando el modelo las necesite.

Etiqueta	Cuándo usarla	Uso en el repositorio
build_nvidia_url	El modelo tiene una página de NVIDIA Build → añade el botón Probar en build.nvidia.com.	~67% de los modelos
matrix_modules_disabled	Algunas pestañas de módulos de la matriz deben estar atenuadas / no ser seleccionables para todos los motores de este modelo.	~10% de los modelos
hide_run_button	Ocultar la interfaz de usuario completa de Ejecutar en Jetson (Servir + Llamar + disparo único) incluso cuando los datos del motor están presentes.	~5% de los modelos
benchmark_key	El modelo tiene rendimiento medido en src/data/benchmarks.json. El valor debe coincidir con el campo name de esa entrada de benchmarks.	~30% de los modelos
benchmark_series: [...]	Mostrar barras de comparación adicionales lado a lado (ej. comparar con la generación anterior de la misma familia). Cada valor es otro name de benchmarks.json.	Un puñado

Bloques de Inferencia (al menos uno requerido a menos que hide_run_button: true)

Bloque	Propósito
serving.entries	Lista de motores de nuevo estilo — preferido para modelos nuevos. Sobrescribe supported_inference_engines en la interfaz de usuario cuando no está vacío.
supported_inference_engines	Array de motores heredado. Todavía funciona y es la forma más común hoy en día.
one_shot_inference	Comandos de ejecución de disparo único (variantes shell/python/por módulo). Renderiza una sección separada de pestañas "Inferencia de disparo único" debajo de Llamar.
client_call.{shell,python,intro}	Sobrescritura opcional para el fragmento Llamar al modelo. Si se omite, la página auto-construye un ejemplo curl a partir de los comandos del motor y hf_checkpoint.

---

Ejecutar en Jetson: las tres palancas de "bloqueo" (cuándo OOM vs ocultar vs atenuar)

Estas están en capas. La matriz de servir las evalúa en este orden:

1. hide_run_button: true (frontmatter, nivel superior)

   • Oculta la sección completa de Ejecutar en Jetson (Servir + Llamar + disparo único).
   • Úsalo cuando el modelo existe en el catálogo pero aún no se puede lanzar desde el sitio (ej. requiere descarga de NGC, punto de control con restricciones, validación pendiente).
   • Ejemplo: src/content/models/cosmos-reason2-8b.md — mantiene los datos del motor para documentación, pero la interfaz de ejecución permanece oculta.

2. matrix_modules_disabled: [moduleId, ...] (frontmatter, nivel superior)

   • Atenúa las pestañas de módulos listadas en todos los motores para este modelo. La pestaña se muestra pero no se puede seleccionar.
   • Úsalo cuando un módulo Jetson es teóricamente posible pero aún no validado para este modelo.

3. engines[].modules_supported: [moduleId, ...] (por motor, dentro de serving.entries[] o supported_inference_engines[])

   • Lista blanca: solo los ids de módulo listados están habilitados para ese motor. Las celdas fuera de la lista se muestran atenuadas para esa fila de motor.
   • Omite el campo por completo → el motor admite todos los módulos de la matriz. Un array vacío significa que el motor no admite nada (raro).
   • Úsalo cuando el modelo se ejecuta en todas partes pero un motor específico solo funciona en un subconjunto (ej. vLLM solo en Thor, Ollama en Orin+Thor).

OOM es un concepto diferente y vive en src/data/benchmarks.json — consulta Puntos de Referencia a continuación.

Quieres expresar…	Usa…
"Este modelo no está listo para ejecutarse desde el sitio en absoluto"	hide_run_button: true
"Este modelo no puede ejecutarse en Orin Nano (ningún motor)"	matrix_modules_disabled: [orin_nano_8]
"vLLM solo funciona en Thor para este modelo; llama.cpp funciona en todas partes"	Entrada vLLM: modules_supported: [thor_t5000, thor_t4000]; omitir en llama.cpp
"Evaluamos esto y se quedó sin memoria en T4000"	Agrega "oom": ["t4000"] a esa cuantificación en benchmarks.json (no pertenece al frontmatter del modelo)
"Evaluamos esto y el modelo simplemente no se ejecuta en Orin Nano"	Agrega "dnr": ["orin_nano_8gb"] a esa cuantificación en benchmarks.json
"Aún no hemos medido esta combinación"	Establece el valor en null en benchmarks.json. No se dibuja ningún marcador; la barra simplemente está ausente.

---

Datos de Inferencia: matriz de servir (motores)

La lista de motores es construida por getSupportedInferenceEngines en src/lib/modelFrontmatterAdapter.ts:

• Si serving.entries está presente y no está vacío → se utilizan esas entradas (preferido para trabajo nuevo).
• De lo contrario, se utiliza supported_inference_engines (array heredado).

Cada fila de motor se asigna a SupportedEngineEntry en src/lib/inferenceCommands.ts. Prefiere:

• serve_command_orin / serve_command_thor para comandos de servir de larga duración (vLLM, Ollama, etc.).
• Los heredados run_command_orin / run_command_thor están obsoletos pero aún se aceptan como recurso.

Campos opcionales:

• modules_supported — consulta la palanca de bloqueo #3 anterior.
• run_commands_by_module: mapa de sobrescritura por celda { moduleId: command } para las celdas de la matriz de Ejecutar.
• install_command / install_command_orin / install_command_thor: prefijado como bloque # Instalación sobre el comando de servir.

El orden de visualización de los motores es fijo por sortEnginesForUi en modelFrontmatterAdapter.ts: vLLM → SGLang → llama.cpp → Ollama → Edge-LLM → todo lo demás (alfabético). No intentes controlar el orden desde el frontmatter.

IDs de módulos Jetson canónicos

Definidos en JETSON_MATRIX_MODULES en src/lib/inferenceCommands.ts. Usa estos ids exactos en modules_supported / matrix_modules_disabled / one_shot_inference.modules_supported.

Id de módulo	¿Pestaña de matriz?	Plataforma
thor_t5000	Sí	thor
thor_t4000	Sí	thor
orin_agx_64	Sí	orin
orin_nx_16	Sí	orin
orin_nano_8	Sí	orin
orin_agx_32	solo datos (sin pestaña)	orin
orin_nx_8	solo datos (sin pestaña)	orin
orin_nano_4	solo datos (sin pestaña)	orin

Los ids "solo datos" (showInMatrixUi: false) son frontmatter válidos y resuelven comandos por platformKey, pero no se muestra ninguna pestaña de la matriz Servir/Ejecutar. No inventes nuevos ids — extender la lista requiere un cambio de código en JETSON_MATRIX_MODULES.

Ejemplos en el repositorio:

• serving.entries (nuevo estilo): src/content/models/ministral3-8b-reasoning.md
• supported_inference_engines heredado con rico modules_supported por motor: src/content/models/nemotron-3-nano-omni.md
• hide_run_button: true: src/content/models/cosmos-reason2-8b.md

---

Inferencia de disparo único

Bloque de frontmatter opcional one_shot_inference (esquema en src/content/config.ts). Campos:

• run_command_orin, run_command_thor — comando único de ejecución por plataforma.
• shell, python — fragmentos no específicos de plataforma.
• shell_by_module, python_by_module — mapas de sobrescritura por módulo, claveados por id de módulo canónico.
• modules_supported — restringe qué pestañas de módulos aparecen.
• intro — introducción Markdown opcional mostrada sobre las pestañas.

Visibilidad: ModelOneShotSection.astro muestra la sección cuando al menos uno de los campos de comando anteriores no está vacío (verificación hasContent).

La resolución de fragmentos/módulos vive en src/lib/evalRunModal.ts (ver evalSnippetByModule, evalMatrixModuleSpecs).

---

Llamar al modelo (client_call)

Bloque de frontmatter opcional — sobrescribe el ejemplo curl auto-generado mostrado en Llamar al modelo.

client_call:
  intro: "Una vez que el servidor esté funcionando:"
  shell: |-
    curl -s http://${JETSON_HOST}:8080/v1/chat/completions \
      -H "Content-Type: application/json" \
      -d '{ "model": "my_model", "messages": [{"role":"user","content":"hola"}] }'
  python: |-
    import openai
    ...

Omite client_call por completo para dejar que ModelCallSection.astro sintetice un ejemplo a partir de hf_checkpoint y el comando de servir del primer motor.

---

Datos de Puntos de Referencia

Los números de punto de referencia no viven en el frontmatter del modelo. Viven en src/data/benchmarks.json bajo models[]. La página del modelo se une mediante el campo de frontmatter benchmark_key, que debe coincidir exactamente con models[].name.

Añadir datos de puntos de referencia

1. Agrega una entrada a models[] en src/data/benchmarks.json:

{
  "family": "Nombre de la Familia",
  "name": "Nombre Exacto (esta es la clave de unión)",
  "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. En el frontmatter del modelo agrega:

benchmark_key: "Nombre Exacto (esta es la clave de unión)"
benchmark_series:
  - "Nombre de la Familia Antepasada"   # opcional — superpone barras de comparación

IDs de producto de punto de referencia ≠ IDs de módulo de matriz (diferencia crítica)

El eje de punto de referencia utiliza ids diferentes a los de la matriz Ejecutar/Servir:

Hardware	Id de módulo de matriz (frontmatter)	Id de producto de punto de referencia (benchmarks.json)
Jetson Thor T5000	thor_t5000	t5000
Jetson Thor T4000	thor_t4000	t4000
Jetson AGX Orin 64GB	orin_agx_64	agx_orin_64gb
Jetson Orin NX 16GB	orin_nx_16	orin_nx_16gb
Jetson Orin Nano 8GB	orin_nano_8	orin_nano_8gb

No uses ids de módulo de matriz en benchmarks.json — no coincidirán y romperán la representación.

---

Resolución de Sobrescrituras de Texto

Varios bloques de frontmatter aceptan un formato de mapa de cadenas donde las claves se refieren a la plataforma o un módulo específico y los valores son el texto a mostrar. Se utiliza en:

• serve_command_orin / run_command_orin para comandos específicos de plataforma.
• run_commands_by_module para sobrescrituras por módulo.

Ejemplo para run_commands_by_module:

serving:
  entries:
    - engine: vLLM
      run_commands_by_module:
        thor_t5000: "python3 -m vllm.entrypoints.openai.api_server --model modelo"
        orin_nx_16: "python3 -m vllm.entrypoints.openai.api_server --model modelo --max-num-seqs 128"

Cuando no se proporciona una sobrescritura, la página construye un comando predeterminado a partir de los campos platformKey y hf_checkpoint.

---

Resolución de Fragmentos de Disparo Único

evalSnippetByModule en src/lib/evalRunModal.ts resuelve los fragmentos de disparo único en este orden:

1. shell_by_module[moduleId] o python_by_module[moduleId] (si se proporciona)
2. shell o python (genérico de plataforma)
3. run_command_orin / run_command_thor (por plataforma)
4. Si todo lo demás falla → fragmento vacío (no se muestra ninguna pestaña)

---

Prácticas Recomendadas

• Siempre establece benchmark_key cuando existan datos de rendimiento; de lo contrario, la sección del gráfico simplemente no se renderiza.
• Usa serving.entries para modelos nuevos; supported_inference_engines es heredado y no se eliminará, pero el nuevo estilo es más limpio y extensible.
• Establece modules_supported explícitamente cuando un motor solo funciona en un subconjunto de hardware. Omite el campo (no un array vacío) para que el motor funcione en todos los módulos.
• Usa hide_run_button con moderación — es un martillo grande. Prefiere matrix_modules_disabled si solo algunos módulos no están listos.
• Nunca coloques oom o dnr en el frontmatter del modelo — solo en benchmarks.json.
• Verifica dos veces los ids de módulo contra JETSON_MATRIX_MODULES al escribir frontmatter. Un id mal escrito no generará un error de compilación, pero la pestaña de matriz correspondiente no aparecerá (comportamiento silencioso).

---

Archivos Relevantes

Archivo	Propósito
src/content/config.ts	Esquema de validación del frontmatter (modelsSchema)
src/pages/models/[slug].astro	Componente de diseño de la página del modelo
src/lib/modelFrontmatterAdapter.ts	Ayudantes de resolución de frontmatter (getSupportedInferenceEngines, sortEnginesForUi)
src/lib/inferenceCommands.ts	SupportedEngineEntry, JETSON_MATRIX_MODULES
src/lib/evalRunModal.ts	Resolución de fragmentos de disparo único
src/data/benchmarks.json	Datos de rendimiento de puntos de referencia
ModelServeSection.astro	Componente de matriz de servir
ModelCallSection.astro	Componente de llamada al modelo
ModelOneShotSection.astro	Componente de disparo único
ModelBenchmarkSection.astro	Componente de gráfico de puntos de referencia