📥 Instalando Ollama
Ollama é o runtime que roda LLMs localmente na sua máquina. Ele gerencia download, quantização e serving dos modelos via uma API REST em localhost:11434. A instalação é simples em qualquer plataforma — um comando e pronto.
Instalação do Ollama
# Linux
curl -fsSL https://ollama.com/install.sh | sh
# Mac
brew install ollama
# Verificar
ollama --version
ollama serve # inicia servidor em localhost:11434💡 Docker Alternative
Se preferir isolar o ambiente, use Docker: docker run -d -v ollama:/root/.ollama -p 11434:11434 ollama/ollama. Funciona igual, com a vantagem de não instalar nada no sistema host.
🤖 Modelos Qwen
A família Qwen3 da Alibaba é atualmente a melhor opção open-source para agentes de código. Modelos densos e MoE (Mixture of Experts) cobrem desde laptops com 8GB até workstations com 40GB+ de VRAM, todos com suporte nativo a tool calling.
Catálogo de Modelos Qwen3
| Modelo | Params | Ativo | Contexto | VRAM |
|---|---|---|---|---|
| qwen3:8b | 8.2B | 8.2B | 32K/131K | ~5GB |
| qwen3:14b | 14B | 14B | 32K/131K | ~9GB |
| qwen3:32b | 32B | 32B | 32K/131K | ~20GB |
| qwen3-coder:30b-a3b | 30B MoE | 3B | 256K | ~20GB |
| qwen3-coder-next | 80B MoE | 3B | 256K/1M | ~35-40GB |
| qwen3.5-9b | 9B | 9B | 256K | ~6GB |
# Baixar modelos recomendados
ollama pull qwen3:8b
ollama pull qwen3-coder:30b-a3b📊 SWE-bench Scores
qwen3:8b: ~35% SWE-bench Verified — bom para tarefas simples e aprendizado
qwen3-coder:30b-a3b: ~55% — MoE eficiente, velocidade surpreendente para o tamanho
qwen3-coder-next: ~69.6% — quase no nível de Claude, mas roda local
Referência: Claude Sonnet 4 atinge ~72-77% no SWE-bench Verified
💾 Escolhendo por Hardware
A escolha do modelo depende diretamente da sua VRAM disponível. Modelos que não cabem na GPU são descarregados para RAM/CPU, ficando 10-50x mais lentos. A regra é simples: escolha o maior modelo que cabe inteiramente na sua GPU.
Guia de Recomendação por VRAM
| VRAM | Modelo Recomendado | Por que |
|---|---|---|
| 8GB | qwen3:8b | Cabe confortável, bom tool calling |
| 16GB | qwen3-coder:30b-a3b | MoE: modelo grande, params ativos pequenos |
| 24GB | qwen3:32b | Melhor single-GPU |
| 40GB+ | qwen3-coder-next (Q4) | 69.6% SWE-bench, quase Claude |
💡 Verificar VRAM Disponível
Use nvidia-smi para ver a VRAM total e em uso da sua GPU. Em Macs com Apple Silicon, a memória unificada é compartilhada entre CPU e GPU — o Ollama usa automaticamente o Metal para aceleração.
📏 Context Window
O Ollama usa um default de 4096 tokens de contexto — absurdamente pouco para um agente que precisa ler arquivos, manter histórico e processar tool calls. Configurar o num_ctx corretamente é obrigatório antes de qualquer uso sério.
Configurando Context Window
# Default é 4096 — MUITO POUCO para agentes!
# Configurar antes de iniciar:
OLLAMA_CONTEXT_LENGTH=65536 ollama serve
# Ou por request:
options: {"num_ctx": 65536}
# KV cache compression (economiza 75% memória):
# No Modelfile: PARAMETER kv_cache_type q4_0⚠️ Armadilha do Default 4096
O default de 4096 tokens é a causa #1 de agentes que "esquecem" o contexto ou geram respostas sem sentido. Sempre configure num_ctx para pelo menos 32768 (32K) — idealmente 65536 (64K) se a VRAM permitir. Sem isso, o modelo trunca silenciosamente as mensagens antigas.
🐍 Python + ollama
A biblioteca oficial ollama para Python fornece uma interface limpa para interagir com o servidor local. A API é compatível com o padrão OpenAI, facilitando migração futura entre modelos locais e cloud.
Setup Python + Ollama
pip install ollama
from ollama import chat
response = chat(
model='qwen3:8b',
messages=[{'role': 'user', 'content': 'Hello!'}],
options={'num_ctx': 65536, 'temperature': 0.6}
)
print(response.message.content)💡 AsyncClient para Async
Para aplicações assíncronas, use from ollama import AsyncClient. Isso permite fazer múltiplas chamadas em paralelo sem bloquear a thread principal — essencial para agentes que precisam responder rápido enquanto processam ferramentas em background.
💬 Primeiro Chat
Agora vamos testar tudo junto: um chat com streaming que mostra os tokens sendo gerados em tempo real. Se funcionar, seu ambiente está pronto para construir o agente.
Chat com Streaming
# Streaming
from ollama import chat
stream = chat(
model='qwen3:8b',
messages=[{'role': 'user', 'content': 'Explique recursão'}],
stream=True,
options={'num_ctx': 65536}
)
for chunk in stream:
print(chunk['message']['content'], end='', flush=True)💡 Smoke Test
Se o streaming funciona e você vê tokens aparecendo em tempo real, seu ambiente está 100% pronto para o agente. Este é o "Hello World" do LLM local — se funciona aqui, funciona no loop do agente.
📋 Resumo do Módulo
Próximo Módulo:
6.2 - 🔗 Tool Calling com LLMs Locais