Como Executar um LLM Local com o Ollama

Cada chamada a uma API de LLM hospedada envia seu prompt para o servidor de outra pessoa e cobra por token. Perdeu a rede, ela para de responder. O Ollama tira os dois problemas do caminho: baixa um modelo de pesos abertos para a sua máquina e o disponibiliza por uma API REST em localhost:11434. Um único binário funciona como gerenciador de modelos, cliente de chat e servidor.

O que o Ollama faz de verdade

O Ollama usa o llama.cpp e engines de inferência parecidas por baixo dos panos, então você nunca precisa mexer numa flag de compilador ou num caminho de biblioteca CUDA. ollama pull llama3.2 baixa um arquivo de modelo quantizado (formato GGUF) do próprio registro do Ollama em vez do Hugging Face, embora também consiga importar arquivos GGUF de lá. Ao executar o modelo, o Ollama entrega esses pesos a um servidor em segundo plano, que os carrega na RAM (ou VRAM, se encontrar uma GPU compatível), os mantém residentes por alguns minutos após a última requisição para que a próxima seja rápida, e os descarrega assim que você para de fazer perguntas.

A CLI, a API e o sistema de Modelfiles giram em torno da mesma tarefa: colocar os pesos em memória e rotear requisições até eles.

Como instalar o Ollama e executar seu primeiro modelo

No Linux ou macOS:

1

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

No Windows, execute o instalador em ollama.com, ou use:

1

irm https://ollama.com/install.ps1 | iex

De qualquer forma, o resultado é a CLI ollama e um servidor em segundo plano escutando na porta 11434. Baixe um modelo pequeno e converse com ele:

1
2

ollama pull llama3.2
ollama run llama3.2

ollama run te leva a um prompt interativo. Faça uma pergunta, leia a resposta, /bye para sair. Outros três comandos que você vai usar o tempo todo:

1
2
3

ollama list   # modelos baixados, com o tamanho em disco
ollama ps     # modelos carregados atualmente na memória
ollama rm llama3.2   # libera o espaço em disco

llama3.2 é uma boa primeira escolha: cerca de 2 GB, rápido o suficiente para rodar na CPU de um notebook. Não é o modelo mais forte da sua faixa de tamanho. O gemma4 lidera a faixa pequena atualmente e também processa imagens, e o qwen3-coder é a melhor escolha se você está testando assistência de código. Comece com o llama3.2 mesmo assim, porque ele prova que sua configuração funciona antes de você se comprometer com um download de 20 GB.

Como conversar com o Ollama pela API REST

O prompt interativo serve para conferir se tudo funciona. Qualquer coisa que você construir vai chamar a API. O formato nativo do Ollama é este:

1
2
3
4
5

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Write a one-line commit message for a typo fix in README.md",
  "stream": false
}'

Com "stream": false você recebe um único objeto JSON, incluindo eval_count e eval_duration, suficiente para medir tokens por segundo no seu próprio hardware. Coloque em true e você recebe, em vez disso, uma série de objetos de resposta parcial, o que uma interface de chat precisa.

Para conversas com várias interações, /api/chat recebe um array messages no mesmo formato usado pela API da OpenAI:

1
2
3
4
5
6
7

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [
    {"role": "user", "content": "What port does Ollama listen on by default?"}
  ],
  "stream": false
}'

O Ollama também fala nativamente o formato da API da OpenAI em /v1, então os SDKs oficiais da OpenAI funcionam com ele sem modificação:

1
2
3
4
5
6
7
8
9

from openai import OpenAI

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

response = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Summarize this changelog in two sentences."}],
)
print(response.choices[0].message.content)

O Ollama ignora api_key, mas o construtor do SDK exige um valor, então qualquer string não vazia serve. Isso faz dele o jeito mais rápido de apontar uma ferramenta já baseada na OpenAI para um modelo local: você troca base_url e deixa o resto do código como está.

Outro endpoint importa se você estiver montando um pipeline de retrieval-augmented generation local. POST /api/embed transforma texto em vetores usando um modelo de embedding (nomic-embed-text é a escolha mais comum), algo que um modelo de chat sozinho não te dá.

Como executar o Ollama no Docker

Se tudo mais na máquina já é um container, o Ollama fornece uma imagem oficial em vez de pedir que você instale algo no host:

1
2
3
4
5

docker run -d \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

O volume nomeado não é opcional na prática: sem ele, cada modelo baixado desaparece no momento em que o container é removido. Para baixar e executar um modelo dentro do container em execução:

1

docker exec -it ollama ollama run llama3.2

Numa máquina com GPU NVIDIA, instale primeiro o NVIDIA Container Toolkit no host, depois adicione uma única flag:

1
2
3
4
5

docker run -d --gpus=all \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

GPUs AMD usam uma tag de imagem separada e montagens de dispositivo em vez de --gpus:

1
2
3
4
5

docker run -d --device /dev/kfd --device /dev/dri \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama:rocm

A mesma coisa como serviço do Docker Compose mantém a porta e o volume, nada mais:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

services:
  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama:/root/.ollama

volumes:
  ollama:

Expor esse container além do localhost é trabalho de um reverse proxy com TLS na frente, assim como qualquer outro serviço de backend. O Ollama não tem autenticação própria, então uma porta 11434 acessível pela rede é um servidor de modelos que qualquer um pode usar.

Como personalizar um modelo com um Modelfile

Um Modelfile fixa um system prompt, uma temperatura e uma sequência de parada num modelo existente sem retreiná-lo. Crie um arquivo chamado Modelfile:

1
2
3
4
5
6
7
8

FROM llama3.2

PARAMETER temperature 0.3

SYSTEM """
You are a terse code reviewer. Reply with the diff and one sentence of
rationale. Never restate the code you were not asked to change.
"""

Depois construa e execute:

1
2

ollama create code-reviewer -f Modelfile
ollama run code-reviewer

code-reviewer agora aparece como sua própria entrada em ollama list, mesmo que os pesos sejam exatamente os que o llama3.2 usa. Só o system prompt e os parâmetros de sampling ficam embutidos. A vantagem é que todo cliente que chamar esse nome herda a configuração sem precisar enviá-la.

Qual tamanho de modelo cabe na sua RAM

O número no nome de um modelo é sua contagem de parâmetros, e prevê razoavelmente bem quanta RAM (ou VRAM, para inferência em GPU) você precisa:

Esses números presumem a quantização de 4 bits que o Ollama baixa por padrão, que troca uma pequena parte da qualidade de saída por um download e um consumo de memória cerca de quatro vezes menores que os pesos em precisão total. Para resumir texto ou redigir mensagens de commit, a quantização não é o que você vai notar. Ficar sem RAM é. Assim que o modelo passa a usar swap em disco, ele vai de lento a inutilizável, uma diferença muito maior que um ponto de precisão.

Quando o Ollama não é a ferramenta certa

O Ollama é feito para um único usuário conversando com um único modelo numa única máquina. Ele não faz batching de requisições nem nenhum tipo de agendamento que permita a uma GPU atender dezenas de usuários simultâneos com eficiência, papel que cabe ao vLLM, ao TGI ou a uma API hospedada. Se você vai colocar um modelo local na frente de tráfego real, meça o throughput do Ollama sob carga concorrente antes de se comprometer: uma única instância trava bem antes do que travaria um servidor com batching de verdade.

Também não é uma ferramenta de fine-tuning. Um Modelfile muda um system prompt e parâmetros de sampling, nunca os pesos. Fazer um modelo aprender um comportamento novo a partir dos seus exemplos é um pipeline separado.

Nenhum dos dois limites afeta um desenvolvedor sozinho num notebook. Baixe um modelo que caiba confortavelmente no seu teto de RAM, execute-o uma vez pela CLI e depois chame-o com curl em /api/generate. Se a resposta voltar em poucos segundos e disser o que você esperava, você tem um servidor de inferência local que qualquer ferramenta compatível com a OpenAI pode usar.

Artigos relacionados

• O Que É RAG: Retrieval-Augmented Generation Explicado
• O Que É Docker Compose e Como Usar
• O Que É um Reverse Proxy e Como Funciona