# Definir modelos de IA en aplicaciones de Docker Compose





Compose te permite definir modelos de IA como componentes principales de tu aplicación, de modo que puedes declarar dependencias de modelos junto con los servicios y ejecutar la aplicación en cualquier plataforma que admita la Especificación de Compose.

## Requisitos previos

- Docker Compose v2.38 o posterior
- Una plataforma que admita modelos de Compose, como [Docker Model Runner (DMR)](/ai/model-runner/#requirements).

## ¿Qué son los modelos de Compose?

Los `models` de Compose son una forma estandarizada de definir dependencias de modelos de IA en tu aplicación. Al usar el [elemento de nivel superior `models`](/reference/compose-file/models/) en tu archivo de Compose, puedes:

- Declarar qué modelos de IA necesita tu aplicación
- Especificar configuraciones y requisitos del modelo
- Hacer que tu aplicación sea portable entre diferentes plataformas
- Permitir que la plataforma se encargue del aprovisionamiento del modelo y de la gestión de su ciclo de vida

## Definición básica de un modelo

Para definir modelos en tu aplicación de Compose, utiliza el elemento de nivel superior `models`:

```yaml
services:
  chat-app:
    image: my-chat-app
    models:
      - llm

models:
  llm:
    model: ai/smollm2
```

Este ejemplo define:

- Un servicio llamado `chat-app` que utiliza un modelo llamado `llm`
- Una definición de modelo para `llm` que hace referencia a la imagen de modelo `ai/smollm2`

## Opciones de configuración del modelo

Los modelos admiten varias opciones de configuración:

```yaml
models:
  llm:
    model: ai/smollm2
    context_size: 1024
    runtime_flags:
      - "--a-flag"
      - "--another-flag=42"
```

Las opciones de configuración comunes incluyen:

- `model` (obligatorio): El identificador de artefacto OCI para el modelo. Esto es lo que Compose descarga (pull) y ejecuta a través del model runner.
- `context_size`: Define el tamaño máximo del contexto de tokens para el modelo.

  > [!NOTE]
  > Cada modelo tiene su propio tamaño de contexto máximo. Al aumentar la longitud del contexto,
  > ten en cuenta las limitaciones de tu hardware. En general, intenta mantener el tamaño del contexto
  > tan pequeño como sea factible para tus necesidades específicas.

- `runtime_flags`: Una lista de flags de línea de comandos sin procesar que se pasan al motor de inferencia cuando se inicia el modelo.
  Consulta las [Opciones de configuración](/ai/model-runner/configuration/) para ver ejemplos y parámetros de uso común.
- Las opciones específicas de la plataforma también pueden estar disponibles a través de atributos de extensión `x-*`

> [!TIP]
> Consulta más ejemplos en la sección de [Configuraciones comunes de ejecución](#configuraciones-comunes-de-ejecución).

## Vinculación de modelos a servicios

Los servicios pueden hacer referencia a los modelos de dos formas: sintaxis corta y sintaxis larga.

### Sintaxis corta

La sintaxis corta es la forma más sencilla de vincular un modelo a un servicio:

```yaml
services:
  app:
    image: my-app
    models:
      - llm
      - embedding-model

models:
  llm:
    model: ai/smollm2
  embedding-model:
    model: ai/all-minilm
```

Con la sintaxis corta, la plataforma genera automáticamente variables de entorno basadas en el nombre del modelo:

- `LLM_URL` - URL para acceder al modelo LLM
- `LLM_MODEL` - Identificador de modelo para el modelo LLM
- `EMBEDDING_MODEL_URL` - URL para acceder al modelo de incrustación (embedding-model)
- `EMBEDDING_MODEL_MODEL` - Identificador de modelo para el modelo de incrustación

### Sintaxis larga

La sintaxis larga te permite personalizar los nombres de las variables de entorno:

```yaml
services:
  app:
    image: my-app
    models:
      llm:
        endpoint_var: AI_MODEL_URL
        model_var: AI_MODEL_NAME
      embedding-model:
        endpoint_var: EMBEDDING_URL
        model_var: EMBEDDING_NAME

models:
  llm:
    model: ai/smollm2
  embedding-model:
    model: ai/all-minilm
```

Con esta configuración, tu servicio recibe:

- `AI_MODEL_URL` y `AI_MODEL_NAME` para el modelo LLM
- `EMBEDDING_URL` y `EMBEDDING_NAME` para el modelo de incrustación

## Portabilidad de la plataforma

Uno de los beneficios clave de usar modelos de Compose es la portabilidad entre diferentes plataformas que admiten la especificación de Compose.

### Docker Model Runner

Cuando [Docker Model Runner está habilitado](/ai/model-runner/):

```yaml
services:
  chat-app:
    image: my-chat-app
    models:
      llm:
        endpoint_var: AI_MODEL_URL
        model_var: AI_MODEL_NAME

models:
  llm:
    model: ai/smollm2
    context_size: 4096
    runtime_flags:
      - "--no-prefill-assistant"
```

Docker Model Runner hará lo siguiente:

- Descargar y ejecutar el modelo especificado localmente
- Proporcionar URLs de endpoint para acceder al modelo
- Inyectar variables de entorno en el servicio

### Proveedores en la nube

La especificación de modelos de Compose es portable. Las plataformas que implementan la especificación de Compose pueden admitir el elemento de nivel superior `models`, lo que permite que el mismo archivo de Compose se ejecute en diferentes infraestructuras. El comportamiento específico de la nube se puede configurar utilizando atributos de extensión (`x-*`):

```yaml
services:
  chat-app:
    image: my-chat-app
    models:
      - llm

models:
  llm:
    model: ai/smollm2
    # Configuraciones específicas de la nube
    x-cloud-options:
      - "cloud.instance-type=gpu-small"
      - "cloud.region=us-west-2"
```

La forma en que una plataforma maneja las definiciones de modelos depende de su implementación. Una plataforma podría:

- Usar servicios de IA gestionados en lugar de ejecutar modelos localmente
- Aplicar optimizaciones y escalados específicos de la plataforma
- Proporcionar capacidades adicionales de monitoreo y registro
- Manejar el control de versiones y las actualizaciones de los modelos de forma automática

## Configuraciones comunes de ejecución

A continuación se presentan algunas configuraciones de ejemplo para varios casos de uso.

### Desarrollo

```yaml
services:
  app:
    image: app
    models:
      dev_model:
        endpoint_var: DEV_URL
        model_var: DEV_MODEL

models:
  dev_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--verbose" # Establecer el nivel de detalle a infinito
      - "--verbose-prompt" # Imprimir un prompt detallado antes de la generación
      - "--log-prefix" # Habilitar prefijo en los mensajes de registro
      - "--log-timestamps" # Habilitar marcas de tiempo en los mensajes de registro
      - "--log-colors" # Habilitar registro con colores
```

### Conservador con razonamiento deshabilitado

```yaml
services:
  app:
    image: app
    models:
      conservative_model:
        endpoint_var: CONSERVATIVE_URL
        model_var: CONSERVATIVE_MODEL

models:
  conservative_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp" # Temperatura
      - "0.1"
      - "--top-k" # Muestreo top-k
      - "1"
      - "--reasoning-budget" # Deshabilitar presupuesto de razonamiento
      - "0"
```

### Creativo con alta aleatoriedad

```yaml
services:
  app:
    image: app
    models:
      creative_model:
        endpoint_var: CREATIVE_URL
        model_var: CREATIVE_MODEL

models:
  creative_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp" # Temperatura
      - "1"
      - "--top-p" # Muestreo top-p
      - "0.9"
```

### Altamente determinista

```yaml
services:
  app:
    image: app
    models:
      deterministic_model:
        endpoint_var: DET_URL
        model_var: DET_MODEL

models:
  deterministic_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp" # Temperatura
      - "0"
      - "--top-k" # Muestreo top-k
      - "1"
```

### Procesamiento concurrente

```yaml
services:
  app:
    image: app
    models:
      concurrent_model:
        endpoint_var: CONCURRENT_URL
        model_var: CONCURRENT_MODEL

models:
  concurrent_model:
    model: ai/model
    context_size: 2048
    runtime_flags:
      - "--threads" # Número de hilos a usar durante la generación
      - "8"
      - "--mlock" # Bloquear memoria para evitar el intercambio (swapping)
```

### Modelo de vocabulario rico

```yaml
services:
  app:
    image: app
    models:
      rich_vocab_model:
        endpoint_var: RICH_VOCAB_URL
        model_var: RICH_VOCAB_MODEL

models:
  rich_vocab_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp" # Temperatura
      - "0.1"
      - "--top-p" # Muestreo top-p
      - "0.9"
```

### Incrustaciones (Embeddings)

Cuando utilices modelos de incrustación con el endpoint `/v1/embeddings`, debes incluir el flag de ejecución `--embeddings` para que el modelo se configure correctamente.

```yaml
services:
  app:
    image: app
    models:
      embedding_model:
        endpoint_var: EMBEDDING_URL
        model_var: EMBEDDING_MODEL

models:
  embedding_model:
    model: ai/all-minilm
    context_size: 2048
    runtime_flags:
      - "--embeddings" # Requerido para modelos de incrustación
```

## Referencia

- [Elemento de nivel superior `models`](/reference/compose-file/models/)
- [Atributo `models`](/reference/compose-file/services/#models)
- [Documentación de Docker Model Runner](/ai/model-runner/)
- [Opciones de configuración](/ai/model-runner/configuration/) - Tamaño de contexto y parámetros de ejecución
- [Motores de inferencia](/ai/model-runner/inference-engines/) - Detalles de llama.cpp y vLLM
- [Referencia de API](/ai/model-runner/api-reference/) - APIs compatibles con OpenAI y Ollama