Tutorial práctico: Ollama en Windows, macOS y Linux

Bienvenidos al módulo dedicado a Ollama.

Hasta ahora, muchos proyectos de inteligencia artificial se construyen consumiendo APIs de modelos en la nube, como OpenAI, Anthropic, Google u otros proveedores. Ese enfoque es muy potente, pero no es el único.

En este tutorial vamos a trabajar con otro escenario: ejecutar modelos de lenguaje directamente en nuestra propia computadora.

Esto es importante por varias razones:

Privacidad local: si se usan modelos descargados y ejecutados localmente, los prompts y respuestas no necesitan salir de la máquina.
Costo por inferencia: no hay costo por token al ejecutar modelos locales, aunque sí existen costos indirectos de hardware, energía y almacenamiento.
Aprendizaje técnico: entender cómo se descargan, cargan, ejecutan y exponen los modelos ayuda a comprender mejor los sistemas de IA reales.
Prototipado rápido: permite experimentar sin depender siempre de una API externa.
Integración: Ollama expone una API HTTP local que se puede consumir desde Python, Node.js, .NET, aplicaciones web, herramientas RAG y agentes.

El tutorial está diseñado para equipos mixtos: Windows, macOS y Linux. Primero veremos los conceptos comunes y luego las diferencias específicas de cada sistema operativo.

Tabla de contenidos

Qué es Ollama
Cuándo conviene usar modelos locales
Requisitos del sistema
Instalación por sistema operativo
Verificación de la instalación
Cómo reiniciar Ollama
Primer modelo local
Comandos esenciales de la CLI
Dónde se guardan los modelos
Variables de entorno por sistema operativo
API REST de Ollama
Integración con Python
Embeddings para RAG
Cómo saber si usa CPU o GPU
Context length
Compatibilidad con la API de OpenAI
Buenas prácticas
Errores frecuentes por sistema operativo
Ejercicios propuestos
Cierre

1. Qué es Ollama

Ollama es una herramienta que permite descargar, gestionar y ejecutar modelos de lenguaje de forma local.

Una forma simple de entenderlo es pensar en Ollama como un entorno de ejecución para modelos de IA. El usuario pide un modelo por nombre, Ollama lo descarga si no está disponible, lo carga en memoria y permite usarlo desde:

la línea de comandos;
una API HTTP local;
librerías como Python o JavaScript;
integraciones compatibles con APIs estilo OpenAI.

Por defecto, el servidor local de Ollama queda disponible en:

http://localhost:11434

Y su API base queda disponible en:

http://localhost:11434/api

Componentes principales

Componente	Descripción
Servidor Ollama	Proceso que ejecuta modelos y atiende requests locales.
CLI `ollama`	Comando para descargar, ejecutar, listar y administrar modelos.
API REST	API HTTP local para integrar modelos en aplicaciones.
Modelos	Archivos descargados localmente que contienen los pesos del modelo.

2. Cuándo conviene usar modelos locales

Ollama es especialmente útil cuando se quiere:

aprender cómo funcionan los modelos localmente;
probar prompts sin costo por token;
construir prototipos privados;
hacer pruebas de RAG en una máquina de desarrollo;
ejecutar modelos sin conexión permanente a internet;
integrar IA en herramientas internas;
comparar modelos pequeños antes de usar modelos cloud más potentes.

Comparación rápida

Aspecto	Ollama local	APIs cloud
Privacidad	Alta si el modelo corre localmente	Depende del proveedor
Costo por token	Sin costo directo por token	Costo por uso
Calidad máxima	Limitada por hardware y modelo local	Acceso a modelos frontera
Velocidad	Depende de CPU/GPU local	Depende de red y proveedor
Offline	Sí, luego de descargar el modelo	No
Mantenimiento	A cargo del usuario	A cargo del proveedor

Regla práctica: use Ollama para aprender, prototipar y construir soluciones locales; use APIs cloud cuando necesite máxima calidad, escalabilidad administrada o modelos de frontera.

3. Requisitos del sistema

Los requisitos dependen del modelo que se quiera ejecutar.

Requisitos generales

8 GB de RAM como mínimo para modelos pequeños.
16 GB de RAM o más para trabajar con mayor comodidad.
SSD recomendado.
Espacio libre suficiente: los modelos pueden ocupar desde algunos GB hasta decenas o cientos de GB.
GPU recomendada para mejor rendimiento, aunque muchos modelos pequeños pueden correr por CPU.

Windows

Requisitos típicos:

Windows 10 22H2 o superior, o Windows 11.
Drivers NVIDIA actualizados si se usa GPU NVIDIA.
Driver AMD Radeon actualizado si se usa GPU AMD Radeon.

macOS

Requisitos típicos:

macOS Sonoma 14 o superior.
Apple Silicon serie M con soporte CPU/GPU.
En Mac Intel/x86, esperar ejecución por CPU.

Linux

Requisitos típicos:

Distribución Linux moderna.
systemd si se va a usar Ollama como servicio, como ocurre en la instalación estándar.
Drivers NVIDIA o AMD/ROCm correctamente instalados si se desea usar GPU.
Permisos para instalar servicios o binarios del sistema.

Regla práctica de tamaño de modelo

Una regla aproximada para modelos cuantizados a 4 bits:

Modelo de N B parámetros, donde B significa miles de millones, ≈ N × 0.6 GB de RAM/VRAM

En este contexto, 7B significa aproximadamente 7 mil millones de parámetros, no 7 billones en español.

Ejemplos aproximados:

Modelo	Memoria aproximada	Comentario
3B	2 a 3 GB	Bueno para máquinas modestas
7B / 8B	4 a 6 GB	Buen punto de entrada
13B / 14B	8 a 10 GB	Requiere más memoria
32B	18 a 24 GB	Recomendable GPU grande o mucha RAM
70B	40 GB o más	Uso avanzado

Estas cifras son orientativas. El consumo real depende de la cuantización, contexto, GPU, offloading y configuración del modelo.

4. Instalación por sistema operativo

4.1 Windows

Opción A: instalador gráfico

Ir a la página oficial de descarga de Ollama.
Descargar OllamaSetup.exe.
Ejecutar el instalador.
Abrir una nueva terminal PowerShell o CMD.
Verificar:

ollama --version

En Windows, Ollama queda ejecutándose en segundo plano y el comando ollama queda disponible en PowerShell, CMD o la terminal preferida.

Opción B: winget

Si se usa winget, se puede instalar con:

winget install Ollama.Ollama

Verificar que el servidor responde

curl.exe http://localhost:11434

La respuesta esperada es similar a:

Ollama is running

En Windows PowerShell clásico, curl puede comportarse distinto porque puede resolverse como alias. Para evitar problemas, use curl.exe o Invoke-WebRequest.

4.2 macOS

Opción recomendada: aplicación oficial

Descargar el archivo .dmg desde la página oficial de Ollama.
Montar el .dmg.
Arrastrar Ollama.app a Applications.
Abrir Ollama.
Si la aplicación solicita permiso para instalar el comando ollama en el PATH, aceptar.

Verificar desde Terminal:

ollama --version

Verificar que el servidor responde:

curl http://localhost:11434

Alternativa con Homebrew

En algunos entornos de desarrollo puede preferirse Homebrew:

brew install --cask ollama-app

Luego abrir la aplicación Ollama y verificar:

ollama --version

4.3 Linux

Instalación con script oficial

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

Luego iniciar y verificar el servicio:

sudo systemctl start ollama
sudo systemctl status ollama

Verificar la API:

curl http://localhost:11434

Respuesta esperada:

Ollama is running

Nota de seguridad

En entornos corporativos o productivos, es buena práctica revisar cualquier script remoto antes de ejecutarlo.

Una alternativa es descargarlo, inspeccionarlo y luego ejecutarlo:

curl -fsSL https://ollama.com/install.sh -o install-ollama.sh
less install-ollama.sh
sh install-ollama.sh

5. Verificación de la instalación

Los comandos básicos son iguales en los tres sistemas.

Windows

ollama --version
curl.exe http://localhost:11434

macOS

ollama --version
curl http://localhost:11434

Linux

ollama --version
curl http://localhost:11434
sudo systemctl status ollama

Si todo está correcto, ollama --version mostrará la versión instalada y curl http://localhost:11434 responderá que Ollama está corriendo.

6. Cómo reiniciar Ollama

En varias partes de este tutorial vamos a decir “reiniciar Ollama”. Conviene dejar claro qué significa en cada sistema operativo.

Windows

Buscar el ícono de Ollama en la bandeja del sistema.
Hacer clic derecho.
Elegir Quit o Salir.
Volver a abrir Ollama desde el menú Inicio.

Luego verificar:

curl.exe http://localhost:11434

macOS

Hacer clic en el ícono de Ollama en la barra de menús.
Elegir Quit Ollama.
Volver a abrir Ollama.app desde Applications.

Luego verificar:

curl http://localhost:11434

Linux

Si Ollama fue instalado como servicio systemd:

sudo systemctl restart ollama
sudo systemctl status ollama

Para revisar logs después del reinicio:

journalctl -e -u ollama

7. Primer modelo local

Vamos a ejecutar un modelo liviano para comenzar.

ollama run llama3.2

La primera vez, Ollama descargará el modelo. Luego abrirá una sesión interactiva:

>>> Send a message (/? for help)

Pruebe:

Explica en una oración qué es el aprendizaje supervisado.

Para salir:

/bye

O también:

Ctrl+D

Qué ocurrió por detrás

Cuando ejecutamos:

ollama run llama3.2

Ollama hace lo siguiente:

Busca si el modelo ya está descargado.
Si no está descargado, lo baja desde el registro de modelos.
Carga el modelo en RAM o VRAM.
Abre una sesión interactiva.
Mantiene el modelo en memoria durante un tiempo para evitar recargarlo en cada consulta.

Por defecto, Ollama mantiene el modelo cargado durante 5 minutos después del último uso. Esto explica por qué la RAM o VRAM no siempre baja inmediatamente al terminar una consulta.

Para liberar memoria manualmente:

ollama stop llama3.2

También puede controlarse con OLLAMA_KEEP_ALIVE o con el parámetro keep_alive en la API.

8. Comandos esenciales de la CLI

Estos comandos funcionan igual en Windows, macOS y Linux.

# Listar modelos descargados
ollama list

# Descargar un modelo sin ejecutarlo
ollama pull llama3.2

# Ejecutar un modelo
ollama run llama3.2

# Ver modelos cargados actualmente en memoria
ollama ps

# Detener un modelo cargado
ollama stop llama3.2

# Eliminar un modelo del disco
ollama rm llama3.2

# Ver información del modelo
ollama show llama3.2

# Iniciar el servidor manualmente
ollama serve

Modelos recomendados para empezar

Los tamaños son orientativos. Pueden variar según el tag exacto, la cuantización y la versión publicada del modelo. Antes de descargar un modelo grande, conviene revisar su ficha en la biblioteca de Ollama.

Uso	Modelo sugerido	Tamaño aproximado	Comentario
Chat liviano	`llama3.2`	~2 GB	Bueno para equipos modestos
Chat general	`gemma3`	~3 GB a ~17 GB	Depende del tag elegido; empezar por variantes chicas
Chat general / razonamiento	`qwen3`	~3 GB a ~5 GB	Buen rendimiento en varios escenarios
Código	`qwen2.5-coder`	~5 GB	Especializado en programación
Embeddings	`embeddinggemma`	<1 GB	Recomendado para embeddings
Embeddings livianos	`all-minilm`	<1 GB	Rápido y liviano

Si su equipo tiene poca VRAM, por ejemplo 4 GB, conviene empezar por modelos livianos y verificar con ollama ps si entran completos en GPU.

Para descargar una variante específica se usa:

ollama pull nombre-modelo:tag

Ejemplo:

ollama pull llama3.1:8b

9. Dónde se guardan los modelos

La ubicación exacta puede variar según el sistema operativo y la forma de instalación.

Sistema	Ubicación típica
Windows	`%USERPROFILE%\.ollama` o `%HOMEPATH%\.ollama`
macOS	`~/.ollama`
Linux	Habitualmente bajo el usuario/servicio de Ollama; puede variar según instalación

Windows

Para abrir la carpeta de modelos y configuración:

explorer %USERPROFILE%\.ollama

Para abrir logs:

explorer %LOCALAPPDATA%\Ollama

macOS

Modelos y configuración:

ls ~/.ollama

Logs:

ls ~/.ollama/logs
cat ~/.ollama/logs/server.log

Linux

Ver logs del servicio:

journalctl -e -u ollama

O en modo seguimiento:

journalctl -u ollama --no-pager --follow --pager-end

10. Variables de entorno por sistema operativo

Ollama se configura mediante variables de entorno.

Variables comunes:

Variable	Uso
`OLLAMA_HOST`	Dirección y puerto donde escucha Ollama.
`OLLAMA_MODELS`	Carpeta donde se guardan modelos.
`OLLAMA_KEEP_ALIVE`	Tiempo que un modelo permanece cargado. Por defecto, 5 minutos.
`OLLAMA_NUM_PARALLEL`	Control de requests paralelos.
`OLLAMA_ORIGINS`	Orígenes permitidos para CORS.
`OLLAMA_CONTEXT_LENGTH`	Contexto efectivo por defecto para los modelos, cuando aplica.
`OLLAMA_FLASH_ATTENTION`	Puede activar Flash Attention si el hardware lo soporta.

10.1 Windows

En Windows, Ollama hereda las variables de entorno del usuario o del sistema.

Pasos:

Cerrar Ollama desde la bandeja del sistema.
Abrir Configuración o Panel de Control.
Buscar “variables de entorno”.
Editar variables de entorno del usuario.
Crear o editar variables como OLLAMA_MODELS, OLLAMA_HOST, OLLAMA_KEEP_ALIVE.
Guardar.
Volver a abrir Ollama desde el menú Inicio.

Ejemplos:

OLLAMA_MODELS=D:\OllamaModels
OLLAMA_HOST=127.0.0.1:11434
OLLAMA_KEEP_ALIVE=5m

10.2 macOS

Si Ollama se ejecuta como aplicación macOS, configurar variables con launchctl.

Ejemplos:

launchctl setenv OLLAMA_HOST "127.0.0.1:11434"
launchctl setenv OLLAMA_MODELS "$HOME/OllamaModels"
launchctl setenv OLLAMA_KEEP_ALIVE "5m"

Luego cerrar y volver a abrir Ollama.app.

Para comprobar una variable:

launchctl getenv OLLAMA_HOST

10.3 Linux

Si Ollama corre como servicio systemd, editar el servicio:

sudo systemctl edit ollama.service

Agregar:

[Service]
Environment="OLLAMA_HOST=127.0.0.1:11434"
Environment="OLLAMA_MODELS=/mnt/models/ollama"
Environment="OLLAMA_KEEP_ALIVE=5m"

Aplicar cambios:

sudo systemctl daemon-reload
sudo systemctl restart ollama
sudo systemctl status ollama

Verificar variables aplicadas al servicio:

systemctl show ollama | grep Environment

Ver logs:

journalctl -e -u ollama

10.4 Acceso desde otras máquinas de la red local

Por defecto, Ollama escucha en 127.0.0.1:11434, es decir, solo acepta conexiones desde la misma máquina.

Para aceptar conexiones desde otras máquinas de la red local, se puede usar:

OLLAMA_HOST=0.0.0.0:11434

Luego hay que reiniciar Ollama según el sistema operativo.

Una vez configurado, desde otra máquina de la red se podría llamar:

curl http://IP_DE_LA_MAQUINA:11434

Advertencia de seguridad: no exponga Ollama directamente a internet. Ollama local no trae autenticación nativa pensada para exposición pública. Si necesita acceso remoto, use firewall, VPN, reverse proxy con autenticación y reglas de red restrictivas.

11. API REST de Ollama

La API local de Ollama queda disponible en:

http://localhost:11434/api

11.1 Endpoint `/api/generate`

Este endpoint genera texto a partir de un prompt.

Windows PowerShell

(Invoke-WebRequest `
  -Method POST `
  -Uri http://localhost:11434/api/generate `
  -ContentType "application/json" `
  -Body '{
    "model": "llama3.2",
    "prompt": "Explica qué es la regresión logística.",
    "stream": false
  }'
).Content | ConvertFrom-Json

macOS / Linux

curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "prompt": "Explica qué es la regresión logística.",
    "stream": false
  }'

11.2 Endpoint `/api/chat`

Este endpoint permite trabajar con mensajes y roles.

Windows PowerShell

(Invoke-WebRequest `
  -Method POST `
  -Uri http://localhost:11434/api/chat `
  -ContentType "application/json" `
  -Body '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "system",
        "content": "Eres un asistente experto en estadística."
      },
      {
        "role": "user",
        "content": "Explica la diferencia entre varianza y desviación estándar."
      }
    ],
    "stream": false
  }'
).Content | ConvertFrom-Json

macOS / Linux

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "system",
        "content": "Eres un asistente experto en estadística."
      },
      {
        "role": "user",
        "content": "Explica la diferencia entre varianza y desviación estándar."
      }
    ],
    "stream": false
  }'

11.3 `keep_alive` en la API

Por defecto, Ollama mantiene el modelo cargado en memoria durante aproximadamente 5 minutos después de una consulta. Esto mejora la respuesta si se hacen varias consultas seguidas.

Para descargar el modelo inmediatamente después de responder:

curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "prompt": "Responde brevemente: ¿qué es Ollama?",
    "stream": false,
    "keep_alive": 0
  }'

Para mantenerlo cargado indefinidamente mientras el servidor siga corriendo:

curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "prompt": "Precarga el modelo.",
    "stream": false,
    "keep_alive": -1
  }'

También se puede liberar manualmente desde CLI:

ollama stop llama3.2

12. Integración con Python

Instalar el cliente oficial:

pip install ollama

Chat básico

import ollama

respuesta = ollama.chat(
    model="llama3.2",
    messages=[
        {
            "role": "user",
            "content": "Dame 3 técnicas para evitar overfitting."
        }
    ]
)

print(respuesta["message"]["content"])

Streaming

import ollama

stream = ollama.chat(
    model="llama3.2",
    messages=[
        {
            "role": "user",
            "content": "Cuéntame una historia corta sobre IA."
        }
    ],
    stream=True
)

for chunk in stream:
    print(chunk["message"]["content"], end="", flush=True)

Chat con system prompt

import ollama

respuesta = ollama.chat(
    model="llama3.2",
    messages=[
        {
            "role": "system",
            "content": "Responde siempre en español claro y con ejemplos simples."
        },
        {
            "role": "user",
            "content": "¿Qué es una red neuronal?"
        }
    ]
)

print(respuesta["message"]["content"])

13. Embeddings para RAG

Los embeddings convierten texto en vectores numéricos. Son fundamentales para construir sistemas de búsqueda semántica y RAG.

Descargar un modelo de embeddings

ollama pull embeddinggemma

También puede evaluar modelos como:

ollama pull all-minilm

Endpoint `/api/embed`

Windows PowerShell

(Invoke-WebRequest `
  -Method POST `
  -Uri http://localhost:11434/api/embed `
  -ContentType "application/json" `
  -Body '{
    "model": "embeddinggemma",
    "input": "El gato se sentó sobre la alfombra."
  }'
).Content | ConvertFrom-Json

macOS / Linux

curl http://localhost:11434/api/embed \
  -H "Content-Type: application/json" \
  -d '{
    "model": "embeddinggemma",
    "input": "El gato se sentó sobre la alfombra."
  }'

Embeddings con Python

import ollama

resp = ollama.embed(
    model="embeddinggemma",
    input="El gato se sentó sobre la alfombra."
)

vector = resp["embeddings"][0]
print(len(vector))
print(vector[:5])

Mini búsqueda semántica con Python

import ollama
import numpy as np

textos = [
    "El perceptrón es un modelo lineal de clasificación.",
    "Las redes convolucionales son útiles para imágenes.",
    "Los transformers usan mecanismos de atención.",
    "El overfitting ocurre cuando un modelo memoriza demasiado el entrenamiento."
]

resp = ollama.embed(
    model="embeddinggemma",
    input=textos
)

vectores = np.array(resp["embeddings"])

consulta = "¿Qué arquitectura usa atención?"
resp_consulta = ollama.embed(
    model="embeddinggemma",
    input=consulta
)

v_consulta = np.array(resp_consulta["embeddings"][0])

similitudes = vectores @ v_consulta / (
    np.linalg.norm(vectores, axis=1) * np.linalg.norm(v_consulta)
)

idx = similitudes.argmax()

print("Texto más relevante:")
print(textos[idx])
print("Similitud:", similitudes[idx])

14. Cómo saber si usa CPU o GPU

Una de las dudas más frecuentes al usar Ollama es si el modelo realmente está usando la GPU.

No conviene guiarse solo por gráficos visuales del sistema operativo. El Administrador de tareas de Windows, Monitor de Actividad en macOS o algunas herramientas gráficas pueden mostrar información parcial o difícil de interpretar.

La forma más directa de verlo desde Ollama es:

ollama ps

La columna importante es PROCESSOR.

Ejemplo conceptual:

NAME        ID              SIZE      PROCESSOR    CONTEXT    UNTIL
llama3.2    abc123          2.0 GB    100% GPU     4096       4 minutes from now

La columna CONTEXT indica el contexto efectivo cargado para ese modelo. La veremos con más detalle en la siguiente sección, dedicada a context length.

Valor	Significado
`100% GPU`	El modelo está completamente cargado en GPU.
`100% CPU`	El modelo está cargado en memoria del sistema y corre por CPU.
`48%/52% CPU/GPU`	Una parte del modelo está en CPU/RAM y otra parte en GPU/VRAM.

Si el modelo aparece repartido entre CPU y GPU, puede funcionar, pero normalmente será más lento que si entra completamente en VRAM.

Por qué puede haber CPU aunque diga `100% GPU`

Aunque ollama ps muestre 100% GPU, es normal ver algo de uso de CPU. La CPU sigue participando en tareas como:

tokenización;
coordinación de la ejecución;
entrada y salida;
sampling;
comunicación con el servidor local.

Por eso, no hay que interpretar “uso de CPU” como sinónimo automático de “no está usando GPU”.

Windows: cuidado con el Administrador de tareas

En Windows, el Administrador de tareas puede confundir. El gráfico 3D no siempre representa cómputo CUDA ni el uso real del modelo.

Para NVIDIA, es mejor abrir otra terminal y ejecutar:

nvidia-smi

También ejecutar:

ollama ps

mientras el modelo está respondiendo.

Si ollama ps muestra 100% GPU, el modelo entró completo en GPU aunque el gráfico 3D del Administrador de tareas no parezca moverse.

Linux con NVIDIA

nvidia-smi
ollama ps

nvidia-smi permite ver memoria VRAM usada, procesos activos y carga de GPU.

Linux con AMD

La verificación depende de la instalación AMD/ROCm y de la distribución. Aun así, ollama ps sigue siendo el primer diagnóstico práctico para ver si Ollama cargó el modelo en CPU, GPU o ambos.

macOS

En Apple Silicon, Ollama puede usar aceleración mediante Metal. Para diagnóstico práctico:

ollama ps

También se puede revisar consumo general con Monitor de Actividad, pero la interpretación más útil para Ollama suele ser la columna PROCESSOR.

Métrica objetiva: tokens por segundo

Para comparar rendimiento real, no alcanza con mirar gráficos de CPU/GPU. La métrica más útil es la velocidad de generación.

Una forma simple de verla desde la CLI es ejecutar el modelo con modo verbose:

ollama run llama3.2 --verbose

El flag --verbose funciona igual en Windows, macOS y Linux. Puede usarse desde PowerShell, Terminal o una shell Bash.

Al terminar la respuesta, Ollama muestra métricas como:

prompt eval rate:  1200.00 tokens/s
eval rate:           45.00 tokens/s

La métrica eval rate indica aproximadamente cuántos tokens por segundo genera el modelo. Cuanto mayor sea, más rápida es la generación.

Desde la API, las respuestas finales también incluyen métricas como eval_count y eval_duration. La velocidad aproximada puede calcularse así:

tokens_por_segundo = eval_count / eval_duration * 1_000_000_000

porque eval_duration se expresa en nanosegundos.

Diagnóstico rápido cuando un modelo va lento

Ejecutar ollama ps.
Revisar si PROCESSOR dice 100% GPU, 100% CPU o una mezcla.
Si hay mezcla CPU/GPU, probar un modelo más pequeño o menor contexto.
Medir con --verbose.
Comparar eval rate entre modelos.
Verificar VRAM con nvidia-smi si se usa NVIDIA.
Evitar asumir que el Administrador de tareas refleja toda la actividad de cómputo del modelo.

15. Context length

El context length es la cantidad máxima de tokens que el modelo puede considerar en una consulta.

Esto importa mucho en:

RAG;
análisis de documentos largos;
agentes;
asistentes de código;
conversaciones extensas.

Contexto máximo vs contexto efectivo

Hay que distinguir dos conceptos:

Concepto	Significado
Contexto máximo del modelo	Lo que el modelo podría soportar según su arquitectura o configuración.
Contexto efectivo	Lo que Ollama usa realmente en una ejecución concreta.

El contexto efectivo se controla con num_ctx en la API o con configuración equivalente. Si no se especifica, Ollama aplica un valor por defecto que puede ser menor que el contexto máximo soportado por el modelo.

Esto suele sorprender a quienes vienen de APIs cloud, donde muchas veces se asume que se está usando automáticamente todo el contexto disponible.

Ver contexto y offloading

Ejecutar:

ollama ps

En versiones recientes, la salida puede incluir una columna CONTEXT, además de PROCESSOR.

Ejemplo conceptual:

NAME             ID              SIZE      PROCESSOR    CONTEXT    UNTIL
gemma3:latest    a2af6cc3eb7f    6.6 GB    100% GPU     65536      2 minutes from now

Esto permite revisar dos cosas a la vez:

cuánto contexto se está usando;
si el modelo entró completo en GPU o quedó repartido entre CPU/GPU.

Configurar contexto en la API

Ejemplo de uso en /api/chat:

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "user",
        "content": "Resume este texto largo..."
      }
    ],
    "stream": false,
    "options": {
      "num_ctx": 8192
    }
  }'

Más contexto no siempre es mejor

Aumentar contexto puede permitir trabajar con textos más largos, pero también puede:

consumir más RAM o VRAM;
hacer que parte del modelo se descargue a CPU;
reducir tokens por segundo;
aumentar el tiempo de respuesta.

En modelos locales, conviene medir. Para muchas tareas simples, un contexto menor puede ser más rápido y suficiente.

Configuración global

También puede configurarse mediante variable de entorno:

OLLAMA_CONTEXT_LENGTH=8192

Después de cambiarla, reiniciar Ollama.

16. Compatibilidad con la API de OpenAI

Ollama también ofrece compatibilidad con endpoints estilo OpenAI.

Esto permite reutilizar parte del código existente cambiando la URL base.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

respuesta = client.chat.completions.create(
    model="llama3.2",
    messages=[
        {
            "role": "user",
            "content": "Hola, explícame qué es Ollama."
        }
    ]
)

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

La API key puede ser cualquier string cuando se usa el servidor local, porque Ollama local no valida una API key como lo haría un proveedor cloud.

17. Buenas prácticas

1. No descargar modelos sin criterio

Cada modelo puede ocupar varios GB. Antes de descargar, revisar tamaño, propósito y requisitos.

ollama show llama3.2

2. Usar tags explícitos cuando importe reproducibilidad

En proyectos reales, evitar depender de alias ambiguos.

Mejor:

ollama run llama3.1:8b

En lugar de depender siempre de un alias genérico.

3. Separar modelo de generación y modelo de embeddings

En sistemas RAG, es común usar:

un modelo de embeddings rápido;
un modelo de chat/generación de mejor calidad.

Ejemplo:

Embeddings: embeddinggemma
Generación: llama3.2, gemma3, qwen3 u otro modelo de chat

4. No exponer Ollama directamente a internet

Si se configura:

OLLAMA_HOST=0.0.0.0:11434

Ollama puede aceptar conexiones desde otras máquinas.

Esto puede ser útil en red local, pero no debe exponerse directamente a internet sin autenticación, firewall y reverse proxy seguro.

5. Medir rendimiento

Para comparar modelos:

medir tiempo de carga;
medir tokens por segundo;
medir consumo de RAM/VRAM;
revisar si usa CPU o GPU con ollama ps.

6. Cuidar CORS

Si se consume Ollama desde una aplicación web local, puede ser necesario configurar OLLAMA_ORIGINS.

En desarrollo se puede usar algo amplio, pero en producción se debe restringir.

18. Errores frecuentes por sistema operativo

18.1 Windows

`ollama` no se reconoce como comando

Cerrar la terminal y abrir una nueva.

Si sigue fallando, revisar que Ollama esté instalado y que el PATH del usuario se haya actualizado.

`curl` no funciona como se espera

En PowerShell clásico, usar:

curl.exe http://localhost:11434

O usar:

Invoke-WebRequest http://localhost:11434

Caracteres extraños en la barra de progreso

Puede ocurrir por fuentes antiguas en Windows 10. Cambiar la fuente de la terminal, por ejemplo a Cascadia Code, o usar Windows Terminal.

Poco espacio en disco C:

Configurar:

OLLAMA_MODELS=D:\OllamaModels

Luego reiniciar Ollama.

No usa GPU

Revisar:

ollama ps

También verificar drivers NVIDIA/AMD y consumo de GPU en Administrador de tareas.

18.2 macOS

La CLI no aparece

Abrir Ollama.app y aceptar la creación del enlace de CLI si lo solicita.

También se puede verificar:

which ollama

Las variables de entorno no aplican

Usar launchctl setenv y reiniciar Ollama.app.

Ejemplo:

launchctl setenv OLLAMA_HOST "127.0.0.1:11434"

Rendimiento bajo en Mac Intel

En Mac Intel/x86, esperar ejecución por CPU. Para mejor rendimiento local, Apple Silicon serie M suele ser más adecuado.

Ver logs

cat ~/.ollama/logs/server.log

18.3 Linux

El servicio no arranca

sudo systemctl status ollama

Ver logs

journalctl -e -u ollama

journalctl -u ollama --no-pager --follow --pager-end

Cambié variables y no se aplican

Después de editar el servicio:

sudo systemctl daemon-reload
sudo systemctl restart ollama

GPU NVIDIA no detectada

Verificar:

nvidia-smi

Si no funciona, revisar instalación de drivers NVIDIA.

GPU AMD no detectada

Revisar drivers AMD/ROCm según la distribución y hardware.

19. Ejercicios propuestos

Ejercicio 1 — Instalación y verificación

Instalar Ollama en su sistema operativo y entregar:

ollama --version
ollama list

Luego ejecutar:

curl http://localhost:11434

En Windows puede usarse:

curl.exe http://localhost:11434

Ejercicio 2 — Primer modelo

Descargar y ejecutar:

ollama run llama3.2

Prompt:

Explica el aprendizaje supervisado en una oración y luego da un ejemplo práctico.

Guardar la respuesta.

Ejercicio 3 — Comparación de modelos

Comparar dos modelos, por ejemplo:

ollama run llama3.2
ollama run gemma3

Usar el mismo prompt:

Explica el teorema de Bayes con un ejemplo médico.

Comparar:

calidad de respuesta;
velocidad percibida;
consumo de RAM/VRAM;
uso de CPU/GPU con ollama ps.

Ejercicio 4 — API REST

Llamar a /api/chat desde el sistema operativo correspondiente.

Windows

(Invoke-WebRequest `
  -Method POST `
  -Uri http://localhost:11434/api/chat `
  -ContentType "application/json" `
  -Body '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "user",
        "content": "Dame 5 ideas de proyectos simples con IA local."
      }
    ],
    "stream": false
  }'
).Content | ConvertFrom-Json

macOS / Linux

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "user",
        "content": "Dame 5 ideas de proyectos simples con IA local."
      }
    ],
    "stream": false
  }'

Ejercicio 5 — Cliente Python

Crear un script que:

Lea preguntas desde un archivo preguntas.txt.
Envíe cada pregunta al modelo usando ollama.chat.
Guarde las respuestas en un archivo JSON con timestamp.

Ejemplo base:

import json
from datetime import datetime
import ollama

with open("preguntas.txt", "r", encoding="utf-8") as f:
    preguntas = [line.strip() for line in f if line.strip()]

resultados = []

for pregunta in preguntas:
    respuesta = ollama.chat(
        model="llama3.2",
        messages=[
            {
                "role": "user",
                "content": pregunta
            }
        ]
    )

    resultados.append({
        "pregunta": pregunta,
        "respuesta": respuesta["message"]["content"],
        "timestamp": datetime.now().isoformat()
    })

with open("respuestas.json", "w", encoding="utf-8") as f:
    json.dump(resultados, f, ensure_ascii=False, indent=2)

Ejercicio 6 — Mini RAG completo

En la sección de embeddings ya vimos cómo buscar el párrafo más similar. En este ejercicio hay que completar el flujo RAG:

Tomar 10 párrafos sobre inteligencia artificial.
Generar embeddings con embeddinggemma.
Guardar los vectores en memoria.
Dada una pregunta, buscar el párrafo más similar.
Pasar ese párrafo como contexto al modelo de chat.
Pedirle al modelo que responda solo usando ese contexto.
Si el contexto no alcanza, el modelo debe responder: “No tengo información suficiente en el contexto”.

Prompt sugerido para la generación:

Responde la pregunta usando solo el contexto proporcionado.

Si el contexto no contiene información suficiente, responde:
"No tengo información suficiente en el contexto".

Contexto:
{{contexto}}

Pregunta:
{{pregunta}}

Ejercicio 7 — Análisis de rendimiento

Ejecutar un mismo prompt con dos modelos diferentes y registrar:

tiempo de carga;
tiempo total;
uso de CPU/GPU;
calidad percibida;
tamaño del modelo.

Usar:

ollama ps

20. Cierre

Con este tutorial ya puede instalar y usar Ollama en Windows, macOS y Linux, ejecutar modelos locales, consumir la API REST, integrarlo con Python y generar embeddings para sistemas RAG.

Ollama es una herramienta muy útil para aprender IA aplicada, experimentar con modelos locales y construir prototipos privados. No reemplaza siempre a los modelos cloud más avanzados, pero sí permite entender mejor la arquitectura de una solución de inteligencia artificial moderna.

En los próximos módulos se puede avanzar hacia:

sistemas RAG completos;
integración con bases vectoriales;
agentes;
herramientas internas para empresas;
asistentes de código;
despliegues locales controlados.

Fuentes oficiales recomendadas

Documentación general de Ollama: https://docs.ollama.com
API de Ollama: https://docs.ollama.com/api/introduction
Instalación en Windows: https://docs.ollama.com/windows
Instalación en macOS: https://docs.ollama.com/macos
Instalación en Linux: https://docs.ollama.com/linux
Embeddings: https://docs.ollama.com/capabilities/embeddings
Endpoint /api/embed: https://docs.ollama.com/api/embed
Troubleshooting: https://docs.ollama.com/troubleshooting
Context length: https://docs.ollama.com/context-length
Métricas de uso y rendimiento: https://docs.ollama.com/api/usage
Biblioteca de modelos: https://ollama.com/library

Tutorial práctico: Ollama en Windows, macOS y Linux

Tabla de contenidos

1. Qué es Ollama

Componentes principales

2. Cuándo conviene usar modelos locales

Comparación rápida

3. Requisitos del sistema

Requisitos generales

Windows

macOS

Linux

Regla práctica de tamaño de modelo

4. Instalación por sistema operativo

4.1 Windows

Opción A: instalador gráfico

Opción B: winget

Verificar que el servidor responde

4.2 macOS

Opción recomendada: aplicación oficial

Alternativa con Homebrew

4.3 Linux

Instalación con script oficial

Nota de seguridad

5. Verificación de la instalación

Windows

macOS

Linux

6. Cómo reiniciar Ollama

Windows

macOS

Linux

7. Primer modelo local

Qué ocurrió por detrás

8. Comandos esenciales de la CLI

Modelos recomendados para empezar

9. Dónde se guardan los modelos

Windows

macOS

Linux

10. Variables de entorno por sistema operativo

10.1 Windows

10.2 macOS

10.3 Linux

10.4 Acceso desde otras máquinas de la red local

11. API REST de Ollama

11.1 Endpoint /api/generate

Windows PowerShell

macOS / Linux

11.2 Endpoint /api/chat

Windows PowerShell

macOS / Linux

11.3 keep_alive en la API

12. Integración con Python

Chat básico

Streaming

Chat con system prompt

13. Embeddings para RAG

Descargar un modelo de embeddings

Endpoint /api/embed

Windows PowerShell

macOS / Linux

Embeddings con Python

Mini búsqueda semántica con Python

14. Cómo saber si usa CPU o GPU

Por qué puede haber CPU aunque diga 100% GPU

Windows: cuidado con el Administrador de tareas

Linux con NVIDIA

Linux con AMD

macOS

Métrica objetiva: tokens por segundo

Diagnóstico rápido cuando un modelo va lento

15. Context length

Contexto máximo vs contexto efectivo

Ver contexto y offloading

Configurar contexto en la API

Más contexto no siempre es mejor

Configuración global

16. Compatibilidad con la API de OpenAI

17. Buenas prácticas

1. No descargar modelos sin criterio

11.1 Endpoint `/api/generate`

11.2 Endpoint `/api/chat`

11.3 `keep_alive` en la API

Endpoint `/api/embed`

Por qué puede haber CPU aunque diga `100% GPU`

`ollama` no se reconoce como comando

`curl` no funciona como se espera