Jetson AI Lab：模型目錄頁面配置

實際情況

Jetson AI Lab 是一個靜態 Astro 網站。它不託管推論 API。使用者從網站複製命令並在自己的 Jetson（或其他機器）上執行。
模型頁面是 Astro 內容集合 models 中的 Markdown 檔案：src/content/models/<slug>.md。
slug（不含 .md 的檔名）成為 URL 路徑段：發布後的路由為 /models/<slug>（參見 src/pages/models/[slug].astro）。
模型頁面上幾乎所有可見元素都由該檔案中的 YAML frontmatter 驅動（英雄區域、模型詳細資訊側邊欄、Run on Jetson 分頁、呼叫程式碼片段、one-shot 分頁、基準測試圖表）。主體 Markdown 僅填充底部的 Model Details 散文區塊。

請不要為「Jetson AI Lab 推論 API」編造一個基礎 URL — 因為根本不存在。

頁面結構（從上到下）

區段	驅動元素	元件 / 檔案
英雄區域（標題、徽章、「Command to Run on Jetson」/「Benchmark」/「Model Details」標籤）	`title`、`is_new`、`type`、`short_description`、引擎和 `benchmark_key` 的存在	`src/pages/models/[slug].astro`
規格側邊欄（參數、模態、上下文長度、授權、精度標籤）	`parameters`（或 `model_size`）、`modalities`（或 `vision_capable`）、`context_length`、`license`、`precision`（每個 token）	`src/pages/models/[slug].astro` L137–193
Run on Jetson → Serve 矩陣	`serving.entries`（較佳）或 `supported_inference_engines`，加上 `matrix_modules_disabled`	`ModelServeSection.astro`
呼叫模型	`client_call.{shell,python,intro}`（或從引擎 + `hf_checkpoint` 自動建構）	`ModelCallSection.astro`
One-shot 推論（每個模組分頁）	`one_shot_inference.*`	`ModelOneShotSection.astro` + `src/lib/evalRunModal.ts`
基準測試圖表	`benchmark_key`（+ 可選的 `benchmark_series`）→ 連接 `src/data/benchmarks.json`	`ModelBenchmarkSection.astro`
Model Details 散文 + 外部連結（「Try on build.nvidia.com」、「View on HuggingFace」）	主體 Markdown + `build_nvidia_url`、`huggingface_url`（或 `hf_checkpoint`）	`src/pages/models/[slug].astro` L242–289

Frontmatter 參考

每個模型頁面都由其 YAML frontmatter 驅動。驗證邏輯位於 src/content/config.ts（modelsSchema）。

始終包含的標籤

這些要麼是 schema 必需的（缺少則建置失敗），要麼是儲存庫中每個模型都使用的。新增模型時請全部包含。

標籤	Schema	作用
`title`	required	模型頁面和目錄卡片上的顯示名稱。
`short_description`	required	目錄網格和英雄區域副標題中的一行摘要。
`precision`	required	以斜線或逗號分隔的量化 token（例如 `"NVFP4 / FP8 / Q4_K_M GGUF"`）。每個 token 在側邊欄中呈現為一個彩色標籤（`[slug].astro` 中的 `precisionPill`）。
`family`	可選但普遍使用	在目錄中對模型進行分組。特殊值 `"Google Gemma4"` 會觸發在散文上方顯示 Gemma 4 教學 CTA 橫幅。
`model_id`、`icon`、`is_new`、`order`、`type`、`hf_checkpoint`、`huggingface_url`、`minimum_jetson`	可選但普遍使用	目錄卡片 / 英雄區域 / 外部連結。省略 `huggingface_url` 時，會回退到 `https://huggingface.co/${hf_checkpoint}`。

Model Details 側邊欄標籤（驅動英雄區域右側的深色規格卡片）

跳過這些會導致該行從側邊欄消失（不會報錯，只是不夠精緻）。

標籤	側邊欄行	備註
`parameters`（或回退到 `model_size`）	「Parameters」	自由文字，例如 `"~9B"` 或 `"30B total / 3B active"`。
`modalities: [...]`	「Modalities」	陣列 `"Text"
`vision_capable`（布林值）	（Modalities 的回退）	即使存在 `modalities` 也明確設定 — 在其他地方用於目錄篩選。
`context_length`	「Context Length」	自由文字，例如 `"128K"`、`"262K"`。
`license`	「License」	自由文字，例如 `"Apache 2.0"`、`"NVIDIA Open Model License"`。
`model_size`	（Parameters 的回退）	例如 `"12GB"`。
`memory_requirements`	不在側邊欄中顯示，但被其他 UI 使用	例如 `"16GB RAM"`。

情境標籤

僅在模型需要時才新增這些。

標籤	何時使用	儲存庫使用情況
`build_nvidia_url`	模型有 NVIDIA Build 頁面 → 新增 Try on build.nvidia.com 按鈕。	約 67% 的模型
`matrix_modules_disabled`	對於此模型的每個引擎，某些矩陣模組分頁應顯示為灰色 / 不可點擊。	約 10% 的模型
`hide_run_button`	隱藏整個 Run on Jetson UI（Serve + Call + one-shot），即使引擎資料存在。	約 5% 的模型
`benchmark_key`	模型在 `src/data/benchmarks.json` 中有測量到的效能。值必須等於該基準測試條目的 `name` 欄位。	約 30% 的模型
`benchmark_series: [...]`	顯示額外的並排比較條（例如，與同一系列的前一代進行比較）。每個值是 `benchmarks.json` 中的另一個 `name`。	少數

推論區塊（除非 `hide_run_button: true`，否則至少需要一個）

區塊	用途
`serving.entries`	新式引擎列表 — 新模型的首選。非空時會覆蓋 UI 中的 `supported_inference_engines`。
`supported_inference_engines`	Legacy 引擎陣列。仍然有效，並且是當今最常見的形狀。
`one_shot_inference`	One-shot 執行命令（shell/python/每個模組變體）。在 Call 下方渲染一個單獨的「One-shot inference」分頁區段。
`client_call.{shell,python,intro}`	可選的覆蓋，用於呼叫模型程式碼片段。如果省略，頁面會從引擎命令和 `hf_checkpoint` 自動建構一個 curl 範例。

Run on Jetson：三個「區塊」控制桿（何時 OOM vs 隱藏 vs 灰顯）

這些是分層的。Serve 矩陣按以下順序評估它們：

hide_run_button: true（frontmatter，頂層）
- 隱藏整個 Run on Jetson 區段（Serve + Call + one-shot）。
- 當模型存在於目錄中但尚未準備好從網站啟動時使用（例如，需要 NGC 下載、門控檢查點、待驗證）。
- 範例：src/content/models/cosmos-reason2-8b.md — 保留引擎資料以供文件使用，但執行 UI 保持隱藏。
matrix_modules_disabled: [moduleId, ...]（frontmatter，頂層）
- 對於此模型，將列出的模組分頁在所有引擎上灰顯。分頁顯示但不可點擊。
- 當 Jetson 模組理論上可能但尚未驗證此模型時使用。
engines[].modules_supported: [moduleId, ...]（每個引擎，位於 serving.entries[] 或 supported_inference_engines[] 內部）
- 允許清單：僅列出的模組 ID 在該引擎上啟用。該引擎行的清單外的儲存格會顯示為灰色。
- 完全省略此欄位 → 引擎支援所有矩陣模組。空陣列表示引擎不支援任何東西（很少見）。
- 當模型可以在任何地方執行，但特定引擎僅適用於子集時使用（例如，vLLM Thor-only，Ollama Orin+Thor）。

OOM 是一個不同的概念，存在於 src/data/benchmarks.json 中 — 請參閱下方的基準測試。

你想要表達…	使用…
「這個模型完全無法從網站執行」	`hide_run_button: true`
「這個模型無法在 Orin Nano 上執行（任何引擎）」	`matrix_modules_disabled: [orin_nano_8]`
「對於這個模型，vLLM 僅在 Thor 上執行；llama.cpp 在任何地方都執行」	`vLLM` 條目：`modules_supported: [thor_t5000, thor_t4000]`；在 `llama.cpp` 上省略
「我們對這個進行了基準測試，它在 T4000 上記憶體不足」	在 `benchmarks.json` 中將 `"oom": ["t4000"]` 新增到該量化項（不屬於模型 frontmatter）
「我們對這個進行了基準測試，模型無法在 Orin Nano 上執行」	在 `benchmarks.json` 中將 `"dnr": ["orin_nano_8gb"]` 新增到該量化項
「我們尚未測量此組合」	在 `benchmarks.json` 中將值設定為 `null`。不會繪製任何標記；該條形圖將不存在。

推論資料：serve 矩陣（引擎）

引擎列表由 getSupportedInferenceEngines 在 src/lib/modelFrontmatterAdapter.ts 中建構：

如果 serving.entries 存在且非空 → 則使用這些條目（新工作首選）。
否則使用 supported_inference_engines（legacy 陣列）。

每個引擎行對應到 src/lib/inferenceCommands.ts 中的 SupportedEngineEntry。偏好：

serve_command_orin / serve_command_thor 用於長時間運行的 serve 命令（vLLM、Ollama 等）。
Legacy run_command_orin / run_command_thor 已被棄用，但作為回退仍被接受。

可選欄位：

modules_supported — 請參閱上方區塊控制桿 #3。
run_commands_by_module：每個儲存格的覆蓋映射 { moduleId: command }，用於 Run 矩陣儲存格。
install_command / install_command_orin / install_command_thor：在 serve 命令上方以 # Installation 區塊為前綴。

引擎顯示順序是固定的，由 modelFrontmatterAdapter.ts 中的 sortEnginesForUi 決定：vLLM → SGLang → llama.cpp → Ollama → Edge-LLM → 其他所有（按字母順序）。請不要嘗試從 frontmatter 控制順序。

官方 Jetson 模組 ID

定義於 JETSON_MATRIX_MODULES 在 src/lib/inferenceCommands.ts 中。在 modules_supported / matrix_modules_disabled / one_shot_inference.modules_supported 中使用這些確切的 ID。

模組 ID	矩陣分頁？	平台
`thor_t5000`	是	thor
`thor_t4000`	是	thor
`orin_agx_64`	是	orin
`orin_nx_16`	是	orin
`orin_nano_8`	是	orin
`orin_agx_32`	僅資料（無分頁）	orin
`orin_nx_8`	僅資料（無分頁）	orin
`orin_nano_4`	僅資料（無分頁）	orin

「僅資料」ID（showInMatrixUi: false）是有效的 frontmatter，並通過 platformKey 解析命令，但不會顯示 Serve/Run 矩陣分頁。請不要發明新 ID — 擴展清單需要在 JETSON_MATRIX_MODULES 中進行程式碼更改。

儲存庫中的範例：

serving.entries（新式）：src/content/models/ministral3-8b-reasoning.md
Legacy supported_inference_engines 搭配豐富的每個引擎 modules_supported：src/content/models/nemotron-3-nano-omni.md
hide_run_button: true：src/content/models/cosmos-reason2-8b.md

One-shot 推論

可選的 frontmatter 區塊 one_shot_inference（schema 在 src/content/config.ts 中）。欄位：

run_command_orin、run_command_thor — 每個平台的單命令執行。
shell、python — 非平台特定的程式碼片段。
shell_by_module、python_by_module — 以官方模組 ID 為鍵的每個模組覆蓋映射。
modules_supported — 限制哪些模組分頁出現。
intro — 可選的 Markdown 介紹，顯示在分頁上方。

可見性：ModelOneShotSection.astro 在至少一個上述命令欄位非空時顯示該區段（hasContent 檢查）。

程式碼片段/模組解析邏輯位於 src/lib/evalRunModal.ts（參見 evalSnippetByModule、evalMatrixModuleSpecs）。

呼叫模型（`client_call`）

可選的 frontmatter 區塊 — 覆蓋在 Call the model 中顯示的自動生成 curl 範例。

client_call:
  intro: "Once the server is up:"
  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
    ...

完全省略 client_call 以讓 ModelCallSection.astro 從 hf_checkpoint 和第一個引擎的 serve 命令合成一個範例。

基準測試資料

基準測試數字不存在於模型 frontmatter 中。它們存在於 src/data/benchmarks.json 的 models[] 下。模型頁面通過 frontmatter 欄位 benchmark_key 進行連接，該欄位必須與 models[].name 完全匹配。

新增基準測試資料

在 src/data/benchmarks.json 的 models[] 中新增一個條目：

{
  "family": "系列名稱",
  "name": "確切名稱（這是連接鍵）",
  "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"]
      }
    }
  }
}

在模型 frontmatter 中新增：

benchmark_key: "確切名稱（這是連接鍵）"
benchmark_series:
  - "前代系列名稱"   # 可選 — 疊加比較條

基準測試產品 ID ≠ 矩陣模組 ID（關鍵陷阱）

基準測試軸使用與 Run/Serve 矩陣不同的 ID：

硬體	矩陣模組 ID（frontmatter）	基準測試產品 ID（`benchmarks.json`）
Jetson Thor T5000	`thor_t5000`	`t5000`
Jetson Thor T4000	`thor_t4000`	`t4000`
Jetson AGX Orin 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	無（不是 Jetson）	`dgx_spark`

轉換：matrix_modules_disabled / modules_supported 使用左側的 ID。基準測試中的 oom / dnr 陣列使用右側的 ID。

基準測試渲染規則

定義於 src/lib/benchmarkChart.ts：

針對每個（引擎 × 精度）組合，迭代每個基準測試模組 ID。
如果值為 null → 不繪製條形圖。
如果值在 oom 陣列中 → 條形圖顯示為紅色 OOM 條。
如果值在 dnr 陣列中 → 條形圖顯示為深灰色 DNR 文字。
否則 → 繪製正常效能條形圖。

此邏輯不影響 Run on Jetson UI。它僅驅動基準測試圖表。

精簡範例

包含所有選項的最小模型 frontmatter：

---
title: My Test Model
short_description: 一個極簡的測試模型頁面
precision: FP8 / INT4
family: Test Family
model_id: my-test-model-8b
icon: model.svg
is_new: true
order: 0
type: chat
hf_checkpoint: test-org/my-test-model-8b
huggingface_url: https://huggingface.co/test-org/my-test-model-8b
minimum_jetson: orin
parameters: ~8B
modalities:
  - Text
vision_capable: false
context_length: 128K
license: Apache 2.0
model_size: 12GB
memory_requirements: 16GB RAM
build_nvidia_url: https://build.nvidia.com/test-org/my-test-model
matrix_modules_disabled:
  - orin_nano_8
hide_run_button: false
benchmark_key: My Test Model
benchmark_series:
  - Predecessor Model
serving:
  entries:
    - engine: vLLM
      serve_command_orin: >-
        docker run ...
      serve_command_thor: >-
        docker run ...
      modules_supported:
        - thor_t5000
        - thor_t4000
        - orin_agx_64
        - orin_nx_16
      install_command: pip install vllm
one_shot_inference:
  intro: 快速測試推論
  run_command_orin: >-
    python test.py
  shell: |-
    echo "Hello"
  shell_by_module:
    thor_t5000: |-
      echo "Thor test"
  modules_supported:
    - thor_t5000
    - orin_agx_64
client_call:
  intro: 一旦伺服器啟動：
  shell: |-
    curl ...
  python: |-
    import requests
---

這是 **Model Details** 散文區塊。

包含此 frontmatter 的完整模型頁面：src/content/models/ministral3-8b-reasoning.md。

常見問題（FAQ）

問：我想隱藏 Run on Jetson UI，但保留引擎資料以供文件使用。

答：設定 hide_run_button: true。引擎資料將保留在 frontmatter 中，但 Serve、Call 和 one-shot 區段都不會渲染。範例：cosmos-reason2-8b.md。

問：我想灰顯一個引擎的所有模組。

答：將該引擎條目的 modules_supported 設定為 []。該引擎行的所有矩陣儲存格將顯示為灰色。

問：我想在所有引擎上灰顯一個特定的 Jetson 模組分頁。

答：使用頂層的 matrix_modules_disabled: [orin_nano_8]。所有引擎的該分頁都將不可點擊。

問：一個引擎需要 modules_supported，另一個不需要。

答：在需要限制的引擎上包含 modules_supported。對於支援所有模組的引擎，完全省略 modules_supported。不要將其設定為一個完整的允許清單。

問：我應該將 OOM 標記放在哪裡，frontmatter 還是 benchmarks.json？

答：始終放在 benchmarks.json 的 oom 陣列中。benchmarks.json 中的 oom 和 dnr 陣列是唯一正確的位置。它們不屬於模型 frontmatter。

問：我想新增一個新的 Jetson 模組（例如 thor_t6000）。我需要更改哪些內容？

答：你需要在 JETSON_MATRIX_MODULES（src/lib/inferenceCommands.ts）中新增一個條目。這是一個程式碼更改，而不僅僅是 frontmatter 更改。

問：基準測試產品 ID 看起來與矩陣模組 ID 不同。

答：是的。請參閱上方表格。矩陣模組 ID（thor_t5000、orin_agx_64）用於 frontmatter 中的 modules_supported / matrix_modules_disabled。基準測試 ID（t5000、agx_orin_64gb）用於 benchmarks.json 中的 oom / dnr / 效能值。

問：我可以在哪個元件中找到負責..的渲染邏輯？

Hero / 側邊欄規格：src/pages/models/[slug].astro
Serve 矩陣：ModelServeSection.astro
Call 程式碼片段：ModelCallSection.astro
One-shot 分頁：ModelOneShotSection.astro + src/lib/evalRunModal.ts
基準測試圖表：ModelBenchmarkSection.astro + src/lib/benchmarkChart.ts
Frontmatter schema 驗證：src/content/config.ts (modelsSchema)
引擎列表建構：src/lib/modelFrontmatterAdapter.ts

NVIDIA-AI-IOT/jetson-ai-lab

jetson-ai-lab 是什麼？

在你喜歡的 AI 中提問

說明文件

Jetson AI Lab：模型目錄頁面配置

實際情況

頁面結構（從上到下）

Frontmatter 參考

始終包含的標籤

Model Details 側邊欄標籤（驅動英雄區域右側的深色規格卡片）

情境標籤

推論區塊（除非 `hide_run_button: true`，否則至少需要一個）

Run on Jetson：三個「區塊」控制桿（何時 OOM vs 隱藏 vs 灰顯）

推論資料：serve 矩陣（引擎）

官方 Jetson 模組 ID

One-shot 推論

呼叫模型（`client_call`）

基準測試資料

新增基準測試資料

基準測試產品 ID ≠ 矩陣模組 ID（關鍵陷阱）

基準測試渲染規則

精簡範例

常見問題（FAQ）

相關文件

相關技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

在你喜歡的 AI 中提問

說明文件

Jetson AI Lab：模型目錄頁面配置

實際情況

頁面結構（從上到下）

Frontmatter 參考

始終包含的標籤

Model Details 側邊欄標籤（驅動英雄區域右側的深色規格卡片）

情境標籤

推論區塊（除非 hide_run_button: true，否則至少需要一個）

Run on Jetson：三個「區塊」控制桿（何時 OOM vs 隱藏 vs 灰顯）

推論資料：serve 矩陣（引擎）

官方 Jetson 模組 ID

One-shot 推論

呼叫模型（client_call）

基準測試資料

新增基準測試資料

基準測試產品 ID ≠ 矩陣模組 ID（關鍵陷阱）

基準測試渲染規則

精簡範例

常見問題（FAQ）

相關文件

相關技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

推論區塊（除非 `hide_run_button: true`，否則至少需要一個）

呼叫模型（`client_call`）