# 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

| Característica               | llama.cpp                                         | vLLM                               | Diffusers                                 |
| ---------------------------- | ------------------------------------------------- | ---------------------------------- | ----------------------------------------- |
| **Formatos de modelo**       | GGUF                                              | Safetensors, HuggingFace           | DDUF                                      |
| **Plataformas**              | Todas (macOS, Windows, Linux)                     | Solo Linux x86_64                  | Linux (x86_64, ARM64)                     |
| **Soporte de GPU**           | NVIDIA, AMD, Apple Silicon, Vulkan                | Solo NVIDIA CUDA                   | Solo NVIDIA CUDA                          |
| **Inferencia de CPU**        | Sí                                                | No                                 | No                                        |
| **Cuantización**             | Integrada (Q4, Q5, Q8, etc.)                      | Limitada                           | Limitada                                  |
| **Eficiencia de memoria**    | Alta (con cuantización)                           | Moderada                           | Moderada                                  |
| **Rendimiento (throughput)** | Bueno                                             | Alto (con procesamiento por lotes) | Bueno                                     |
| **Ideal para**               | Desarrollo local, entornos con recursos limitados | Producción, alto rendimiento       | Generación de imágenes                    |
| **Caso de uso**              | Generación de texto (LLM)                         | Generación de texto (LLM)          | Generación de imágenes (Stable Diffusion) |

## llama.cpp

[llama.cpp](https://github.com/ggerganov/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

| Plataforma            | Soporte de GPU      | Notas                                   |
| --------------------- | ------------------- | --------------------------------------- |
| macOS (Apple Silicon) | Metal               | Aceleración por GPU automática          |
| Windows (x64)         | NVIDIA CUDA         | Requiere controladores NVIDIA 576.57+   |
| Windows (ARM64)       | Adreno OpenCL       | Qualcomm serie 6xx y posteriores        |
| Linux (x64)           | NVIDIA, AMD, Vulkan | Múltiples opciones de backend           |
| Linux                 | Solo CPU            | Funciona en cualquier sistema x64/ARM64 |

### 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

| Cuantización | Bits por peso | Uso de memoria | Calidad       |
| ------------ | ------------- | -------------- | ------------- |
| Q2_K         | ~2.5          | Mínimo         | Reducida      |
| Q3_K_M       | ~3.5          | Muy bajo       | Aceptable     |
| Q4_K_M       | ~4.5          | Bajo           | Buena         |
| Q5_K_M       | ~5.5          | Moderado       | Excelente     |
| Q6_K         | ~6.5          | Mayor          | Excelente     |
| Q8_0         | 8             | Alto           | Casi original |
| F16          | 16            | El más alto    | Original      |

**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):

```console
$ 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:

```console
$ docker model run ai/smollm2
```

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

```console
$ 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:

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

O sin el prefijo del motor:

```text
POST /engines/v1/chat/completions
```

## vLLM

[vLLM](https://github.com/vllm-project/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

| Plataforma       | GPU         | Estado de compatibilidad          |
| ---------------- | ----------- | --------------------------------- |
| Linux x86_64     | NVIDIA CUDA | Compatible                        |
| Windows con WSL2 | NVIDIA CUDA | Compatible (Docker Desktop 4.54+) |
| macOS            | -           | No compatible                     |
| Linux ARM64      | -           | No compatible                     |
| GPU de AMD       | -           | No compatible                     |

> [!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:

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

Verifica la instalación:

```console
$ 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:
   ```console
   $ docker model install-runner --backend vllm --gpu cuda
   ```

### Ejecutar modelos con vLLM

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

```console
$ docker model run ai/smollm2-vllm
```

Para especificar el backend de vLLM explícitamente:

```console
$ 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:

```text
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:

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

#### Ajustes comunes de vLLM

| Ajuste                   | Descripción                           | Ejemplo |
| ------------------------ | ------------------------------------- | ------- |
| `max_model_len`          | Longitud máxima del contexto          | 8192    |
| `gpu_memory_utilization` | Fracción de memoria de GPU a utilizar | 0.9     |
| `tensor_parallel_size`   | GPU para paralelismo de tensores      | 2       |

### Comparación de rendimiento entre vLLM y llama.cpp

| Escenario                          | Motor recomendado               |
| ---------------------------------- | ------------------------------- |
| Usuario único, desarrollo local    | llama.cpp                       |
| Múltiples solicitudes concurrentes | vLLM                            |
| Memoria de GPU limitada            | llama.cpp (con cuantización)    |
| Rendimiento máximo                 | vLLM                            |
| Sistema solo con CPU               | llama.cpp                       |
| Mac con Apple Silicon              | llama.cpp                       |
| Despliegue en producción           | vLLM (si el hardware lo admite) |

## Diffusers

[Diffusers](https://github.com/huggingface/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

| Plataforma   | GPU         | Estado de compatibilidad |
| ------------ | ----------- | ------------------------ |
| Linux x86_64 | NVIDIA CUDA | Compatible               |
| Linux ARM64  | NVIDIA CUDA | Compatible               |
| Windows      | -           | No compatible            |
| macOS        | -           | No compatible            |

> [!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:

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

Verifica la instalación:

```console
$ 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:

```console
$ 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:

```console
$ 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:

```text
POST /engines/diffusers/v1/images/generations
```

### Parámetros admitidos

| Parámetro | Tipo   | Descripción                                                                    |
| --------- | ------ | ------------------------------------------------------------------------------ |
| `model`   | string | Requerido. El identificador del modelo (por ejemplo, `stable-diffusion:Q4`).   |
| `prompt`  | string | Requerido. La descripción en texto de la imagen a generar.                     |
| `size`    | string | Dimensiones de la imagen en formato `ANCHO_POR_ALTO` (por ejemplo, `512x512`). |

## 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:

```console
$ 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

| Motor                | Ruta de API                                | Caso de uso                                               |
| -------------------- | ------------------------------------------ | --------------------------------------------------------- |
| llama.cpp            | `/engines/llama.cpp/v1/chat/completions`   | Generación de texto                                       |
| vLLM                 | `/engines/vllm/v1/chat/completions`        | Generación de texto                                       |
| Diffusers            | `/engines/diffusers/v1/images/generations` | Generación de imágenes                                    |
| Selección automática | `/engines/v1/chat/completions`             | Generación de texto (selecciona automáticamente el motor) |

## Gestionar motores de inferencia

### Instalar un motor

```console
$ 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

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

### Comprobar el estado del motor

```console
$ docker model status
```

### Ver los registros (logs) del motor

```console
$ docker model logs
```

## Empaquetar modelos para cada motor

### Empaquetar un modelo GGUF (llama.cpp)

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

### Empaquetar un modelo Safetensors (vLLM)

```console
$ 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:

   ```console
   $ nvidia-smi
   ```

2. Comprueba que Docker tenga acceso a la GPU:

   ```console
   $ 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:

   ```console
   $ docker model pull ai/model:Q4_K_M
   ```

3. Reduce el tamaño del contexto:
   ```console
   $ 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`:
   ```console
   $ docker model configure --hf_overrides '{"gpu_memory_utilization": 0.8}' ai/model
   ```

## Qué sigue

- [Opciones de configuración](/ai/model-runner/inference-engines/configuration/) - Referencia detallada de parámetros
- [Referencia de la API](/ai/model-runner/inference-engines/api-reference/) - Documentación de la API
- [Soporte de GPU](/desktop/features/gpu/) - Configuración de GPU para Docker Desktop