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 前置元数据驱动（英雄区域、模型详情侧边栏、在 Jetson 上运行标签、调用片段、一次性标签、基准测试图表）。正文 Markdown 仅填充底部的 模型详情 散文部分。

不要为“Jetson AI Lab 推理 API”发明基础 URL — 因为不存在。

页面结构（从上到下）

部分	驱动方式	组件/文件
英雄区域（标题、徽章、“在 Jetson 上运行的命令”/“基准测试”/“模型详情”标签）	`title`、`is_new`、`type`、`short_description`、引擎和 `benchmark_key` 的存在	`src/pages/models/[slug].astro`
规格侧边栏（参数、模态、上下文长度、许可证、精度标签）	`parameters`（或 `model_size`）、`modalities`（或 `vision_capable`）、`context_length`、`license`、`precision`（按令牌）	`src/pages/models/[slug].astro` L137–193
在 Jetson 上运行 → 服务矩阵	`serving.entries`（首选）或 `supported_inference_engines`，加上 `matrix_modules_disabled`	`ModelServeSection.astro`
调用模型	`client_call.{shell,python,intro}`（或从引擎 + `hf_checkpoint` 自动构建）	`ModelCallSection.astro`
一次性推理（按模块标签）	`one_shot_inference.*`	`ModelOneShotSection.astro` + `src/lib/evalRunModal.ts`
基准测试图表	`benchmark_key`（+ 可选 `benchmark_series`）→ 联接 `src/data/benchmarks.json`	`ModelBenchmarkSection.astro`
模型详情散文 + 外部链接（“在 build.nvidia.com 上尝试”、“在 HuggingFace 上查看”）	正文 Markdown + `build_nvidia_url`、`huggingface_url`（或 `hf_checkpoint`）	`src/pages/models/[slug].astro` L242–289

前置元数据参考

每个模型页面都由其 YAML 前置元数据驱动。验证逻辑位于 src/content/config.ts（modelsSchema）。

始终包含的标签

要么是 schema 必需的（缺少则构建失败），要么是仓库中每个模型都使用的。添加新模型时全部包含。

标签	Schema	作用
`title`	必需	模型页面和目录卡片上的显示名称。
`short_description`	必需	目录网格和英雄副标题中的一行摘要。
`precision`	必需	斜杠或逗号分隔的量化令牌（例如 `"NVFP4 / FP8 / Q4_K_M GGUF"`）。每个令牌在侧边栏中渲染为彩色标签（`[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}`。

模型详情侧边栏标签（驱动英雄右侧的深色规格卡片）

跳过这些会导致侧边栏中的行消失（没有错误，只是不够完善）。

标签	侧边栏行	笔记
`parameters`（或回退到 `model_size`）	“参数”	自由文本，例如 `"~9B"` 或 `"30B 总计 / 3B 激活"`。
`modalities: [...]`	“模态”	`"Text"
`vision_capable`（布尔值）	（模态的回退）	即使存在 `modalities` 也显式设置 — 在其他地方用于目录过滤器。
`context_length`	“上下文长度”	自由文本，例如 `"128K"`、`"262K"`。
`license`	“许可证”	自由文本，例如 `"Apache 2.0"`、`"NVIDIA Open Model License"`。
`model_size`	（参数的回退）	例如 `"12GB"`。
`memory_requirements`	不在侧边栏中显示，但被其他 UI 使用	例如 `"16GB RAM"`。

情境标签

仅在模型需要时添加。

标签	何时使用	仓库用法
`build_nvidia_url`	模型有 NVIDIA Build 页面 → 添加在 build.nvidia.com 上尝试按钮。	~67% 的模型
`matrix_modules_disabled`	对于此模型的每个引擎，某些矩阵模块标签应灰显/不可点击。	~10% 的模型
`hide_run_button`	隐藏整个在 Jetson 上运行 UI（服务 + 调用 + 一次性），即使存在引擎数据。	~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`	旧式引擎数组。仍然有效，并且是今天最常见的形式。
`one_shot_inference`	一次性运行命令（shell/python/按模块变体）。在“调用”下方渲染一个单独的一次性推理标签部分。
`client_call.{shell,python,intro}`	调用模型片段的可选覆盖。如果省略，页面从引擎命令和 `hf_checkpoint` 自动构建一个 curl 示例。

在 Jetson 上运行：三个“模块”杠杆（何时 OOM vs 隐藏 vs 灰显）

这些是分层的。服务矩阵按以下顺序评估它们：

hide_run_button: true（前置元数据，顶层）
- 隐藏整个在 Jetson 上运行部分（服务 + 调用 + 一次性）。
- 当模型存在于目录中但尚未可从网站启动（例如需要 NGC 下载、门控检查点、等待验证）时使用。
- 示例：src/content/models/cosmos-reason2-8b.md — 保留引擎数据以供文档使用，但运行 UI 保持隐藏。
matrix_modules_disabled: [moduleId, ...]（前置元数据，顶层）
- 灰显列出的模块标签跨此模型的所有引擎。标签显示但不可点击。
- 当 Jetson 模块理论上可能但尚未为此模型验证时使用。
engines[].modules_supported: [moduleId, ...]（按引擎，在 serving.entries[] 或 supported_inference_engines[] 内部）
- 允许列表：仅列出的模块 ID 对于该引擎启用。列表外的单元格在该引擎行上显示灰显。
- 完全省略该字段 → 引擎支持所有矩阵模块。空数组意味着引擎不支持任何内容（很少见）。
- 当模型在所有地方运行，但特定引擎仅适用于子集（例如 vLLM Thor 仅、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"]`（不属于模型前置元数据）
“我们对此进行了基准测试，模型根本无法在 Orin Nano 上运行”	在 `benchmarks.json` 中对该量化添加 `"dnr": ["orin_nano_8gb"]`
“我们尚未测量此组合”	在 `benchmarks.json` 中将值设置为 `null`。不绘制标记；条仅缺失。

推理数据：服务矩阵（引擎）

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

如果 serving.entries 存在且非空 → 使用这些条目（新工作首选）。
否则使用 supported_inference_engines（旧式数组）。

每个引擎行映射到 src/lib/inferenceCommands.ts 中的 SupportedEngineEntry。首选：

serve_command_orin / serve_command_thor 用于长期运行的服务命令（vLLM、Ollama 等）。
旧式 run_command_orin / run_command_thor 已弃用，但仍作为回退被接受。

可选字段：

modules_supported — 参见上面的模块杠杆 #3。
run_commands_by_module：运行矩阵单元格的按单元覆盖映射 { moduleId: command }。
install_command / install_command_orin / install_command_thor：作为服务命令上方的 # Installation 块前缀。

引擎显示顺序固定，由 modelFrontmatterAdapter.ts 中的 sortEnginesForUi 决定：vLLM → SGLang → llama.cpp → Ollama → Edge-LLM → 其他所有（字母顺序）。不要尝试从前置元数据控制顺序。

规范 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）是有效的前置元数据，通过 platformKey 解析命令，但不显示服务/运行矩阵标签。不要发明新的 ID — 扩展列表需要对 JETSON_MATRIX_MODULES 进行代码更改。

仓库中的示例：

serving.entries（新样式）：src/content/models/ministral3-8b-reasoning.md
旧式 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_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`）

可选前置元数据块 — 覆盖在 调用模型 中显示的自动生成的 curl 示例。

client_call:
  intro: "一旦服务器启动："
  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 和第一个引擎的服务命令合成示例。

基准测试数据

基准测试数字不存在于模型前置元数据中。它们存在于 src/data/benchmarks.json 中的 models[] 下。模型页面通过前置元数据字段 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"]
      }
    }
  }
}

在模型前置元数据中添加：

benchmark_key: "确切名称（这是联接键）"
benchmark_series:
  - "前代系列名称"   # 可选 — 叠加比较条

基准测试产品 ID ≠ 矩阵模块 ID（关键陷阱）

基准测试轴使用与运行/服务矩阵不同的 ID：

硬件	矩阵模块 ID（前置元数据）	基准测试产品 ID（`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`
Jetson Orin AGX 32GB	`orin_agx_32`	不在基准测试矩阵中
Jetson Orin NX 8GB	`orin_nx_8`	不在基准测试矩阵中
Jetson Orin Nano 4GB	`orin_nano_4`	不在基准测试矩阵中

在 benchmarks.json 的 oom / dnr 数组中使用基准测试产品 ID，而不是矩阵模块 ID。

OOM vs DNR vs null 语义

每个基准测试产品 ID 的每个吞吐量值可以是：

值	含义	UI 效果
`null`	尚未测量	没有条绘制 — 该单元格留空
一个数字	测量吞吐量（tokens/秒）	绘制该条
（数组中的字符串）	`"oom"` → 所有并发均 OOM；`"dnr"` → 硬件明确不支持	红色/灰色标签显示在图表中

对于 null：不要试图暗示任何东西。无条 = 未测量，与有标签的 OOM/DNR 不同。

文件位置

src/content/models/ — 模型页面 Markdown（前置元数据 + 正文）
src/content/config.ts — 前置元数据 schema 验证（modelsSchema）
src/data/benchmarks.json — 基准测试性能数据
src/lib/modelFrontmatterAdapter.ts — getSupportedInferenceEngines、sortEnginesForUi、getModelEval
src/lib/inferenceCommands.ts — JETSON_MATRIX_MODULES、原型组件
src/lib/evalRunModal.ts — evalSnippetByModule、evalMatrixModuleSpecs
src/pages/models/[slug].astro — 模型页面布局
src/components/ModelBenchmarkSection.astro — 基准测试图表
src/components/ModelCallSection.astro — 调用片段
src/components/ModelOneShotSection.astro — 一次性推理
src/components/ModelServeSection.astro — 服务矩阵

Jetson AI Lab：模型目录页面配置