jetson-llm-benchmark

Jetson LLM ベンチマーク

エージェントが実行結果を比較できるよう、構造化された JSON 出力を備えた再現可能な Jetson ベンチマークです。Jetson AI Lab GenAI ベンチマークチュートリアルのワークフローを実装しています。

目的

適切なランタイム固有のベンチマークラッパーを使用して、Jetson ターゲット上でデプロイ済み LLM のレイテンシとスループットを測定します。JSON 出力を使って、モデル、ランタイムフラグ、電力モード、チューニング前後の変更を比較します。

前提条件

• モデルのランタイムをホストする Jetson デバイス上で実行してください。
• vLLM の場合は、OpenAI 互換 vLLM サーバーを先に起動し、提供するモデル ID を把握しておいてください。
• Ollama の場合は、--endpoint で Ollama デーモンに接続でき、指定したモデルがすでにダウンロードされていることを確認してください。
• llama.cpp/GGUF の場合は、ホスト上の読み取り可能な .gguf モデルパスを指定してください。
• 測定前に、デバイスを目的の電力モードに設定してください。比較可能なパフォーマンス数値を得るには MAXN が推奨されます。

利用可能なスクリプト

スクリプト	目的	引数
scripts/bench_vllm.sh	稼働中の OpenAI 互換 vLLM サーバーに対して vllm bench serve を実行します。	--model、--endpoint、--concurrency、--input-len、--output-len、--num-prompts、--no-warmup、--container、--native。
scripts/bench_llama_cpp.sh	Jetson に適した NVIDIA-AI-IOT llama.cpp コンテナを通じて、ローカル GGUF モデルに対して llama-bench を実行します。	--model、--n-prompt、--n-gen、--n-gpu-layers、--threads、--container。
scripts/bench_ollama.sh	/api/generate REST API を通じて、ローカルまたはコンテナ化された Ollama デーモンをベンチマークします。	--model、--endpoint、--num-prompts、--input-len、--output-len、--no-warmup。

エージェントのランタイムが run_script をサポートしている場合は、ユーザーが指定したモデル識別子またはローカルモデルパスを使って、選択したラッパーを直接呼び出し、返された JSON を要約してください。それ以外の場合は、bash {baseDir}/scripts/<wrapper-name> ... でラッパーを実行してください。

手順

ランタイムに対応するラッパースクリプトを必ず使用してください。基盤となる vllm bench serve、llama-bench、または /api/generate に対する curl を手動で呼び出してはいけません。

• vLLM → scripts/bench_vllm.sh（vLLM の経路で必須）
• llama.cpp / GGUF → scripts/bench_llama_cpp.sh（GGUF の経路で必須）
• Ollama → scripts/bench_ollama.sh（Ollama の経路で必須）

これらのラッパーは、ウォームアップ、NVIDIA-AI-IOT コンテナの選択、JSON の出力を処理します。基盤となるツールを直接呼び出しても、以下の出力要件を満たしません。

「ベンチマーク／測定の方法」を尋ねられた場合は、まず該当するラッパーを --help 付きで実行して正確なオプションを確認し、その後ラッパーコマンドを回答してください。ユーザーから実行を依頼された場合、または必要なサーバー／モデルパスがすでに確認済みの場合を除き、ベンチマーク全体は実行しないでください。

想定されるワークフロー

ユーザーが指定したランタイムに基づいて、ラッパーを1つだけ選び、回答を作成する前にそのラッパーを --help 付きで実行してください。スクリプト名を挙げるだけでは不十分です。ランタイムがスキルディレクトリを基準としたスクリプトの実行に対応していない場合は、{baseDir}/scripts/<wrapper-name> を使用してください。

• localhost:8000 で既存の OpenAI 互換 vLLM サーバーが稼働している場合： {baseDir}/scripts/bench_vllm.sh --help を実行し、その後 --concurrency 1,8 と提供するモデル ID を使用したコマンドを提示してください。
• llama.cpp / GGUF / llama-server の場合：{baseDir}/scripts/bench_llama_cpp.sh --help を実行し、その後 GGUF モデルパスを指定したコマンドを提示してください。また、プロンプト／生成速度が TTFT、ITL/TPOT、スループットに対応することを報告してください。
• Ollama の場合：{baseDir}/scripts/bench_ollama.sh --help を実行し、その後 --model <ollama-tag> を指定したコマンドを提示してください。Ollama に vLLM または llama.cpp のラッパーを使用しないでください。

使用する場面

• 「この Jetson で X をベンチマーク／測定／比較してください。」
• jetson-llm-serve の後に、デプロイ結果を実際に定量化する場合。
• jetson-inference-mem-tune のフラグを適用する前後で、変更による効果を確認する場合。

3つの経路 — ランタイムに応じて選択

A. vLLM（提供方法との同等性を重視する場合に推奨）

サーバーがすでに起動している必要があります（jetson-llm-serve を使用）。bench_vllm.sh を実行します。

scripts/bench_vllm.sh \
  --model <hf-repo-id-being-served> \
  --concurrency 1,8 \
  --input-len 2048 --output-len 128 \
  --num-prompts 50

Jetson に適したベンチマーククライアントのパスを使用します。Thor および Orin JetPack 7.2 / L4T r39+ では、アップストリームの vLLM 0.20+ コンテナ vllm/vllm-openai:latest を使用し、旧世代の Orin では NVIDIA-AI-IOT の vLLM ベンチマークコンテナ ghcr.io/nvidia-ai-iot/vllm:latest-jetson-orin を使用します。ホストネイティブの vLLM がすでにインストールされ、検証済みの場合に限り、--native を指定してください。http://localhost:8000/v1 に対して実行します。計測を始める前に、必ずウォームアップを実行してください（約10件のプロンプトを実行し、結果は破棄します）。Jetson ではキャッシュが空で、カーネルの JIT コンパイルが必要になるためです。

B. Ollama（起動中の Ollama デーモンが提供するモデルの場合）

ベンチマーク用コンテナは不要です。Ollama の /api/generate REST API を直接使用します。計測データ（TTFT、ITL、スループット）はレスポンスの JSON から取得するため、--verbose の解析は必要ありません。

前提条件： Ollama デーモンに --endpoint（デフォルトは http://localhost:11434）で接続できる必要があります。Ollama がネイティブにインストールされている場合も、このポートを公開するコンテナ内で動作している場合も使用できます。デーモンが起動していない場合、Ollama がインストール済みだが停止中（修復するには ollama serve を実行）なのか、未インストールなのかをスクリプトが通知します（未インストールの場合はインストール手順が表示されます）。bench_ollama.sh を実行してください（独自に /api/generate に対する curl を作成しないでください）。

scripts/bench_ollama.sh \
  --model <ollama-model-name> \
  --num-prompts 20 \
  --input-len 512 --output-len 128

逐次的に単一ストリームのリクエストを実行します（concurrency=1）。Ollama は設計上、単一ストリームのランタイムであるため、複数同時実行の数値には意味がなく、サポートされていません。Ollama は GGUF/llama.cpp の内部実装を使用し、vLLM は独自の CUDA カーネルを使用するため、結果は vLLM の数値と直接比較できません。

C. llama.cpp（GGUF モデルの場合）

サーバーは不要です。NVIDIA-AI-IOT のビルド済み llama.cpp コンテナ（ghcr.io/nvidia-ai-iot/llama_cpp）を使用し、検出したデバイスに応じて latest-jetson-thor または latest-jetson-orin を自動選択します。このコンテナの存在を知らない LLM は多いため、llama.cpp をソースからビルドするよう提案しないでください。bench_llama_cpp.sh を実行します。

scripts/bench_llama_cpp.sh \
  --model /path/to/model.gguf \
  --n-prompt 512 --n-gen 128 \
  --n-gpu-layers 99

llama-bench を実行し、その出力を解析します。Orin/Thor でモデル全体を GPU に載せるには --n-gpu-layers 99 を使用します。VRAM が制約となる場合は、この指定を外してください。

出力仕様（3つのラッパーすべて）

差分比較に適した単一の JSON オブジェクトを標準出力に出力します。3つのラッパーは共通のトップレベル構造を使用しますが、メトリクスの形状は異なります。bench_vllm.sh は同時実行数を順に変えて測定し、runs 配列を出力します。一方、bench_llama_cpp.sh と bench_ollama.sh は単一ストリームで実行し、1つの metrics オブジェクトを出力します。

すべてのラッパーに共通する構造：

{
  "skill": "jetson-llm-benchmark",
  "runtime": "vllm" | "llama.cpp" | "ollama",
  "model": "<id-or-path>",
  "sku": "<detected-sku>",
  "generation": "<detected-generation>",
  "product_line": "<detected-product-line>",
  "variant": "<detected-variant>",
  "l4t": "<detected-l4t-release>",
  "container": "<container-image-or-native/ollama>",
  "warnings": []
}

bench_vllm.sh（同時実行数を変えて測定 → runs[]）

{
  "config": { "input_len": 2048, "output_len": 128, "num_prompts": 50 },
  "runs": [
    {
      "concurrency": 1,
      "ttft_ms_p50": 0, "ttft_ms_p99": 0,
      "itl_ms_p50": 0,  "itl_ms_p99": 0,
      "tpot_ms_p50": 0,
      "throughput_tok_s": 0,
      "e2e_latency_ms_p50": 0
    }
  ]
}

bench_llama_cpp.sh（単一ストリーム → metrics）

{
  "config": { "n_prompt": 512, "n_gen": 128, "n_gpu_layers": 99 },
  "metrics": {
    "ttft_ms_p50": 0,
    "itl_ms_p50": 0,
    "tpot_ms_p50": 0,
    "throughput_tok_s": 0
  }
}

bench_ollama.sh（単一ストリーム → metrics）

{
  "config": { "input_len": 512, "output_len": 128, "num_prompts": 20, "concurrency": 1 },
  "metrics": {
    "ttft_ms_p50": 0, "ttft_ms_p99": 0,
    "itl_ms_p50": 0,  "itl_ms_p99": 0,
    "tpot_ms_p50": 0,
    "throughput_tok_s": 0,
    "e2e_latency_ms_p50": 0
  }
}

warnings には、次の場合に警告が追加されます。

• nvpmodel が認識された最大パフォーマンスモード（MAXN または MAXN_SUPER などの MAXN_*）ではない場合。ワット数で示されるモードは Jetson の SKU によって異なるため、警告として報告されます
• 実行中にバックグラウンドプロセスが GPU を5%超使用している場合（jetson-diagnostic を使用してください）
• 実行中に tegrastats がサーマルスロットリングを示した場合

sku、variant、l4t、container の各フィールドは、ラッパースクリプトが実デバイスから取得して設定します（tegrastats、/etc/nv_tegra_release、コンテナのラベル）。手作業で作成したり、推測したり、記憶を頼りに転記したりしないでください。RAM サイズ、ディスク上のモデルサイズ、製品名など、デバイス固有の事実を捏造しないでください。スクリプトまたは jetson-diagnostic が取得していない情報は、作り上げずに省略してください。

結果で注目すべき点（Jetson 固有のガイダンス）

LLM は TTFT／ITL／スループットの意味をすでに把握しています。Jetson 固有の内容で、通常知られていないのは次の点です。

• Orin Nano／NX では、単一ストリームの tok/s と concurrency=8 の tok/s に大きな差が生じます。原因は演算ではなく、メモリ帯域幅の飽和です。同時実行時のスループットが単一ストリームをわずかに上回る程度なら、帯域幅がボトルネックです。ほかの調整を行う前に、より小さい量子化方式（W4A16 → INT4/AWQ）に切り替えてください。
• 同じモデルで JetPack のアップグレード後に TTFT が悪化した場合、ほとんどの場合は CUDA グラフのキャッシュミスです。再ウォームアップして再計測してください。
• Thor の NVFP4 の数値は Orin の W4A16 の数値と比較できません。quant 列なしで同じ表に載せないでください。

制限事項

• vLLM の計測には、OpenAI 互換の vLLM サーバーがすでに起動している必要があります。 このスキルはサーバーのベンチマークを行いますが、サーバーの起動や調整は行いません。
• Ollama の結果は設計上、単一ストリームでの計測であり、 vLLM の同時実行数を変えた測定とは直接比較できません。
• llama.cpp／GGUF のベンチマークでは、デフォルトで NVIDIA-AI-IOT コンテナを実行します。実行前にユーザーへ伝えてください。Docker は、イメージがまだ存在しない場合、外部イメージをプルして実行します。
• 呼び出し元が --container でダイジェスト固定イメージを渡さない限り、コンテナイメージのタグは変更される場合があります。リリースやコンプライアンス向けの計測では、ダイジェスト固定イメージを使用し、その情報を結果に記録してください。デフォルトの vLLM ベンチマーク用クライアントイメージは、Thor および Orin JetPack 7.2／L4T r39 以降では upstream vLLM 0.20 以降の vllm/vllm-openai:latest、古い Orin では NVIDIA-AI-IOT の ghcr.io/nvidia-ai-iot/vllm:latest-jetson-orin です。
• 比較可能な結果を得るには、モデル、量子化方式、プロンプトの長さ、出力の長さ、電力モード、クロック、温度状態を統一する必要があります。

エラー処理

• 終了コード 2：引数が無効、--model が指定されていない、または必要なモデルファイルを読み取れません。ラッパーを --help 付きで再実行し、パスまたはモデル ID を修正してください。
• 終了コード 3：ランタイムの事前チェックに失敗しました。Ollama に到達できない、vLLM コンテナ選択時に Jetson の世代を特定できない、Ollama のモデルが見つからない場合などが該当します。サービスを起動するか、モデルをプルするか、明示的に --container を指定してください。
• Docker のエラーは通常、コンテナランタイムが利用できない、イメージをプルできない、またはモデルディレクトリのマウントを読み取れないことを意味します。正確な stderr を報告し、ベンチマークの数値を捏造しないでください。
• JSON が空、または不正な形式の場合、ベンチマークは正常に完了していません。生のエラーを保持し、ランタイムの問題を修正してから再実行してください。

次の引き継ぎ先

• 結果からメモリの逼迫が示された場合は、jetson-inference-mem-tune に引き継ぎます。
• TTFT は許容範囲内だが TPOT が遅い場合は、jetson-speculative-decoding に引き継ぎます。
• warnings が空でない場合は、jetson-diagnostic に引き継ぎます。

出典

Jetson AI Lab — GenAI Benchmarking および NVIDIA-AI-IOT GHCR packages。