Saltar al contenido principal

Ollama

Ollama es una herramienta que permite ejecutar modelos de lenguaje grandes (LLMs) directamente en tu máquina, sin depender de APIs externas ni incurrir en costes por token. Expone una API REST local compatible con el formato de OpenAI, lo que facilita su integración en proyectos Node.js.

Ventajas:

  • Privacidad total. Los datos no salen de tu infraestructura.
  • Sin coste por token.
  • Sin latencia de red (para prototipos o entornos controlados).
  • Ideal para desarrollo y testing.

Desventajas:

  • Requiere hardware potente (GPU recomendada).
  • Los modelos locales son menos capaces que los frontier models (GPT-4, Claude, Gemini, etc.).
  • No escala como una API cloud.

Instalación​

macOS / Linux​

curl -fsSL https://ollama.com/install.sh | sh

Windows​

Descarga el instalador desde ollama.com

Docker​

Es la forma más sencilla de ejecutar Ollama de forma aislada.

docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

# Con GPU NVIDIA (requiere NVIDIA Container Toolkit):
docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

Docker Compose​

Para entornos más complejos, es recomendable usar un archivo docker-compose.yml:

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    # Descomenta las siguientes líneas si usas GPU NVIDIA
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: all
    #           capabilities: [gpu]

volumes:
  ollama_data:

Gestión de modelos​

Ollama permite gestionar modelos de forma similar a como Docker gestiona imágenes. Puedes descargar (pull), ejecutar (run) o eliminar (rm) modelos con comandos sencillos.

# Descargar y ejecutar un modelo (abre un chat interactivo en la terminal)
ollama run llama4:8b

# Solo descargar el modelo (útil para scripts o servidores)
ollama pull llama4:8b
ollama pull phi4:3b         # muy rápido y ligero
ollama pull qwen3-coder:7b  # especializado en código

Modelos recomendados (Marzo 2026)​

A continuación se muestran los modelos más populares y eficaces disponibles actualmente en Ollama:

  • llama4:8b: El estándar actual. Excelente equilibrio entre razonamiento, velocidad y coherencia. Ideal para uso general.
  • llama4:70b: Para tareas complejas que requieren razonamiento avanzado. Necesita hardware potente (mínimo 48GB VRAM).
  • phi4:3b: Modelo ultra-ligero de Microsoft. Impresionante rendimiento para su tamaño, ideal si no tienes GPU o tienes poca RAM.
  • mistral-small:22b: Muy popular por su capacidad de seguir instrucciones complejas con un tamaño manejable.
  • qwen3-coder:7b: El mejor modelo actual para generación y corrección de código en múltiples lenguajes.
  • deepseek-r2:7b: Especializado en razonamiento paso a paso (chain-of-thought), ideal para problemas matemáticos o lógicos.
  • nomic-embed-text-v1.5: El estándar para generar embeddings en aplicaciones de búsqueda semántica (RAG).

API REST de Ollama​

Ollama expone su API en http://localhost:11434. Los principales endpoints son:

POST /api/generate​

Completado simple:

curl http://localhost:11434/api/generate \
  -d '{ "model": "llama3.2", "prompt": "¿Qué es Node.js?", "stream": false }'

POST /api/chat​

Chat con historial:

curl http://localhost:11434/api/chat \
  -d '{
    "model": "llama3.2",
    "stream": false,
    "messages": [
      { "role": "user", "content": "¿Qué es el event loop?" }
    ]
  }'

Integración en Node.js​

Opción 1: SDK oficial de Ollama​

npm install ollama
import ollama from 'ollama';

// Chat básico
const response = await ollama.chat({
  model: 'llama3.2',
  messages: [
    { role: 'system', content: 'Eres un asistente de programación.' },
    { role: 'user',   content: '¿Cómo creo un servidor HTTP en Node.js?' }
  ]
});

console.log(response.message.content);

Opción 2: API compatible con OpenAI​

Ollama expone un endpoint compatible con la API de OpenAI en /v1, lo que permite usar el SDK de OpenAI apuntando a Ollama:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:11434/v1',
  apiKey: 'ollama' // Valor requerido pero ignorado por Ollama
});

const response = await client.chat.completions.create({
  model: 'llama3.2',
  messages: [
    { role: 'user', content: '¿Qué es el event loop?' }
  ]
});

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

Esta opción es muy útil para tener un código unificado que funcione tanto con Ollama (local) como con OpenAI (producción) cambiando solo baseURL y apiKey.

Streaming con Ollama​

import ollama from 'ollama';

const stream = await ollama.chat({
  model: 'llama3.2',
  messages: [{ role: 'user', content: 'Explícame los closures en JavaScript' }],
  stream: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.message.content);
}
console.log(); // salto de línea final

Express con Ollama​

import express from 'express';
import ollama from 'ollama';

const app = express();
app.use(express.json());

app.post('/chat', async (req, res) => {
  const { messages } = req.body;

  if (!messages?.length) {
    return res.status(400).json({ error: 'Se requiere el campo messages' });
  }

  try {
    const response = await ollama.chat({
      model: 'llama3.2',
      messages
    });

    res.json({ reply: response.message.content });
  } catch (err) {
    console.error(err);
    res.status(500).json({ error: 'Error al contactar con Ollama' });
  }
});

app.listen(3000, () => console.log('Servidor en http://localhost:3000'));

Modelfiles: personalizar modelos​

A menudo queremos que el modelo tenga una personalidad específica o parámetros fijos (como la temperatura). Ollama permite crear modelos derivados mediante un Modelfile. Esto no es un re-entrenamiento del modelo, sino una configuración de su comportamiento por defecto.

# Modelfile
FROM llama4:8b

# Temperatura baja (0.1 - 0.3) para respuestas más predecibles y precisas
# Temperatura alta (0.7 - 0.9) para respuestas más creativas
PARAMETER temperature 0.2

# System prompt: Define el "rol" del modelo
SYSTEM """
Eres AsistenteNode, un experto en Node.js y desarrollo backend.
Responde siempre en español y con ejemplos de código cuando sea posible.
No respondas preguntas que no estén relacionadas con programación.
"""
# Crear el modelo personalizado
ollama create asistente-node -f ./Modelfile

# Usarlo
ollama run asistente-node
// En Node.js
const response = await ollama.chat({
  model: 'asistente-node',
  messages: [{ role: 'user', content: '¿Cómo uso streams en Node.js?' }]
});

Embeddings con Ollama​

Los embeddings son representaciones numéricas (vectores) de un texto que capturan su significado semántico. Son la pieza clave para construir sistemas RAG (Retrieval Augmented Generation), ya que permiten buscar fragmentos de información por su significado en lugar de por palabras clave exactas.

import ollama from 'ollama';

const result = await ollama.embeddings({
  model: 'nomic-embed-text-v1.5',
  prompt: 'Node.js es un entorno de ejecución de JavaScript'
});

console.log(result.embedding); // Un array de cientos de números flotantes

Cambiar entre local y cloud fácilmente​

Una de las mejores prácticas es diseñar tu aplicación para que el proveedor de IA sea intercambiable. Esto te permite usar Ollama en desarrollo (para ahorrar costes y trabajar sin conexión) y cambiar a un modelo más potente en producción (como GPT-4 o Claude) simplemente modificando una variable de entorno.

// llm-client.js
import OpenAI from 'openai';

const isLocal = process.env.USE_LOCAL_LLM === 'true';

// Gracias a la compatibilidad de Ollama, el mismo SDK de OpenAI funciona para ambos
export const llm = new OpenAI(
  isLocal
    ? { baseURL: 'http://localhost:11434/v1', apiKey: 'ollama' }
    : { apiKey: process.env.OPENAI_API_KEY }
);

export const DEFAULT_MODEL = isLocal ? 'llama4:8b' : 'gpt-4o';
# .env.development
USE_LOCAL_LLM=true

# .env.production
USE_LOCAL_LLM=false
OPENAI_API_KEY=sk-...