13 min de leitura 22 de agosto de 2026

Instalar o Ollama no Docker: CPU, GPU, volumes e API

Um caminho prático para executar o Ollama no Docker sem perder modelos, confundir a rede do host com a do contêiner ou expor uma API local por acidente.

Equipe editorial do Odysseus AI Wiki
Equipe editorial do Odysseus AI Wiki
Documentação técnica independente e verificação
Ilustração conceitual de um modelo Ollama executado dentro de uma fronteira Docker com CPU, GPU, armazenamento e um host local
Uma implantação Docker cria uma fronteira ao redor do runtime do Ollama; mantenha explícitos os caminhos de armazenamento, computação e rede.

Resposta curta: Sim, o Ollama pode rodar no Docker. A configuração mais confiável usa um volume nomeado para /root/.ollama, uma porta publicada somente quando necessária e um comando separado para CPU ou GPU conforme o host. Verifique o contêiner, o endpoint /api/tags e uma solicitação de modelo antes de conectar outro aplicativo.

Neste guia

A expressão instalar o Ollama no Docker normalmente esconde três decisões diferentes: onde os arquivos dos modelos ficarão, como o contêiner alcançará o host ou outro serviço e se ele usará CPU ou uma GPU disponível. Comece pelo menor caminho funcional. Execute a imagem oficial do Ollama com um volume nomeado, verifique a API local e só depois adicione flags de GPU ou um segundo aplicativo.

O que muda ao executar o Ollama no Docker

O Ollama normalmente se comporta como um serviço local: um comando inicia o runtime, os modelos ficam na máquina e os clientes chamam a porta 11434. O Docker envolve esse serviço em um contêiner com seu próprio sistema de arquivos, namespace de processos, regras de rede e ciclo de vida. Isso facilita uma implantação repetível, mas também significa que um modelo baixado dentro do contêiner pode desaparecer quando ele for removido, caso /root/.ollama não esteja respaldado por um volume.

Por isso, um comando Docker que funciona não é a configuração completa. Decida se o Docker será o único runtime do Ollama, se um aplicativo no host ou outro contêiner irá chamá-lo e se os modelos baixados devem sobreviver às atualizações. Deixe essas fronteiras claras antes de adicionar OpenCode, um host MCP, uma interface web ou um cliente remoto.

O ciclo de vida do contêiner não é o armazenamento dos modelos

Remover um contêiner só é seguro quando o diretório dos modelos está fora da camada gravável dele. Um volume nomeado ou um bind mount escolhido conscientemente é o que torna persistente uma implantação do Ollama no Docker.

Escolher CPU, NVIDIA GPU ou AMD GPU

Use primeiro o caminho de CPU ao validar a rede, os volumes ou um host novo. Ele tem menos variáveis e oferece uma base limpa para comparar o tempo de carregamento do modelo e a velocidade das respostas. Quando a API funcionar, troque para o comando específico do acelerador documentado para seu host, em vez de copiar flags Docker aleatórias de outro runtime.

Contêineres NVIDIA normalmente dependem de um driver funcional no host e do NVIDIA Container Toolkit. Implantações AMD podem usar outra tag de imagem e outro mapeamento de dispositivos; o suporte depende do sistema operacional, do runtime e das instruções atuais do Ollama. Trate a GPU como uma camada de otimização: ela não deve mudar o endpoint, o caminho do volume ou as verificações básicas de saúde.

Confirmar que o Docker está disponível
docker version
Verificar se o host expõe uma GPU NVIDIA
docker run --rm --gpus=all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi
Caminho Use quando Verificação importante
CPU Você quer a base mais simples ou não tem um acelerador compatível Confirme a API e a resposta do modelo antes de ajustar o desempenho
NVIDIA GPU O driver do host e o NVIDIA Container Toolkit já estão funcionando Verifique se o Docker enxerga a GPU antes de baixar um modelo grande
AMD GPU O host e a imagem do Ollama suportam o caminho ROCm necessário Siga os requisitos atuais de imagem e dispositivos para esse host
Host e contêiner Outro serviço precisa chamar o Ollama pela rede Docker Use o nome do serviço na rede, não o endereço de loopback do host

Criar armazenamento persistente para modelos

Um volume nomeado é o padrão mais simples para instalar o Ollama no Docker, porque o Docker administra o local e o contêiner pode ser substituído sem mover os modelos manualmente. A imagem oficial armazena os dados do Ollama em /root/.ollama; monte o volume sempre nesse caminho. Não crie um volume na primeira execução e outro na atualização, a menos que queira deliberadamente uma biblioteca nova.

Um bind mount pode ser útil para acompanhar o uso de disco, fazer backup de um diretório conhecido do host ou colocar os modelos em uma unidade específica. Ele também cria mais decisões de permissão e caminho. Na primeira implantação, um volume nomeado costuma ser mais fácil de explicar e mais difícil de quebrar.

Não confunda volume com backup

Um volume Docker protege os modelos contra a troca do contêiner, mas não é automaticamente uma segunda cópia. Faça backup ou recrie o volume de forma planejada se a biblioteca de modelos for importante.

Diagrama conceitual de rede com clientes do host conectados a um contêiner Ollama Docker, um volume persistente e uma rede externa separada
O caminho do aplicativo, a fronteira do contêiner, o volume persistente e a rede de saída devem ser decisões separadas.
Criar um volume nomeado
docker volume create ollama-data
Executar o contêiner CPU com armazenamento persistente
docker run -d --name ollama -p 11434:11434 -v ollama-data:/root/.ollama ollama/ollama
Baixar um modelo no contêiner
docker exec -it ollama ollama pull <model-name>

Iniciar o contêiner e verificar a API

Depois que docker run retornar um ID de contêiner, verifique o estado antes de baixar um modelo grande. docker ps mostra se o processo continua rodando; docker logs pode revelar erros de porta, permissão ou runtime. Em seguida, consulte /api/tags a partir do host. Uma resposta bem-sucedida confirma que o endpoint HTTP está acessível, mas não que todos os modelos foram carregados ou que todo cliente tem permissão para usá-los.

Faça uma solicitação com um modelo pequeno como segunda verificação. Assim você separa um listener HTTP saudável de um caminho de modelo funcional. Se a API responder, mas a solicitação do modelo falhar, verifique o nome do modelo, o espaço em disco, a memória e os logs do contêiner antes de mudar as configurações de rede.

  1. Verificar o processo

    Confirme que o contêiner está Up e que a porta publicada é a que você pretendia expor.

  2. Verificar o endpoint

    Solicite /api/tags na mesma máquina que publicou a porta 11434 e registre o código de resposta.

  3. Verificar um modelo

    Baixe ou use um modelo pequeno e execute um prompt simples antes de conectar um editor ou agente.

Verificar o estado do contêiner
docker ps --filter name=ollama
Ler os logs recentes
docker logs ollama --tail 100
Verificar a API local
curl http://127.0.0.1:11434/api/tags
Listar modelos dentro do contêiner
docker exec -it ollama ollama list

Conectar aplicativos sem confundir localhost

A URL correta do Ollama depende do local onde o cliente executa. Um aplicativo desktop no mesmo host pode normalmente chamar http://127.0.0.1:11434 quando o Docker publica a porta. Outro contêiner na mesma rede Docker deve chamar o serviço Ollama pelo nome do serviço no Compose e pela porta, por exemplo http://ollama:11434. Dentro de um contêiner, 127.0.0.1 significa o próprio contêiner; não significa automaticamente o host Windows, macOS ou Linux.

Para um cliente remoto, use um endereço protegido e uma regra de firewall explícitos. Não publique a porta 11434 na internet apenas para conectar um aplicativo de teste. Se o cliente precisar de um endpoint remoto, documente a rota, a autenticação ou a fronteira da rede privada e o serviço de modelos exato ao qual ele poderá acessar.

Local do cliente Endpoint típico Erro comum
Desktop no host http://127.0.0.1:11434 Usar o nome do serviço do contêiner em um aplicativo do host
Outro serviço Compose http://ollama:11434 Usar localhost, que aponta de volta para o contêiner chamador
Outra máquina Endereço privado do host protegido por firewall Publicar uma API sem autenticação em uma interface pública
Odysseus ou um editor Endpoint exigido pelas configurações do provedor do aplicativo Mudar o endpoint antes de a verificação básica da API passar

Manter modelos, contexto e exposição mais seguros

O Docker não torna um serviço Ollama privado automaticamente. Uma porta publicada pode ser vinculada a todas as interfaces, dependendo do comando e dos padrões do host. Para um teste somente no host, prefira um bind de loopback como -p 127.0.0.1:11434:11434 quando nenhuma outra máquina precisar acessar. Se um serviço Compose precisar da API internamente, mantenha-o em uma rede privada e não publique uma porta no host sem necessidade.

O tamanho do contexto, a concorrência e a memória da GPU podem alterar a quantidade de RAM ou VRAM usada pelo contêiner. Aumente uma variável por vez e observe docker stats, a memória do host e o comportamento das respostas. Mantenha segredos fora das imagens, do histórico do shell, das capturas de tela e dos arquivos Compose versionados; um endpoint de modelo local e uma ferramenta de busca de terceiros têm limites de privacidade diferentes.

Verificação Por que importa Padrão mais seguro
Vinculação da porta Define quais interfaces podem alcançar a API Vincular ao loopback em testes somente no host
Caminho do volume Define se os modelos sobrevivem à troca do contêiner Usar um volume nomeado e documentá-lo
Contexto e concorrência Podem multiplicar o uso de memória durante as solicitações Começar pequeno e medir antes de aumentar os limites
Ferramentas externas Podem enviar prompts ou conteúdo recuperado para fora do host Revisar o provedor e manter as permissões restritas

Diagnosticar falhas de saúde, GPU, volume e API

Quando uma implantação do Ollama no Docker falhar, altere uma camada por vez. Primeiro verifique se o Docker consegue iniciar um contêiner simples. Depois confirme que o contêiner Ollama continua em execução. Em seguida, verifique o volume, a API, o modelo e, por fim, o aplicativo cliente. Substituir o comando inteiro após cada erro esconde a fronteira que realmente falhou.

Falhas de GPU geralmente estão no runtime do host, não na API do Ollama. Um contêiner pode responder a /api/tags e ainda usar CPU porque a GPU não foi repassada, o driver é incompatível ou a imagem escolhida não corresponde ao host. Se um modelo sumir depois de recriar o contêiner, compare a saída de docker inspect e o destino montado antes de baixá-lo novamente.

Remover o contêiner não é o mesmo que excluir o volume

O último comando remove apenas o contêiner. Não execute docker volume rm ollama-data até confirmar que os modelos não são mais necessários ou que foram copiados.

Ilustração conceitual de diagnóstico do Ollama Docker comparando caminhos CPU e GPU com volume persistente, sinal de saúde e proteção de rede
Diagnostique nesta ordem: runtime, caminho de computação, armazenamento, endpoint e limite de exposição.
Inspecionar mounts e portas
docker inspect ollama
Observar o uso de recursos do contêiner
docker stats ollama
Parar e remover somente o contêiner
docker stop ollama && docker rm ollama
Sintoma Limite provável Próxima verificação
O contêiner encerra imediatamente Imagem, comando, permissões ou runtime Ler docker logs ollama e verificar o código de saída
Conexão com a API recusada Vinculação da porta ou saúde do processo Verificar docker ps, portas publicadas e /api/tags
O modelo desapareceu Volume errado ou ausente Comparar os mounts de docker inspect com o destino /root/.ollama
A flag de GPU falha Driver do host ou runtime do contêiner Executar o menor teste de GPU do fornecedor antes do Ollama
Funciona no host, mas não no contêiner Namespace de rede Trocar localhost pelo nome do serviço Compose
As solicitações usam memória demais Contexto, concorrência ou tamanho do modelo Reduzir uma configuração e observar as métricas do host e do contêiner

Perguntas frequentes sobre Ollama no Docker

Sim. O caminho oficial do Ollama no Docker inicia o serviço em um contêiner. Os detalhes práticos são a imagem, o volume /root/.ollama, o runtime de CPU ou acelerador e o endpoint usado pelo cliente.

Crie um volume nomeado, execute a imagem oficial com a porta 11434 e monte o volume em /root/.ollama. Depois verifique docker ps e /api/tags antes de baixar um modelo. Para comandos específicos de aceleradores, use a documentação oficial atual.

É possível planejar um armazenamento compartilhado, mas não aponte casualmente dois runtimes para o mesmo diretório de modelos com escrita. Um único responsável, um plano de backup e uma migração documentada reduzem surpresas de bloqueio e permissão.

Use CPU como base para comprovar a configuração. Use NVIDIA ou AMD somente quando driver do host, runtime do contêiner, imagem e mapeamento de dispositivos forem compatíveis em conjunto. O caminho de GPU deve melhorar a inferência sem mudar a verificação do volume ou da API.

Os dois clientes usam namespaces de rede diferentes. O host pode usar 127.0.0.1:11434 quando a porta está publicada; outro serviço Compose normalmente deve usar o nome do serviço Ollama, como http://ollama:11434.

Use a variável de ambiente e a configuração de imagem documentadas para a versão do Ollama que você executa e recrie o contêiner com o mesmo volume de modelos. Aumente o limite gradualmente e observe a memória; um contexto maior pode exigir muito mais RAM ou VRAM.

Não presuma que seja. Verifique o endereço de bind do host e o firewall. Em uma configuração somente no host, vincule a porta ao loopback; para comunicação entre serviços, prefira uma rede Docker privada e evite uma porta pública desnecessária.

Referências oficiais

  1. Documentação do Ollama Docker - Imagens oficiais de contêiner e orientações de implantação Docker
  2. Documentação da API do Ollama - Referência oficial de endpoints e solicitações
  3. Suporte a GPU no Docker Compose - Orientações oficiais sobre reserva de GPU e Compose

Guias relacionados de configuração de IA local

Última atualização: 22 de agosto de 2026

Voltar à página inicial