Ollama: cómo correr un LLM en local sin API key (y cuándo no compensa)

TL;DR: Ollama descarga modelos abiertos (Qwen, Gemma, Llama, gpt-oss…) y los sirve en tu máquina por HTTP en localhost:11434. Las peticiones locales no necesitan API key, y su endpoint /v1 es compatible con el SDK de OpenAI. Lo que decide si te sirve es la memoria: los pesos del modelo más la caché de contexto tienen que caber en tu VRAM (o en tu RAM, mucho más lento). Abajo tienes la instalación por sistema, los comandos clave, cómo calcular la memoria, la API y los casos en que el local no compensa. Todo verificado contra la documentación y el repositorio de Ollama a 7 de octubre de 2026 (versión v0.40.0).

Qué es Ollama y qué significa "sin API key"

Ollama es un runtime open-source que gestiona modelos de lenguaje (descarga, carga en memoria, inferencia) y los expone por una API HTTP local. Por debajo usa llama.cpp y, en Mac con Apple Silicon, el motor MLX: desde la v0.40.0 los modelos con arquitectura soportada por MLX se ejecutan en MLX por defecto. También puede importar ficheros GGUF propios con un Modelfile.

Dos matices antes de empezar:

• Local no pide clave. La documentación de la API lo dice tal cual: las peticiones a la nube de Ollama necesitan API key, las locales no.
• No todo lo que ejecuta Ollama es local. Los modelos con etiqueta :cloud (por ejemplo gemma4:cloud) se ejecutan en los servidores de ollama.com y requieren iniciar sesión con ollama signin. Si quieres que tus prompts se procesen solo en tu máquina, desactiva las funciones cloud con la variable OLLAMA_NO_CLOUD=1 o con "disable_ollama_cloud": true en ~/.ollama/server.json. Eso desactiva la inferencia remota y la búsqueda web, no todo el tráfico de red: Ollama sigue conectándose a internet para descargar modelos, y las apps de macOS y Windows descargan actualizaciones automáticamente.

Instalación por sistema operativo

macOS y Linux (en Linux el script crea un usuario de sistema y un servicio systemd que arranca Ollama):

# Instala Ollama en macOS o Linux con el script oficial
curl -fsSL https://ollama.com/install.sh | sh

Windows, desde PowerShell (al terminar, Ollama queda corriendo en segundo plano y el comando ollama está disponible en la terminal):

# Instala Ollama en Windows con el script oficial
irm https://ollama.com/install.ps1 | iex

Docker con GPU NVIDIA en Linux. Antes, instala el NVIDIA Container Toolkit (paquete nvidia-container-toolkit) y configura Docker para usarlo; sin él, --gpus=all no funciona:

# Registra el runtime de NVIDIA en Docker (con el toolkit ya instalado) y reinicia Docker
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Levanta Ollama con GPU, persiste los modelos en un volumen
# y publica el puerto solo en localhost (127.0.0.1)
docker run -d --gpus=all -v ollama:/root/.ollama -p 127.0.0.1:11434:11434 --name ollama ollama/ollama

# Ejecuta un modelo dentro del contenedor
docker exec -it ollama ollama run llama3.2

El prefijo 127.0.0.1: importa: según la documentación de Docker, un puerto publicado sin dirección se abre en todas las direcciones del host, y la API de Ollama no pide autenticación. Con 127.0.0.1 solo accede el propio host (en versiones de Docker anteriores a la 28.0.0, equipos del mismo segmento de red podían alcanzar también esos puertos). Sin GPU, el mismo comando sin --gpus=all corre en CPU.

Primeros comandos: run, pull, list, ps y stop

Con el servidor en marcha, ollama run descarga el modelo si no lo tienes y abre un chat en la terminal:

# Descarga qwen3:8b (5,2 GB) si hace falta y abre un chat interactivo
ollama run qwen3:8b

# Igual, pero al final de cada respuesta muestra tiempos y la velocidad real ("eval rate" en tokens/s)
ollama run qwen3:8b --verbose

Dentro del chat interactivo, /set parameter num_ctx 16384 cambia el tamaño de contexto de esa sesión y /set parameter temperature 0.2 la temperatura.

Cuánta memoria necesita un modelo y cómo calcularla

La memoria que ocupa un modelo cargado tiene dos partes grandes: los pesos y la caché KV del contexto. Ambas se pueden estimar con aritmética simple.

1. Pesos: parámetros × bits por peso

Los pesos ocupan aproximadamente número de parámetros × bits por peso ÷ 8 bytes. Con qwen3:8b (8.200 millones de parámetros según la ficha de Qwen3-8B):

• En fp16 (16 bits por peso): 8,2 × 10⁹ × 2 bytes ≈ 16 GB, que es lo que pesa la etiqueta qwen3:8b-fp16.
• En q8_0: la etiqueta qwen3:8b-q8_0 pesa 8,9 GB, unos 8,7 bits por peso (8,9 × 8 ÷ 8,2).
• En q4_K_M, la cuantización de la etiqueta por defecto: 5,2 GB, unos 5,1 bits por peso de media (5,2 × 8 ÷ 8,2).

Regla práctica derivada: el tamaño de descarga que muestra la librería de Ollama es una buena aproximación de lo que ocupan los pesos en memoria.

2. Caché KV: crece con el contexto

Por cada token de contexto, el modelo guarda claves y valores en cada capa: 2 × capas × cabezas KV × dimensión por cabeza × bytes por elemento. Para Qwen3-8B (36 capas, 8 cabezas KV, dimensión 128, según su config.json) y caché en f16 (2 bytes, el valor por defecto de Ollama):

• 2 × 36 × 8 × 128 × 2 = 147.456 bytes por token (144 KiB).
• Con 4.096 tokens de contexto: 576 MiB.
• Con el máximo del modelo en Ollama, 40.960 tokens: 5,6 GiB, más que los propios pesos en q4_K_M.

Por eso Ollama ajusta el contexto por defecto a tu VRAM: 4k tokens con menos de 24 GiB, 32k entre 24 y 48 GiB, y 256k a partir de 48 GiB. La propia documentación recomienda al menos 64.000 tokens para agentes, herramientas de código o búsqueda web, así que en esos usos tendrás que subirlo y pagar la memoria correspondiente. Dos palancas oficiales para contenerla: OLLAMA_KV_CACHE_TYPE=q8_0 reduce la caché a la mitad aproximadamente (requiere Flash Attention activa) y q4_0 a un cuarto, con más pérdida de precisión. Y si atiendes peticiones en paralelo, la memoria escala con OLLAMA_NUM_PARALLEL × OLLAMA_CONTEXT_LENGTH.

Tamaños reales de modelos de la librería

Tamaños de descarga en ollama.com/library a 7 de octubre de 2026 con la cuantización de cada etiqueta. Súmale la caché KV del contexto que vayas a usar:

Algunas etiquetas sin sufijo (gemma4:latest, qwen3.5:9b) muestran un rango de tamaños porque agrupan variantes para distintos motores (GGUF y MLX); las etiquetas con sufijo de cuantización tienen tamaño fijo.

Comprueba la cifra real con ollama ps

La estimación sirve para elegir; la medida la da ollama ps con el modelo cargado. Ejemplo de salida de la documentación:

NAME             ID              SIZE      PROCESSOR    CONTEXT    UNTIL
gemma4:latest    c6eb396dbd59    9.6 GB    100% GPU     131072     2 minutes from now

PROCESSOR es la columna clave: 100% GPU significa que todo cabe en VRAM; algo como 48%/52% CPU/GPU indica que parte del modelo se ha desbordado a RAM, y la documentación recomienda evitarlo para tener buen rendimiento. Sin GPU compatible, Ollama corre en CPU con la RAM del sistema; funciona, pero mide la velocidad con --verbose antes de decidir si te vale.

La API local: nativa y compatible con OpenAI

El servidor escucha en http://localhost:11434 con dos familias de endpoints.

API nativa (/api/...): /api/chat, /api/generate, /api/embed, /api/tags (modelos descargados), /api/ps (modelos cargados), /api/show, /api/pull, /api/create, /api/copy, /api/delete y /api/version. Las respuestas van en streaming (NDJSON) por defecto; "stream": false devuelve un único JSON.

# Petición de chat a la API nativa, sin streaming
curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:8b",
  "messages": [{"role": "user", "content": "Explica qué es la cuantización en una frase."}],
  "stream": false
}'

API compatible con OpenAI (http://localhost:11434/v1/): soporta /v1/chat/completions (con streaming, modo JSON, visión y herramientas), /v1/completions, /v1/models, /v1/embeddings y /v1/responses (solo sin estado). Ollama implementa un subconjunto de la API de OpenAI: el código escrito con su SDK puede apuntar a Ollama cambiando la base_url, siempre que solo use endpoints y campos que Ollama soporta. La librería exige un valor de api_key, pero Ollama lo ignora.

# SDK de OpenAI apuntando a Ollama local (pip install openai)
import os
from openai import OpenAI

# URL, clave y modelo salen del entorno: el nombre del modelo cambia con el proveedor
client = OpenAI(
    base_url=os.getenv("LLM_BASE_URL", "http://localhost:11434/v1/"),
    api_key=os.getenv("LLM_API_KEY", "ollama"),  # obligatoria para el SDK, Ollama la ignora
)

respuesta = client.chat.completions.create(
    model=os.getenv("LLM_MODEL", "qwen3:8b"),
    messages=[
        {"role": "system", "content": "Eres un asistente conciso en español."},
        {"role": "user", "content": "Explica qué es la cuantización en una frase."},
    ],
)

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

Leer URL, clave y modelo de variables de entorno convierte el cambio de proveedor en configuración, siempre que el destino soporte los mismos endpoints y campos que uses. Te sirve para prototipar contra Ollama, por ejemplo mientras iteras sobre el chunking de un pipeline de procesamiento de documentos para RAG.

Limitaciones que marca la documentación de compatibilidad: las imágenes solo se aceptan en base64 (no por URL), tool_choice no está soportado y /v1/responses no guarda el historial entre peticiones (no hay previous_response_id). La misma tabla marca logprobs como no soportado, pero el código de la v0.40.0 ya acepta logprobs y top_logprobs y los traslada a la petición nativa; si dependes de ellos, compruébalo con tu modelo antes. Tampoco hay forma de fijar el tamaño de contexto desde la API de OpenAI: la documentación indica crear un modelo con PARAMETER num_ctx en un Modelfile y llamarlo por ese nombre.

Variables de entorno que importan

Dónde se fijan depende de cómo arranca el servidor. En Linux con systemd, con sudo systemctl edit ollama añade bajo [Service] una línea Environment="OLLAMA_HOST=0.0.0.0:11434" y reinicia:

# Recarga la configuración de systemd y reinicia Ollama para aplicar las variables
sudo systemctl daemon-reload
sudo systemctl restart ollama

En macOS con la app, launchctl setenv OLLAMA_HOST "0.0.0.0:11434" y reinicia la aplicación. En Windows, crea la variable en la configuración de variables de entorno de tu cuenta y reinicia Ollama. Si lanzas el servidor a mano, basta con anteponerla: OLLAMA_CONTEXT_LENGTH=32768 ollama serve.

Ojo con 0.0.0.0: la API local no pide autenticación, así que exponerla en todas las interfaces deja el puerto 11434 abierto a cualquiera que llegue a él por red. Restringe el acceso con el firewall o ponlo detrás de un proxy inverso, como sugiere la propia FAQ con Nginx.

Interfaz tipo chat con Open WebUI

Open WebUI es un frontend open-source que se conecta a Ollama con historial, usuarios y subida de documentos. Su comando recomendado con Ollama instalado en el host:

# Open WebUI en http://localhost:3000, conectado a Ollama del host
# WEBUI_SECRET_KEY: genera una con "openssl rand -hex 32" y mantenla fija entre reinicios
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data -e WEBUI_SECRET_KEY=tu-clave-secreta \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

La primera cuenta que creas es la de administrador. Igual que con Ollama, -p 3000:8080 publica la interfaz en todas las direcciones del host; si solo la vas a usar desde tu equipo, usa -p 127.0.0.1:3000:8080. Si la interfaz no ve tus modelos, la guía de errores de conexión de Open WebUI propone dos salidas: ejecutar el contenedor con --network=host y -e OLLAMA_BASE_URL=http://127.0.0.1:11434 (la interfaz pasa entonces al puerto 8080), o hacer que Ollama escuche en todas las interfaces con OLLAMA_HOST=0.0.0.0, con la precaución de red de la sección anterior.

Cuándo no compensa correr el LLM en local

El local gana cuando los prompts y los datos no deben procesarse fuera de tu máquina, cuando necesitas trabajar sin conexión una vez descargado el modelo o cuando iteras mucho sobre prompts y no quieres facturar cada prueba. Deja de compensar en estos casos:

• Necesitas modelos que no caben. qwen3:235b pesa 142 GB y llama3.1:405b 243 GB en q4_K_M. Si la tarea pide ese nivel y tu equipo tiene 8 o 16 GB de VRAM, la alternativa local es un modelo bastante más pequeño. Mide si te basta con tus propias tareas, como harías al elegir un modelo para un agente de coding, en lugar de fiarte de benchmarks genéricos.
• Necesitas contexto largo con poca VRAM. Con el cálculo de arriba, llevar qwen3:8b a su contexto máximo añade 5,6 GiB de caché KV en f16. Pesos y caché suman unos 11 GB (5,2 GB + 6,0 GB), así que en una GPU de 8 GB tendrás que desbordar a RAM, cuantizar la caché a q4_0 o quedarte con menos contexto.
• Vas a servir a muchos usuarios a la vez. Por defecto Ollama procesa 1 petición en paralelo por modelo y encola el resto (hasta 512). Puedes subir OLLAMA_NUM_PARALLEL, pero la memoria escala con el paralelismo por el contexto. Para servir en producción con concurrencia, vLLM está diseñado para eso: batching continuo de peticiones, PagedAttention para gestionar la caché KV y métricas Prometheus en /metrics. Hay un caso práctico en Claude Code con vLLM en Linux.
• Tu uso es esporádico. El hardware cuesta lo mismo lo uses o no. Haz la cuenta con tus números: meses para amortizar = coste del hardware ÷ (gasto mensual en API − coste eléctrico mensual), con coste eléctrico = vatios × horas de uso ÷ 1000 × precio del kWh. Si el denominador es pequeño o negativo, la nube sale más barata y el argumento para el local es solo privacidad o control.

Sea cual sea la decisión, vigila la calidad de las respuestas con métricas, igual que harías con la calidad de un modelo en producción.

Errores comunes y depuración

• "connection refused" en el puerto 11434. El servidor no está corriendo. En Linux, sudo systemctl status ollama; en macOS y Windows, abre la app; o arráncalo a mano con ollama serve.
• Va muy lento. Mira la columna PROCESSOR de ollama ps. Si aparece CPU, el modelo o el contexto no caben en VRAM: elige una etiqueta más pequeña, baja el contexto o cuantiza la caché KV. Si pone 100% CPU teniendo GPU NVIDIA, comprueba el driver con nvidia-smi y revisa el log.
• El modelo "olvida" el principio de un documento largo. Probablemente estás en el contexto por defecto de 4k tokens. Súbelo con OLLAMA_CONTEXT_LENGTH, con num_ctx en el Modelfile o con /set parameter num_ctx, y verifica la columna CONTEXT de ollama ps.
• Open WebUI no ve los modelos. Ver la sección de Open WebUI: --network=host con OLLAMA_BASE_URL, o OLLAMA_HOST=0.0.0.0.
• Te quedas sin disco. Mueve los modelos a otra unidad con OLLAMA_MODELS y borra los que no uses con ollama rm.

Dónde están los logs: macOS en ~/.ollama/logs/server.log; Linux con journalctl -u ollama --no-pager --follow --pager-end; Windows en %LOCALAPPDATA%\Ollama\server.log. Con OLLAMA_DEBUG=1 el servidor registra más detalle, incluida la detección de GPU.

Preguntas frecuentes

¿Necesito GPU para usar Ollama?

No. Sin GPU compatible, Ollama ejecuta el modelo en CPU con la RAM del sistema, más despacio. En Mac, Apple Silicon usa CPU y GPU; los Mac Intel solo CPU. En NVIDIA hace falta compute capability 5.0 o superior y driver 550 o posterior (570 o posterior para compute capability 5.0 a 6.2). Mide la velocidad real con ollama run MODELO --verbose.

¿Ollama envía mis prompts a algún servidor?

Con modelos locales, no: la FAQ oficial indica que Ollama no ve tus prompts ni tus datos cuando ejecutas en local. Los modelos con etiqueta :cloud sí se procesan en ollama.com. Para bloquearlos, define OLLAMA_NO_CLOUD=1.

¿En qué puerto escucha Ollama?

En 127.0.0.1:11434 por defecto. La API nativa está en /api y la compatible con OpenAI en /v1. Para cambiar la dirección o el puerto, usa OLLAMA_HOST.

¿Dónde guarda Ollama los modelos?

En ~/.ollama/models en macOS y Windows, y en /usr/share/ollama/.ollama/models en Linux cuando se instala como servicio. Puedes cambiarlo con la variable OLLAMA_MODELS.

¿Puedo usar el SDK de OpenAI con Ollama?

Sí. Apunta base_url a http://localhost:11434/v1/ y pasa cualquier valor como api_key: el SDK lo exige y Ollama lo ignora. Ollama implementa un subconjunto de la API: chat completions, completions, embeddings, models y responses sin estado. tool_choice no está soportado, y logprobs figura como no soportado en la documentación aunque el código reciente ya lo acepta. Si cambias de proveedor, cambia también el nombre del modelo.

¿Qué modelo elijo para empezar?

El que quepa entero en tu VRAM junto con el contexto que necesitas. Con 8 GB, una etiqueta de 7-9B en q4_K_M como qwen3:8b (5,2 GB) deja unos 2,8 GB para caché y buffers. Con 24 GB, los pesos de las etiquetas de 27-31B en q4_K_M (17-20 GB) caben, pero el margen para el contexto se queda en 4-7 GB. Compruébalo con ollama ps y evalúalo con tus propias tareas.

Resumen

Ollama convierte "tener un LLM en local" en instalar, hacer ollama run y apuntar tu código a localhost:11434, sin API key. La decisión real es de memoria (pesos más caché KV, comprobada con ollama ps) y de uso: compensa para privacidad, trabajo offline e iteración intensiva; no compensa cuando necesitas modelos que no caben, contexto largo con poca VRAM, muchos usuarios simultáneos o un uso tan esporádico que el hardware no se amortiza.