Adicionando suporte a GPU da NVIDIA ao Docker Model Runner

Habilite a aceleração da GPU para o Docker Model Runner com suporte à NVIDIA CUDA

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

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

Se você estiver procurando uma solução alternativa de hospedagem de LLM com configuração de GPU mais simples, considere Ollama, que possui suporte integrado à GPU e instalação mais simples. No entanto, o Docker Model Runner oferece melhor integração com o ecossistema do Docker e a distribuição de artefatos OCI.

Docker Model Runner com suporte à GPU da NVIDIA Esta imagem agradável foi gerada pelo modelo AI Flux 1 dev.

Pré-requisitos

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

Verifique se sua GPU está acessível:

nvidia-smi

Teste o acesso à GPU do Docker:

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

Para mais comandos do Docker e opções de configuração, veja nossa Docker Cheatsheet.

Etapa 1: Configurar o Daemon do Docker para o Runtime da NVIDIA

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

Localizar o Caminho do Runtime da NVIDIA Container

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

which nvidia-container-runtime

Isso normalmente retorna /usr/bin/nvidia-container-runtime. Anote esse caminho para a próxima etapa.

Configurar o Daemon do 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 de "path" na configuração JSON conforme necessário.

Reiniciar o Serviço do Docker

Aplicar a configuração reiniciando o Docker:

sudo systemctl restart docker

Verificar a Configuração

Confirme que o runtime da NVIDIA está configurado:

docker info | grep -i runtime

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

Etapa 2: Instalar o Docker Model Runner com Suporte à GPU

O Docker Model Runner deve ser instalado ou reinstalado com suporte à GPU explícito. O próprio contêiner 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 à GPU CUDA:

docker model reinstall-runner --gpu cuda

Este comando:

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

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

Backends de GPU Disponíveis

O Docker Model Runner suporta múltiplos backends de GPU:

  • cuda - NVIDIA CUDA (mais comum para GPUs da NVIDIA)
  • rocm - AMD ROCm (para GPUs da 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 da NVIDIA, sempre use --gpu cuda explicitamente.

Etapa 3: Verificar o Acesso à GPU

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

Verificar o Acesso à GPU no Contêiner do Runner

Teste o acesso à GPU dentro do contêiner do Docker Model Runner:

docker exec docker-model-runner nvidia-smi

Isso deve exibir as informações da sua GPU, confirmando que o contêiner tem acesso à GPU.

Verificar o Status do Runner

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

docker model status

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

Etapa 4: Testar um Modelo com GPU

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

Executar um Modelo

Iniciar uma inferência de modelo:

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

Verificar Uso da GPU nos Logs

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

docker model logs | grep -i cuda

Você deve ver mensagens indicando o uso da GPU:

  • using device CUDA0 (NVIDIA GeForce RTX 4080) - dispositivo de 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 na GPU
  • CUDA0 KV buffer size = 640.00 MiB - cache de chave-valor na GPU
  • CUDA0 compute buffer size = 306.75 MiB - buffer de computação na GPU

Monitorar o Uso da GPU

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

nvidia-smi -l 1

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

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

Solução de Problemas

Modelo Ainda Usando CPU

Se o modelo ainda estiver usando a CPU:

  1. Verificar a configuração do daemon do Docker:

    docker info | grep -i runtime

    Deve mostrar Default Runtime: nvidia

  2. Verificar o runtime do contêiner do runner:

    docker inspect docker-model-runner | grep -A 2 '"Runtime"'

    Deve mostrar "Runtime": "nvidia"

  3. Reinstalar o runner com suporte à GPU:

    docker model reinstall-runner --gpu cuda

  4. Verificar logs para erros:

    docker model logs | tail -50

GPU Não Detectada

Se a GPU não for detectada:

  1. Verificar se o NVIDIA Container Toolkit está instalado:

    dpkg -l | grep nvidia-container-toolkit

  2. Testar o acesso à GPU com o Docker padrão:

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

    Para solucionar problemas com o Docker, consulte nossa Docker Cheatsheet.

  3. Verificar os drivers da NVIDIA:

    nvidia-smi

Problemas de Desempenho

Se o desempenho da GPU for ruim:

  1. Verificar a utilização da GPU:

    nvidia-smi

    Procure por uma porcentagem alta de utilização da GPU

  2. Verificar 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

  3. Verificar por problemas de memória:

    nvidia-smi

    Certifique-se de que a memória da GPU não esteja esgotada

Boas Práticas

  1. Sempre especifique o backend da GPU explicitamente: Use --gpu cuda em vez de --gpu auto para GPUs da NVIDIA para garantir a configuração correta.

  2. Verifique a configuração após alterações: Sempre verifique docker info | grep -i runtime após modificar as configurações do daemon do Docker.

  3. Monitore o uso da GPU: Use nvidia-smi para monitorar a memória e a utilização da GPU durante a inferência do modelo. Para ferramentas de monitoramento mais avançadas, veja nosso guia sobre aplicações de monitoramento da GPU no Linux / Ubuntu.

  4. Verifique os logs regularmente: Revise docker model logs para garantir que os modelos estejam usando a aceleração da GPU.

  5. 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 comparação das especificações da GPU da NVidia para IA.