Auditoria de Memória do Jetson

Snapshot focado na memória de leitura exclusiva (ROM) para um Jetson, além do auxiliar de loop de verificação `drop_caches`, que confirma se a memória liberada realmente aparece como livre, em vez de armazenada em cache.

Objetivo

Medir os atuais consumidores de memória do Jetson, capturar valores de referência antes e depois e verificar se as alterações aprovadas pelo usuário realmente recuperaram DRAM. Utilizar dados em tempo real do dispositivo, em vez de estimativas baseadas no tamanho do contêiner, no tamanho do modelo ou na memória genérica do processo.

CRÍTICO: A memória parece travada após a interrupção do vLLM / sglang (JetPack abaixo da versão 7.2 / L4T abaixo da r39.0)

Essa é a confusão de memória mais comum nas versões do Jetson anteriores ao JetPack 7.2 ou ao L4T r39.0.

Depois de parar um servidor vLLM, sglang ou Ollama (ou qualquer carga de trabalho CUDA), a memória exibida como livre pelo comando `free -h ` ou pelo `tegrastats` pode não ser recuperada — mesmo que o processo tenha sido encerrado. O `nvidia-smi` também pode exibir uma quantidade enganosamente baixa de memória livre da GPU.

Causa principal: o Thor RM (gerenciador de recursos) mantém as páginas de memória do sistema (sysmem) liberadas em seu próprio pool após o encerramento de um contexto CUDA. Em dispositivos com Arquitetura de Memória Unificada (UMA), como o Jetson, o `cudaMemGetInfo` lê o estado do pool do RM e relata uma quantidade de memória livre muito menor do que a realmente disponível para um novo processo.

Solução alternativa (para JetPack abaixo da versão 7.2 ou L4T abaixo da r39.0):

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

Execute isso no host, não dentro de um contêiner. A operação importante é o `sudo sysctl -w vm.drop_caches=3`; execute o `sudo sync ` imediatamente antes dela para que os dados não validados sejam liberados antes que os caches de páginas/dentry/inode recuperáveis sejam descartados. Após a execução, os comandos `free -h ` e ` tegrastats ` refletirão a memória disponível real.

Para as versões afetadas, recomenda-se este comando quando um usuário relatar:

• “A memória não foi liberada depois que eu parei o vLLM/sglang”
• “Por que o tegrastats ainda mostra um uso alto depois que meu contêiner foi encerrado?”
• “OOM mesmo sem nada em execução”
• “A memória estava normal ontem, mas agora está cheia”

No JetPack abaixo da versão 7.2 ou no L4T abaixo da r39.0, o comando `drop_caches` é a solução alternativa confiável quando a memória parece travada após o encerramento de uma carga de trabalho CUDA; em versões mais recentes, use-o apenas se o mesmo sintoma for observado e o usuário aprovar.

Quando usar

• “Quanta memória está em uso neste Jetson? O que está ocupando-a?”
• “Desativei a GUI / parei o vLLM / saí do meu contêiner — a memória realmente foi liberada?”
• "Por que o comando ` free -h ` ainda mostra pouca memória livre depois que parei minha carga de trabalho?"
• Como referência antes de aplicar o jetson-headless-mode ou outras alterações relacionadas à memória, e novamente depois para calcular a diferença real.

Pré-requisitos

• Execute no host do Jetson ou em uma sandbox/contêiner com /proc, /etc/nv_tegra_release, tegrastats e dados de processos visíveis ao host.
• As leituras do NvMap no debugfs podem exigir privilégios de root. Se não estiverem disponíveis, informe que a alocação de memória da GPU está limitada, em vez de fazer suposições.
• O `drop_caches.sh` requer privilégios de root ou `sudo -n` sem senha; execute-o somente após o usuário autorizar explicitamente a liberação do cache.

Scripts disponíveis

Se o ambiente de execução do seu agente suportar run_script, use-o para executar scripts/audit.sh ou scripts/drop_caches.sh e resuma a saída retornada. Caso contrário, execute os scripts com o bash a partir da raiz do repositório.

Instruções

Para perguntas do tipo “quanta memória está em uso no momento?”, execute scripts/audit.sh e relate apenas os valores do snapshot JSON.

Orientação para relatórios

Não se limite a imprimir ou mencionar o caminho para um auxiliar. Chame o auxiliar e, em seguida, resuma os dados retornados.

• Para solicitações do tipo “quanta memória está em uso?”, execute scripts/audit.sh e cite mem_total_gb, memory_kb.available e o processo procrank_top principal ou o consumidor nvmap.top_clients.
• Para solicitações de memória da GUI/área de trabalho, execute scripts/audit.sh e relate default_systemd_target, além de qualquer gerenciador de tela em candidate_services (gdm3, gdm, lightdm, sddm ou display-manager). Não desative nada; encaminhe para o jetson-headless-mode para um plano.
• Para solicitações que autorizem explicitamente a liberação do cache após a interrupção de uma carga de trabalho, execute scripts/drop_caches.sh (equivalente a sudo sync && sudo sysctl -w vm.drop_caches=3 por padrão) e relate as variações antes e depois em termos de memória livre, disponível e em cache. Se o root não estiver disponível, explique que o comando deve ser executado no host com o `sudo`.

Se o ambiente de execução do seu agente não executar scripts auxiliares relativos a este diretório de habilidades, resolva os caminhos dos scripts com o placeholder AgentSkills {baseDir}:

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

Não chame jetson-memory-audit como nome de ferramenta, a menos que o ambiente de execução registre explicitamente as habilidades como ferramentas chamáveis; as habilidades de agente são normalmente instruções acompanhadas de arquivos, e não funções diretas de ferramentas.

Observação sobre a sandbox para agentes: a visualização deste arquivo de skill não garante acesso aos dados da memória do host Jetson. Se /proc/device-tree/model, /etc/nv_tegra_release, tegrastats, /sys/kernel/debug/nvmap ou dados do processo do host estiverem ausentes dentro de uma sandbox do NemoClaw/OpenClaw, informe que a sandbox não tem visibilidade do host do Jetson e peça ao usuário para executar no host do Jetson ou reiniciar com um perfil de sandbox com visibilidade do host. Não invente valores para o total de memória, memória disponível, PSS, NvMap ou diferenças de recuperação.

Para perguntas do tipo “quanta memória essa alteração liberou?”, use o delta entre o antes e o depois. Não estime a memória liberada com base no tamanho do contêiner, no tamanho da imagem, no RSS ou em um único snapshot pós-alteração.

1. Antes da alteração, execute o script audit.sh e salve a linha de base em JSON.
2. Faça a alteração aprovada pelo usuário (pare o contêiner, alterne o modo, aplique uma recomendação de ajuste etc.).
3. No JetPack abaixo da versão 7.2 / L4T abaixo da r39.0, ou quando o mesmo sintoma de memória travada for observado em uma versão mais recente, esvazie o cache de páginas recuperáveis no host (não dentro de um contêiner) para que as páginas liberadas apareçam como livres em vez de armazenadas em cache:

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

4. Execute novamente o script scripts/audit.sh e compare o valor de memory_kb.available antes e depois — essa diferença representa a recuperação real.

Se o usuário já tiver feito a alteração e não houver uma linha de base, informe que a quantidade exata de memória liberada não pode ser recuperada apenas a partir do snapshot atual. Capture uma nova linha de base agora para que a próxima alteração possa ser medida.

Use os dados de auditoria em tempo real como fonte de referência. Os totais de memória, a memória disponível, os totais do NvMap, os valores de PSS, o estado do gerenciador de tela e as diferenças de economia devem vir do script scripts/audit.sh, do comando free -h ou do tegrastats no próprio dispositivo. Se um número não estiver presente nessas saídas, não tente adivinhá-lo.

Formato de saída para 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" } ]
}

Limitações

• Para obter diferenças exatas de memória liberada, é necessário um snapshot inicial, a alteração aprovada pelo usuário, a limpeza do cache quando apropriado e um snapshot final.
• A atribuição do NvMap depende do acesso ao debugfs visível no host; se ele não estiver disponível, relate a atribuição limitada de memória da GPU em vez de fazer suposições.
• Execuções em sandbox/contêiner podem não ter acesso aos dados do host em /proc, tegrastats, systemd ou NvMap, a menos que o ambiente de execução os exponha.

Tratamento de erros

• Se o script scripts/audit.sh não conseguir acessar os dados do Jetson no host, informe a falta de visibilidade e solicite que seja executado novamente no host Jetson ou em uma sandbox visível ao host.
• Se o scripts/drop_caches.sh não tiver acesso como root ou sudo -n sem senha, informe que a limpeza do cache deve ser executada no host com aprovação do sudo.
• Se não houver um snapshot anterior, informe que a quantidade exata recuperada não pode ser obtida apenas a partir do estado atual e capture uma nova linha de base para a próxima alteração.

Segurança

Somente leitura. O `drop_caches` é não destrutivo (o kernel libera apenas as páginas que poderia recuperar sob pressão de qualquer maneira; o `sync` é executado primeiro para preservar os dados alterados).

Passe para

• jetson-headless-mode — o maior ganho individual no espaço do usuário em sistemas que ainda inicializam o graphical.target.
• jetson-inference-mem-tune — quando um servidor de modelo é o maior consumidor de NvMap/PSS.
• Se as alterações em tempo de execução não conseguirem atingir a meta, informe que uma recuperação adicional está fora do escopo desta habilidade, em vez de sugerir edições inseguras no momento da inicialização.