Motores de inferencia

Docker Model Runner admite tres motores de inferencia: llama.cpp, vLLM y Diffusers. Cada motor tiene diferentes fortalezas, plataformas compatibles y requisitos de formato de modelo. Esta guía te ayuda a elegir el motor adecuado y a configurarlo para tu caso de uso.

Comparación de motores

llama.cpp

llama.cpp es el motor de inferencia predeterminado en Docker Model Runner. Está diseñado para una inferencia local eficiente y admite una amplia gama de configuraciones de hardware.

Compatibilidad de plataformas

Formato de modelo: GGUF

llama.cpp utiliza el formato GGUF, que admite una cuantización eficiente para reducir el uso de memoria sin una pérdida significativa de calidad.

Niveles de cuantización

Recomendado: Q4_K_M ofrece el mejor equilibrio entre calidad y uso de memoria para la mayoría de los casos de uso.

Descargar modelos cuantizados

Los modelos en Docker Hub a menudo incluyen la cuantización en la etiqueta (tag):

$ docker model pull ai/llama3.2:3B-Q4_K_M

Usar llama.cpp

llama.cpp es el motor predeterminado. No se requiere ninguna configuración especial:

$ docker model run ai/smollm2

Para especificar explícitamente llama.cpp al ejecutar modelos:

$ docker model run ai/smollm2 --backend llama.cpp

Endpoints de la API de llama.cpp

Al utilizar llama.cpp, las llamadas a la API utilizan la ruta del motor llama.cpp:

POST /engines/llama.cpp/v1/chat/completions

O sin el prefijo del motor:

POST /engines/v1/chat/completions

vLLM

vLLM es un motor de inferencia de alto rendimiento optimizado para cargas de trabajo de producción con requisitos de alto rendimiento.

Compatibilidad de plataformas

Important

vLLM requiere una GPU NVIDIA con soporte para CUDA. No admite inferencia solo con CPU.

Formato de modelo: Safetensors

vLLM funciona con modelos en formato Safetensors, que es el formato estándar para los modelos de HuggingFace. Estos modelos suelen utilizar más memoria que los modelos GGUF cuantizados, pero pueden ofrecer una mejor calidad y una inferencia más rápida en hardware potente.

Configuración de vLLM

Docker Engine (Linux)

Instala el Model Runner con el backend de vLLM:

$ docker model install-runner --backend vllm --gpu cuda

Verifica la instalación:

$ docker model status
Docker Model Runner is running

Status:
llama.cpp: running llama.cpp version: c22473b
vllm: running vllm version: 0.11.0

Docker Desktop (Windows con WSL2)

1. Asegúrate de tener:

   • Docker Desktop 4.54 o posterior (versión mínima para soporte de vLLM)
   • GPU NVIDIA con controladores actualizados
   • WSL2 habilitado

2. Instala el backend de vLLM:

   $ docker model install-runner --backend vllm --gpu cuda
   

Ejecutar modelos con vLLM

Los modelos vLLM suelen estar etiquetados con el sufijo -vllm:

$ docker model run ai/smollm2-vllm

Para especificar el backend de vLLM explícitamente:

$ docker model run ai/model --backend vllm

Endpoints de la API de vLLM

Al utilizar vLLM, especifica el motor en la ruta de la API:

POST /engines/vllm/v1/chat/completions

Configuración de vLLM

Anulaciones (overrides) de HuggingFace

Usa --hf_overrides para pasar anulaciones de configuración del modelo:

$ docker model configure --hf_overrides '{"max_model_len": 8192}' ai/model-vllm

Ajustes comunes de vLLM

Comparación de rendimiento entre vLLM y llama.cpp

Diffusers

Diffusers es un motor de inferencia para modelos de generación de imágenes, incluyendo Stable Diffusion. A diferencia de llama.cpp y vLLM que se enfocan en la generación de texto con LLM, Diffusers te permite generar imágenes a partir de prompts de texto.

Compatibilidad de plataformas

Important

Diffusers requiere una GPU NVIDIA con soporte para CUDA. No admite inferencia solo con CPU.

Configuración de Diffusers

Instala el Model Runner con el backend de Diffusers:

$ docker model reinstall-runner --backend diffusers --gpu cuda

Verifica la instalación:

$ docker model status
Docker Model Runner is running

Status:
llama.cpp: running llama.cpp version: 34ce48d
mlx: not installed
sglang: sglang package not installed
vllm: vLLM binary not found
diffusers: running diffusers version: 0.36.0

Descargar modelos de Diffusers

Descarga un modelo de Stable Diffusion:

$ docker model pull stable-diffusion:Q4

Generar imágenes con Diffusers

Diffusers utiliza un endpoint de la API de generación de imágenes. Para generar una imagen:

$ curl -s -X POST http://localhost:12434/engines/diffusers/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stable-diffusion:Q4",
    "prompt": "A picture of a nice cat",
    "size": "512x512"
  }' | jq -r '.data[0].b64_json' | base64 -d > image.png

Este comando:

1. Envía una solicitud POST al endpoint de generación de imágenes de Diffusers.
2. Especifica el modelo, el prompt y el tamaño de la imagen de salida.
3. Extrae la imagen codificada en base64 de la respuesta.
4. La decodifica y la guarda como image.png.

Endpoint de la API de Diffusers

Al utilizar Diffusers, especifica el motor en la ruta de la API:

POST /engines/diffusers/v1/images/generations

Parámetros admitidos

Ejecutar múltiples motores

Puedes ejecutar llama.cpp, vLLM y Diffusers simultáneamente. Docker Model Runner enruta las solicitudes al motor adecuado según el modelo o la selección explícitamente del motor.

Comprueba qué motores se están ejecutando:

$ docker model status
Docker Model Runner is running

Status:
llama.cpp: running llama.cpp version: 34ce48d
mlx: not installed
sglang: sglang package not installed
vllm: running vllm version: 0.11.0
diffusers: running diffusers version: 0.36.0

Rutas de API específicas del motor

Gestionar motores de inferencia

Instalar un motor

$ docker model install-runner --backend <engine> [--gpu <type>]

Opciones:

• --backend: llama.cpp, vllm o diffusers
• --gpu: cuda, rocm, vulkan o metal (depende de la plataforma)

Reinstalar un motor

$ docker model reinstall-runner --backend <engine>

Comprobar el estado del motor

$ docker model status

Ver los registros (logs) del motor

$ docker model logs

Empaquetar modelos para cada motor

Empaquetar un modelo GGUF (llama.cpp)

$ docker model package --gguf ./model.gguf --push myorg/mymodel:Q4_K_M

Empaquetar un modelo Safetensors (vLLM)

$ docker model package --safetensors ./model/ --push myorg/mymodel-vllm

Resolución de problemas

vLLM no se inicia

1. Verifica que la GPU NVIDIA esté disponible:

   $ nvidia-smi
   

2. Comprueba que Docker tenga acceso a la GPU:

   $ docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
   

3. Verifica que estés en una plataforma compatible (Linux x86_64 o Windows WSL2).

llama.cpp es lento

1. Asegúrate de que la aceleración de GPU esté funcionando (comprueba los registros para ver mensajes de Metal/CUDA).

2. Prueba con una cuantización más agresiva:

   $ docker model pull ai/model:Q4_K_M
   

3. Reduce el tamaño del contexto:

   $ docker model configure --context-size 2048 ai/model
   

Errores de falta de memoria (out of memory)

1. Usa una cuantización más pequeña (Q4 en lugar de Q8).
2. Reduce el tamaño del contexto.
3. Para vLLM, ajusta gpu_memory_utilization:

   $ docker model configure --hf_overrides '{"gpu_memory_utilization": 0.8}' ai/model
   

Qué sigue

• Opciones de configuración - Referencia detallada de parámetros
• Referencia de la API - Documentación de la API
• Soporte de GPU - Configuración de GPU para Docker Desktop