Compartir comentarios
Las respuestas se generan en base a la documentación.

Definir modelos de IA en aplicaciones de Docker Compose

Tabla de contenidos
Requiere: Docker Compose 2.38.0 y posterior

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

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

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:

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

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:

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:

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:

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

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

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

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

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

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

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

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.

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