Preciso reinstalar o Docker Model Runner para habilitar a GPU?

Sim, se o Docker Model Runner já estiver instalado sem suporte a GPU, você deve reinstalá-lo usando o comando docker model reinstall-runner –gpu cuda. Isso baixa a versão habilitada para CUDA (docker/model-runner_latest-cuda) em vez da versão apenas para CPU.

E se o nvidia-container-runtime estiver em uma localização diferente?

Use o nvidia-container-runtime para localizar o caminho de instalação e, em seguida, atualize o valor de “path” em /etc/docker/daemon.json conforme necessário. O caminho é geralmente /usr/bin/nvidia-container-runtime, mas pode variar dependendo da sua instalação.

Como posso verificar se a GPU está sendo utilizada?

Verifique os logs do Docker Model Runner com o comando docker model logs | grep -i cuda . Você deve ver mensagens como “using device CUDA0”, “offloaded X/X layers to GPU” e “CUDA0 model buffer size”. Você também pode monitorar o uso da GPU com o nvidia-smi enquanto executa um modelo.

Quais backends de GPU são suportados?

O Docker Model Runner suporta várias backends de GPU: cuda (NVIDIA CUDA), rocm (AMD ROCm), musa (Moore Threads MUSA), cann (Huawei CANN), auto (detecção automática) e none (apenas CPU). Utilize a flag –gpu durante a instalação para especificar sua backend.

Onde o Docker Model Runner com GPU se encaixa no cenário de hospedagem de LLMs?

O Docker Model Runner é uma opção local/auto-hospedada. Nosso guia principal de hospedagem de LLMs compara-o com Ollama, vLLM, LocalAI e provedores de nuvem, incluindo compensações de custos e infraestrutura.

A configuração de GPU é mais fácil com o Ollama do que com o Docker Model Runner?

Sim. O Ollama detecta e utiliza GPUs automaticamente, sem necessidade de um daemon ou etapas de reinstalação. O Docker Model Runner requer o daemon do Docker, o tempo de execução da NVIDIA e a instalação de um runner habilitado para CUDA. Ambos estão abordados no guia de Hospedagem de LLM.

Adicionando Suporte a GPU NVIDIA ao Docker Model Runner

Q: Por que o Docker Model Runner não utiliza GPU por padrão?

O Docker Model Runner exige configuração explícita de GPU, pois precisa ser instalado com a versão habilitada para CUDA. Diferente dos comandos padrão docker run, o docker model run não suporta as flags –gpus; portanto, o suporte a GPU deve ser configurado no nível do daemon Docker e durante a instalação do runner.

Ative a aceleração por GPU para o Docker Model Runner com suporte NVIDIA CUDA.

Docker Model Runner é a ferramenta oficial da Docker para executar modelos de IA localmente, mas habilitar a aceleração de GPU da NVidia no Docker Model Runner requer configuração específica.

Diferente dos comandos padrão docker run, o docker model run não suporta as flags --gpus ou -e, portanto, o suporte a GPU deve ser configurado no nível do daemon Docker e durante a instalação do runner.

Se você procura uma solução alternativa de hospedagem de LLM com configuração de GPU mais fácil, considere o Ollama, que possui suporte nativo a GPU e configuração mais simples. No entanto, o Docker Model Runner oferece melhor integração com o ecossistema da Docker e distribuição de artefatos OCI. Para uma comparação mais ampla do Docker Model Runner com Ollama, vLLM, LocalAI e provedores de nuvem — incluindo compensações de custo e infraestrutura — veja Hospedagem de LLM: Infraestrutura Local, Auto-Hospedada e Nuvem Comparadas.

Docker Model Runner com suporte a GPU NVIDIA Esta bela imagem foi gerada pelo modelo de IA Flux 1 dev.

Pré-requisitos

Antes de configurar o suporte a GPU, certifique-se de ter:

GPU NVIDIA com drivers compatíveis instalados. Para ajuda na escolha da GPU certa para cargas de trabalho de IA, veja nosso guia sobre Comparando especificações de GPU NVidia para adequação à IA.
NVIDIA Container Toolkit instalado (veja a seção de suporte a NVIDIA RTX)
Docker Model Runner instalado (pode ser reinstalado com suporte a GPU)

Verifique se sua GPU está acessível:

nvidia-smi

Teste o acesso à GPU no Docker:

docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi

Para mais comandos Docker e opções de configuração, veja nosso Guia de Atalhos do Docker.

Passo 1: Configurar o Daemon Docker para Runtime NVIDIA

O Docker Model Runner requer que o runtime NVIDIA seja definido como runtime padrão na configuração do daemon Docker.

Localizar o Caminho do Runtime NVIDIA Container

Primeiro, localize onde nvidia-container-runtime está instalado:

which nvidia-container-runtime

Isso geralmente retorna /usr/bin/nvidia-container-runtime. Anote este caminho para o próximo passo.

Configurar o Daemon Docker

Crie ou atualize /etc/docker/daemon.json para definir a NVIDIA como o runtime padrão:

sudo tee /etc/docker/daemon.json > /dev/null << 'EOF'
{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
EOF

Importante: Se which nvidia-container-runtime retornou um caminho diferente, atualize o valor "path" na configuração JSON conforme necessário.

Reiniciar o Serviço Docker

Aplique a configuração reiniciando o Docker:

sudo systemctl restart docker

Verificar Configuração

Confirme que o runtime NVIDIA está configurado:

docker info | grep -i runtime

Você deve ver Default Runtime: nvidia na saída.

Passo 2: Instalar o Docker Model Runner com Suporte a GPU

O Docker Model Runner deve ser instalado ou reinstalado com suporte explícito a GPU. O próprio container do runner precisa ser a versão habilitada para CUDA.

Parar o Runner Atual (se estiver em execução)

Se o Docker Model Runner já estiver instalado, pare-o primeiro:

docker model stop-runner

Instalar/Reinstalar com Suporte CUDA

Instale ou reinstale o Docker Model Runner com suporte a GPU CUDA:

docker model reinstall-runner --gpu cuda

Este comando:

Baixa a versão habilitada para CUDA (docker/model-runner:latest-cuda) em vez da versão apenas para CPU
Configura o container do runner para usar o runtime NVIDIA
Habilita a aceleração de GPU para todos os modelos

Nota: Se você já instalou o Docker Model Runner sem suporte a GPU, deve reinstalá-lo com a flag --gpu cuda. Apenas configurar o daemon Docker não é suficiente — o próprio container do runner precisa ser a versão habilitada para CUDA.

Backends de GPU Disponíveis

O Docker Model Runner suporta vários backends de GPU:

cuda - NVIDIA CUDA (mais comum para GPUs NVIDIA)
rocm - AMD ROCm (para GPUs AMD)
musa - Moore Threads MUSA
cann - Huawei CANN
auto - Detecção automática (padrão, pode não funcionar corretamente)
none - Apenas CPU

Para GPUs NVIDIA, use sempre --gpu cuda explicitamente.

Passo 3: Verificar Acesso à GPU

Após a instalação, verifique se o Docker Model Runner pode acessar sua GPU.

Verificar Acesso à GPU do Container do Runner

Teste o acesso à GPU de dentro do container do Docker Model Runner:

docker exec docker-model-runner nvidia-smi

Isso deve exibir suas informações de GPU, confirmando que o container tem acesso à GPU.

Verificar Status do Runner

Verifique se o Docker Model Runner está em execução:

docker model status

Você deve ver que o runner está ativo com suporte a llama.cpp.

Passo 4: Testar Modelo com GPU

Execute um modelo e verifique se ele está usando a GPU.

Executar um Modelo

Inicie uma inferência de modelo:

docker model run ai/qwen3:14B-Q6_K "quem é você?"

Verificar Uso de GPU nos Logs

Verifique os logs do Docker Model Runner para confirmação de GPU:

docker model logs | grep -i cuda

Você deve ver mensagens indicando o uso de GPU:

using device CUDA0 (NVIDIA GeForce RTX 4080) - dispositivo GPU detectado
offloaded 41/41 layers to GPU - camadas do modelo carregadas na GPU
CUDA0 model buffer size = 10946.13 MiB - alocação de memória GPU
CUDA0 KV buffer size = 640.00 MiB - cache chave-valor na GPU
CUDA0 compute buffer size = 306.75 MiB - buffer de computação na GPU

Monitorar Uso de GPU

Em outro terminal, monitore o uso de GPU em tempo real:

nvidia-smi -l 1

Você deve ver o uso de memória e utilização da GPU aumentando quando o modelo estiver em execução.

Para opções e ferramentas de monitoramento de GPU mais avançadas, veja nosso guia sobre Aplicativos de monitoramento de GPU no Linux / Ubuntu.

Solução de Problemas

Modelo Ainda Usando CPU

Se o modelo ainda estiver rodando na CPU:

Verifique a configuração do daemon Docker:
```
docker info | grep -i runtime
```
Deve mostrar Default Runtime: nvidia
Verifique o runtime do container do runner:
```
docker inspect docker-model-runner | grep -A 2 '"Runtime"'
```
Deve mostrar "Runtime": "nvidia"

Reinstale o runner com suporte a GPU:

docker model reinstall-runner --gpu cuda

Verifique erros nos logs:
```
docker model logs | tail -50
```

GPU Não Detectada

Se a GPU não for detectada:

Verifique se o NVIDIA Container Toolkit está instalado:
```
dpkg -l | grep nvidia-container-toolkit
```
Teste o acesso à GPU com Docker padrão:
```
docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi
```
Para solucionar problemas do Docker, consulte nosso Guia de Atalhos do Docker.
Verifique os drivers da NVIDIA:
```
nvidia-smi
```

Problemas de Desempenho

Se o desempenho da GPU for ruim:

Verifique a utilização da GPU:
```
nvidia-smi
```
Procure por alta porcentagem de utilização da GPU
Verifique se as camadas do modelo estão na GPU:
```
docker model logs | grep "offloaded.*layers to GPU"
```
Todas as camadas devem ser transferidas para a GPU
Verifique problemas de memória:
```
nvidia-smi
```
Certifique-se de que a memória da GPU não esteja esgotada

Melhores Práticas

Sempre especifique o backend de GPU explicitamente: Use --gpu cuda em vez de --gpu auto para GPUs NVIDIA para garantir a configuração correta.
Verifique a configuração após alterações: Sempre verifique docker info | grep -i runtime após modificar as configurações do daemon Docker.
Monitore o uso da GPU: Use nvidia-smi para monitorar memória e utilização da GPU durante a inferência do modelo. Para ferramentas de monitoramento mais avançadas, veja nosso guia sobre Aplicativos de monitoramento de GPU no Linux / Ubuntu.
Verifique os logs regularmente: Revise docker model logs para garantir que os modelos estão usando aceleração de GPU.
Use tamanhos de modelo apropriados: Certifique-se de que sua GPU tenha memória suficiente para o modelo. Use modelos quantizados (Q4, Q5, Q6, Q8) para melhor eficiência de memória da GPU. Para ajuda na escolha da GPU certa para suas cargas de trabalho de IA, veja nosso guia sobre Comparando especificações de GPU NVidia para adequação à IA.

Uma vez que o suporte a GPU esteja habilitado, o Docker Model Runner é uma de várias maneiras de executar LLMs localmente. Para ver como ele se encaixa com Ollama, vLLM, APIs de nuvem e outras opções, verifique nosso guia Hospedagem de LLM: Infraestrutura Local, Auto-Hospedada e Nuvem Comparadas.