API REST de DMR

Una vez habilitado Model Runner, nuevos endpoints de la API estarán disponibles. Puedes usar estos endpoints para interactuar con un modelo de forma programática. Docker Model Runner proporciona compatibilidad con los formatos de API de OpenAI, Anthropic y Ollama.

Determinar la URL base

La URL base para interactuar con los endpoints depende de cómo ejecutes Docker y de qué formato de API estés utilizando.

Acceso desde	URL base
Contenedores	`http://model-runner.docker.internal`
Procesos del host (TCP)	`http://localhost:12434`

Note
El acceso TCP desde el host debe estar habilitado. Consulta Habilitar Docker Model Runner.

Acceso desde	URL base
Contenedores	`http://172.17.0.1:12434`
Procesos del host	`http://localhost:12434`

Note
Es posible que la interfaz 172.17.0.1 no esté disponible por defecto para los contenedores dentro de un proyecto de Compose. En este caso, añade una directiva extra_hosts al YAML de tu servicio de Compose:
extra_hosts:
  - "model-runner.docker.internal:host-gateway"
De este modo, podrás acceder a las API de Docker Model Runner en http://model-runner.docker.internal:12434/

URL base para herramientas de terceros

Al configurar herramientas de terceros que esperan API compatibles con OpenAI, utiliza estas URL base:

Tipo de herramienta	Formato de URL base
SDK / clientes de OpenAI	`http://localhost:12434/engines/v1`
SDK / clientes de Anthropic	`http://localhost:12434`
Clientes compatibles con Ollama	`http://localhost:12434`

Consulta Integraciones de IDE y herramientas para ver ejemplos de configuración específicos.

API compatibles

Docker Model Runner admite múltiples formatos de API:

API	Descripción	Caso de uso
API de OpenAI	Completados de chat y embeddings compatibles con OpenAI	La mayoría de frameworks y herramientas de IA
API de Anthropic	Endpoint de mensajes compatible con Anthropic	Herramientas creadas para Claude
API de Ollama	Endpoints compatibles con Ollama	Herramientas creadas para Ollama
API de generación de imágenes	Generación de imágenes basada en Diffusers	Generación de imágenes a partir de prompts de texto
API de DMR	Endpoints nativos de Docker Model Runner	Gestión de modelos

API compatible con OpenAI

DMR implementa la especificación de la API de OpenAI para lograr la máxima compatibilidad con las herramientas y frameworks existentes.

Endpoints

Endpoint	Método	Descripción
`/engines/v1/models`	GET	Listar modelos
`/engines/v1/models/{namespace}/{name}`	GET	Obtener modelo
`/engines/v1/chat/completions`	POST	Crear completado de chat
`/engines/v1/completions`	POST	Crear completado
`/engines/v1/embeddings`	POST	Crear embeddings

Note
Opcionalmente, puedes incluir el nombre del motor en la ruta: /engines/llama.cpp/v1/chat/completions. Esto es útil cuando se ejecutan varios motores de inferencia.

Formato del nombre del modelo

Al especificar un modelo en las solicitudes de la API, utiliza el identificador de modelo completo, incluyendo el espacio de nombres:

{
  "model": "ai/smollm2",
  "messages": [...]
}

Formatos comunes de nombres de modelos:

Modelos de Docker Hub: ai/smollm2, ai/llama3.2, ai/qwen2.5-coder
Versiones con etiquetas: ai/smollm2:360M-Q4_K_M
Modelos personalizados: miorg/mimodel

Parámetros admitidos

Se admiten los siguientes parámetros de la API de OpenAI:

Parámetro	Tipo	Descripción
`model`	string	Requerido. El identificador del modelo.
`messages`	array	Requerido para completados de chat. El historial de la conversación.
`prompt`	string	Requerido para completados. El texto del prompt.
`max_tokens`	integer	Cantidad máxima de tokens a generar.
`temperature`	float	Temperatura de muestreo (0.0-2.0).
`top_p`	float	Parámetro de muestreo nucleus (0.0-1.0).
`stream`	Boolean	Habilitar respuestas en streaming.
`stop`	string/array	Secuencias de parada.
`presence_penalty`	float	Penalización de presencia (-2.0 a 2.0).
`frequency_penalty`	float	Penalización de frecuencia (-2.0 a 2.0).

Limitaciones y diferencias con OpenAI

Ten en cuenta estas diferencias al utilizar la API compatible con OpenAI de DMR:

Característica	Comportamiento de DMR
Clave de API	No requerida. DMR ignora la cabecera `Authorization`.
Llamada a funciones	Admitida con llama.cpp para modelos compatibles.
Visión	Admitida para modelos multimodales (por ejemplo, LLaVA).
Modo JSON	Admitido mediante `response_format: {"type": "json_object"}`.
Logprobs	Admitido.
Conteo de tokens	Utiliza el codificador de tokens nativo del modelo, el cual puede diferir del de OpenAI.

API compatible con Anthropic

DMR proporciona compatibilidad con la API de mensajes de Anthropic para herramientas y frameworks creados para Claude.

Endpoints

Endpoint	Método	Descripción
`/anthropic/v1/messages`	POST	Crear un mensaje
`/anthropic/v1/messages/count_tokens`	POST	Contar tokens

Parámetros admitidos

Se admiten los siguientes parámetros de la API de Anthropic:

Parámetro	Tipo	Descripción
`model`	string	Requerido. El identificador del modelo.
`messages`	array	Requerido. Los mensajes de la conversación.
`max_tokens`	integer	Cantidad máxima de tokens a generar.
`temperature`	float	Temperatura de muestreo (0.0-1.0).
`top_p`	float	Parámetro de muestreo nucleus.
`top_k`	integer	Parámetro de muestreo top-k.
`stream`	Boolean	Habilitar respuestas en streaming.
`stop_sequences`	array	Secuencias de parada personalizadas.
`system`	string	Prompt del sistema.

Ejemplo: Chat con la API de Anthropic

curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Ejemplo: Respuesta en streaming

curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from 1 to 10"}
    ]
  }'

API compatible con Ollama

DMR también proporciona endpoints compatibles con Ollama para herramientas y frameworks creados para Ollama.

Endpoints

Endpoint	Método	Descripción
`/api/tags`	GET	Listar modelos disponibles
`/api/show`	POST	Mostrar información del modelo
`/api/chat`	POST	Crear completado de chat
`/api/generate`	POST	Crear completado
`/api/embeddings`	POST	Generar embeddings

Ejemplo: Chat con la API de Ollama

curl http://localhost:12434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Ejemplo: Listar modelos

curl http://localhost:12434/api/tags

API de generación de imágenes (Diffusers)

DMR admite la generación de imágenes a través del backend de Diffusers, lo que te permite generar imágenes a partir de prompts de texto utilizando modelos como Stable Diffusion.

Note
El backend de Diffusers requiere una GPU NVIDIA con soporte para CUDA y solo está disponible en Linux (x86_64 y ARM64). Consulta Motores de inferencia para obtener instrucciones de configuración.

Endpoint

Endpoint	Método	Descripción
`/engines/diffusers/v1/images/generations`	POST	Generar una imagen a partir de un prompt de texto

Parámetros admitidos

Parámetro	Tipo	Descripción
`model`	string	Requerido. El identificador del modelo (por ejemplo, `stable-diffusion:Q4`).
`prompt`	string	Requerido. La descripción en texto de la imagen a generar.
`size`	string	Dimensiones de la imagen en formato `ANCHO_POR_ALTO` (por ejemplo, `512x512`).

Formato de respuesta

El API devuelve una respuesta JSON con la imagen generada codificada en base64:

{
  "data": [
    {
      "b64_json": "<base64-encoded-image-data>"
    }
  ]
}

Ejemplo: Generar una imagen

curl -s -X POST http://localhost:12434/engines/diffusers/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stable-diffusion:Q4",
    "prompt": "A picture of a nice cat",
    "size": "512x512"
  }' | jq -r '.data[0].b64_json' | base64 -d > image.png

Este comando:

Envía una solicitud POST al endpoint de generación de imágenes de Diffusers.
Especifica el modelo, el prompt y el tamaño de la imagen de salida.
Extrae la imagen codificada en base64 de la respuesta utilizando jq.
Decodifica los datos en base64 y los guarda como image.png.

Endpoints nativos de DMR

Estos endpoints son específicos de Docker Model Runner para la gestión de modelos:

Endpoint	Método	Descripción
`/models/create`	POST	Descargar/crear un modelo
`/models`	GET	Listar modelos locales
`/models/{namespace}/{name}`	GET	Obtener detalles del modelo
`/models/{namespace}/{name}`	DELETE	Eliminar un modelo local

Ejemplos de API REST

Solicitud desde el interior de un contenedor

Para llamar al endpoint de OpenAI chat/completions desde el interior de otro contenedor utilizando curl:

#!/bin/sh

curl http://model-runner.docker.internal/engines/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "ai/smollm2",
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Please write 500 words about the fall of Rome."
            }
        ]
    }'

Solicitud desde el host utilizando TCP

Para llamar al endpoint de OpenAI chat/completions desde el host a través de TCP:

Habilita el soporte de TCP en el lado del host desde la interfaz de usuario de Docker Desktop, o a través de la CLI de Docker Desktop. Por ejemplo: docker desktop enable model-runner --tcp <port>.
Si estás ejecutando en Windows, habilita también la inferencia respaldada por GPU. Consulta Habilitar Docker Model Runner.
Interactúa con él como se documenta en la sección anterior utilizando localhost y el puerto correcto.

#!/bin/sh

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
      "model": "ai/smollm2",
      "messages": [
          {
              "role": "system",
              "content": "You are a helpful assistant."
          },
          {
              "role": "user",
              "content": "Please write 500 words about the fall of Rome."
          }
      ]
  }'

Solicitud desde el host utilizando un socket Unix

Para llamar al endpoint de OpenAI chat/completions a través del socket de Docker desde el host utilizando curl:

#!/bin/sh

curl --unix-socket $HOME/.docker/run/docker.sock \
    localhost/exp/vDD4.40/engines/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "ai/smollm2",
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Please write 500 words about the fall of Rome."
            }
        ]
    }'

Respuestas en streaming

Para recibir respuestas en streaming, establece stream: true:

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
      "model": "ai/smollm2",
      "stream": true,
      "messages": [
          {"role": "user", "content": "Count from 1 to 10"}
      ]
  }'

Uso con SDK de OpenAI

Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="not-needed"  # DMR no requiere una clave de API
)

response = client.chat.completions.create(
    model="ai/smollm2",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:12434/engines/v1",
  apiKey: "not-needed",
});

const response = await client.chat.completions.create({
  model: "ai/smollm2",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);

Qué sigue

Integraciones de IDE y herramientas - Configura Cline, Continue, Cursor y otras herramientas
Opciones de configuración - Ajusta el tamaño del contexto y los parámetros de tiempo de ejecución
Motores de inferencia - Obtén información sobre las opciones de llama.cpp, vLLM y Diffusers

¿En qué te puedo ayudar?

API REST de DMR