Modelos locales con Docker Model Runner

Tabla de contenidos

Docker Model Runner te permite ejecutar modelos de IA de forma local en tu máquina. Sin claves de API, sin costos recurrentes y tus datos permanecen privados.

¿Por qué usar modelos locales?

Docker Model Runner te permite ejecutar modelos localmente sin claves de API ni costos recurrentes. Tus datos permanecen en tu máquina y puedes trabajar sin conexión (offline) una vez descargados los modelos. Esta es una alternativa a los proveedores de modelos en la nube.

Requisitos previos

Necesitas tener instalado y en ejecución Docker Model Runner:

Docker Desktop (macOS/Windows) - Habilita Docker Model Runner en Settings > AI > Enable Docker Model Runner (Configuración > IA > Habilitar Docker Model Runner). Consulta Primeros pasos con DMR para obtener instrucciones detalladas.
Docker Engine (Linux) - Instálalo con sudo apt-get install docker-model-plugin o sudo dnf install docker-model-plugin. Consulta Primeros pasos con DMR.

Verifica que Docker Model Runner esté disponible:

$ docker model version

Si el comando devuelve información sobre la versión, estás listo para usar modelos locales.

Uso de modelos con DMR

Docker Model Runner puede ejecutar cualquier modelo compatible. Los modelos pueden provenir de:

Repositorios de Docker Hub (docker.io/namespace/nombre-modelo)
Tus propios artefactos OCI empaquetados y subidos a cualquier registro
Modelos de Hugging Face directamente (hf.co/org/nombre-modelo)
El catálogo de modelos de Docker en Docker Desktop

Para ver los modelos disponibles en el catálogo local de Docker, ejecuta:

$ docker model list --openai

Para usar un modelo, haz referencia a él en tu configuración. DMR descarga (pull) automáticamente los modelos en su primer uso si aún no están disponibles de forma local.

Configuración

Configura tu agente para que use Docker Model Runner con el proveedor dmr:

agents:
  root:
    model: dmr/ai/qwen3
    instruction: You are a helpful assistant
    toolsets:
      - type: filesystem

La primera vez que ejecutes tu agente, Docker Agent te preguntará si deseas descargar el modelo si aún no está disponible de forma local:

$ docker agent run agent.yaml
Model not found locally. Do you want to pull it now? ([y]es/[n]o)

Cómo funciona

Cuando configuras un agente para usar DMR, Docker Agent se conecta automáticamente a tu Docker Model Runner local y le redirige las solicitudes de inferencia. Si un modelo no está disponible localmente, Docker Agent te pedirá descargarlo en el primer uso. No se requieren claves de API ni autenticación.

Configuración avanzada

Para un mayor control sobre el comportamiento del modelo, define una configuración de modelo:

models:
  local-qwen:
    provider: dmr
    model: ai/qwen3:14B
    temperature: 0.7
    max_tokens: 8192

agents:
  root:
    model: local-qwen
    instruction: You are a helpful coding assistant

Inferencia más rápida con decodificación especulativa

Acelera las respuestas del modelo utilizando decodificación especulativa con un modelo borrador (draft model) más pequeño:

models:
  fast-qwen:
    provider: dmr
    model: ai/qwen3:14B
    provider_opts:
      speculative_draft_model: ai/qwen3:0.6B-Q4_K_M
      speculative_num_tokens: 16
      speculative_acceptance_rate: 0.8

El modelo borrador genera candidatos de tokens y el modelo principal los valida. Esto puede mejorar significativamente el rendimiento de las respuestas más largas.

Flags de ejecución (Runtime flags)

Pasa flags específicos del motor para optimizar el rendimiento:

models:
  optimized-qwen:
    provider: dmr
    model: ai/qwen3
    provider_opts:
      runtime_flags: ["--ngl=33", "--threads=8"]

Flags comunes:

--ngl - Número de capas de GPU
--threads - Número de hilos de CPU
--repeat-penalty - Penalización por repetición

Uso de DMR para RAG

Docker Model Runner admite tanto incrustaciones (embeddings) como reclasificaciones (reranking) para flujos de trabajo RAG.

Incrustación (Embedding) con DMR

Utiliza incrustaciones locales para indexar tu base de conocimientos:

rag:
  codebase:
    docs: [./src]
    strategies:
      - type: chunked-embeddings
        embedding_model: dmr/ai/embeddinggemma
        database: ./code.db

Reclasificación (Reranking) con DMR

DMR proporciona reclasificación nativa para obtener mejores resultados en RAG:

models:
  reranker:
    provider: dmr
    model: hf.co/ggml-org/qwen3-reranker-0.6b-q8_0-gguf

rag:
  docs:
    docs: [./documentation]
    strategies:
      - type: chunked-embeddings
        embedding_model: dmr/ai/embeddinggemma
        limit: 20
    results:
      reranking:
        model: reranker
        threshold: 0.5
      limit: 5

La reclasificación nativa de DMR es la opción más rápida para reclasificar los resultados de RAG.

Resolución de problemas

Si Docker Agent no puede encontrar Docker Model Runner:

Verifica el estado de Docker Model Runner:
$ docker model status
Comprueba los modelos disponibles:
$ docker model list
Revisa los registros del modelo en busca de errores:
$ docker model logs
Asegúrate de que Docker Desktop tenga habilitado Model Runner en la configuración (macOS/Windows)

¿Qué sigue?

Sigue el tutorial para crear tu primer agente con modelos locales
Aprende sobre RAG para dar acceso a tus agentes a códigos fuente y documentación
Consulta la referencia de configuración para conocer todas las opciones de DMR

¿En qué te puedo ayudar?

Modelos locales con Docker Model Runner