Utilizar vLLM con Docker para desplegar nuestros modelos llm en producción

Tiempo de lectura: 2 minutos

Es un servidor inferencial optimizado (usa paged attention) que soporta modelos como Llama 3, Mistral, Gemma, Phi, Qwen, etc.

Ofrece una API OpenAI-compatible, perfecta para integrarse fácilmente.

Vamos a crear el docker compose que nos permitirá desplegarlo:

Archivo: docker-compose.yml

version: "3.9"

services:
  vllm:
    image: vllm/vllm-openai:latest
    container_name: vllm
    restart: unless-stopped
    ports:
      - "8000:8000" # Puerto de la API OpenAI
    environment:
      - MODEL_NAME=meta-llama/Meta-Llama-3-8B-Instruct
      # Cambia por cualquier modelo disponible en Hugging Face, por ejemplo:
      # - mistralai/Mistral-7B-Instruct-v0.3
      # - meta-llama/Meta-Llama-3-8B
      # - TheBloke/Llama-2-7B-Chat-GGUF  (si usas variantes cuantizadas)
      # - huggingface_token=tu_token (opcional si el modelo es privado)
    volumes:
      - ./models:/root/.cache/huggingface/hub  # caché local de modelos
    command: >
      --model $(MODEL_NAME)
      --port 8000
      --host 0.0.0.0
      --max-num-batched-tokens 4096
      --tensor-parallel-size 1
      --gpu-memory-utilization 0.90

Cómo usarlo

1. Guarda el archivo como docker-compose.yml.
2. Asegúrate de tener Docker y Docker Compose instalados.
3. Ejecuta: docker compose up -d
4. El contenedor descargará el modelo automáticamente desde Hugging Face (puede tardar la primera vez).
5. Una vez levantado, tendrás una API en: http://localhost:8000/v1 Compatible con el formato OpenAI (puedes usar curl, Postman, LangChain, n8n, OpenWebUI…).

Probar que funciona

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Meta-Llama-3-8B-Instruct",
    "messages": [{"role": "user", "content": "Hola, ¿quién eres?"}]
  }'

Deberías recibir una respuesta tipo JSON del modelo.

• Si quieres usar un modelo distinto, cambia la línea MODEL_NAME=.
• Puedes guardar los modelos localmente (en ./models) para no volver a descargarlos.
• Compatible con Nginx Proxy Manager o traefik si quieres servirlo en un dominio (https://api.midominio.com).

Si queremos acceder a la GPU tendremos que usar el siguiente docker compose:

services:
  vllm:
    image: vllm/vllm-openai:latest
    container_name: vllm
    restart: unless-stopped
    # IMPORTANTE: Configura el runtime de NVIDIA para acceso a la GPU
    runtime: nvidia
    ports:
      - "8000:8000" # Puerto de la API OpenAI
    environment:
      - MODEL_NAME=meta-llama/Llama-3.2-3B
      # Cambia por cualquier modelo disponible en Hugging Face, por ejemplo:
      # - mistralai/Mistral-7B-Instruct-v0.3
      # - meta-llama/Meta-Llama-3-8B
      # - meta-llama/Meta-Llama-3-70B
      # - meta-llama/Llama-3.2-3B
      # - Qwen/Qwen3-0.6B
      # - TheBloke/Llama-2-7B-Chat-GGUF  (si usas variantes cuantizadas)
      # - huggingface_token=tu_token (opcional si el modelo es privado)
      # - OPENAI_API_KEY=${OPENAI_API_KEY}
      - HUGGING_FACE_HUB_TOKEN=${HUGGING_FACE_HUB_TOKEN}
    volumes:
      - ./model:/root/.cache/huggingface
    command: >
      --model meta-llama/Llama-3.2-3B
      --port 8000
      --host 0.0.0.0
      --max-num-batched-tokens 4096
      --tensor-parallel-size 1
      --gpu-memory-utilization 0.80
      --dtype float16
      --max-model-len 4096
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]
    ipc: host
    networks:
      - docker-network

networks:
  docker-network:
    driver: bridge
    external: true