1. Introducción
Docker Model Runner, introducido en Docker Desktop 4.40 para Mac con Apple Silicon (al momento de redactar este artículo), revoluciona el desarrollo local de IA al simplificar la implementación y gestión de modelos de lenguaje grande (LLMs). Aborda desafíos comunes como procesos de configuración complejos, altos costos de inferencia en la nube y preocupaciones de privacidad de datos.
Al ofrecer una API de Inferencia compatible con OpenAI, Model Runner permite la integración sin problemas con frameworks como Spring AI, lo que permite a los desarrolladores crear aplicaciones impulsadas por IA localmente con facilidad. En este tutorial, aprenderemos a configurar Docker Model Runner y crear una aplicación Spring AI que se conecte a él. Al final, tendremos una aplicación de IA local totalmente funcional que aprovecha un potente LLM.
2. Docker Model Runner
Docker Model Runner es una herramienta diseñada para simplificar la implementación y ejecución de LLMs dentro de contenedores Docker. Es un motor de inferencia de IA que ofrece una amplia gama de modelos de diversos proveedores.
Veamos las funciones clave que incluye Docker Model Runner:
-
Implementación de modelos simplificada: Los modelos se distribuyen como artefactos estándar de la Open Container Initiative (OCI) en Docker Hub bajo el espacio de nombres ai. Esto facilita la descarga, ejecución y gestión de modelos de IA directamente dentro de Docker Desktop.
-
Amplio soporte de modelos: Admite una variedad de LLMs de múltiples proveedores, como Mistral, LLaMA y Phi-4, garantizando flexibilidad en la selección del modelo.
-
Inferencia local: Ejecuta modelos localmente, mejorando la privacidad de los datos y eliminando la dependencia de la inferencia basada en la nube.
-
API compatible con OpenAI: Proporciona una API estándar que se integra sin esfuerzo con los frameworks de IA existentes, reduciendo la carga de desarrollo.
3. Configuración del entorno
Esta sección describe los requisitos previos para usar Docker Model Runner y las dependencias de Maven para crear una aplicación Spring AI que utilice Model Runner.
3.1. Requisitos previos
Para usar Docker Model Runner, necesitaremos algunas cosas:
- Docker Desktop 4.40 o posterior: Instalado en un Mac con Apple Silicon.
- Java 21 o posterior: Requerido para el desarrollo de Spring AI.
- LLM compatible con Model Runner: Un modelo compatible con Docker Model Runner, como LLaMA o Gemma 3.
3.2. Dependencias de Maven
Comencemos importando las dependencias spring-boot-starter-web, spring-ai-openai-spring-boot-starter, spring-ai-spring-boot-testcontainers y junit-jupiter al pom.xml:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>1.0.0-M6</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
<version>1.0.0-M6</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-spring-boot-testcontainers</artifactId>
<version>1.0.0-M6</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>junit-jupiter</artifactId>
<version>1.19.8</version>
<scope>test</scope>
</dependency>
4. Habilitar y configurar Docker Model Runner
Esta sección describe los pasos para habilitar Docker Model Runner y descargar un modelo específico utilizando dos métodos distintos.
4.1. Habilitar Model Runner con un puerto TCP específico
Primero, habilitemos Model Runner y expongámoslo en un puerto TCP específico (por ejemplo, 12434):
docker desktop enable model-runner --tcp 12434
Esto configura Model Runner para escuchar en http://localhost:12434/engines. En nuestra aplicación Spring AI, necesitamos configurar la api-key, model y la URL base para apuntar al punto final de Model Runner:
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.base-url=http://localhost:12434/engines
spring.ai.openai.chat.options.model=ai/gemma3
4.2. Habilitar Model Runner con Testcontainers
Podemos ejecutar el siguiente comando para habilitar Model Runner sin especificar un puerto:
docker desktop enable model-runner
Esto configura Model Runner para ejecutarse en la red Docker interna predeterminada. Luego, utilizamos Testcontainers y configuramos base-url, api-key y model de la siguiente manera:
@TestConfiguration(proxyBeanMethods = false)
class TestcontainersConfiguration {
@Bean
DockerModelRunnerContainer socat() {
return new DockerModelRunnerContainer("alpine/socat:1.8.0.1");
}
@Bean
DynamicPropertyRegistrar properties(DockerModelRunnerContainer dmr) {
return (registrar) -> {
registrar.add("spring.ai.openai.base-url", dmr::getOpenAIEndpoint);
registrar.add("spring.ai.openai.api-key", () -> "test-api-key");
registrar.add("spring.ai.openai.chat.options.model", () -> "ai/gemma3");
};
}
}
La clase TestcontainersConfiguration proporcionada es una @TestConfiguration de Spring Boot diseñada para pruebas de integración con Testcontainers. Define dos beans: un DockerModelRunnerContainer que inicia un contenedor Docker utilizando la imagen alpine/socat:1.8.0.1, probablemente para proxy o simular un punto final de servicio de IA, y un DynamicPropertyRegistrar que establece dinámicamente las propiedades de Spring AI. Estas propiedades configuran el cliente de IA con una URL base desde el punto final del contenedor (a través de getOpenAIEndpoint()), una clave de API de prueba (test-api-key) y un identificador de modelo (ai/gemma3). La anotación @TestConfiguration(proxyBeanMethods = false) asegura la creación ligera de beans para las pruebas sin hacer proxy. Esta configuración permite que las pruebas simulen un entorno de servicio de IA sin dependencias externas, utilizando el contenedor socat para manejar las solicitudes. El socat reenvía el tráfico al servicio interno model-runner.docker.internal.
4.3. Descargar y verificar el modelo Gemma 3
Ahora, después de habilitar Model Runner usando una de las opciones, descargamos el modelo Gemma 3:
docker model pull ai/gemma3
Luego, podemos confirmar que está disponible localmente:
docker model list
Este comando enumera todos los modelos disponibles localmente, incluido ai/gemma3.
5. Integración con Spring AI
Ahora, creemos un controlador sencillo para interactuar con el modelo:
@RestController
class ModelRunnerController {
private final ChatClient chatClient;
public ModelRunnerController(ChatClient.Builder chatClientBuilder) {
this.chatClient = chatClientBuilder.build();
}
@GetMapping("/chat")
public String chat(@RequestParam("message") String message) {
return this.chatClient.prompt()
.user(message)
.call()
.content();
}
}
5.1. Probar Model Runner con un puerto TCP específico
Para usar Docker Model Runner, debemos configurar el cliente OpenAI para apuntar al punto final correcto y usar el modelo descargado anteriormente. Ahora, iniciamos la aplicación y probamos el punto final /chat:
curl "http://localhost:8080/chat?prompt=What%20is%20the%20future%20of%20AI%20development?"
La respuesta será generada por el modelo Gemma 3 que se ejecuta en Model Runner.
5.2. Probar Model Runner con Testcontainers
Creemos la clase ModelRunnerApplicationTest. Importará la clase TestcontainersConfiguration y llamará al controlador de muestra:
@Import(TestcontainersConfiguration.class)
class ModelRunnerApplicationTest {
// ...
@Test
void givenMessage_whenCallChatController_thenSuccess() {
// given
String userMessage = "Hello, how are you?";
// when
ResponseEntity<String> response = restTemplate.getForEntity(
baseUrl + "/chat?message=" + userMessage, String.class);
// then
assertThat(response.getStatusCode().is2xxSuccessful()).isTrue();
assertThat(response.getBody()).isNotEmpty();
}
}
La anotación @Import(TestcontainersConfiguration.class) importa la clase TestcontainersConfiguration, que define un DockerModelRunnerContainer (ejecutando alpine/socat:1.8.0.1). Además, registra dinámicamente las propiedades de Spring AI (por ejemplo, spring.ai.openai.base-url, spring.ai.openai.api-key, spring.ai.openai.chat.options.model). Esto asegura que el entorno de prueba esté configurado con un punto final de servicio de IA simulado proporcionado por el contenedor administrado por Testcontainers.
6. Conclusión
Docker Model Runner ofrece una solución amigable para el desarrollador, enfocada en la privacidad y rentable para ejecutar LLMs localmente, especialmente para aquellos que construyen aplicaciones GenAI dentro del ecosistema Docker. En este artículo, exploramos las capacidades de Docker Model Runner y demostramos su integración con Spring AI.
Newsletter Semanal de Java
Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.
Sin spam. Cancela cuando quieras.