Docker para IA Local: Despliegue de Contenedores con vLLM y Ollama

Q: ¿Cómo conservo los modelos descargados entre reinicios del contenedor?

Monta un volumen persistente para la caché de Hugging Face: ~/.cache/huggingface:/root/.cache/huggingface. Los modelos quedan entonces en el host y sobreviven a la recreación del contenedor, así que un redespliegue no vuelve a descargarlos.

Respuesta rápida: IA local con Docker Compose. Instala NVIDIA Container Toolkit, confirma que la GPU es visible con docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi, y define un servicio de Compose con reserva de GPU (driver: nvidia, count: all), ipc: host para vLLM, un volumen persistente para la caché de modelos (~/.cache/huggingface:/root/.cache/huggingface) y el puerto 8000 para la API compatible con OpenAI. Consulta la guía de despliegues Docker en producción para builds multi-etapa y la categoría DevOps para el resto de la serie.

Por Sarah Lin • Avanzado • 21 min de lectura • Actualizado 2026-11-01

Lo Que Dominarás en Este Tutorial

Configure NVIDIA Container Toolkit to pass physical GPU acceleration into Docker containers.
Deploy vLLM in Docker for high-throughput serving with PagedAttention and continuous batching.
Orchestrate a complete local AI developer stack using Docker Compose.
Optimize shared memory (shm-size) and persistent model cache storage across deployments.

1. Configuring GPU Passthrough with NVIDIA Container Toolkit

Running local LLMs inside Docker requires exposing the host GPU and CUDA drivers to the container runtime. The modern standard is the NVIDIA Container Toolkit (nvidia-ctk).

BASH

# Configure NVIDIA repository and install toolkit
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Test GPU access inside container
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Nota: Crucial Configuration: Always verify that nvidia-smi runs successfully inside the test container before deploying AI stacks.

2. Production Docker Compose: vLLM + WebUI + OpenClaw

Below is a battle-tested Docker Compose manifest orchestrating high-throughput vLLM serving, persistent Hugging Face cache volumes, and an OpenAI-compatible API endpoint.

YAML

services:
  vllm-inference:
    image: vllm/vllm-openai:latest
    container_name: vllm-deepseek
    runtime: nvidia
    restart: unless-stopped
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "8000:8000"
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: >
      --model deepseek-ai/DeepSeek-R1-Distill-Qwen-14B
      --tensor-parallel-size 1
      --max-model-len 8192
      --gpu-memory-utilization 0.90
      --trust-remote-code

Nota: Performance Note: ipc: host is mandatory for vLLM and PyTorch to prevent Shared Memory (shm) allocation panics during high-concurrency inference.

Evaluación Rápida: Pon a Prueba tus Conocimientos

1. Why is 'ipc: host' required when running vLLM inside Docker?

Preguntas frecuentes sobre Docker para IA local

¿Cómo compruebo que Docker ve mi GPU antes de desplegar una pila de IA local?

Instala NVIDIA Container Toolkit, configura el runtime de Docker con sudo nvidia-ctk runtime configure --runtime=docker, reinicia Docker y ejecuta docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi. Verifica siempre que nvidia-smi funcione dentro del contenedor de prueba antes de desplegar pilas de IA.

¿Por qué el servicio vLLM en Docker Compose necesita ipc: host?

Porque vLLM y PyTorch necesitan la memoria compartida del host para la comunicación de tensores entre procesos. Sin ella, la inferencia de alta concurrencia puede sufrir errores de asignación de memoria compartida que parecen fallos de falta de memoria.

¿Cómo conservo los modelos descargados entre reinicios del contenedor?

Monta un volumen persistente para la caché de Hugging Face, como en esta guía: ~/.cache/huggingface:/root/.cache/huggingface. Los modelos quedan entonces en el host y sobreviven a la recreación del contenedor, así que un redespliegue no vuelve a descargarlos. La guía de DeepSeek R1 y Ollama cubre la ejecución local de modelos con más detalle.