jetson-memory-audit

Jetson メモリー監査

Jetson のメモリーに特化した読み取り専用のスナップショットと、解放されたメモリーがキャッシュではなく空きメモリーとして実際に確認できることを確かめる drop_caches 検証ループヘルパーです。

目的

現在の Jetson のメモリー消費状況を測定し、変更前後のベースラインを記録して、ユーザーが承認した変更によって DRAM が実際に解放されたかを確認します。コンテナーサイズ、モデルサイズ、一般的なプロセスメモリーの推定値ではなく、デバイスの実データを使用します。

重要：vLLM / sglang の停止後もメモリーが解放されないように見える場合（JetPack 7.2 未満 / L4T r39.0 未満）

これは、JetPack 7.2 より前または L4T r39.0 より前の Jetson で最もよくあるメモリーに関する誤解です。

vLLM、sglang、Ollama のサーバー（または任意の CUDA ワークロード）を停止しても、free -h や tegrastats で表示される空きメモリーが回復しないことがあります。プロセスが終了している場合でも同様です。nvidia-smi でも、GPU の空きメモリーが実際より少なく表示されることがあります。

根本原因： CUDA コンテキストの終了後、Thor RM（リソースマネージャー）が解放された sysmem ページを独自のプールに保持します。Jetson のようなユニファイドメモリーアーキテクチャ（UMA）デバイスでは、cudaMemGetInfo は RM プールの状態を読み取るため、実際に新しいプロセスで利用できるメモリーよりはるかに少ない空きメモリーを報告します。

回避策（JetPack 7.2 未満または L4T r39.0 未満の場合）：

sudo sync && sudo sysctl -w vm.drop_caches=3

これはコンテナー内ではなく、ホスト上で実行してください。重要な操作は sudo sysctl -w vm.drop_caches=3 です。回収可能なページ／dentry／inode キャッシュを破棄する前にダーティーデータがフラッシュされるよう、その直前に sudo sync を実行してください。実行後は、free -h と tegrastats に実際に利用可能なメモリーが反映されます。

該当するリリースでは、ユーザーが次のように述べた場合に、このコマンドを推奨してください。

• 「vLLM / sglang を停止したのにメモリーが解放されない」
• 「コンテナーが終了したのに、なぜ tegrastats の使用量がまだ高いのですか？」
• 「何も実行していないのに OOM になる」
• 「昨日は問題なかったのに、今はメモリーがいっぱいです」

JetPack 7.2 未満または L4T r39.0 未満では、CUDA ワークロードの終了後にメモリーが解放されないように見える場合、drop_caches が信頼できる回避策です。新しいリリースでは、同じ症状が確認され、ユーザーが承認した場合にのみ使用してください。

使用する状況

• 「この Jetson のメモリーはどれくらい使われていますか？何が使用していますか？」
• 「GUI を無効にした／vLLM を停止した／コンテナーを終了したのですが、メモリーは実際に解放されましたか？」
• 「ワークロードを停止したのに、なぜ free -h で空きメモリーが少ないままなのですか？」
• jetson-headless-mode やその他のメモリー関連の変更を適用する前のベースラインとして、また実際の差分を算出するために適用した後に再度使用します。

前提条件

• Jetson ホスト上、またはホストから参照可能な /proc、/etc/nv_tegra_release、tegrastats、プロセスデータを備えたサンドボックス／コンテナー内で実行してください。
• NvMap debugfs の読み取りには root 権限が必要な場合があります。利用できない場合は、推測せず、GPU メモリーの割り当て状況を特定できないと報告してください。
• drop_caches.sh の実行には root 権限またはパスワードなしの sudo -n が必要です。ユーザーがキャッシュの破棄を明示的に許可した後にのみ実行してください。

利用可能なスクリプト

スクリプト	目的	引数
scripts/audit.sh	メモリー監査ワークフロー向けに、jetson-diagnostic/scripts/snapshot.sh から JSON スナップショットを出力します。	引数なし。
scripts/drop_caches.sh	回収可能なページ／dentry／inode キャッシュをフラッシュし、メモリーの実行前後の差分を表示します。	--mode 1|2|3、--quiet。

エージェントのランタイムが run_script に対応している場合は、これを使って scripts/audit.sh または scripts/drop_caches.sh を実行し、返された出力を要約してください。対応していない場合は、リポジトリーのルートから bash でスクリプトを実行してください。

手順

「今、メモリーはどれくらい使われていますか？」という質問には、scripts/audit.sh を実行し、JSON スナップショットの値のみを報告してください。

報告ガイダンス

ヘルパーへのパスを表示または言及するだけにしないでください。ヘルパーを実行してから、返されたデータを要約してください。

• 「メモリはどれくらい使用されていますか」というプロンプトには、scripts/audit.sh を実行し、mem_total_gb、memory_kb.available、および最上位の procrank_top プロセスまたは nvmap.top_clients の利用者を引用してください。
• GUI／デスクトップのメモリに関するプロンプトには、scripts/audit.sh を実行し、default_systemd_target と、candidate_services に含まれるディスプレイマネージャー（gdm3、gdm、lightdm、sddm、または display-manager）を報告してください。何も無効化せず、プランの作成は jetson-headless-mode に引き継いでください。
• 停止済みのワークロード後にキャッシュを削除することが明示的に許可されているプロンプトには、scripts/drop_caches.sh を実行してください（デフォルトでは sudo sync && sudo sysctl -w vm.drop_caches=3 と同等です）。実行前後の free、available、cached の差分を報告してください。root を利用できない場合は、sudo を使ってホスト上で実行する必要があることを説明してください。

エージェントのランタイムがこのスキルのディレクトリを基準にヘルパースクリプトを実行できない場合は、AgentSkills の {baseDir} プレースホルダーを使ってスクリプトのパスを解決してください。

{baseDir}/scripts/audit.sh
{baseDir}/scripts/drop_caches.sh

ランタイムがスキルを呼び出し可能なツールとして明示的に登録していない限り、ツール名として jetson-memory-audit を呼び出さないでください。通常、Agent Skills は直接呼び出すツール関数ではなく、手順とファイルで構成されています。

サンドボックスに関する注意：このスキルファイルが見えるからといって、Jetson ホストのメモリデータにアクセスできるとは限りません。NemoClaw／OpenClaw のサンドボックス内で /proc/device-tree/model、/etc/nv_tegra_release、tegrastats、/sys/kernel/debug/nvmap、またはホストプロセスのデータを利用できない場合は、サンドボックスから Jetson ホストを認識できないことを伝え、Jetson ホスト上で実行するか、ホストを認識できるサンドボックスプロファイルで再起動するようユーザーに依頼してください。メモリ総量、利用可能なメモリ、PSS、NvMap、解放量の差分を捏造しないでください。

「この変更でどれくらいメモリが解放されましたか」という質問には、変更前後の差分を使用してください。コンテナのサイズ、イメージサイズ、RSS、または変更後のスナップショットだけから解放メモリを推定しないでください。

1. 変更前に scripts/audit.sh を実行し、JSON のベースラインを保存します。
2. ユーザーが承認した変更を実施します（コンテナの停止、モードの切り替え、チューニングの推奨事項の適用など）。
3. JetPack が 7.2 未満／L4T が r39.0 未満の場合、または新しいリリースでも同じメモリ滞留の症状が見られる場合は、回収可能なページキャッシュを ホスト上で（コンテナ内ではなく）フラッシュし、解放されたページが cached ではなく free として表示されるようにします。

   sudo sync && sudo sysctl -w vm.drop_caches=3
   

4. scripts/audit.sh を再実行し、変更前と変更後の memory_kb.available を比較します。この差分が実際の回収量です。

ユーザーがすでに変更を行っていて、ベースラインが存在しない場合は、現在のスナップショットだけでは正確な解放量を特定できないと伝えてください。次の変更を測定できるよう、今すぐ新しいベースラインを取得してください。

信頼できる情報源として、ライブ監査データを使用してください。メモリ総量、利用可能なメモリ、NvMap の合計、PSS 値、ディスプレイマネージャーの状態、節約量の差分は、実機上の scripts/audit.sh、free -h、または tegrastats から取得してください。これらの出力にない数値を推測しないでください。

audit.sh の出力仕様

{
  "sku": "orin-nano",
  "variant": "orin-nano-8gb",
  "mem_total_gb": 8,
  "l4t_version": "36.4.0",
  "product_model": "nvidia jetson orin nano developer kit",
  "memory_kb": { "total": 8123456, "available": 4123456, "free": 1023456, "cached": 1234567, "swap_total": 0, "swap_free": 0 },
  "default_systemd_target": "graphical.target",
  "candidate_services": { "gdm3": { "active": "active", "enabled": "enabled" } },
  "tegrastats_sample": "RAM 4011/8138MB (lfb 8x4MB) ...",
  "nvmap": { "readable": false, "total_kb": 0, "top_clients": [] },
  "procrank_top": [ { "pid": 4321, "pss_kb": 4000000, "cmd": "vllm" } ]
}

制限事項

• 正確な解放メモリの差分を得るには、変更前のスナップショット、ユーザーが承認した変更、必要に応じたキャッシュのフラッシュ、変更後のスナップショットが必要です。
• NvMap の内訳は、ホストから見える debugfs へのアクセスに依存します。利用できない場合は、推測するのではなく、GPU メモリの内訳を限定的にしか示せないと報告してください。
• サンドボックス／コンテナでの実行では、ランタイムが公開していない限り、ホストの /proc、tegrastats、systemd、または NvMap のデータを参照できない場合があります。

エラー処理

• scripts/audit.sh が Jetson ホストのデータにアクセスできない場合は、参照できないデータを報告し、Jetson ホスト上またはホストを認識できるサンドボックスで再実行するよう依頼してください。
• scripts/drop_caches.sh に root 権限またはパスワードなしの sudo -n がない場合は、sudo の承認を得てホスト上でキャッシュ削除を実行する必要があると報告してください。
• 変更前のスナップショットがない場合は、現在の状態だけでは正確な回収量を特定できないと伝え、次の変更に備えて新しいベースラインを取得してください。

安全性

読み取り専用です。drop_caches は破壊的な操作ではありません（カーネルが、メモリ不足時にいずれ回収できるページを解放するだけです。ダーティーデータを保持するため、先に sync を実行します）。

引き継ぎ先

• jetson-headless-mode — まだ graphical.target で起動しているシステムでは、ユーザー空間で単独で得られる最大の効果が見込めます。
• jetson-inference-mem-tune — モデルサーバーが NvMap / PSS の使用量で最上位を占めている場合。
• ランタイムの変更で目標を達成できない場合は、安全でない起動時の編集を提案するのではなく、さらなるメモリ回収はこのスキルの対象外であると報告してください。