hf-mem

hf_mem estima a memória necessária para inferência, incluindo pesos do modelo e um cache KV opcional, para Safetensors e GGUF para modelos no Hugging Face Hub usando requisições HTTP Range, ou seja, sem baixar ou carregar pesos localmente.

Quando usar?

• O usuário pergunta quanta VRAM ou memória um modelo precisa para rodar
• O usuário quer saber se um modelo cabe na sua GPU ou em uma instância específica
• O usuário referencia um ID de modelo ou URL do Hugging Face e pergunta sobre os requisitos de inferência

Quais são os requisitos?

• uv instalado (para uvx)
• HF_TOKEN do gerenciamento de credenciais privadas do host para repositórios restritos/privados; evite colocar tokens em argumentos de comando, logs ou relatórios.
• Uma versão de pacote hf-mem fixada e revisada, e permissão para acessar os metadados do modelo solicitado. Esta skill não inclui o executável.

Como executar?

As formas entre colchetes angulares e quadrados abaixo são notação de uso, não comandos de shell para colar literalmente. Coloque IDs de modelo e caminhos de arquivo entre aspas. Inspecione a --help do pacote selecionado, escolha uma versão revisada (por exemplo, com uvx --from "hf-mem==REVIEWED_VERSION" hf-mem ...) e use um cache privado onde os metadados são sensíveis. Não imprima credenciais.

Execute com --model-id apontando para o repositório Hugging Face Hub, que verificará se ele contém pesos de modelo Safetensors (via model.safetensors, model.safetensors.index.json se sharded, ou model_index.json para Diffusers) ou GGUF.

uvx hf-mem --model-id <model-id> --json-output

Se o repositório contiver pesos de modelo GGUF em múltiplas precisões/quantizações, as estimativas serão por arquivo, enquanto para inferência você não carregará todos eles, mas sim apenas uma única precisão. Dito isso, para GGUF você pode precisar fornecer --gguf-file para direcionar o arquivo específico (ou caminho se sharded) que você deseja executar.

uvx hf-mem --model-id <model-id> --gguf-file <file-or-path> --json-output

Adicionalmente, hf-mem vem com um flag --experimental que também calculará os requisitos de memória do cache KV, útil para modelos de linguagem grandes, o que significa que se aplica a LLMs (...ForCausalLM), VLMs (...ForConditionalGeneration) e modelos GGUF.

Quanto à janela de contexto, ela será lida do padrão ou substituída com --max-model-len, similar ao vLLM. E o mesmo vale para a precisão do cache KV, que terá como padrão a precisão do modelo, a menos que seja definida manualmente via --kv-cache-dtype, também similar ao vLLM.

Para Safetensors, use assim:

uvx hf-mem --model-id <model-id> --experimental [--max-model-len N] [--batch-size N] [--kv-cache-dtype auto|bfloat16|fp8|fp8_ds_mla|fp8_e4m3|fp8_e5m2|fp8_inc] --json-output

E, para GGUF, use assim:

uvx hf-mem --model-id <model-id> --gguf-file <file-or-path> --experimental [--max-model-len N] [--batch-size N] [--kv-cache-dtype auto|F32|F16|Q4_0|Q4_1|Q5_0|Q5_1|Q8_0|Q8_1|Q2_K|Q3_K|Q4_K|Q5_K|Q6_K|Q8_K|IQ2_XXS|IQ2_XS|IQ3_XXS|IQ1_S|IQ4_NL|IQ3_S|IQ2_S|IQ4_XS|I8|I16|I32|I64|F64|IQ1_M|BF16|TQ1_0|TQ2_0|MXFP4] --json-output

Exemplos

Para Transformers com pesos Safetensors:

uvx hf-mem --model-id MiniMaxAI/MiniMax-M2 --json-output

Para Diffusers com pesos Safetensors:

uvx hf-mem --model-id Qwen/Qwen-Image --json-output

Para Sentence Transformers com pesos Safetensors:

uvx hf-mem --model-id google/embeddinggemma-300m --json-output

Com --experimental para incluir a estimativa do cache KV para LLMs e VLMs:

uvx hf-mem --model-id mistralai/Mistral-7B-v0.1 --experimental --json-output

E, para LLMs ou VLMs com pesos GGUF:

uvx hf-mem --model-id unsloth/Qwen3.5-397B-A17B-GGUF --gguf-file Q4_K_M --experimental --json-output

Limitações

• Use esta skill apenas quando a tarefa corresponder claramente ao escopo do seu produto ou API upstream.
• Verifique comandos, comportamento da API, preços, cotas, credenciais e efeitos de implantação contra a documentação oficial atual antes de fazer alterações.
• Não trate exemplos gerados como substitutos para testes específicos do ambiente, revisão de segurança ou aprovação do usuário para ações destrutivas ou custosas.

Interpretação e verificação

…