Cómo ejecutar modelos de lenguaje de gran tamaño (LLM) localmente con Docker

Cuando los desarrolladores conocen los modelos de lenguaje grandes (LLM), suele ser en un contexto muy asociado con modelos fundacionales, como GPT-4o de OpenAI, Gemini 2.5 Pro de Google y Claude Sonnet 4 de Anthropic. Sin embargo, algunos casos de uso de IA generativa pueden resolverse completamente de forma local en tu propia máquina de desarrollo.

En esta guía de inicio rápido, te explicaré brevemente cómo configurar modelos para ejecutarlos localmente en tu laptop (o hacer inferencias, si tienes las GPU necesarias), sin tener que profundizar en la terminología del aprendizaje automático, las herramientas de Python u otros conocimientos que pueden parecer fuera de tu alcance como desarrollador de software.

¿Por qué ejecutar modelos LLM localmente en tu propia máquina?

Ya sea por el costo de los modelos, las inquietudes sobre privacidad y seguridad, las políticas de la empresa o las regulaciones externas, algunos casos de uso y requisitos exigen ejecutar modelos localmente en tu propio entorno (un centro de datos local) o directamente en tu PC o laptop.

Cómo ejecutar modelos con Docker

Docker se ha destacado por ser una tecnología que abstrae muchos de los desafíos de empaquetar aplicaciones y permite ejecutarlas sin problemas en distintas plataformas. Ahora Docker hace lo mismo con los LLM.

Para este tutorial necesitas:

• Docker Engine o Docker Desktop, versión 4.41 o posterior. Te recomendamos actualizar tu instalación local para completar el tutorial correctamente.

Para obtener más información, consulta la documentación de Docker Model Runner.

Paso 1: Habilita Docker Model Runner

Si actualizaste a la versión más reciente de Docker, es muy probable que esta función ya esté habilitada. Sin embargo, también tendrás que habilitar host-side TCP support para poder conectarte al modelo desde código de programa, por ejemplo, con el AI SDK de Vercel. De lo contrario, solo podrás interactuar con el ejecutor de modelos mediante la CLI de docker.

Abre Docker Desktop Settings, ve a Beta features, y habilita estas dos opciones:

• “Enable Docker Model Runner”

• “Enable host-side TCP support”

Paso 2: Obtén un modelo LLM

Después, abre el panel de Docker Desktop y selecciona Models en el menú de la barra lateral izquierda para ver todos los modelos disponibles:

También puedes buscar modelos en la web, en Docker Hub.

Usaremos el modelo smollm2, que ocupa menos de 300 megabytes de espacio en disco. Sin embargo, para obtener un mejor rendimiento, recomiendo los modelos de la familia 3B a 4B, como gemma3, o el siguiente nivel, con modelos de 7B a 8B parámetros. También puedes probar phi4 de Microsoft, con 14B parámetros.

Ten en cuenta que el rendimiento del modelo depende en gran medida de la CPU y la GPU locales, así como del motor de inferencia disponible localmente para aprovechar esos recursos. Docker facilita la experimentación local, pero es probable que la configuración predeterminada no esté optimizada para obtener el mejor rendimiento.

Ahora que elegimos el modelo local que queremos ejecutar, basta con ejecutar este comando desde la terminal:

docker model run ai/smollm2

Como es probable que no tengas el modelo instalado en tu entorno, Docker lo descargará del registro y luego lo ejecutará:

Ahora puedes interactuar con el modelo en una sesión interactiva desde la CLI.

Paso 3: Usa el LLM local desde un SDK de IA

El AI SDK de Vercel suele usarse con endpoints de modelos alojados, como los de OpenAI o Anthropic. Sin embargo, se puede adaptar fácilmente para funcionar con un modelo autohospedado, como uno que se ejecuta mediante Docker Model Runner.

Por lo general, para enviar instrucciones a un LLM se crea un fetcher personalizado con las primitivas createStreamableUI() y streamText() del SDK. A continuación se muestra un ejemplo de código TypeScript que ilustra cómo configurarlo como si fuera un endpoint de OpenAI.

Primero, asegúrate de tener instalado el AI SDK:

npm install ai

Configura las variables de entorno:

OPENAI_API_KEY=docker
OPENAI_BASE_URL=http://localhost:12434/engines/llama.cpp/v1

Ten en cuenta que OPENAI_API_KEY se establece en docker; no es un marcador de posición genérico.

Luego, podemos usar una definición de ruta de API como la siguiente:

import { OpenAIStream, StreamingTextResponse } from 'ai';
import OpenAI from 'openai';

// or 'nodejs' depending on your environment
export const runtime = 'edge';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
  baseURL: process.env.OPENAI_BASE_URL!,
});

export async function POST(req: Request) {
  const { messages } = await req.json();

  const response = await openai.chat.completions.create({
    model: 'ai/smollm2',
    messages,
    stream: true,
  });

  const stream = OpenAIStream(response);
  return new StreamingTextResponse(stream);
}

También puedes usar el SDK oficial de OpenAI y configurarlo con nuestros propios valores locales de Docker Model Runner para OPENAI_BASE_URL y OPENAI_API_KEY.

Más sobre Docker, IA y seguridad

Ahora que tienes un LLM ejecutándose localmente, quizá te interese tomar medidas para garantizar que los LLM generen código seguro, asegurarte de conocer los ataques de inyección de prompts y explorar el espacio de MCP.

Si quieres profundizar en alguno de estos temas, te recomiendo los siguientes artículos:

• Como ya tienes Docker para este tutorial sobre LLM locales, quizá te interese explorar cómo ejecutar servidores MCP con Docker.

• Descubre cómo se puede aprovechar el texto invisible de un PDF para realizar una inyección de prompts y engañar a la lógica basada en LLM.

• Si no conoces MCP, te recomendamos leer esta guía para comprender visualmente la arquitectura de MCP.

• Sobre MCP, consulta algunos de los servidores MCP más populares para desarrolladores.