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（资源管理器）会将释放的系统内存页保留在自己的内存池中。在 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；请在它之前紧接着运行 sudo sync，以便在回收可回收的页缓存、目录项和 inode 缓存之前刷新脏数据。运行后，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	刷新可回收的页缓存、目录项和 inode 缓存，并打印前后的内存差值。	--mode 1|2|3、--quiet。

如果 Agent 运行时支持 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），并报告清理前后可用内存、available 和 cached 的变化量。如果无法使用 root 权限，请说明必须在主机上使用 sudo 运行。

如果你的 Agent 运行时无法相对于此技能目录执行辅助脚本，请使用 AgentSkills {baseDir} 占位符解析脚本路径：

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

除非运行时明确将技能注册为可调用工具，否则不要将 jetson-memory-audit 当作工具名称调用；Agent Skills 通常是说明和文件，而非直接可调用的工具函数。

Agent 沙盒说明：看到此技能文件并不意味着可以访问 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. 对于低于 7.2 版 JetPack／低于 r39.0 版 L4T 的系统，或者在较新版本上也观察到相同的内存滞留症状时，请在主机（而非容器内）刷新可回收的页缓存，使释放的页面显示为 free，而不是 cached：

   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 的主要消耗者时。
• 如果运行时更改无法达到目标，应说明进一步回收不在此技能的范围内，而不要建议不安全的启动时修改。