Tutorial prático: Ollama no Windows, macOS e Linux

Sejam bem-vindos ao módulo dedicado ao Ollama.

Até agora, muitos projetos de inteligência artificial são construídos consumindo APIs de modelos na nuvem, como OpenAI, Anthropic, Google ou outros provedores. Essa abordagem é muito poderosa, mas não é a única.

Neste tutorial vamos trabalhar com outro cenário: executar modelos de linguagem diretamente no nosso próprio computador.

Isso é importante por várias razões:

Privacidade local: se forem usados modelos baixados e executados localmente, os prompts e respostas não precisam sair da máquina.
Custo por inferência: não há custo por token ao executar modelos locais, embora existam custos indiretos de hardware, energia e armazenamento.
Aprendizado técnico: entender como os modelos são baixados, carregados, executados e expostos ajuda a compreender melhor os sistemas de IA reais.
Prototipagem rápida: permite experimentar sem depender sempre de uma API externa.
Integração: o Ollama expõe uma API HTTP local que pode ser consumida a partir de Python, Node.js, .NET, aplicações web, ferramentas RAG e agentes.

O tutorial foi pensado para equipes mistas: Windows, macOS e Linux. Primeiro veremos os conceitos comuns e depois as diferenças específicas de cada sistema operacional.

Sumário

O que é Ollama
Quando convém usar modelos locais
Requisitos do sistema
Instalação por sistema operacional
Verificação da instalação
Como reiniciar o Ollama
Primeiro modelo local
Comandos essenciais da CLI
Onde os modelos são salvos
Variáveis de ambiente por sistema operacional
API REST do Ollama
Integração com Python
Embeddings para RAG
Como saber se usa CPU ou GPU
Context length
Compatibilidade com a API da OpenAI
Boas práticas
Erros frequentes por sistema operacional
Exercícios propostos
Encerramento

1. O que é Ollama

O Ollama é uma ferramenta que permite baixar, gerenciar e executar modelos de linguagem de forma local.

Uma maneira simples de entendê-lo é pensar no Ollama como um ambiente de execução para modelos de IA. O usuário pede um modelo pelo nome, o Ollama o baixa caso não esteja disponível, carrega-o em memória e permite usá-lo a partir de:

linha de comando;
uma API HTTP local;
bibliotecas como Python ou JavaScript;
integrações compatíveis com APIs estilo OpenAI.

Por padrão, o servidor local do Ollama fica disponível em:

http://localhost:11434

E sua API base fica disponível em:

http://localhost:11434/api

Componentes principais

Componente	Descrição
Servidor Ollama	Processo que executa modelos e atende requisições locais.
CLI `ollama`	Comando para baixar, executar, listar e administrar modelos.
API REST	API HTTP local para integrar modelos em aplicações.
Modelos	Arquivos baixados localmente que contêm os pesos do modelo.

2. Quando convém usar modelos locais

O Ollama é especialmente útil quando se quer:

aprender como os modelos funcionam localmente;
testar prompts sem custo por token;
construir protótipos privados;
fazer testes de RAG em uma máquina de desenvolvimento;
executar modelos sem conexão permanente à internet;
integrar IA em ferramentas internas;
comparar modelos pequenos antes de usar modelos cloud mais potentes.

Comparação rápida

Aspecto	Ollama local	APIs cloud
Privacidade	Alta se o modelo rodar localmente	Depende do provedor
Custo por token	Sem custo direto por token	Custo por uso
Qualidade máxima	Limitada pelo hardware e modelo local	Acesso a modelos de fronteira
Velocidade	Depende de CPU/GPU local	Depende da rede e do provedor
Offline	Sim, depois de baixar o modelo	Não
Manutenção	A cargo do usuário	A cargo do provedor

Regra prática: use o Ollama para aprender, prototipar e construir soluções locais; use APIs cloud quando precisar de qualidade máxima, escalabilidade gerenciada ou modelos de fronteira.

3. Requisitos do sistema

Os requisitos dependem do modelo que se queira executar.

Requisitos gerais

8 GB de RAM no mínimo para modelos pequenos.
16 GB de RAM ou mais para trabalhar com mais conforto.
SSD recomendado.
Espaço livre suficiente: os modelos podem ocupar desde alguns GB até dezenas ou centenas de GB.
GPU recomendada para melhor desempenho, embora muitos modelos pequenos consigam rodar por CPU.

Windows

Requisitos típicos:

Windows 10 22H2 ou superior, ou Windows 11.
Drivers NVIDIA atualizados se for usada GPU NVIDIA.
Driver AMD Radeon atualizado se for usada GPU AMD Radeon.

macOS

Requisitos típicos:

macOS Sonoma 14 ou superior.
Apple Silicon série M com suporte a CPU/GPU.
Em Mac Intel/x86, esperar execução por CPU.

Linux

Requisitos típicos:

Distribuição Linux moderna.
systemd se for usar o Ollama como serviço, como acontece na instalação padrão.
Drivers NVIDIA ou AMD/ROCm corretamente instalados se quiser usar GPU.
Permissões para instalar serviços ou binários do sistema.

Regra prática de tamanho de modelo

Uma regra aproximada para modelos quantizados em 4 bits:

Modelo de N B parâmetros, onde B significa bilhões, ≈ N × 0.6 GB de RAM/VRAM

Nesse contexto, 7B significa aproximadamente 7 bilhões de parâmetros.

Exemplos aproximados:

Modelo	Memória aproximada	Comentário
3B	2 a 3 GB	Bom para máquinas modestas
7B / 8B	4 a 6 GB	Bom ponto de partida
13B / 14B	8 a 10 GB	Requer mais memória
32B	18 a 24 GB	Recomendável GPU grande ou bastante RAM
70B	40 GB ou mais	Uso avançado

Esses números são apenas indicativos. O consumo real depende da quantização, contexto, GPU, offloading e configuração do modelo.

4. Instalação por sistema operacional

4.1 Windows

Opção A: instalador gráfico

Acessar a página oficial de download do Ollama.
Baixar OllamaSetup.exe.
Executar o instalador.
Abrir um novo terminal PowerShell ou CMD.
Verificar:

ollama --version

No Windows, o Ollama fica em execução em segundo plano e o comando ollama fica disponível no PowerShell, CMD ou no terminal preferido.

Opção B: winget

Se for usado winget, é possível instalar com:

winget install Ollama.Ollama

Verificar se o servidor responde

curl.exe http://localhost:11434

A resposta esperada é semelhante a:

Ollama is running

No Windows PowerShell clássico, curl pode se comportar de modo diferente porque pode ser resolvido como alias. Para evitar problemas, use curl.exe ou Invoke-WebRequest.

4.2 macOS

Opção recomendada: aplicativo oficial

Baixar o arquivo .dmg na página oficial do Ollama.
Montar o .dmg.
Arrastar Ollama.app para Applications.
Abrir o Ollama.
Se o aplicativo solicitar permissão para instalar o comando ollama no PATH, aceitar.

Verificar pelo Terminal:

ollama --version

Verificar se o servidor responde:

curl http://localhost:11434

Alternativa com Homebrew

Em alguns ambientes de desenvolvimento pode-se preferir o Homebrew:

brew install --cask ollama-app

Em seguida, abrir o aplicativo Ollama e verificar:

ollama --version

4.3 Linux

Instalação com script oficial

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

Em seguida, iniciar e verificar o serviço:

sudo systemctl start ollama
sudo systemctl status ollama

Verificar a API:

curl http://localhost:11434

Resposta esperada:

Ollama is running

Nota de segurança

Em ambientes corporativos ou produtivos, é boa prática revisar qualquer script remoto antes de executá-lo.

Uma alternativa é baixá-lo, inspecioná-lo e depois executá-lo:

curl -fsSL https://ollama.com/install.sh -o install-ollama.sh
less install-ollama.sh
sh install-ollama.sh

5. Verificação da instalação

Os comandos básicos são iguais nos três sistemas.

Windows

ollama --version
curl.exe http://localhost:11434

macOS

ollama --version
curl http://localhost:11434

Linux

ollama --version
curl http://localhost:11434
sudo systemctl status ollama

Se tudo estiver correto, ollama --version mostrará a versão instalada e curl http://localhost:11434 responderá que o Ollama está em execução.

6. Como reiniciar o Ollama

Em várias partes deste tutorial vamos dizer “reiniciar o Ollama”. Convém deixar claro o que isso significa em cada sistema operacional.

Windows

Procurar o ícone do Ollama na bandeja do sistema.
Clicar com o botão direito.
Escolher Quit ou Sair.
Abrir o Ollama novamente pelo menu Iniciar.

Em seguida, verificar:

curl.exe http://localhost:11434

macOS

Clicar no ícone do Ollama na barra de menus.
Escolher Quit Ollama.
Abrir novamente Ollama.app em Applications.

Em seguida, verificar:

curl http://localhost:11434

Linux

Se o Ollama foi instalado como serviço systemd:

sudo systemctl restart ollama
sudo systemctl status ollama

Para revisar logs após o reinício:

journalctl -e -u ollama

7. Primeiro modelo local

Vamos executar um modelo leve para começar.

ollama run llama3.2

Na primeira vez, o Ollama baixará o modelo. Em seguida, abrirá uma sessão interativa:

>>> Send a message (/? for help)

Experimente:

Explica em uma frase o que é aprendizado supervisionado.

Para sair:

/bye

Ou também:

Ctrl+D

O que aconteceu por trás

Quando executamos:

ollama run llama3.2

O Ollama faz o seguinte:

Verifica se o modelo já está baixado.
Se não estiver baixado, faz o download a partir do registro de modelos.
Carrega o modelo em RAM ou VRAM.
Abre uma sessão interativa.
Mantém o modelo em memória por algum tempo para evitar recarregá-lo a cada consulta.

Por padrão, o Ollama mantém o modelo carregado durante 5 minutos após o último uso. Isso explica por que a RAM ou VRAM nem sempre baixa imediatamente ao terminar uma consulta.

Para liberar memória manualmente:

ollama stop llama3.2

Também é possível controlar com OLLAMA_KEEP_ALIVE ou com o parâmetro keep_alive na API.

8. Comandos essenciais da CLI

Esses comandos funcionam da mesma forma no Windows, macOS e Linux.

# Listar modelos baixados
ollama list

# Baixar um modelo sem executá-lo
ollama pull llama3.2

# Executar um modelo
ollama run llama3.2

# Ver modelos atualmente carregados em memória
ollama ps

# Parar um modelo carregado
ollama stop llama3.2

# Remover um modelo do disco
ollama rm llama3.2

# Ver informação do modelo
ollama show llama3.2

# Iniciar o servidor manualmente
ollama serve

Modelos recomendados para começar

Os tamanhos são indicativos. Podem variar conforme a tag exata, a quantização e a versão publicada do modelo. Antes de baixar um modelo grande, convém revisar sua ficha na biblioteca do Ollama.

Uso	Modelo sugerido	Tamanho aproximado	Comentário
Chat leve	`llama3.2`	~2 GB	Bom para equipamentos modestos
Chat geral	`gemma3`	~3 GB a ~17 GB	Depende da tag escolhida; comece pelas variantes pequenas
Chat geral / raciocínio	`qwen3`	~3 GB a ~5 GB	Bom desempenho em vários cenários
Código	`qwen2.5-coder`	~5 GB	Especializado em programação
Embeddings	`embeddinggemma`	<1 GB	Recomendado para embeddings
Embeddings leves	`all-minilm`	<1 GB	Rápido e leve

Se seu equipamento tem pouca VRAM, por exemplo 4 GB, convém começar pelos modelos leves e verificar com ollama ps se eles cabem completamente na GPU.

Para baixar uma variante específica, usa-se:

ollama pull nome-modelo:tag

Exemplo:

ollama pull llama3.1:8b

9. Onde os modelos são salvos

A localização exata pode variar conforme o sistema operacional e a forma de instalação.

Sistema	Localização típica
Windows	`%USERPROFILE%\.ollama` ou `%HOMEPATH%\.ollama`
macOS	`~/.ollama`
Linux	Geralmente sob o usuário/serviço do Ollama; pode variar conforme a instalação

Windows

Para abrir a pasta de modelos e configuração:

explorer %USERPROFILE%\.ollama

Para abrir os logs:

explorer %LOCALAPPDATA%\Ollama

macOS

Modelos e configuração:

ls ~/.ollama

Logs:

ls ~/.ollama/logs
cat ~/.ollama/logs/server.log

Linux

Ver logs do serviço:

journalctl -e -u ollama

Ou em modo de acompanhamento:

journalctl -u ollama --no-pager --follow --pager-end

10. Variáveis de ambiente por sistema operacional

O Ollama é configurado por meio de variáveis de ambiente.

Variáveis comuns:

Variável	Uso
`OLLAMA_HOST`	Endereço e porta onde o Ollama escuta.
`OLLAMA_MODELS`	Pasta onde os modelos são salvos.
`OLLAMA_KEEP_ALIVE`	Tempo em que um modelo permanece carregado. Por padrão, 5 minutos.
`OLLAMA_NUM_PARALLEL`	Controle de requisições paralelas.
`OLLAMA_ORIGINS`	Origens permitidas para CORS.
`OLLAMA_CONTEXT_LENGTH`	Contexto efetivo padrão para os modelos, quando aplicável.
`OLLAMA_FLASH_ATTENTION`	Pode ativar Flash Attention se o hardware suportar.

10.1 Windows

No Windows, o Ollama herda as variáveis de ambiente do usuário ou do sistema.

Passos:

Fechar o Ollama na bandeja do sistema.
Abrir Configurações ou Painel de Controle.
Procurar “variáveis de ambiente”.
Editar variáveis de ambiente do usuário.
Criar ou editar variáveis como OLLAMA_MODELS, OLLAMA_HOST, OLLAMA_KEEP_ALIVE.
Salvar.
Abrir o Ollama novamente pelo menu Iniciar.

Exemplos:

OLLAMA_MODELS=D:\OllamaModels
OLLAMA_HOST=127.0.0.1:11434
OLLAMA_KEEP_ALIVE=5m

10.2 macOS

Se o Ollama é executado como aplicativo macOS, configure variáveis com launchctl.

Exemplos:

launchctl setenv OLLAMA_HOST "127.0.0.1:11434"
launchctl setenv OLLAMA_MODELS "$HOME/OllamaModels"
launchctl setenv OLLAMA_KEEP_ALIVE "5m"

Em seguida, fechar e abrir novamente o Ollama.app.

Para verificar uma variável:

launchctl getenv OLLAMA_HOST

10.3 Linux

Se o Ollama roda como serviço systemd, edite o serviço:

sudo systemctl edit ollama.service

Adicionar:

[Service]
Environment="OLLAMA_HOST=127.0.0.1:11434"
Environment="OLLAMA_MODELS=/mnt/models/ollama"
Environment="OLLAMA_KEEP_ALIVE=5m"

Aplicar mudanças:

sudo systemctl daemon-reload
sudo systemctl restart ollama
sudo systemctl status ollama

Verificar variáveis aplicadas ao serviço:

systemctl show ollama | grep Environment

Ver logs:

journalctl -e -u ollama

10.4 Acesso a partir de outras máquinas da rede local

Por padrão, o Ollama escuta em 127.0.0.1:11434, ou seja, só aceita conexões da mesma máquina.

Para aceitar conexões de outras máquinas da rede local, é possível usar:

OLLAMA_HOST=0.0.0.0:11434

Em seguida, é preciso reiniciar o Ollama de acordo com o sistema operacional.

Uma vez configurado, a partir de outra máquina da rede seria possível chamar:

curl http://IP_DA_MAQUINA:11434

Aviso de segurança: não exponha o Ollama diretamente à internet. O Ollama local não traz autenticação nativa pensada para exposição pública. Se precisar de acesso remoto, use firewall, VPN, reverse proxy com autenticação e regras de rede restritivas.

11. API REST do Ollama

A API local do Ollama fica disponível em:

http://localhost:11434/api

11.1 Endpoint `/api/generate`

Esse endpoint gera texto a partir de um prompt.

Windows PowerShell

(Invoke-WebRequest `
  -Method POST `
  -Uri http://localhost:11434/api/generate `
  -ContentType "application/json" `
  -Body '{
    "model": "llama3.2",
    "prompt": "Explica o que é regressão logística.",
    "stream": false
  }'
).Content | ConvertFrom-Json

macOS / Linux

curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "prompt": "Explica o que é regressão logística.",
    "stream": false
  }'

11.2 Endpoint `/api/chat`

Esse endpoint permite trabalhar com mensagens e papéis.

Windows PowerShell

(Invoke-WebRequest `
  -Method POST `
  -Uri http://localhost:11434/api/chat `
  -ContentType "application/json" `
  -Body '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "system",
        "content": "Você é um assistente especialista em estatística."
      },
      {
        "role": "user",
        "content": "Explica a diferença entre variância e desvio padrão."
      }
    ],
    "stream": false
  }'
).Content | ConvertFrom-Json

macOS / Linux

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "system",
        "content": "Você é um assistente especialista em estatística."
      },
      {
        "role": "user",
        "content": "Explica a diferença entre variância e desvio padrão."
      }
    ],
    "stream": false
  }'

11.3 `keep_alive` na API

Por padrão, o Ollama mantém o modelo carregado em memória por aproximadamente 5 minutos após uma consulta. Isso melhora a resposta caso sejam feitas várias consultas seguidas.

Para descarregar o modelo imediatamente após responder:

curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "prompt": "Responde brevemente: o que é Ollama?",
    "stream": false,
    "keep_alive": 0
  }'

Para mantê-lo carregado indefinidamente enquanto o servidor continuar em execução:

curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "prompt": "Pré-carrega o modelo.",
    "stream": false,
    "keep_alive": -1
  }'

Também é possível liberar manualmente pela CLI:

ollama stop llama3.2

12. Integração com Python

Instalar o cliente oficial:

pip install ollama

Chat básico

import ollama

resposta = ollama.chat(
    model="llama3.2",
    messages=[
        {
            "role": "user",
            "content": "Me dá 3 técnicas para evitar overfitting."
        }
    ]
)

print(resposta["message"]["content"])

Streaming

import ollama

stream = ollama.chat(
    model="llama3.2",
    messages=[
        {
            "role": "user",
            "content": "Me conta uma história curta sobre IA."
        }
    ],
    stream=True
)

for chunk in stream:
    print(chunk["message"]["content"], end="", flush=True)

Chat com system prompt

import ollama

resposta = ollama.chat(
    model="llama3.2",
    messages=[
        {
            "role": "system",
            "content": "Responda sempre em português claro e com exemplos simples."
        },
        {
            "role": "user",
            "content": "O que é uma rede neural?"
        }
    ]
)

print(resposta["message"]["content"])

13. Embeddings para RAG

Os embeddings convertem texto em vetores numéricos. São fundamentais para construir sistemas de busca semântica e RAG.

Baixar um modelo de embeddings

ollama pull embeddinggemma

Você também pode avaliar modelos como:

ollama pull all-minilm

Endpoint `/api/embed`

Windows PowerShell

(Invoke-WebRequest `
  -Method POST `
  -Uri http://localhost:11434/api/embed `
  -ContentType "application/json" `
  -Body '{
    "model": "embeddinggemma",
    "input": "O gato sentou no tapete."
  }'
).Content | ConvertFrom-Json

macOS / Linux

curl http://localhost:11434/api/embed \
  -H "Content-Type: application/json" \
  -d '{
    "model": "embeddinggemma",
    "input": "O gato sentou no tapete."
  }'

Embeddings com Python

import ollama

resp = ollama.embed(
    model="embeddinggemma",
    input="O gato sentou no tapete."
)

vector = resp["embeddings"][0]
print(len(vector))
print(vector[:5])

Mini busca semântica com Python

import ollama
import numpy as np

textos = [
    "O perceptron é um modelo linear de classificação.",
    "As redes convolucionais são úteis para imagens.",
    "Os transformers usam mecanismos de atenção.",
    "O overfitting ocorre quando um modelo memoriza demais o treinamento."
]

resp = ollama.embed(
    model="embeddinggemma",
    input=textos
)

vetores = np.array(resp["embeddings"])

consulta = "Qual arquitetura usa atenção?"
resp_consulta = ollama.embed(
    model="embeddinggemma",
    input=consulta
)

v_consulta = np.array(resp_consulta["embeddings"][0])

similaridades = vetores @ v_consulta / (
    np.linalg.norm(vetores, axis=1) * np.linalg.norm(v_consulta)
)

idx = similaridades.argmax()

print("Texto mais relevante:")
print(textos[idx])
print("Similaridade:", similaridades[idx])

14. Como saber se usa CPU ou GPU

Uma das dúvidas mais frequentes ao usar o Ollama é se o modelo realmente está usando a GPU.

Não convém se guiar apenas pelos gráficos visuais do sistema operacional. O Gerenciador de Tarefas do Windows, o Monitor de Atividade no macOS ou algumas ferramentas gráficas podem mostrar informações parciais ou difíceis de interpretar.

A forma mais direta de ver isso pelo Ollama é:

ollama ps

A coluna importante é PROCESSOR.

Exemplo conceitual:

NAME        ID              SIZE      PROCESSOR    CONTEXT    UNTIL
llama3.2    abc123          2.0 GB    100% GPU     4096       4 minutes from now

A coluna CONTEXT indica o contexto efetivo carregado para esse modelo. Veremos isso com mais detalhe na próxima seção, dedicada ao context length.

Valor	Significado
`100% GPU`	O modelo está totalmente carregado na GPU.
`100% CPU`	O modelo está carregado na memória do sistema e roda pela CPU.
`48%/52% CPU/GPU`	Uma parte do modelo está em CPU/RAM e outra parte em GPU/VRAM.

Se o modelo aparecer dividido entre CPU e GPU, pode funcionar, mas normalmente será mais lento do que se couber inteiramente em VRAM.

Por que pode haver CPU mesmo com `100% GPU`

Embora ollama ps mostre 100% GPU, é normal ver algum uso de CPU. A CPU continua participando em tarefas como:

tokenização;
coordenação da execução;
entrada e saída;
sampling;
comunicação com o servidor local.

Por isso, não se deve interpretar “uso de CPU” como sinônimo automático de “não está usando GPU”.

Windows: cuidado com o Gerenciador de Tarefas

No Windows, o Gerenciador de Tarefas pode confundir. O gráfico 3D nem sempre representa computação CUDA nem o uso real do modelo.

Para NVIDIA, é melhor abrir outro terminal e executar:

nvidia-smi

Também execute:

ollama ps

enquanto o modelo está respondendo.

Se ollama ps mostrar 100% GPU, o modelo entrou completo na GPU mesmo que o gráfico 3D do Gerenciador de Tarefas não pareça se mexer.

Linux com NVIDIA

nvidia-smi
ollama ps

O nvidia-smi permite ver memória VRAM utilizada, processos ativos e carga da GPU.

Linux com AMD

A verificação depende da instalação AMD/ROCm e da distribuição. Mesmo assim, ollama ps continua sendo o primeiro diagnóstico prático para ver se o Ollama carregou o modelo em CPU, GPU ou ambos.

macOS

No Apple Silicon, o Ollama pode usar aceleração via Metal. Para diagnóstico prático:

ollama ps

Também é possível revisar o consumo geral com o Monitor de Atividade, mas a interpretação mais útil para o Ollama costuma ser a coluna PROCESSOR.

Métrica objetiva: tokens por segundo

Para comparar desempenho real, não basta olhar gráficos de CPU/GPU. A métrica mais útil é a velocidade de geração.

Uma forma simples de vê-la pela CLI é executar o modelo em modo verbose:

ollama run llama3.2 --verbose

A flag --verbose funciona da mesma forma no Windows, macOS e Linux. Pode ser usada pelo PowerShell, Terminal ou um shell Bash.

Ao terminar a resposta, o Ollama mostra métricas como:

prompt eval rate:  1200.00 tokens/s
eval rate:           45.00 tokens/s

A métrica eval rate indica aproximadamente quantos tokens por segundo o modelo gera. Quanto maior, mais rápida é a geração.

Pela API, as respostas finais também incluem métricas como eval_count e eval_duration. A velocidade aproximada pode ser calculada assim:

tokens_por_segundo = eval_count / eval_duration * 1_000_000_000

porque eval_duration é expresso em nanossegundos.

Diagnóstico rápido quando um modelo está lento

Executar ollama ps.
Verificar se PROCESSOR diz 100% GPU, 100% CPU ou uma mistura.
Se houver mistura CPU/GPU, testar um modelo menor ou contexto menor.
Medir com --verbose.
Comparar eval rate entre modelos.
Verificar a VRAM com nvidia-smi se for usada NVIDIA.
Evitar supor que o Gerenciador de Tarefas reflete toda a atividade de computação do modelo.

15. Context length

O context length é a quantidade máxima de tokens que o modelo pode considerar em uma consulta.

Isso importa muito em:

RAG;
análise de documentos longos;
agentes;
assistentes de código;
conversas extensas.

Contexto máximo vs contexto efetivo

É preciso distinguir dois conceitos:

Conceito	Significado
Contexto máximo do modelo	O que o modelo poderia suportar conforme sua arquitetura ou configuração.
Contexto efetivo	O que o Ollama realmente usa em uma execução concreta.

O contexto efetivo é controlado por num_ctx na API ou por configuração equivalente. Se não for especificado, o Ollama aplica um valor padrão que pode ser menor que o contexto máximo suportado pelo modelo.

Isso costuma surpreender quem vem de APIs cloud, onde muitas vezes se assume que se está usando automaticamente todo o contexto disponível.

Ver contexto e offloading

Executar:

ollama ps

Em versões recentes, a saída pode incluir uma coluna CONTEXT, além de PROCESSOR.

Exemplo conceitual:

NAME             ID              SIZE      PROCESSOR    CONTEXT    UNTIL
gemma3:latest    a2af6cc3eb7f    6.6 GB    100% GPU     65536      2 minutes from now

Isso permite verificar duas coisas ao mesmo tempo:

quanto contexto está sendo usado;
se o modelo entrou completo na GPU ou ficou dividido entre CPU/GPU.

Configurar contexto na API

Exemplo de uso em /api/chat:

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "user",
        "content": "Resume este texto longo..."
      }
    ],
    "stream": false,
    "options": {
      "num_ctx": 8192
    }
  }'

Mais contexto nem sempre é melhor

Aumentar o contexto pode permitir trabalhar com textos mais longos, mas também pode:

consumir mais RAM ou VRAM;
fazer com que parte do modelo seja descarregada para a CPU;
reduzir os tokens por segundo;
aumentar o tempo de resposta.

Em modelos locais, convém medir. Para muitas tarefas simples, um contexto menor pode ser mais rápido e suficiente.

Configuração global

Também é possível configurar por meio de uma variável de ambiente:

OLLAMA_CONTEXT_LENGTH=8192

Após alterá-la, reinicie o Ollama.

16. Compatibilidade com a API da OpenAI

O Ollama também oferece compatibilidade com endpoints estilo OpenAI.

Isso permite reaproveitar parte do código existente alterando a URL base.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

resposta = client.chat.completions.create(
    model="llama3.2",
    messages=[
        {
            "role": "user",
            "content": "Olá, me explica o que é Ollama."
        }
    ]
)

print(resposta.choices[0].message.content)

A API key pode ser qualquer string ao usar o servidor local, porque o Ollama local não valida uma API key como faria um provedor cloud.

17. Boas práticas

1. Não baixar modelos sem critério

Cada modelo pode ocupar vários GB. Antes de baixar, revise tamanho, propósito e requisitos.

ollama show llama3.2

2. Usar tags explícitas quando importar reprodutibilidade

Em projetos reais, evite depender de aliases ambíguos.

Melhor:

ollama run llama3.1:8b

Em vez de depender sempre de um alias genérico.

3. Separar modelo de geração e modelo de embeddings

Em sistemas RAG, é comum usar:

um modelo de embeddings rápido;
um modelo de chat/geração de melhor qualidade.

Exemplo:

Embeddings: embeddinggemma
Geração: llama3.2, gemma3, qwen3 ou outro modelo de chat

4. Não expor o Ollama diretamente à internet

Se for configurado:

OLLAMA_HOST=0.0.0.0:11434

O Ollama pode aceitar conexões de outras máquinas.

Isso pode ser útil em rede local, mas não deve ser exposto diretamente à internet sem autenticação, firewall e reverse proxy seguro.

5. Medir desempenho

Para comparar modelos:

medir tempo de carga;
medir tokens por segundo;
medir consumo de RAM/VRAM;
verificar se usa CPU ou GPU com ollama ps.

6. Cuidar do CORS

Se o Ollama for consumido a partir de uma aplicação web local, pode ser necessário configurar OLLAMA_ORIGINS.

Em desenvolvimento pode ser usado algo amplo, mas em produção deve ser restrito.

18. Erros frequentes por sistema operacional

18.1 Windows

`ollama` não é reconhecido como comando

Feche o terminal e abra um novo.

Se continuar falhando, verifique se o Ollama está instalado e se o PATH do usuário foi atualizado.

`curl` não funciona como esperado

No PowerShell clássico, use:

curl.exe http://localhost:11434

Ou use:

Invoke-WebRequest http://localhost:11434

Caracteres estranhos na barra de progresso

Pode ocorrer por causa de fontes antigas no Windows 10. Mude a fonte do terminal, por exemplo para Cascadia Code, ou use o Windows Terminal.

Pouco espaço no disco C:

Configure:

OLLAMA_MODELS=D:\OllamaModels

Em seguida, reinicie o Ollama.

Não usa GPU

Verifique:

ollama ps

Verifique também os drivers NVIDIA/AMD e o consumo da GPU no Gerenciador de Tarefas.

18.2 macOS

A CLI não aparece

Abra Ollama.app e aceite a criação do link da CLI se for solicitado.

Você também pode verificar:

which ollama

As variáveis de ambiente não são aplicadas

Use launchctl setenv e reinicie o Ollama.app.

Exemplo:

launchctl setenv OLLAMA_HOST "127.0.0.1:11434"

Desempenho baixo em Mac Intel

Em Mac Intel/x86, esperar execução pela CPU. Para melhor desempenho local, o Apple Silicon série M costuma ser mais adequado.

Ver logs

cat ~/.ollama/logs/server.log

18.3 Linux

O serviço não inicia

sudo systemctl status ollama

Ver logs

journalctl -e -u ollama

Ou:

journalctl -u ollama --no-pager --follow --pager-end

Alterei variáveis e elas não são aplicadas

Após editar o serviço:

sudo systemctl daemon-reload
sudo systemctl restart ollama

GPU NVIDIA não detectada

Verifique:

nvidia-smi

Se não funcionar, revise a instalação dos drivers NVIDIA.

GPU AMD não detectada

Revise os drivers AMD/ROCm conforme a distribuição e o hardware.

19. Exercícios propostos

Exercício 1 — Instalação e verificação

Instale o Ollama no seu sistema operacional e entregue:

ollama --version
ollama list

Em seguida execute:

curl http://localhost:11434

No Windows pode ser usado:

curl.exe http://localhost:11434

Exercício 2 — Primeiro modelo

Baixe e execute:

ollama run llama3.2

Prompt:

Explica o aprendizado supervisionado em uma frase e depois dê um exemplo prático.

Salve a resposta.

Exercício 3 — Comparação de modelos

Compare dois modelos, por exemplo:

ollama run llama3.2
ollama run gemma3

Use o mesmo prompt:

Explica o teorema de Bayes com um exemplo médico.

Compare:

qualidade da resposta;
velocidade percebida;
consumo de RAM/VRAM;
uso de CPU/GPU com ollama ps.

Exercício 4 — API REST

Chame /api/chat a partir do sistema operacional correspondente.

Windows

(Invoke-WebRequest `
  -Method POST `
  -Uri http://localhost:11434/api/chat `
  -ContentType "application/json" `
  -Body '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "user",
        "content": "Me dá 5 ideias de projetos simples com IA local."
      }
    ],
    "stream": false
  }'
).Content | ConvertFrom-Json

macOS / Linux

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "user",
        "content": "Me dá 5 ideias de projetos simples com IA local."
      }
    ],
    "stream": false
  }'

Exercício 5 — Cliente Python

Crie um script que:

Leia perguntas a partir de um arquivo preguntas.txt.
Envie cada pergunta ao modelo usando ollama.chat.
Salve as respostas em um arquivo JSON com timestamp.

Exemplo base:

import json
from datetime import datetime
import ollama

with open("preguntas.txt", "r", encoding="utf-8") as f:
    perguntas = [line.strip() for line in f if line.strip()]

resultados = []

for pergunta in perguntas:
    resposta = ollama.chat(
        model="llama3.2",
        messages=[
            {
                "role": "user",
                "content": pergunta
            }
        ]
    )

    resultados.append({
        "pergunta": pergunta,
        "resposta": resposta["message"]["content"],
        "timestamp": datetime.now().isoformat()
    })

with open("respostas.json", "w", encoding="utf-8") as f:
    json.dump(resultados, f, ensure_ascii=False, indent=2)

Exercício 6 — Mini RAG completo

Na seção de embeddings já vimos como buscar o parágrafo mais similar. Neste exercício, é preciso completar o fluxo RAG:

Pegue 10 parágrafos sobre inteligência artificial.
Gere embeddings com embeddinggemma.
Salve os vetores em memória.
Dada uma pergunta, busque o parágrafo mais similar.
Passe esse parágrafo como contexto ao modelo de chat.
Peça ao modelo que responda somente usando esse contexto.
Se o contexto não for suficiente, o modelo deve responder: “Não tenho informação suficiente no contexto”.

Prompt sugerido para a geração:

Responda à pergunta usando apenas o contexto fornecido.

Se o contexto não contiver informação suficiente, responda:
"Não tenho informação suficiente no contexto".

Contexto:
{{contexto}}

Pergunta:
{{pergunta}}

Exercício 7 — Análise de desempenho

Execute um mesmo prompt com dois modelos diferentes e registre:

tempo de carga;
tempo total;
uso de CPU/GPU;
qualidade percebida;
tamanho do modelo.

Use:

ollama ps

20. Encerramento

Com este tutorial você já consegue instalar e usar o Ollama no Windows, macOS e Linux, executar modelos locais, consumir a API REST, integrá-lo com Python e gerar embeddings para sistemas RAG.

O Ollama é uma ferramenta muito útil para aprender IA aplicada, experimentar com modelos locais e construir protótipos privados. Ele nem sempre substitui os modelos cloud mais avançados, mas permite entender melhor a arquitetura de uma solução de inteligência artificial moderna.

Nos próximos módulos pode-se avançar para:

sistemas RAG completos;
integração com bases vetoriais;
agentes;
ferramentas internas para empresas;
assistentes de código;
implantações locais controladas.

Fontes oficiais recomendadas

Documentação geral do Ollama: https://docs.ollama.com
API do Ollama: https://docs.ollama.com/api/introduction
Instalação no Windows: https://docs.ollama.com/windows
Instalação no macOS: https://docs.ollama.com/macos
Instalação no Linux: https://docs.ollama.com/linux
Embeddings: https://docs.ollama.com/capabilities/embeddings
Endpoint /api/embed: https://docs.ollama.com/api/embed
Troubleshooting: https://docs.ollama.com/troubleshooting
Context length: https://docs.ollama.com/context-length
Métricas de uso e desempenho: https://docs.ollama.com/api/usage
Biblioteca de modelos: https://ollama.com/library

Tutorial prático: Ollama no Windows, macOS e Linux

Sumário

1. O que é Ollama

Componentes principais

2. Quando convém usar modelos locais

Comparação rápida

3. Requisitos do sistema

Requisitos gerais

Windows

macOS

Linux

Regra prática de tamanho de modelo

4. Instalação por sistema operacional

4.1 Windows

Opção A: instalador gráfico

Opção B: winget

Verificar se o servidor responde

4.2 macOS

Opção recomendada: aplicativo oficial

Alternativa com Homebrew

4.3 Linux

Instalação com script oficial

Nota de segurança

5. Verificação da instalação

Windows

macOS

Linux

6. Como reiniciar o Ollama

Windows

macOS

Linux

7. Primeiro modelo local

O que aconteceu por trás

8. Comandos essenciais da CLI

Modelos recomendados para começar

9. Onde os modelos são salvos

Windows

macOS

Linux

10. Variáveis de ambiente por sistema operacional

10.1 Windows

10.2 macOS

10.3 Linux

10.4 Acesso a partir de outras máquinas da rede local

11. API REST do Ollama

11.1 Endpoint /api/generate

Windows PowerShell

macOS / Linux

11.2 Endpoint /api/chat

Windows PowerShell

macOS / Linux

11.3 keep_alive na API

12. Integração com Python

Chat básico

Streaming

Chat com system prompt

13. Embeddings para RAG

Baixar um modelo de embeddings

Endpoint /api/embed

Windows PowerShell

macOS / Linux

Embeddings com Python

Mini busca semântica com Python

14. Como saber se usa CPU ou GPU

Por que pode haver CPU mesmo com 100% GPU

Windows: cuidado com o Gerenciador de Tarefas

Linux com NVIDIA

Linux com AMD

macOS

Métrica objetiva: tokens por segundo

Diagnóstico rápido quando um modelo está lento

15. Context length

Contexto máximo vs contexto efetivo

Ver contexto e offloading

Configurar contexto na API

Mais contexto nem sempre é melhor

Configuração global

16. Compatibilidade com a API da OpenAI

17. Boas práticas

1. Não baixar modelos sem critério

11.1 Endpoint `/api/generate`

11.2 Endpoint `/api/chat`

11.3 `keep_alive` na API

Endpoint `/api/embed`

Por que pode haver CPU mesmo com `100% GPU`

`ollama` não é reconhecido como comando

`curl` não funciona como esperado