jetson-inference-mem-tune

Jetson 推論メモリの調整

Jetson の SKU／バリアントとユーザーのワークロードに基づいて、推論ランタイムと渡すべき具体的なメモリ関連フラグを推奨します。量子化レシピの選定は含みません（その選定はモデルベンチマークのスキルで扱います）が、各ランタイムが効率よく処理できる精度の下限は示します。

目的

最新の jetson-memory-audit スナップショットを、Jetson での LLM／VLM サービング向けのランタイムおよび起動フラグの推奨に変換します。モデルを動作させたい場合、OOM のリスクを下げたい場合、またはよりメモリ使用量の少ないサービングスタックに切り替えたい場合に使用してください。

使用する場面

• 「Orin Nano 8 GB で 7B モデルを実行するには、どのサービングスタックを使えばよいですか？」
• 「vLLM で OOM が発生しています。--gpu-memory-utilization と --max-model-len はいくつにすべきですか？」
• 「同じモデルをもっと少ないメモリで使いたいのですが、vLLM から llama.cpp に切り替えられますか？」
• jetson-memory-audit でモデルサーバーが NvMap／PSS の最大消費元として示された後。

前提条件

• 対象の Jetson で取得した、最新の jetson-memory-audit/scripts/audit.sh JSON スナップショットから始めます。
• 想定するワークロードを把握しておきます。llm-server、vlm-server、embedding、rag のいずれかです。
• ユーザーが空きメモリの目標値を指定した場合は --target-mb で渡します。指定がない場合は、スクリプトで SKU のデフォルト値を使用します。

使用可能なスクリプト

スクリプト	目的	引数
scripts/recommend.py	監査 JSON を読み込み、ランタイムと起動フラグの推奨を出力します。	--audit PATH、--runtime、--workload、--target-mb、--human。

エージェントのランタイムが run_script に対応している場合は、run_script("scripts/recommend.py", ["--audit", "/tmp/audit.json", "--runtime", "auto", "--workload", "llm-server"]) を実行し、返された JSON を要約します。対応していない場合は、リポジトリのルートから python3 で実行します。

手順

1. jetson-memory-audit/scripts/audit.sh を実行して、デバイスのベースラインを取得します。
2. scripts/recommend.py --audit /tmp/audit.json --runtime auto --workload llm-server --target-mb 6000 を実行し、ランタイムとフラグの推奨を含む JSON を取得します。
3. エージェントは推奨ランタイムと具体的な CLI フラグを提示します。ユーザー（または上位のエージェント）がそれらのフラグを使ってサーバーを起動／再起動します。
4. 監査を再実行して確認します。

想定されるワークフロー

該当するプロンプトに対する具体的な回答には、scripts/recommend.py を使用し、出力された JSON に基づいて回答してください。直接実行できない場合は、python3 {baseDir}/scripts/recommend.py ... を実行します。

• vLLM の OOM に関するプロンプトでは、--runtime vllm --workload llm-server を指定して実行し、launch_flags の具体的な --gpu-memory-utilization=<0.x> と --max-model-len=<number> の値を含めます。
• 「最小メモリ」または Orin Nano 8 GB に関するプロンプトでは、--runtime auto --workload llm-server を指定して実行します。JSON のランタイムを優先し、llama-cpp が選択された場合は GGUF／4-bit のトレードオフを明示します。
• SGLang に関するプロンプトでは、--runtime sglang を指定して実行し、--mem-fraction-static、--max-running-requests、およびコンテキスト／KV キャッシュに関する注意点を引用します。
• 「vLLM から llama.cpp に切り替える」プロンプトでは、--runtime llama-cpp を指定して実行し、-ngl、-c、--no-mmap を引用します。

制限事項

• 推奨の鮮度は監査 JSON の鮮度に依存します。サービスの停止後、電力モードの変更後、またはモデルサーバーの再起動後に jetson-memory-audit を再実行してください。
• スクリプトは SKU のデフォルト値と監査の合計値からメモリ負荷を推定します。モデル固有の KV キャッシュ、量子化、トークナイザーの挙動については、引き続きベンチマークが必要になる場合があります。
• このスキルが出力するのはフラグのみです。モデルサーバーの起動、停止、再起動は行いません。

エラー処理

• 終了コード 2：監査 JSON を読み取れない、解析できない、または有効な数値のメモリフィールドが含まれていません。ユーザーに jetson-memory-audit/scripts/audit.sh の再実行を依頼してください。
• 終了コード 3：サポートされていないランタイムまたはワークロードが指定されています。scripts/recommend.py --help に記載された --runtime と --workload の値のいずれかを指定して再実行してください。
• launch_flags が空、または存在しない場合：代替フラグを捏造しないでください。スクリプトの失敗を報告し、新しい監査結果を取得するか、サポート対象のランタイムを指定するよう依頼してください。

recommend.py の出力仕様

{
  "sku": "orin-nx",
  "variant": "orin-nx-16gb",
  "mem_total_gb": 16,
  "runtime": "vllm",
  "rationale": "Highest throughput at this memory budget given continuous batching + paged attention.",
  "launch_flags": [
    "--gpu-memory-utilization=0.55",
    "--max-model-len=4096",
    "--max-num-seqs=8",
    "--enable-prefix-caching"
  ],
  "alternatives": [
    { "runtime": "llama-cpp", "rationale": "Lower memory floor with GGUF Q4_K_M.", "launch_flags": ["-ngl 28", "-c 4096", "--no-mmap"] }
  ],
  "notes": ["Lower --gpu-memory-utilization further if you also run a small VLM alongside."]
}

対応ランタイム

ランタイム	最適な用途	主なメモリ調整項目	推奨インストール方法
llama.cpp	予算を最小限に抑えたい場合。GGUF。Orin Nano クラス	-ngl、-c、--mlock、--no-mmap	ghcr.io/nvidia-ai-iot/llama_cpp:latest-jetson-{orin,thor}
vLLM	継続的バッチ処理による高スループットのサービング	--gpu-memory-utilization、--max-model-len、--max-num-seqs、--enable-prefix-caching	Thor および Orin JetPack 7.2 / L4T r39 以降：アップストリーム vLLM 0.20 以降（vllm/vllm-openai）のコンテナ、または検証済みのネイティブ vLLM 0.20 以降。旧バージョンの Orin：NVIDIA-AI-IOT イメージ
SGLang	プログラム可能なワークフロー（RAG、ツールの使用、構造化出力）	--mem-fraction-static、--mem-fraction-dynamic、--max-running-requests	Thor：NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3、SGLang 0.5.5.post2）。Orin：JetPack に対応した環境
TensorRT Edge-LLM	NVIDIA 向けに最適化された本番環境でのサービング	SKU ごとのビルドプロファイル。ページド KV。KV の再利用	対象の JetPack 向けベンダードキュメント

Orin JetPack 7.2 / L4T r39 以降では、アップストリーム vLLM 0.20 以降がサポートされています。旧バージョンの Orin では、JetPack に対応する CUDA/cuDNN/TensorRT スタックが同梱されているため、利用可能な場合は NVIDIA-AI-IOT のビルド済み vLLM イメージを優先してください。Thor では、アップストリーム vLLM 0.20 以降（vllm/vllm-openai）または検証済みのネイティブ vLLM 0.20 以降のインストールを優先してください。SGLang には、NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3、SGLang 0.5.5.post2）、または Jetson Thor のサポートを明記した新しい NVIDIA SGLang リリースノートを使用してください。Thor に Orin 固有の Jetson コンテナの手順を無理に適用しないでください。また、Orin でネイティブのアップストリーム SGLang がサポートされていると想定しないでください。

量子化に関する推奨事項

ランタイム固有の量子化名を使用してください。vLLM と SGLang では通常、W4A16、AWQ、GPTQ、FP16、NVFP4 などの Hugging Face チェックポイントを使用します。llama.cpp と Ollama では GGUF モデルを使用するため、代わりに INT4/Q4_K_M スタイルの GGUF を推奨してください。

ランタイムファミリー	Jetson ファミリー	第一候補	代替候補
vLLM / SGLang	Thor	モデル／ランタイムが対応している場合は NVFP4	W4A16
vLLM / SGLang	Orin Nano / NX	W4A16	AWQ または GPTQ 4-bit
vLLM / SGLang	AGX Orin	W4A16	AWQ または GPTQ 4-bit
llama.cpp / Ollama	Orin および Thor	GGUF INT4 / Q4_K_M	メモリが不足する場合は、より小さい INT4 GGUF モデル

GGUF Q4_K_M を W4A16/AWQ/GPTQ として説明しないでください。出力に quant フィールドが含まれていない限り、Thor の NVFP4 の結果と Orin の W4A16 の結果を比較しないでください。

ランタイムコマンドのガイダンス

メモリ関連の設定値については recommend.py を信頼できる情報源とし、その launch_flags を対応するサービングコマンドに追加してください。エージェントが一連の指示をまとめて取り込めるよう、コマンドのガイダンスは個別の小さなリファレンスファイルに分けず、このスキル内に記載してください。

JetPack 7.2／L4T r39 以降の Orin で vLLM を使う場合は、上流の vLLM 0.20 以降（vllm/vllm-openai:latest）を使用してください。古い Orin リリースでは、NVIDIA-AI-IOT イメージを使用してください。

docker run --rm -it --runtime nvidia --network host --name vllm \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN="$HF_TOKEN" \
  ghcr.io/nvidia-ai-iot/vllm:latest-jetson-orin \
  vllm serve <hf-model-id-or-local-path> \
    --host 0.0.0.0 \
    --port 8000 \
    --gpu-memory-utilization 0.60 \
    --max-model-len 4096 \
    --max-num-seqs 8 \
    --enable-prefix-caching

Thor で vLLM を使う場合は、ホストネイティブの vLLM 0.20 以降がすでにインストールされ、検証済みでない限り、上流の vLLM 0.20 以降（vllm/vllm-openai:latest）を使用してください。

docker run --rm -it --runtime nvidia --network host --ipc host --name vllm \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN="$HF_TOKEN" \
  vllm/vllm-openai:latest \
  vllm serve <hf-model-id-or-local-path> \
    --host 0.0.0.0 \
    --port 8000 \
    --gpu-memory-utilization 0.75 \
    --max-model-len 8192 \
    --max-num-seqs 32 \
    --enable-prefix-caching

Thor の vLLM に関する注意：vLLM 0.20 より前の結果で Thor のサポートを判断しないでください。上流の vLLM がサポートを開始したのは vLLM 0.20 以降です。

Thor で SGLang を使う場合は、NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3）を使用してください。NVIDIA SGLang 26.01 には SGLang 0.5.5.post2 が含まれており、Jetson Thor のサポートが明示されています。古いプレリリースの SGLang の結果で Thor のサポートを判断しないでください。これらの既知の問題が修正されたと新しい NVIDIA SGLang のリリースノートに記載されていない限り、Thor では gpt-oss や FP8 の経路を推奨しないでください。

docker run --rm -it --runtime nvidia --network host --ipc host --name sglang \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN="$HF_TOKEN" \
  nvcr.io/nvidia/sglang:26.01-py3 \
  python3 -m sglang.launch_server \
    --model-path <hf-model-id-or-local-path> \
    --host 0.0.0.0 \
    --port 8000 \
    --mem-fraction-static 0.60 \
    --max-running-requests 8

llama.cpp では、利用可能な場合は NVIDIA-AI-IOT llama.cpp イメージを、そうでない場合は JetPack に対応したビルドの llama-server バイナリを使用してください。Orin と Thor のどちらでも、まずは GGUF INT4／Q4_K_M から始めてください。監査の結果、メモリに余裕がない場合は、より小さい INT4 GGUF モデルを選んでください。

docker run --rm -it --runtime nvidia --network host --name llama-cpp \
  -v "$PWD/models:/models:ro" \
  ghcr.io/nvidia-ai-iot/llama_cpp:latest-jetson-<orin-or-thor> \
  llama-server \
    -m /models/<model>.gguf \
    --host 0.0.0.0 \
    --port 8000 \
    -ngl 28 \
    -c 4096 \
    --no-mmap \
    --flash-attn

手順（スクリプトにこの手順が実装されています）

1. ユーザーが必要とする機能（連続バッチ処理、構造化生成、CPU オフロードなど）を満たす、最も軽量なランタイムを選びます。
2. ユーザーの精度基準を満たす、最も低い精度を選びます（model-benchmarking スキル）。
3. ランタイムのメモリ設定値（vLLM ではまず gpu-memory-utilization、llama.cpp では n-gpu-layers と ctx-size）を段階的に調整し、目標スループットを維持できる最小のフットプリントを見つけます。
4. jetson-memory-audit で再測定します。

安全性

読み取り専用です。このスキルがモデルサーバーを起動、停止、再起動することはありません。フラグを出力します。ランタイムを実行するのは、ユーザー（または外部のオーケストレーションエージェント）の責任です。