NVIDIA Nemotron Nano 9B v2 em GGUF: arquitetura, quantização e inferência local

Executar o NVIDIA Nemotron Nano 9B v2 localmente exigia uma distribuição compatível com o ecossistema llama.cpp. Para viabilizar isso, ajudei a implementar o suporte à arquitetura híbrida Nemotron v2, identificada no runtime como nemotron_h, no llama.cpp. Essa implementação, registrada no PR #15507, tornou possível reconhecer a arquitetura e converter os pesos publicados pela NVIDIA para GGUF. A partir desse suporte, converti e publiquei os pesos em GGUF, com diferentes níveis de quantização. A NVIDIA criou a arquitetura, os dados, o treinamento, o alinhamento, a poda, a destilação e o checkpoint final de 8.888.227.328 parâmetros [1–3][12].

Minha contribuição começa, portanto, antes do arquivo GGUF: participei da implementação da arquitetura nemotron_h no llama.cpp e do caminho que permite carregar e converter seus tensores. Depois parti do checkpoint da NVIDIA, converti seus pesos para GGUF, gerei as quantizações e publiquei os arquivos para uso local [1][12]. A arquitetura original, o treinamento, a avaliação e os controles de raciocínio permanecem atribuições da NVIDIA [2–5]. Não preservei publicamente logs, versão do conversor, matriz de importância ou resultados por quantização; por isso, não preencho essas decisões por suposição.

Do modelo NVIDIA ao artefato DominguesM

A NVIDIA partiu do Nemotron-Nano-12B-v2-Base, com 62 camadas e dimensão oculta 5.120, pré-treinado em aproximadamente 20 trilhões de tokens. O relatório descreve treinamento FP8 E4M3 em blocos 128 × 128 para pesos, tiles 1 × 128 para ativações, pesos mestres FP32 e as primeiras e últimas quatro camadas lineares em BF16. Depois houve extensão de contexto, alinhamento por múltiplos estágios de SFT, GRPO, DPO e RLHF, além de mesclagem de checkpoints [3]. Esses procedimentos são trabalho da NVIDIA.

Para chegar ao modelo de 9B, a NVIDIA aplicou uma variante da estratégia Minitron. A busca podou profundidade, canais de embedding e largura da FFN sob uma restrição de memória. O candidato escolhido reteve 56 camadas, quatro delas de atenção, reduziu a dimensão oculta de 5.120 para 4.480 e a dimensão intermediária da FFN de 20.480 para 15.680, preservando 128 cabeças Mamba. A recuperação de qualidade usou destilação por divergência KL entre logits e etapas adicionais de preferência e reforço [3]. Portanto, a passagem 12B → 9B também não foi feita por DominguesM.

Com o suporte nemotron_h disponível no llama.cpp, parti do checkpoint, da configuração, do tokenizer e do template de chat da NVIDIA; converti os pesos para a arquitetura reconhecida pelo runtime, gravei metadados e tensores em GGUF e gerei as variantes quantizadas a partir de uma versão de alta precisão. Não publiquei o script, a versão exata do llama.cpp, o inventário das entradas nem o log dessa execução. Os comandos apresentados mais adiante são uma receita atual de reprodução, não o comando histórico de agosto de 2025 [12].

Por que a arquitetura é híbrida

Um Transformer causal calcula, em cada camada de autoatenção, relações entre o token atual e o prefixo. Durante geração, o cache KV evita recomputar chaves e valores, mas cresce linearmente com o comprimento e precisa ser consultado a cada passo. Mamba-2 representa o prefixo por estados recorrentes estruturados. Seu custo e seu estado por novo token não crescem como uma camada de atenção completa; em troca, a informação passada é comprimida, e não acessada por uma matriz explícita de pares de tokens [4, 5].

Nemotron-H combina os dois mecanismos em vez de declarar um vencedor universal. No modelo final de 9B, somente quatro das 56 camadas usam autoatenção, distribuídas pela rede; as restantes alternam sobretudo Mamba-2 e FFN. As camadas Mamba-2 fornecem processamento recorrente eficiente para longas trajetórias de raciocínio. As poucas camadas de atenção restauram pontos de interação global explícita. As FFNs transformam cada posição no espaço de atributos. A família usa GQA nas camadas de atenção, RMSNorm, ativação squared ReLU, conexões residuais, embeddings de entrada e saída separados e não usa embedding posicional [3, 4].

Mamba-2 não é simplesmente uma “atenção barata”. Em alto nível, uma entrada passa por projeções, convolução causal local e atualização de um modelo de espaço de estados; parâmetros dependentes da entrada controlam como o estado é atualizado e lido. O estado comprime o histórico em dimensão fixa por camada Mamba. Já a atenção conserva K e V por token nas quatro camadas correspondentes. Por isso o híbrido reduz, mas não elimina, o cache KV e o custo crescente com contexto. A alegação da NVIDIA de até 3–6 vezes mais throughput que Qwen3-8B refere-se a cenários, software, precisão e hardware definidos no relatório, como entrada de 8k e saída de 16k em A10G; não é um benchmark destes GGUFs [3].

Arquivos que publiquei

Publiquei 10 modelos de arquivo único. A tabela usa os bytes registrados pelo Hub, convertidos para GB decimal e GiB binário; não são estimativas [1].

Também publiquei .gitattributes, README.md, config.json e duas imagens, accuracy_chart.png e acc-vs-budget.png; não gerei variantes Q3, IQ, BF16 nem shards. Na README, reaproveitei parte do card da NVIDIA e incluí uma execução Q2_K cuja saída identifica incorretamente modelo, contexto e quantização. Mantenho esse trecho apenas como demonstração de geração, não como inspeção confiável do arquivo nem como benchmark [1].

GGUF é um contêiner binário, extensível e favorável a mmap. O cabeçalho registra versão, número de tensores e pares chave–valor; depois vêm descritores com nome, forma, tipo e offset alinhado, seguidos pelos dados. Tokenizer, tokens especiais, template de chat, arquitetura e proveniência podem viajar no mesmo arquivo [6]. “Arquivo único”, contudo, não significa que qualquer versão do executor o suporte: a implementação de nemotron_h, seus operadores Mamba-2 e os tipos de quantização também precisam existir no runtime.

No GGUF F16 que publiquei, o Hub extrai context_length = 1.048.576; no checkpoint da NVIDIA, max_position_embeddings = 131.072, e a empresa documenta suporte a 128K [1, 2]. Não preservei a origem do valor de 1M nem publiquei validação nessa extensão. Por isso, uso 128K como limite documentado do modelo de origem e trato 1M como metadado não validado do meu empacotamento, não como capacidade comprovada.

Quantização em blocos, bits e MSE

Quantização substitui pesos contínuos por códigos discretos. Para um bloco de B pesos, uma forma afim simplificada escolhe escala s, mínimo m e inteiros de b bits:

O quantizador procura parâmetros que reduzam erro, frequentemente aproximado por MSE. Esquemas simétricos omitem m e representam sinais em torno de zero. Blocos pequenos adaptam melhor a escala à distribuição local, mas repetem mais metadados. Minimizar MSE de pesos também não garante preservar perplexidade, instruções ou raciocínio: camadas têm sensibilidades diferentes, e pequenos erros podem se acumular. Uma importance matrix pode ponderar erros segundo ativações de um corpus de calibração; eu não preservei se usei uma nessa conversão [7].

Para $N=8\,888\,227\,328$ parâmetros, a conta ideal

produz:

Os arquivos reais são maiores porque “Q4”, por exemplo, descreve o tipo predominante, não quatro bits para todo byte do modelo. Escalas, mínimos, alinhamento e metadados ocupam espaço; embeddings e saída podem receber mais bits; tensores pequenos, normas e pesos Mamba incompatíveis podem permanecer em F16. O llama-quantize atual inclusive preserva pequenas convoluções SSM e aplica fallbacks quando a forma não é divisível pelo tamanho do bloco [7]. Isso explica por que Q2_K ocupa 5,01 GB, não 2,22 GB.

As famílias publicadas têm compromissos distintos:

• F16 mantém a maior parte dos pesos em 16 bits. É a melhor referência disponível para medir o dano das demais e exige mais disco, RAM e largura de banda.
• Q8_0 usa blocos simétricos de 8 bits com escala. Reduz quase pela metade o F16 e tende a ser a opção conservadora, sem tornar a saída matematicamente idêntica.
• Q6_K usa superblocos K de 6 bits e metadados hierárquicos. É um degrau de alta fidelidade; neste híbrido, seu arquivo está muito mais perto de Q8_0 que da estimativa ideal de 6 bits.
• Q5_0 é o esquema legado simétrico de 5 bits. Q5_K_M usa K-quants e uma mistura: o tipo-base é Q5_K, enquanto tensores considerados mais sensíveis podem receber Q6_K. O sufixo M designa o preset de mistura, não um novo número fixo de bits.
• Q4_0 é o legado simétrico de 4 bits. Q4_1 armazena escala e mínimo por bloco, custa mais e representa blocos assimétricos. Q4_K_S usa predominantemente Q4_K com uma mistura menor; Q4_K_M promove subconjuntos sensíveis, como partes de projeções de valor e ffn_down, a tipos superiores segundo a lógica do quantizador. Entre as variantes publicadas, Q4_K_M é o ponto de partida mais razoável para equilibrar memória e qualidade, mas isso deve ser medido no domínio real.
• Q2_K comprime agressivamente com códigos de 2 bits dentro de superblocos, mas mistura tipos mais altos em tensores sensíveis. É útil quando fazer o modelo caber é condição absoluta; não se deve inferir qualidade a partir do tamanho.

Não é recomendável gerar uma quantização a partir de outra. A opção --allow-requantize existe, mas a documentação alerta para perda severa; cada variante deve derivar de F16/F32 ou do checkpoint original [7].

Conversão e execução reproduzíveis

Uma reprodução atual começa escolhendo uma release ou tag do llama.cpp, instalando seus requisitos e convertendo diretamente o repositório NVIDIA. O suporte muda rapidamente; registre a versão ou data da release, sistema, compilador e backend. A sequência documentada é [7, 9]:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j 8
python3 -m pip install -r requirements.txt
 
python3 convert_hf_to_gguf.py \
  --remote nvidia/NVIDIA-Nemotron-Nano-9B-v2 \
  --outfile nemotron-nano-9b-v2-f16.gguf \
  --outtype f16
 
./build/bin/llama-quantize \
  nemotron-nano-9b-v2-f16.gguf \
  nemotron-nano-9b-v2-q4_k_m.gguf Q4_K_M

Quem só quer executar pode baixar exatamente um arquivo, sem clonar dezenas de gigabytes [11]:

hf download dominguesm/NVIDIA-Nemotron-Nano-9B-v2-GGUF \
  nemotron-nano-9b-v2-q4_k_m.gguf --local-dir models
 
./build/bin/llama-cli \
  -m models/nemotron-nano-9b-v2-q4_k_m.gguf \
  -c 8192 -ngl 99 -cnv

-ngl 99 solicita offload das camadas para GPU; reduza o valor se faltar VRAM ou use --device none para CPU. Em Apple Silicon, Metal é habilitado por padrão; em NVIDIA, compile separadamente com -DGGML_CUDA=ON; CPUs x86 usam kernels adequados às instruções disponíveis [9]. Para uma API local e um teste explícito do template:

./build/bin/llama-server \
  -m models/nemotron-nano-9b-v2-q4_k_m.gguf \
  -c 8192 -ngl 99 --port 8080
 
curl http://localhost:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"system","content":"/no_think"},{"role":"user","content":"Explique o que é um SSM em três frases."}],"temperature":0,"max_tokens":256}'

O template oficial liga raciocínio por padrão; /think o mantém ligado e /no_think pede resposta direta. A NVIDIA recomenda temperature=0.6, top_p=0.95 e pelo menos 1.024 novos tokens para raciocínio, e busca gulosa para modo direto [2]. O “budget” fino é diferente: o cliente conta tokens após <think>, tenta inserir </think> na próxima quebra de linha ao atingir o limite e força o fechamento até 500 tokens depois. Isso é orquestração do runtime descrita pela NVIDIA, não uma propriedade automática de qualquer leitor GGUF. Confirme se sua versão do servidor implementa esse controle; caso contrário, /think e /no_think não criam por si sós um orçamento numérico [2, 3].

Memória e escolha de hardware

O tamanho do arquivo é um piso útil, não a RAM necessária. Some pesos mapeados ou copiados, estado recorrente Mamba, cache KV das quatro camadas de atenção, buffers de computação, contexto do runtime e overhead do sistema. mmap pode fazer o RSS e a memória residente variarem com cache de páginas. Contexto de 128k aumenta estado e buffers mesmo que o arquivo permaneça igual.

Como regra operacional, escolha um arquivo com folga de vários GiB sobre RAM/VRAM livre e teste o contexto desejado. Máquinas com cerca de 8 GiB livres devem começar em Q2_K e contexto curto, aceitando risco de qualidade. Com 12–16 GiB livres, Q4_K_S/M ou Q5 costumam ser alvos mais realistas. Q6_K e Q8_0 pedem mais folga; F16, com 16,57 GiB só de arquivo, normalmente requer bem mais de 20 GiB para uma execução confortável. Em memória unificada Apple, CPU e GPU compartilham o mesmo orçamento. Em GPU discreta, offload parcial permite dividir trabalho com RAM, mas tráfego PCIe pode limitar geração.

A meta da NVIDIA de 128k em A10G com 22 GiB foi demonstrada para o modelo 9B em BF16 e uma pilha específica, não como garantia universal para llama.cpp. Para uso local, meça primeiro 8k, depois aumente -c, observando falha de alocação e queda de throughput. CPU tende a ser limitada por largura de banda durante geração; GPU ganha mais quando pesos e buffers cabem no dispositivo.

Protocolo de benchmark que adotei

Não há tabela publicada de perplexidade, tokens/s ou pico de RAM para estes 10 arquivos. Uma comparação reproduzível deve manter corpus, versão do runtime, backend, contexto, batch, threads e offload constantes; registrar CPU, RAM, GPU, driver, sistema e temperatura; reiniciar ou declarar o estado do cache; e repetir cada medição. Use F16 como referência da mesma arquitetura e tokenizer, nunca números de outro modelo.

Para perplexidade, a convenção do llama.cpp é WikiText-2; menor é melhor, mas o valor só é comparável sob a mesma implementação e tokenização [8]:

./scripts/get-wikitext-2.sh
./build/bin/llama-perplexity \
  -m models/nemotron-nano-9b-v2-q4_k_m.gguf \
  -f wikitext-2-raw/wiki.test.raw -c 4096

Execute F16 e cada quantização três vezes ou mais, reporte média, incerteza e

WikiText-2 é inglês e não substitui uma avaliação de português, código, tool calling ou raciocínio. Para velocidade, separe processamento de prompt (pp) e geração (tg); o llama-bench não inclui tokenização nem amostragem [9]:

./build/bin/llama-bench \
  -m models/nemotron-nano-9b-v2-q4_k_m.gguf \
  -p 512 -n 128 -r 10 -t 8 -ngl 99 -o json

Registre média e desvio em tokens/s, sem misturar CPU e GPU na mesma coluna. Para RAM no Linux, envolva uma execução padronizada com /usr/bin/time -v e reporte “Maximum resident set size”; no macOS, use /usr/bin/time -l e “maximum resident set size”. Meça após o warm-up, com o mesmo prompt, -c, -b, -ub, cache KV e offload. Para VRAM, amostre nvidia-smi ou a ferramenta nativa do backend. O resultado final deve conter ao menos: versão e data do llama.cpp, arquivo e tamanho, confirmação de integridade do GGUF, PPL e ΔPPL, pp512, tg128, pico de RAM/VRAM e todos os parâmetros. Só então é defensável afirmar que uma variante é “melhor” para uma máquina.

Segurança, licença e limites de uso

Quantização pode degradar mais que fluência: formato de tool calls, fechamento de <think>, código e respostas longas podem falhar antes de conversa curta. O modelo pode produzir fatos falsos, código vulnerável, vieses e conteúdo inadequado. Português aparece entre dados e idiomas citados no corpo do card da NVIDIA, mas o metadado principal lista apenas seis idiomas; eu não publiquei uma avaliação local específica de português. Não use o modelo sem validação humana em decisões médicas, jurídicas, financeiras, de segurança ou de alto impacto [2, 3].

O modelo e seus derivados são regidos pela NVIDIA Open Model License, não pela licença MIT do llama.cpp. A versão atual permite uso comercial e criação e distribuição de modelos derivados, mas condiciona os direitos ao acordo, aos termos de Trustworthy AI e a outras obrigações. Na redistribuição do modelo, exige fornecer o acordo e incluir em arquivo Notice a atribuição “Licensed by NVIDIA Corporation under the NVIDIA Open Model License”; também contém regras sobre guardrails, marcas, componentes de terceiros, exportação, ausência de garantia e indenização [10]. Na versão atual do repositório GGUF, não incluí um arquivo Notice nem uma cópia separada do acordo. Isso não determina sozinho qual versão contratual valia no upload, mas significa que um redistribuidor não deve presumir que apenas apontar para o card satisfaz os termos atuais. Consulte o texto aplicável e assessoria jurídica.

Por fim, trate GGUF como artefato de cadeia de suprimentos: baixe do namespace esperado, prefira uma versão ou snapshot publicado, verifique a integridade por um mecanismo confiável e mantenha o executor atualizado. GGUF evita código Python remoto durante a carga, mas um parser de binário ainda pode ter vulnerabilidades. A conversão amplia acesso local; não transforma o modelo em sistema seguro, deterministicamente correto ou livre de suas obrigações de origem.

Conclusão

Com a implementação do suporte nemotron_h no llama.cpp, ajudei a tornar o checkpoint da NVIDIA compatível com o conversor e o runtime; em seguida, converti os pesos e publiquei as quantizações GGUF com diferentes compromissos de memória. Minha contribuição foi essa ponte entre a arquitetura Nemotron v2 e a execução local. Para tornar futuras conversões mais comparáveis, aprendi a importância de preservar receitas, versões e benchmarks por quantização.

Referências

1. DominguesM. NVIDIA-Nemotron-Nano-9B-v2-GGUF: card, histórico e inventário de arquivos. Hugging Face, 2025. huggingface.co/dominguesm/NVIDIA-Nemotron-Nano-9B-v2-GGUF
2. NVIDIA. NVIDIA-Nemotron-Nano-9B-v2 Model Card. Hugging Face, 2025. huggingface.co/nvidia/NVIDIA-Nemotron-Nano-9B-v2
3. NVIDIA. NVIDIA Nemotron Nano 2: An Accurate and Efficient Hybrid Mamba-Transformer Reasoning Model. arXiv:2508.14444, 2025. arxiv.org/abs/2508.14444
4. NVIDIA. Nemotron-H: A Family of Accurate and Efficient Hybrid Mamba-Transformer Models. arXiv:2504.03624, 2025. arxiv.org/abs/2504.03624
5. Dao, T.; Gu, A. Transformers are SSMs: Generalized Models and Efficient Algorithms Through Structured State Space Duality. arXiv:2405.21060, 2024. arxiv.org/abs/2405.21060
6. ggml-org. GGUF specification. github.com/ggml-org/ggml/blob/master/docs/gguf.md
7. ggml-org. llama.cpp quantize documentation and implementation. github.com/ggml-org/llama.cpp/tree/master/tools/quantize
8. ggml-org. llama.cpp perplexity documentation. github.com/ggml-org/llama.cpp/tree/master/tools/perplexity
9. ggml-org. llama.cpp build and llama-bench documentation. github.com/ggml-org/llama.cpp
10. NVIDIA. NVIDIA Open Model License Agreement. nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license
11. Hugging Face. Command Line Interface: hf download. huggingface.co/docs/huggingface_hub/guides/cli
12. ggml-org. llama.cpp PR #15507: nvidia nemotron nano v2 (nemotronh). 2025. github.com/ggml-org/llama.cpp/pull/15507

BibTeX

@misc{nvidia2025nemotronnano2,
  title = {NVIDIA Nemotron Nano 2: An Accurate and Efficient Hybrid Mamba-Transformer Reasoning Model},
  author = {{NVIDIA}},
  year = {2025},
  eprint = {2508.14444},
  archivePrefix = {arXiv},
  primaryClass = {cs.CL},
  url = {https://arxiv.org/abs/2508.14444}
}
 
@misc{nvidia2025nemotronh,
  title = {Nemotron-H: A Family of Accurate and Efficient Hybrid Mamba-Transformer Models},
  author = {{NVIDIA}},
  year = {2025},
  eprint = {2504.03624},
  archivePrefix = {arXiv},
  primaryClass = {cs.CL},
  url = {https://arxiv.org/abs/2504.03624}
}
 
@article{dao2024transformers,
  title = {Transformers are SSMs: Generalized Models and Efficient Algorithms Through Structured State Space Duality},
  author = {Dao, Tri and Gu, Albert},
  year = {2024},
  eprint = {2405.21060},
  archivePrefix = {arXiv},
  primaryClass = {cs.LG},
  url = {https://arxiv.org/abs/2405.21060}
}
 
@misc{domingues2025nemotrongguf,
  title = {NVIDIA-Nemotron-Nano-9B-v2-GGUF},
  author = {DominguesM},
  year = {2025},
  howpublished = {Hugging Face model repository},
  url = {https://huggingface.co/dominguesm/NVIDIA-Nemotron-Nano-9B-v2-GGUF}
}
 
@misc{nvidia2025nemotroncard,
  title = {NVIDIA-Nemotron-Nano-9B-v2 Model Card},
  author = {{NVIDIA}},
  year = {2025},
  howpublished = {Hugging Face model repository},
  url = {https://huggingface.co/nvidia/NVIDIA-Nemotron-Nano-9B-v2}
}
 
@misc{ggmlgguf,
  title = {GGUF Specification},
  author = {{ggml-org}},
  howpublished = {GitHub repository documentation},
  url = {https://github.com/ggml-org/ggml/blob/master/docs/gguf.md}
}
 
@misc{llamacppquantize,
  title = {llama.cpp Quantization Documentation},
  author = {{ggml-org}},
  howpublished = {GitHub repository documentation},
  url = {https://github.com/ggml-org/llama.cpp/tree/master/tools/quantize}
}
 
@misc{nvidiaopenmodellicense,
  title = {NVIDIA Open Model License Agreement},
  author = {{NVIDIA}},
  url = {https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/}
}