# Modelos locales con Docker Model Runner


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](/ai/docker-agent/local-models/model-providers/).

## 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](/ai/model-runner/get-started/#enable-docker-model-runner) 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](/ai/model-runner/get-started/#docker-engine).

Verifica que Docker Model Runner esté disponible:

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

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

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

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

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

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

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

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

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

1. Verifica el estado de Docker Model Runner:

   ```console
   $ docker model status
   ```

2. Comprueba los modelos disponibles:

   ```console
   $ docker model list
   ```

3. Revisa los registros del modelo en busca de errores:

   ```console
   $ docker model logs
   ```

4. Asegúrate de que Docker Desktop tenga habilitado Model Runner en la configuración (macOS/Windows)

## ¿Qué sigue?

- Sigue el [tutorial](/ai/docker-agent/local-models/tutorial/) para crear tu primer agente con modelos locales
- Aprende sobre [RAG](/ai/docker-agent/local-models/rag/) para dar acceso a tus agentes a códigos fuente y documentación
- Consulta la [referencia de configuración](/ai/docker-agent/local-models/reference/config/#docker-model-runner-dmr) para conocer todas las opciones de DMR