# Opciones de configuración


Docker Model Runner proporciona varias opciones de configuración para ajustar el comportamiento del modelo, el uso de memoria y el rendimiento de la inferencia. Esta guía cubre las configuraciones clave y cómo aplicarlas.

## Tamaño del contexto (longitud del contexto)

El tamaño del contexto determina el número máximo de tokens que un modelo puede procesar en una sola solicitud, incluyendo tanto el prompt de entrada como la salida generada. Esta es una de las configuraciones más importantes que afectan al uso de memoria y a las capacidades del modelo.

### Tamaño de contexto predeterminado

Por defecto, Docker Model Runner utiliza un tamaño de contexto que equilibra la capacidad con la eficiencia de los recursos:

| Motor     | Comportamiento predeterminado                             |
| --------- | --------------------------------------------------------- |
| llama.cpp | 4096 tokens                                               |
| vLLM      | Utiliza el tamaño de contexto máximo entrenado del modelo |

> [!NOTE]
> El valor predeterminado real varía según el modelo. La mayoría de los modelos admiten entre 2,048 y 8,192 tokens por defecto. Algunos modelos más nuevos admiten contextos de 32K, 128K o incluso mayores.

### Configurar el tamaño del contexto

Puedes ajustar el tamaño del contexto por modelo utilizando el comando `docker model configure`:

```console
$ docker model configure --context-size 8192 ai/qwen2.5-coder
```

O en un archivo de Compose:

```yaml
models:
  llm:
    model: ai/qwen2.5-coder
    context_size: 8192
```

### Directrices para el tamaño del contexto

| Tamaño del contexto | Caso de uso típico                                    | Impacto en memoria |
| ------------------- | ----------------------------------------------------- | ------------------ |
| 2,048               | Consultas sencillas, fragmentos de código cortos      | Bajo               |
| 4,096               | Conversaciones estándar, archivos de código medianos  | Moderado           |
| 8,192               | Conversaciones largas, archivos de código más grandes | Mayor              |
| 16,384+             | Documentos extensos, contexto de múltiples archivos   | Alto               |

> [!IMPORTANT]
> Los tamaños de contexto más grandes requieren más memoria (RAM/VRAM). Si experimentas errores de falta de memoria (out-of-memory), reduce el tamaño del contexto. Como guía aproximada, cada 1,000 tokens adicionales requieren aproximadamente entre 100 y 500 MB de memoria adicional, según el tamaño del modelo.

### Comprobar el contexto máximo de un modelo

Para ver la configuración de un modelo, incluido el tamaño de su contexto:

```console
$ docker model inspect ai/qwen2.5-coder
```

> [!NOTE]
> El comando `docker model inspect` muestra la longitud máxima de contexto admitida por el modelo (por ejemplo, `gemma3.context_length`), no el tamaño del contexto configurado. El tamaño del contexto configurado es el que se establece con `docker model configure --context-size` y representa el límite real utilizado durante la inferencia, el cual debe ser menor o igual a la longitud de contexto máxima admitida por el modelo.

## Banderas de tiempo de ejecución (runtime flags)

Las banderas de tiempo de ejecución te permiten pasar parámetros directamente al motor de inferencia subyacente. Esto proporciona un control detallado sobre el comportamiento del modelo.

### Uso de banderas de tiempo de ejecución

Las banderas de tiempo de ejecución se pueden proporcionar a través de múltiples mecanismos:

#### Uso de Docker Compose

En un archivo de Compose:

```yaml
models:
  llm:
    model: ai/qwen2.5-coder
    context_size: 4096
    runtime_flags:
      - "--temp"
      - "0.7"
      - "--top-p"
      - "0.9"
```

#### Uso de la línea de comandos

Con el comando `docker model configure`:

```console
$ docker model configure ai/qwen2.5-coder -- --temp 0.7 --top-p 0.9
```

### Parámetros comunes de llama.cpp

Estos son los parámetros de llama.cpp más utilizados. No necesitas buscar en la documentación de llama.cpp para los casos de uso típicos.

#### Parámetros de muestreo

| Bandera            | Descripción                                                                  | Predeterminado | Rango   |
| ------------------ | ---------------------------------------------------------------------------- | -------------- | ------- |
| `--temp`           | Temperatura para el muestreo. Menor = más determinista, mayor = más creativo | 0.8            | 0.0-2.0 |
| `--top-k`          | Limita el muestreo a los mejores K tokens. Menor = más enfocado              | 40             | 1-100   |
| `--top-p`          | Umbral de muestreo nucleus. Menor = más enfocado                             | 0.9            | 0.0-1.0 |
| `--min-p`          | Umbral de probabilidad mínima                                                | 0.05           | 0.0-1.0 |
| `--repeat-penalty` | Penalización por repetición de tokens                                        | 1.1            | 1.0-2.0 |

**Ejemplo: Salida determinista (para generación de código)**

```yaml
runtime_flags:
  - "--temp"
  - "0"
  - "--top-k"
  - "1"
```

**Ejemplo: Salida creativa (para redacción de historias)**

```yaml
runtime_flags:
  - "--temp"
  - "1.2"
  - "--top-p"
  - "0.95"
```

#### Parámetros de rendimiento

| Bandera           | Descripción                                      | Predeterminado | Notas                                                    |
| ----------------- | ------------------------------------------------ | -------------- | -------------------------------------------------------- |
| `--threads`       | Hilos de CPU para la generación                  | Auto           | Establecer en el número de núcleos de rendimiento        |
| `--threads-batch` | Hilos de CPU para el procesamiento por lotes     | Auto           | Generalmente el mismo que `--threads`                    |
| `--batch-size`    | Tamaño del lote para el procesamiento del prompt | 512            | Mayor = procesamiento de prompts más rápido              |
| `--mlock`         | Bloquear el modelo en memoria                    | Desactivado    | Evita el intercambio (swapping), requiere RAM suficiente |
| `--no-mmap`       | Deshabilitar el mapeo de memoria                 | Desactivado    | Puede mejorar el rendimiento en algunos sistemas         |

**Ejemplo: Optimizado para CPU multinúcleo**

```yaml
runtime_flags:
  - "--threads"
  - "8"
  - "--batch-size"
  - "1024"
```

#### Parámetros de GPU

| Bandera          | Descripción                           | Predeterminado                | Notas                            |
| ---------------- | ------------------------------------- | ----------------------------- | -------------------------------- |
| `--n-gpu-layers` | Capas a descargar en la GPU           | Todas (si hay GPU disponible) | Reducir si te quedas sin VRAM    |
| `--main-gpu`     | GPU a utilizar para el cálculo        | 0                             | Para sistemas con varias GPU     |
| `--split-mode`   | Cómo dividir el trabajo entre las GPU | layer                         | Opciones: `none`, `layer`, `row` |

**Ejemplo: Descarga parcial en GPU (VRAM limitada)**

```yaml
runtime_flags:
  - "--n-gpu-layers"
  - "20"
```

#### Parámetros avanzados

| Bandera                  | Descripción                                        | Predeterminado            |
| ------------------------ | -------------------------------------------------- | ------------------------- |
| `--rope-scaling`         | Método de escalado RoPE                            | Auto                      |
| `--rope-freq-base`       | Frecuencia base de RoPE                            | Predeterminada del modelo |
| `--rope-freq-scale`      | Escala de frecuencia de RoPE                       | Predeterminada del modelo |
| `--no-prefill-assistant` | Deshabilitar el prellenado del asistente           | Desactivado               |
| `--reasoning-budget`     | Presupuesto de tokens para modelos de razonamiento | 0 (deshabilitado)         |

### Parámetros de vLLM

Cuando se utiliza el backend de vLLM, hay otros parámetros disponibles.

Usa `--hf_overrides` para pasar anulaciones (overrides) de configuración del modelo de HuggingFace como JSON:

```console
$ docker model configure --hf_overrides '{"rope_scaling": {"type": "dynamic", "factor": 2.0}}' ai/model-vllm
```

## Ajustes predeterminados de configuración

Aquí hay ejemplos completos de configuración para casos de uso comunes.

### Completado de código (rápido, determinista)

```yaml
models:
  coder:
    model: ai/qwen2.5-coder
    context_size: 4096
    runtime_flags:
      - "--temp"
      - "0.1"
      - "--top-k"
      - "1"
      - "--batch-size"
      - "1024"
```

### Asistente de chat (equilibrado)

```yaml
models:
  assistant:
    model: ai/llama3.2
    context_size: 8192
    runtime_flags:
      - "--temp"
      - "0.7"
      - "--top-p"
      - "0.9"
      - "--repeat-penalty"
      - "1.1"
```

### Escritura creativa (temperatura alta)

```yaml
models:
  writer:
    model: ai/llama3.2
    context_size: 8192
    runtime_flags:
      - "--temp"
      - "1.2"
      - "--top-p"
      - "0.95"
      - "--repeat-penalty"
      - "1.0"
```

### Análisis de documentos largos (contexto grande)

```yaml
models:
  analyzer:
    model: ai/qwen2.5-coder:14B
    context_size: 32768
    runtime_flags:
      - "--mlock"
      - "--batch-size"
      - "2048"
```

### Sistema con poca memoria

```yaml
models:
  efficient:
    model: ai/smollm2:360M-Q4_K_M
    context_size: 2048
    runtime_flags:
      - "--threads"
      - "4"
```

## Configuración basada en el entorno

También puedes configurar los modelos a través de variables de entorno en los contenedores:

| Variable    | Descripción                                           |
| ----------- | ----------------------------------------------------- |
| `LLM_URL`   | URL inyectada automáticamente del endpoint del modelo |
| `LLM_MODEL` | Identificador del modelo inyectado automáticamente    |

Consulta [Modelos y Compose](/ai/compose/models-and-compose/) para obtener detalles sobre cómo se rellenan estas variables.

## Restablecer configuración

La configuración establecida a través de `docker model configure` persiste hasta que se elimina el modelo. Para restablecer la configuración:

```console
$ docker model configure --context-size -1 ai/qwen2.5-coder
```

El uso de `-1` restablece el valor predeterminado.

## Qué sigue

- [Motores de inferencia](/ai/model-runner/configuration/inference-engines/) - Obtén información sobre llama.cpp y vLLM
- [Referencia de la API](/ai/model-runner/configuration/api-reference/) - Parámetros de la API para la configuración por solicitud
- [Modelos y Compose](/ai/compose/models-and-compose/) - Configura modelos en aplicaciones de Compose