
Ativar Modelos NVIDIA no Hermes Agent: config.yaml Completo | @CanalQb | 14/11/2026
Leitura: ~8 min
- O Hermes usa NVIDIA NIM quando o
config.yamltemprovider: nvidiae abase_urlhttps://integrate.api.nvidia.com/v1, com a chave guardada fora do arquivo. - Uma cadeia de fallbacks de 12 modelos evita que um limite de uso (429) ou um modelo sem acesso (404) pare o agente.
- Teste cada modelo com hello world antes de adicionar: o catálogo lista 83 modelos, mas a conta só acessa parte deles.
Nota Técnica: Os comandos e configurações deste tutorial têm fins educacionais. Teste em ambiente controlado e nunca publique sua chave de API. @CanalQb não se responsabiliza por danos, perdas ou bloqueios decorrentes do uso indevido.
A maioria das pessoas cola a chave direto no config.yaml e esquece que o arquivo vai parar num backup, num print ou num repositório. Aqui no @CanalQb, validamos outro caminho: a chave fica em variável de ambiente e o arquivo só aponta para a NVIDIA.
O Hermes Agent, da Nous Research, guarda o que não é segredo no config.yaml e os segredos no .env. Neste guia você configura o provider NVIDIA NIM (build.nvidia.com), define o modelo padrão e monta a cadeia de fallbacks que testamos em 14/11/2026. Mais abaixo, o erro de "Function not found for account" que derruba quem copia a lista cegamente.
Quais são as soluções rápidas para os problemas mais comuns?
Quase todo problema vem de três lugares: variável de ambiente que não carregou, modelo sem acesso na conta ou arquivo YAML com indentação errada. Confira abaixo o atalho de cada caso e siga o link para o passo completo.
- 401 Invalid JWT: a variável não carregou ou a chave está errada; reabra o terminal e confira com echo. ver passo completo
- 404 Function not found for account: o modelo existe no catálogo, mas sua conta não tem acesso; troque por um que retorne 200. ver passo completo
- hermes status mostra provider antigo: o gateway subiu com o config anterior; reinicie com hermes gateway restart. ver passo completo
- 429 rate limit: é o cenário para o qual a cadeia de fallbacks existe. ver passo completo
Onde fica o config.yaml do Hermes no Windows e no Linux?
No Windows, nesta instalação, o arquivo fica em C:\Users\{user}\AppData\Local\hermes\config.yaml. No Linux, a documentação oficial indica ~/.hermes/config.yaml. Em ambos, a variável HERMES_HOME pode apontar para outra pasta.
Esse caminho importa porque é o único arquivo que o Hermes lê para decidir provider e modelo. Se você editar uma cópia em outra pasta, o hermes status continua mostrando o provider antigo e parece que nada funcionou.
| Sistema | Caminho do config.yaml | Atalho no terminal |
|---|---|---|
| Windows | C:\Users\{user}\AppData\Local\hermes\config.yaml | %LOCALAPPDATA%\hermes\config.yaml |
| Linux / macOS | ~/.hermes/config.yaml | $HOME/.hermes/config.yaml |
| Qualquer sistema | pasta definida em HERMES_HOME | hermes config edit |
Substitua {user} pelo seu nome de usuário do Windows. O comando hermes config edit abre o arquivo no editor padrão e evita errar a pasta. Exceção: se você usa perfis ou Docker, o HERMES_HOME muda e o arquivo fica em outro lugar, como /opt/data no contêiner oficial. Erro comum: editar ~/.hermes dentro do WSL enquanto o Hermes roda no Windows; são instalações diferentes, cada uma com seu próprio arquivo.
Como criar a chave da NVIDIA sem expor a API?
Entre em build.nvidia.com, abra a página de chaves de API do seu perfil e gere uma chave que começa com nvapi-. Guarde-a em um gerenciador de senhas e nunca em arquivo versionado, print ou post.
A chave dá acesso aos modelos NIM em https://integrate.api.nvidia.com/v1, com o limite de uso da sua conta. Como ela é um segredo, o config.yaml deste tutorial usa api_key: "" de propósito: o Hermes resolve a credencial pelo pool de variáveis de ambiente. Se a chave vazar, revogue na mesma página e gere outra; trocar o valor da variável basta, sem tocar no YAML.
Erro comum: colar a chave dentro do YAML "só para testar". Esse arquivo costuma entrar em backups; se isso aconteceu, revogue a chave agora.
Como guardar a chave em variáveis de ambiente?
No Windows, use setx e reabra o terminal. No Linux, use export no seu shell ou o arquivo ~/.hermes/.env, que a documentação define como o lugar dos segredos. Uma chave já basta; até quatro entram em rodízio.
O Hermes monta um pool lendo NVIDIA_API_KEY e NVIDIA_API_KEY_2 até NVIDIA_API_KEY_4. Slots extras ajudam a distribuir o limite de uso, mas só use chaves da sua própria conta e dentro dos termos da NVIDIA.
:: Windows (PowerShell) - troque pelos seus valores setx NVIDIA_API_KEY "nvapi-SUA_CHAVE_1" setx NVIDIA_API_KEY_2 "nvapi-SUA_CHAVE_2" # opcional # Linux / macOS (bash ou zsh) export NVIDIA_API_KEY="nvapi-SUA_CHAVE_1" # ou, via CLI do Hermes (grava no .env automaticamente): hermes config set NVIDIA_API_KEY nvapi-SUA_CHAVE_1
O setx só vale para terminais abertos depois dele; sem reabrir, o Hermes não enxerga a variável e você recebe o erro 401. Confira com echo $env:NVIDIA_API_KEY_2 no PowerShell, que deve mostrar um valor e não uma linha vazia. No Linux, rode echo "${NVIDIA_API_KEY:0:6}" para ver só o prefixo e não imprimir a chave inteira na tela.
Como configurar o provider e o modelo padrão no config.yaml?
Na seção model:, defina provider nvidia, a base_url da NVIDIA, o modelo padrão e deixe api_key vazia. O Hermes lê a credencial do pool de ambiente e passa a usar o NIM em todas as conversas.
Faça um backup antes de editar: no Windows, copy "$env:LOCALAPPDATA\hermes\config.yaml" "$env:LOCALAPPDATA\hermes\config.yaml.bak-ANTES-NVIDIA"; no Linux, cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak. A URL direta funciona porque, nos nossos testes, o Hermes não enviou prompt_cache_key ao NIM, então não precisa de proxy local.
model:
api_key: ""
base_url: https://integrate.api.nvidia.com/v1
default: mistralai/mistral-large-4-1t-a52b
provider: nvidiaA indentação do YAML usa espaços, nunca tabulação; quatro espaços como no exemplo funcionam. Resultado esperado: ao rodar hermes status, aparecem Provider NVIDIA NIM e o modelo mistralai/mistral-large-4-1t-a52b. Se aparecer o provider antigo, veja o caso correspondente em Erros e Soluções.
Como montar a cadeia de fallbacks com os modelos NVIDIA?
Adicione a lista fallback_providers: ao config.yaml. Quando o modelo principal falha por 404, 410, rate limit ou erro 5xx, o Hermes tenta o próximo da lista, na ordem em que aparecem.
Esta é a cadeia de 12 modelos que respondeu 200 com conteúdo na nossa conta em 14/11/2026, tanto pela API crua quanto por hermes -z -m. A ordem prioriza capacidade primeiro e velocidade depois; ajuste conforme seu uso.
fallback_providers:
- provider: nvidia
model: nvidia/nemotron-3-ultra-550b-a55b
- provider: nvidia
model: nvidia/nemotron-3.5-lightning-30b-a3b
- provider: nvidia
model: nvidia/nemotron-3.5-bolt-e4b
- provider: nvidia
model: poolside/laguna-xs-2.1
- provider: nvidia
model: nvidia/nemotron-3.5-super-vl-120b-a12b
- provider: nvidia
model: stepfun-ai/step-5-preview
- provider: nvidia
model: meta/llama-3.2-90b-vision-instruct
- provider: nvidia
model: google/gemma-4-31b-it
- provider: nvidia
model: minimaxai/minimax-m3.1-flash
- provider: nvidia
model: nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
- provider: nvidia
model: meta/muse-glimmer-30b
- provider: nvidia
model: nvidia/ising-calibration-1.5-31bImportante: acesso a modelo é por conta. Os testes aqui valem para a conta usada; a sua pode liberar outro conjunto. Por isso a próxima seção ensina a testar antes de aceitar a lista. Limitação: o fallback só cobre falhas de API; uma resposta ruim mas com status 200 não aciona a troca.
Como saber quais modelos a sua conta realmente acessa?
Liste o catálogo em /v1/models e depois teste cada candidato em /v1/chat/completions. Só o que responder 200 com conteúdo entra na cadeia; o restante retorna 404 "Function not found for account".
O catálogo público lista 83 modelos, mas isso não significa acesso. Na nossa conta, deepseek-ai/deepseek-v4.1-flash e z-ai/glm-5.3-flash deram timeout, openai/gpt-oss-20b respondeu vazio pelo Hermes e a maioria dos demais retornou 404. Esses resultados são da nossa conta e do dia do teste, então revalide na sua.
# Listar o catálogo
curl -H "Authorization: Bearer $NVIDIA_API_KEY" https://integrate.api.nvidia.com/v1/models
# Testar um modelo (PowerShell)
$body = @{ model = "NOME_DO_MODELO"; messages = @(@{ role = "user"; content = "Say exactly: hello world" }); max_tokens = 64 } | ConvertTo-Json -Depth 5
Invoke-RestMethod -Uri https://integrate.api.nvidia.com/v1/chat/completions -Method Post -Headers @{ Authorization = "Bearer $env:NVIDIA_API_KEY"; "Content-Type" = "application/json" } -Body $bodyNo Linux, o equivalente do teste usa curl com -d e o corpo JSON entre aspas simples. Resultado esperado: um JSON com o texto "hello world" no campo content. Se vier timeout ou content vazio, não adicione o modelo à cadeia, mesmo que ele apareça no catálogo.
Como verificar se o Hermes está usando a NVIDIA?
Rode hermes status, hermes fallback list e dois testes com hermes -z: um no modelo padrão e outro forçando um fallback com a opção -m. Se os três responderem, a configuração está completa.
- Confirme o provider. Rode
hermes status. O esperado é Provider NVIDIA NIM e o modelo mistralai/mistral-large-4-1t-a52b. Se mostrar outro provider, o Hermes ainda lê o config antigo. - Liste a cadeia. Rode
hermes fallback list. Devem aparecer o Primary e os 12 fallbacks, na ordem do YAML. Faltou algum? Revise a indentação. - Teste o padrão. Rode
hermes -z "Say exactly: hello world". Isso valida chave, URL e modelo juntos. - Teste um fallback. Rode
hermes -z "Say exactly: hello world" -m nvidia/nemotron-3.5-bolt-e4b. Se responder, o modelo está acessível pela conta.
Para trocar de modelo na hora, use hermes -z "..." -m MODELO ou o comando hermes model. Para voltar atrás, copie o arquivo .bak de volta sobre o config.yaml e reinicie o gateway se ele estiver rodando. Seguro por padrão: o backup é a sua rede de proteção, então não pule o passo.
Perguntas Frequentes
Preciso de cartão de crédito para usar os modelos NVIDIA no Hermes?
Posso colocar a chave direto no config.yaml?
Por que o erro 404 "Function not found for account" aparece?
Quantos fallbacks devo configurar?
O Hermes funciona do mesmo jeito no Linux e no Windows?
Erros e Soluções
Os erros mais frequentes nesta configuração vêm de variável de ambiente, acesso do modelo à conta, gateway com config antigo e limite de uso. Cada card traz a mensagem, a causa, a correção e como evitar.
401 "Invalid JWT"
Causa: a variável de ambiente não carregou ou a chave está errada.
Solução: feche e reabra o terminal após o setx, confira com echo e revise a chave em build.nvidia.com.
Prevenção: sempre reabra o terminal depois de definir variáveis.
404 "Function not found for account"
Causa: o modelo está no catálogo, mas a conta não tem acesso.
Solução: troque por um modelo que retorne 200 no teste hello world.
Prevenção: teste cada modelo antes de adicionar à cadeia.
hermes status mostra o provider antigo
Causa: o gateway estava parado e subiu com a configuração anterior, ou você editou outro arquivo.
Solução: rode hermes gateway restart ou feche e abra o terminal; confirme o caminho com hermes config edit.
Prevenção: edite sempre pelo caminho oficial da seção de localização.
429 (rate limit)
Causa: o limite de uso da conta foi atingido.
Solução: aguarde ou conte com a cadeia de fallbacks; slots extras de chave da própria conta ajudam no rodízio.
Prevenção: mantenha ao menos três fallbacks validados.
Resposta vazia ou timeout num modelo
Causa: o modelo responde 200 sem conteúdo ou demora demais; na nossa conta isso ocorreu com alguns nomes do catálogo.
Solução: remova o modelo da cadeia e teste outro.
Prevenção: valide pelo Hermes (hermes -z -m), não só pela API crua.
Funcionou para você? Veja mais tutoriais no canal @CanalQb no YouTube.
Fontes e Referências
- Hermes Agent: documentação de configuração (verificado em 14/11/2026)
- Hermes Agent no GitHub
- NVIDIA build (catálogo NIM)
- APM: integração com Hermes (HERMES_HOME)
Conformidade Global: As informações refletem o cenário no momento da publicação. Termos e limites da NVIDIA mudam; consulte as fontes oficiais. Este conteúdo não constitui aconselhamento jurídico. IAPP Global Privacy Directory.
Feito com Master Rules Claude v9.4