Módulo 3.1: O que é Ollama | Claude Code Open

🦙 O que é Ollama

Ollama é um servidor local que roda modelos de linguagem (LLM) diretamente na sua máquina. Diferente dos serviços em nuvem, nenhum dado sai do seu ambiente — tudo acontece localmente, no seu próprio hardware.

🦙 Conceito Principal

Ollama é um servidor local que roda modelos de linguagem (LLM) diretamente na sua máquina, sem enviar dados para nenhuma nuvem.

• Funciona como um daemon em background — você inicia uma vez e ele fica disponível
• Expõe uma API REST local acessível em localhost:11434
• Compatível com o formato da API da OpenAI — ferramentas existentes funcionam sem modificação

📊 Dados do Projeto

100+ modelos disponíveis na biblioteca oficial (ollama.com/library)
API compatível com OpenAI — sem necessidade de adaptar código
Plataformas: Windows, macOS (Intel e Apple Silicon), Linux
Open-source — licença MIT, código disponível no GitHub

💡 Por que usar modelo local

Usar modelos locais oferece vantagens que os serviços em nuvem simplesmente não conseguem superar: privacidade absoluta, custo zero por token e funcionamento offline. Para muitos casos de uso, isso muda completamente a equação.

✓ Use Local quando

✓ Dados confidenciais ou propriedade intelectual que não podem sair da empresa
✓ Volume alto de requisições onde custo de API se tornaria proibitivo
✓ Desenvolvimento em ambientes sem acesso confiável à internet
✓ Experimentação e testes onde latência de rede incomoda

✗ Prefira Nuvem quando

✗ Hardware limitado (menos de 8GB RAM) — modelos úteis não vão caber
✗ Tarefas que exigem máxima qualidade (Claude 3.7 Sonnet não roda local)
✗ Precisa de multimodal (imagens, vídeo) sem GPU potente
✗ Ambiente de produção onde SLA e escalabilidade são críticos

💰 Dica Prática

Após o download do modelo, o uso é 100% gratuito. Um modelo de 20GB baixado uma única vez pode ser usado ilimitadamente — ideal para aprendizado, protótipos e projetos pessoais onde tokens de API sairiam caro.

⚙️ Como Ollama funciona

Por baixo dos panos, Ollama gerencia o ciclo de vida dos modelos automaticamente: carrega na memória quando necessário e descarrega após inatividade. Você interage via API REST local.

Instalação e Inicialização

Após instalar, o Ollama inicia automaticamente como serviço

No Linux, vira um serviço systemd. No Mac/Windows, inicia com o sistema. O servidor fica escutando na porta 11434.

Ollama Serve

O servidor HTTP é iniciado e fica aguardando requisições

Expõe dois conjuntos de endpoints: /api/* (nativo Ollama) e /v1/* (compatível OpenAI). Claude Code usa o endpoint /v1/chat/completions.

API em localhost:11434

Endpoints REST disponíveis localmente

Qualquer ferramenta que fale com a API OpenAI pode se conectar mudando apenas a base URL. A compatibilidade é o que permite usar Ollama com Claude Code sem patches.

Claude Code se Conecta

CC envia requisições para o Ollama em vez da Anthropic

Via ANTHROPIC_BASE_URL apontando para localhost:11434, todas as chamadas são redirecionadas. O modelo local responde como se fosse um modelo Anthropic.

🔌 Endpoints Principais

• GET :11434/api/tags — lista modelos instalados
• POST :11434/api/generate — geração de texto (nativo)
• POST :11434/v1/chat/completions — chat (compatível OpenAI)
• GET :11434/v1/models — lista modelos (formato OpenAI)

💻 Requisitos de Hardware

O hardware disponível é o fator limitante principal ao usar Ollama. RAM é o gargalo — o modelo precisa caber inteiro na memória (RAM ou VRAM) para rodar com velocidade aceitável.

Tabela de Requisitos

RAM Disponível	Tamanho Suportado	Modelos Recomendados	Performance
8 GB	7B – 8B	granite3.3:8b, glm-4.7-flash:9b	Moderada
16 GB	14B – 20B	devstral-2-small:24b (quantizado)	Boa
32 GB	30B+	qwen3-coder:30b	Muito Boa
Apple Silicon 24GB	24B (memória unificada)	devstral-2-small:24b	Excelente
GPU 8GB VRAM	7B – 8B (na GPU)	granite3.3:8b	Excelente
GPU 24GB VRAM	30B	qwen3-coder:30b	Excelente

⚠️ Atenção: CPU sem GPU

Sem GPU, Ollama usa a CPU para inferência. Funciona, mas é muito mais lento — espere 5-20 tokens/segundo em vez de 30-100+. Para Claude Code, onde latência impacta produtividade, considere GPU ou usar modelos menores.

⬇️ Instalando Ollama

A instalação do Ollama é deliberadamente simples. No Linux e Mac, um único comando faz tudo. No Windows, há um instalador gráfico. Em todos os casos, o servidor inicia automaticamente após a instalação.

🐧

Linux — 1 comando

Instala e configura o serviço systemd automaticamente

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

🍎

macOS — 2 opções

Instalador gráfico (.dmg) ou via Homebrew

# Opção 1: baixar .dmg em ollama.com/download
# Opção 2: via Homebrew
brew install ollama

🪟

Windows — Instalador .exe

Baixar e executar o instalador do site oficial

# Baixar em: ollama.com/download/windows
# Executar OllamaSetup.exe
# Ollama inicia automaticamente na bandeja do sistema

✅ Verificando a Instalação

Após instalar, verifique se o servidor está rodando:

curl http://localhost:11434
# Deve retornar: "Ollama is running"

🎮 Comandos Básicos

O CLI do Ollama tem comandos simples e intuitivos para gerenciar todo o ciclo de vida dos modelos. Memorize estes 6 comandos e você terá controle completo sobre seus modelos locais.

🎮 Referência de Comandos

ollama pull qwen3-coder     # baixar modelo do repositório
ollama list                  # listar modelos instalados
ollama run qwen3-coder       # iniciar chat interativo
ollama serve                 # iniciar servidor (geralmente automático)
ollama show qwen3-coder      # ver info do modelo (contexto, parâmetros)
ollama rm qwen3-coder        # remover modelo da máquina

📥 Gerenciar Modelos

pull — baixa um modelo (retomável se interrompido)
list — mostra nome, tamanho e data de download
rm — remove da máquina (libera espaço em disco)
show --modelfile — mostra parâmetros internos do modelo

🖥️ Executar e Servir

run — abre chat interativo no terminal
run --nowordwrap — sem quebra de linha automática
serve — inicia servidor HTTP na porta 11434
ps — lista modelos carregados na memória

💡 Dica: Verificar Contexto do Modelo

Antes de usar um modelo com Claude Code, verifique o tamanho da janela de contexto:

ollama show qwen3-coder --modelfile | grep context

Procure por num_ctx no output. Valores abaixo de 32768 podem causar problemas com arquivos grandes.

📋 Resumo do Módulo

✓

Ollama é um servidor local — roda LLMs na sua máquina sem enviar dados para a nuvem

✓

API compatível com OpenAI — em localhost:11434, permite conectar Claude Code sem modificações

✓

RAM é o gargalo principal — 8GB para modelos 7B, 16GB para 14B, 32GB para 30B+

✓

Instalação em 1 linha — curl no Linux/Mac, .exe no Windows

✓

6 comandos essenciais — pull, list, run, serve, show, rm

✓

100% gratuito após download — zero custo por token, funciona offline

Próximo Módulo:

3.2 — Escolhendo o Modelo Certo: tabelas RAM, modelos recomendados 2026 e benchmarks

← Voltar para Trilha 3 Próximo Módulo →