Rodar Localmente com Ollama

O problema

APIs de LLM na nuvem cobram por token. Uma sessão pesada de programação pode custar de US$ 5 a US$ 20. Para projetos pessoais, aprendizado ou trabalho sensível à privacidade, isso se acumula — e você está enviando cada conversa para um terceiro.

O que este guia resolve

Você vai colocar o Hermes Agent para rodar inteiramente no seu próprio hardware, usando o Ollama como backend de modelo. Sem chaves de API, sem assinaturas, sem dados saindo da sua máquina. Depois de configurado, o Hermes funciona exatamente como funciona com OpenRouter ou Anthropic — comandos de terminal, edição de arquivos, navegação na web, delegação — mas o modelo roda localmente.

No fim, você vai ter:

• Ollama servindo um ou mais modelos de pesos abertos
• Hermes conectado ao Ollama como endpoint personalizado
• Um agente local funcionando, capaz de editar arquivos, rodar comandos e navegar na web
• Opcional: um bot de Telegram/Discord movido inteiramente pelo seu hardware

O que você precisa

Componente	Mínimo	Recomendado
RAM	8 GB (para modelos de 3B)	32+ GB (para modelos de 27B+)
Armazenamento	5 GB livres	30+ GB (para vários modelos)
CPU	4 núcleos	8+ núcleos (AMD EPYC, Ryzen, Intel Xeon)
GPU	Não é obrigatória	GPU NVIDIA com 8+ GB de VRAM acelera bastante

Só CPU funciona, mas espere respostas mais lentas

O Ollama roda em servidores só com CPU. Um modelo de 9B em uma CPU moderna de 8 núcleos entrega cerca de 10 tokens/s. Um modelo de 31B em CPU é mais lento (~2–5 tokens/s) — cada resposta leva de 30 a 120 segundos, mas funciona. Uma GPU melhora muito isso. Em configurações só com CPU, amplie o timeout da API pela variável de ambiente (não é uma chave de config.yaml):

# ~/.hermes/.env
HERMES_API_TIMEOUT=1800   # 30 minutos — generoso para modelos locais lentos

Passo 1: instale o Ollama

curl -fsSL https://ollama.com/install.sh | sh

Confirme que ele está rodando:

ollama --version
curl http://localhost:11434/api/tags   # Deve retornar {"models":[]}

Passo 2: baixe um modelo

Escolha conforme o seu hardware:

Modelo	Tamanho em disco	RAM necessária	Chamada de ferramentas	Melhor para
gemma4:31b	~20 GB	24+ GB	Sim	Melhor qualidade — bom uso de ferramentas e raciocínio
gemma2:27b	~16 GB	20+ GB	Não	Tarefas conversacionais, sem uso de ferramentas
gemma2:9b	~5 GB	8+ GB	Não	Conversa rápida, perguntas e respostas — não chama ferramentas
llama3.2:3b	~2 GB	4+ GB	Não	Só respostas rápidas e leves

Chamada de ferramentas faz diferença

O Hermes é um assistente agêntico — ele edita arquivos, roda comandos e navega na web por meio de chamadas de ferramenta. Modelos sem suporte a chamada de ferramentas só conversam; não conseguem agir. Para a experiência completa do Hermes, use um modelo com suporte a ferramentas (como o gemma4:31b).

Baixe o modelo escolhido:

ollama pull gemma4:31b

Vários modelos

Você pode baixar vários modelos e alternar entre eles dentro do Hermes com /model. O Ollama carrega o modelo ativo na memória sob demanda e descarrega os ociosos automaticamente.

Confirme que o modelo funciona:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma4:31b",
    "messages": [{"role": "user", "content": "Say hello"}],
    "max_tokens": 50
  }'

Você deve ver uma resposta JSON com a réplica do modelo.

Passo 3: configure o Hermes

Rode o assistente de configuração do Hermes:

hermes setup

Quando ele pedir um provedor, escolha Custom Endpoint e informe:

• Base URL: http://localhost:11434/v1
• API Key: deixe vazio ou digite no-key (o Ollama não precisa de chave)
• Model: gemma4:31b (ou o modelo que você baixou)

Como alternativa, edite ~/.hermes/config.yaml diretamente:

model:
  default: "gemma4:31b"
  provider: "custom"
  base_url: "http://localhost:11434/v1"

Passo 4: comece a usar o Hermes

hermes

É isso. Você agora roda um agente totalmente local. Experimente:

Você: Liste todos os arquivos Python neste diretório e conte as linhas de código de cada um

Você: Leia o README.md e resuma o que este projeto faz

Você: Crie um script Python que busca a previsão do tempo de Ho Chi Minh

O Hermes vai usar a ferramenta de terminal, as operações de arquivo e o seu modelo local — sem nenhuma chamada à nuvem.

Passo 5: escolha o modelo certo para cada tarefa

Nem toda tarefa precisa do maior modelo. Um guia prático:

Tarefa	Modelo recomendado	Por quê
Edição de arquivos, código, comandos de terminal	gemma4:31b	Único modelo com chamada de ferramentas confiável
Perguntas rápidas (sem uso de ferramentas)	gemma2:9b	Respostas rápidas para tarefas conversacionais
Conversa leve	llama3.2:3b	O mais rápido, mas com capacidades bem limitadas

observação

Para trabalho agêntico completo (editar arquivos, rodar comandos, navegar), o gemma4:31b é hoje a melhor opção local com suporte a chamada de ferramentas. Consulte a biblioteca de modelos do Ollama para novidades — o suporte a chamada de ferramentas está crescendo rápido.

Troque de modelo na hora, dentro de uma sessão:

/model gemma2:9b

Passo 6: otimize para velocidade

Aumente a janela de contexto do Ollama

Por padrão, o Ollama usa um contexto de 2048 tokens. O Hermes exige pelo menos 64.000 tokens para trabalho agêntico com ferramentas:

# Crie um Modelfile que amplia o contexto
cat > /tmp/Modelfile << 'EOF'
FROM gemma4:31b
PARAMETER num_ctx 64000
EOF

ollama create gemma4-64k -f /tmp/Modelfile

Depois atualize a configuração do Hermes para usar gemma4-64k como nome do modelo.

Mantenha o modelo carregado

Por padrão, o Ollama descarrega modelos após 5 minutos de inatividade. Para um bot de gateway sempre ativo, mantenha-o carregado:

# Define o keep-alive em 24 horas
curl http://localhost:11434/api/generate \
  -d '{"model": "gemma4:31b", "keep_alive": "24h"}'

Ou defina isso globalmente no ambiente do Ollama:

# /etc/systemd/system/ollama.service.d/override.conf
[Service]
Environment="OLLAMA_KEEP_ALIVE=24h"

Use offload para GPU (se houver)

Se você tem uma GPU NVIDIA, o Ollama transfere camadas para ela automaticamente. Verifique com:

ollama ps   # Mostra qual modelo está carregado e quantas camadas estão na GPU

Para um modelo de 31B em uma GPU de 12 GB, você terá offload parcial (~40 camadas na GPU, o resto na CPU), o que ainda dá um ganho de velocidade significativo.

Passo 7: rode como bot de gateway (opcional)

Depois que o Hermes funcionar localmente na CLI, você pode expô-lo como bot de Telegram ou Discord — ainda rodando inteiramente no seu hardware.

Telegram

1. Crie um bot pelo @BotFather e pegue o token
2. Adicione ao seu ~/.hermes/config.yaml:

model:
  default: "gemma4:31b"
  provider: "custom"
  base_url: "http://localhost:11434/v1"

platforms:
  telegram:
    enabled: true
    token: "SEU_TOKEN_DE_BOT_DO_TELEGRAM"

3. Inicie o gateway:

hermes gateway

Agora mande mensagem para o seu bot no Telegram — ele responde usando o seu modelo local.

Discord

1. Crie um aplicativo Discord em discord.com/developers
2. Adicione à configuração:

platforms:
  discord:
    enabled: true
    token: "SEU_TOKEN_DE_BOT_DO_DISCORD"

3. Inicie: hermes gateway

Passo 8: configure provedores de reserva (opcional)

Modelos locais podem penar em tarefas complexas. Configure um provedor de reserva na nuvem que só entra em ação quando o modelo local falha:

model:
  default: "gemma4:31b"
  provider: "custom"
  base_url: "http://localhost:11434/v1"

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4

Assim, 90% do seu uso é gratuito (local), e só as tarefas difíceis batem na API paga.

Resolução de problemas

"Connection refused" na inicialização

O Ollama não está rodando. Inicie-o:

sudo systemctl start ollama
# ou
ollama serve

Respostas lentas

• Compare o tamanho do modelo com a RAM: se o modelo precisa de mais RAM do que existe, ele vai para o disco (swap). Use um modelo menor ou aumente a RAM.
• Confira ollama ps: se nenhuma camada foi para a GPU, as respostas dependem só da CPU. Isso é normal em servidores sem GPU.
• Reduza o contexto: conversas grandes deixam a inferência mais lenta. Use /compress com frequência, ou defina um limite de compressão menor na configuração.

Primeira resposta lenta (prefill)

O Hermes envia uma carga fixa em toda chamada de API — o prompt de sistema mais os esquemas de todas as ferramentas habilitadas — antes de qualquer conteúdo da sua conversa. Em configurações só com CPU ou com pouca VRAM, processar esse prompt (a fase de prefill) domina o primeiro turno: o modelo pode ficar em silêncio por minutos enquanto trabalha no prompt, e só então gerar no ritmo normal. Isso é comportamento esperado, não travamento. O guia de LLM local no Mac documenta o mesmo efeito — durante o prefill em contextos grandes, modelos locais podem não produzir saída nenhuma por minutos enquanto processam o prompt — e o Hermes aumenta automaticamente o timeout de leitura do stream de 120s para 1800s em endpoints locais (HERMES_STREAM_READ_TIMEOUT).

O que ajuda:

• Mantenha o modelo carregado — o Ollama descarrega modelos ociosos após 5 minutos, o que acrescenta um recarregamento completo antes do próximo prefill. Defina OLLAMA_KEEP_ALIVE=24h (veja o Passo 6).
• Amplie o timeout da API — defina HERMES_API_TIMEOUT=1800 em ~/.hermes/.env (veja O que você precisa).
• Meça e enxugue o prompt fixo — rode hermes prompt-size para ver a divisão em bytes do prompt de sistema e dos esquemas de ferramentas, depois desabilite conjuntos de ferramentas não usados com hermes tools e desinstale skills desnecessárias com hermes skills.
• Use offload para GPU — mesmo um offload parcial dá um ganho significativo (veja o Passo 6).

O modelo não segue as chamadas de ferramenta

Modelos sem suporte a chamada de ferramentas produzem texto puro em vez de chamadas de função estruturadas. Soluções:

• Use um modelo com suporte a chamada de ferramentas — dos modelos listados acima, só o gemma4:31b tem chamada de ferramentas confiável.
• O Hermes tem reparo automático — ele detecta chamadas de ferramenta malformadas e tenta corrigi-las sozinho.
• Configure um provedor de reserva — se o modelo local falhar 3 vezes, o Hermes recorre a um provedor na nuvem.

Se o modelo imprime JSON cru como {"name": "web_search", ...} na resposta em vez de realmente executar a ferramenta, geralmente o problema é do servidor, não do modelo — a chamada de ferramentas não está habilitada ou o formato de chamada não está sendo interpretado. Veja a tabela de correções por servidor em Provedores (llama.cpp precisa de --jinja, vLLM precisa de --enable-auto-tool-choice --tool-call-parser hermes, e assim por diante).

Erros de janela de contexto

O contexto padrão do Ollama (2048 tokens) é pequeno demais para trabalho agêntico. Veja o Passo 6 para aumentá-lo.

Comparação de custo

Veja quanto rodar localmente economiza em relação às APIs na nuvem, com base em uma sessão típica de programação (~100 mil tokens de entrada, ~20 mil de saída):

Provedor	Custo por sessão	Mensal (uso diário)
Anthropic Claude Sonnet	~US$ 0,80	~US$ 24
OpenRouter (GPT-4o)	~US$ 0,60	~US$ 18
Ollama (local)	US$ 0,00	US$ 0,00

Seu único custo é a eletricidade — algo entre US$ 0,01 e US$ 0,05 por sessão, conforme o hardware.

O que funciona bem localmente

• Edição de arquivos e geração de código — modelos de 9B para cima dão conta bem
• Comandos de terminal — o Hermes monta o comando, executa e lê a saída, seja qual for o modelo
• Navegação na web — a ferramenta de navegador faz a busca; o modelo só interpreta os resultados
• Tarefas agendadas com cron — funcionam igual às configurações na nuvem
• Gateway multiplataforma — Telegram, Discord e Slack funcionam com modelos locais

O que fica melhor com modelos na nuvem

• Raciocínio complexo de muitos passos — modelos de 70B+ ou de nuvem como o Claude Opus são visivelmente melhores
• Janelas de contexto longas — modelos na nuvem oferecem de 100 mil a 1 milhão de tokens; runtimes locais costumam vir abaixo do mínimo de 64 mil do Hermes, a menos que você configure
• Velocidade em respostas grandes — a inferência na nuvem é mais rápida que a local só com CPU em gerações longas

O ponto ideal: use o local no dia a dia e configure uma reserva na nuvem para o que for difícil.

---