Auditoría de memoria de Jetson

Instantánea centrada en la memoria de solo lectura para un Jetson, además de la herramienta auxiliar «drop_caches» para el bucle de verificación, que confirma que la memoria liberada aparece realmente como libre en lugar de como almacenada en caché.

Objetivo

Medir los consumidores actuales de memoria de Jetson, capturar valores de referencia previos y posteriores, y verificar si los cambios aprobados por el usuario han liberado realmente DRAM. Utilizar datos en tiempo real del dispositivo en lugar de estimaciones basadas en el tamaño del contenedor, el tamaño del modelo o la memoria genérica del proceso.

CRÍTICO: La memoria parece atascada tras detener vLLM / sglang (JetPack inferior a 7.2 / L4T inferior a r39.0)

Este es el problema de memoria más habitual en las versiones de Jetson anteriores a JetPack 7.2 o a L4T r39.0.

Tras detener un servidor vLLM, sglang u Ollama (o cualquier carga de trabajo CUDA), es posible que la memoria que aparece como libre en free -h o tegrastats no se recupere, aunque el proceso ya haya finalizado. nvidia-smi también puede mostrar un nivel de memoria libre de la GPU engañosamente bajo.

Causa principal: el gestor de recursos (RM) de Thor retiene las páginas de memoria del sistema (sysmem) liberadas en su propio grupo tras la salida de un contexto CUDA. En dispositivos con arquitectura de memoria unificada (UMA), como Jetson, `cudaMemGetInfo` lee el estado del grupo del RM e indica una cantidad de memoria libre muy inferior a la que realmente está disponible para un nuevo proceso.

Solución provisional (para JetPack inferior a la versión 7.2 o L4T inferior a la r39.0):

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

Ejecuta esto en el host, no dentro de un contenedor. La operación importante es sudo sysctl -w vm.drop_caches=3; mantén sudo sync inmediatamente antes de ella para que los datos no validados se vacíen antes de que se eliminen las cachés recuperables de páginas, dentry e inodos. Tras ejecutarlo, los comandos ` free -h ` y ` tegrastats ` mostrarán la memoria disponible real.

Para las versiones afectadas, se recomienda este comando cuando un usuario indique:

• «La memoria no se ha liberado después de detener vLLM/sglang»
• «¿Por qué tegrastats sigue mostrando un uso elevado después de que mi contenedor se haya cerrado?»
• «Aparece un error OOM aunque no haya nada en ejecución»
• «Ayer la memoria funcionaba bien, pero ahora está llena».

En JetPack inferior a la versión 7.2 o L4T inferior a la r39.0, «drop_caches» es la solución alternativa fiable cuando la memoria parece atascada tras salir de una carga de trabajo de CUDA; en versiones más recientes, utilízala solo si se observa el mismo síntoma y el usuario da su consentimiento.

Cuándo utilizarlo

• «¿Cuánta memoria está en uso en este Jetson? ¿Qué la está ocupando?»
• «He desactivado la interfaz gráfica / he detenido vLLM / he cerrado mi contenedor: ¿se ha liberado realmente la memoria?»
• «¿Por qué free -h sigue mostrando poca memoria libre después de haber detenido mi carga de trabajo?»
• Como referencia antes de aplicar jetson-headless-mode u otros cambios relacionados con la memoria, y de nuevo después para calcular la diferencia real.

Requisitos previos

• Ejecutar en el host del Jetson, o en un entorno aislado/contenedor con acceso del host a /proc, /etc/nv_tegra_release, tegrastats y datos de procesos.
• Las lecturas de NvMap en debugfs pueden requerir privilegios de root. Si no están disponibles, informa de que la atribución de memoria de la GPU es limitada, en lugar de hacer conjeturas.
• drop_caches.sh requiere privilegios de root o sudo -n sin contraseña; ejecútalo solo después de que el usuario autorice explícitamente la eliminación de la caché.

Scripts disponibles

Si el entorno de ejecución de tu agente es compatible con run_script, utilízalo para ejecutar scripts/audit.sh o scripts/drop_caches.sh y resume el resultado devuelto. De lo contrario, ejecuta los scripts con bash desde la raíz del repositorio.

Instrucciones

Para preguntas del tipo «¿cuánta memoria se está utilizando en este momento?», ejecuta scripts/audit.sh e informa únicamente de los valores de la instantánea JSON.

Orientación para la elaboración de informes

No te limites a mostrar o mencionar la ruta de acceso a una herramienta auxiliar. Ejecuta la herramienta y, a continuación, resume los datos devueltos.

• Para las consultas del tipo «¿cuánta memoria se está utilizando?», ejecuta scripts/audit.sh e indica los valores de mem_total_gb, memory_kb.available y el proceso procrank_top principal o el consumidor nvmap.top_clients.
• Para las consultas sobre la memoria de la interfaz gráfica de usuario (GUI) o del escritorio, ejecuta scripts/audit.sh e informa de default_systemd_target más cualquier gestor de pantalla de candidate_services (gdm3, gdm, lightdm, sddm o display-manager). No desactives nada; remítete a jetson-headless-mode para obtener un plan.
• Para las solicitudes que autoricen explícitamente el vaciado de la caché tras detener una carga de trabajo, ejecuta scripts/drop_caches.sh (equivalente a sudo sync && sudo sysctl -w vm.drop_caches=3 por defecto) e informa de las variaciones en «free», «available» y «cached» antes y después. Si no se dispone de privilegios de root, explica que debe ejecutarse en el host con sudo.

Si el entorno de ejecución de tu agente no ejecuta scripts auxiliares relativos a este directorio de habilidades, resuelve las rutas de los scripts con el marcador de posición {baseDir} de AgentSkills:

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

No utilices jetson-memory-audit como nombre de herramienta a menos que el entorno de ejecución registre explícitamente las habilidades como herramientas invocables; las habilidades de agente suelen consistir en instrucciones más archivos, no en funciones directas de herramientas.

Nota sobre el entorno de pruebas para agentes: el hecho de ver este archivo de habilidad no garantiza el acceso a los datos de la memoria del host Jetson. Si faltan /proc/device-tree/model, /etc/nv_tegra_release, tegrastats, /sys/kernel/debug/nvmap o los datos del proceso del host no están disponibles dentro de un entorno de pruebas de NemoClaw/OpenClaw, indica que el entorno carece de visibilidad del host de Jetson y pide al usuario que lo ejecute en el host de Jetson o que lo reinicie con un perfil de entorno de pruebas con visibilidad del host. No inventes valores de memoria total, memoria disponible, PSS, NvMap ni diferencias de recuperación de memoria.

Para preguntas del tipo «¿cuánta memoria ha liberado este cambio?», utiliza la diferencia entre el antes y el después. No calcules la memoria liberada a partir del tamaño del contenedor, el tamaño de la imagen, el RSS o una única instantánea posterior al cambio.

1. Antes del cambio, ejecuta el script audit.sh y guarda la línea de base en formato JSON.
2. Realice el cambio aprobado por el usuario (detenga el contenedor, cambie de modo, aplique una recomendación de ajuste, etc.).
3. En JetPack inferior a la versión 7.2 o L4T inferior a la r39.0, o cuando se observe el mismo síntoma de memoria bloqueada en una versión más reciente, vacía la caché de páginas recuperables en el host (no dentro de un contenedor) para que las páginas liberadas aparezcan como libres en lugar de en caché:

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

4. Vuelve a ejecutar scripts/audit.sh y compara el valor de memory_kb.available antes y después: esa diferencia es la recuperación real.

Si el usuario ya ha realizado el cambio y no existe una línea de base, indica que la cantidad exacta liberada no se puede recuperar solo a partir de la instantánea actual. Captura ahora una nueva línea de base para que se pueda medir el próximo cambio.

Utiliza los datos de auditoría en tiempo real como fuente de referencia. Los totales de memoria, la memoria disponible, los totales de NvMap, los valores de PSS, el estado del gestor de pantalla y las diferencias de ahorro deben proceder de scripts/audit.sh, free -h o tegrastats en el dispositivo real. Si un valor no aparece en esas salidas, no lo estimis.

Formato de salida de 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/8138 MB (lfb 8x4 MB) ...",
  "nvmap": { "readable": false, "total_kb": 0, "top_clients": [] },
  "procrank_top": [ { "pid": 4321, "pss_kb": 4000000, "cmd": "vllm" } ]
}

Limitaciones

• Para obtener las diferencias exactas de memoria liberada se requiere una instantánea previa, el cambio aprobado por el usuario, el vaciado de la caché cuando sea necesario y una instantánea posterior.
• La atribución de NvMap depende del acceso a debugfs visible desde el host; si no está disponible, se informará de una atribución limitada de la memoria de la GPU en lugar de realizar estimaciones.
• Es posible que las ejecuciones en entornos aislados (sandbox) o contenedores no puedan ver los datos de /proc, tegrastats, systemd o NvMap del host, a menos que el entorno de ejecución los exponga.

Gestión de errores

• Si el script scripts/audit.sh no puede acceder a los datos del host Jetson, se informará de la falta de visibilidad y se solicitará que se vuelva a ejecutar en el host Jetson o en un entorno de pruebas accesible desde el host.
• Si scripts/drop_caches.sh carece de privilegios de root o de sudo -n sin contraseña, informa de que la eliminación de la caché debe ejecutarse en el host con autorización de sudo.
• Si no existe ninguna instantánea previa, indica que la cantidad exacta recuperada no puede determinarse a partir del estado actual por sí solo y captura una nueva referencia para el próximo cambio.

Seguridad

Solo lectura. drop_caches no es destructivo (el kernel solo libera páginas que, de todos modos, podría recuperar bajo presión; primero se ejecuta sync para conservar los datos modificados).

Pasar el control a

• jetson-headless-mode: la mayor mejora en el espacio de usuario en sistemas que aún arrancan con graphical.target.
• jetson-inference-mem-tune: cuando un servidor de modelos es el principal consumidor de NvMap / PSS.
• Si los cambios en tiempo de ejecución no pueden alcanzar el objetivo, informa de que una mayor recuperación queda fuera del alcance de esta función, en lugar de sugerir modificaciones inseguras durante el arranque.