Aprende Ollama en un servidor privado para prototipos de IA con API local

Probar automatizaciones con modelos locales requiere una API sencilla y controlada, especialmente cuando los datos internos no deben enviarse a un proveedor externo durante cada experimento.

Ollama expone su API local en el puerto 11434 y puede ejecutarse en Linux o dentro de un contenedor. Es una opción útil para prototipos, staging y validaciones internas, pero no incorpora por sí solo autenticación, alta disponibilidad, aislamiento entre usuarios ni una política completa de auditoría.

Cuándo conviene aplicarlo

Este enfoque resulta útil para pruebas como:

Bots internos.
Clasificación de tickets.
Resúmenes de logs.
Extracción de datos estructurados.
Pruebas de RAG en staging.
Automatizaciones con información que debe permanecer en una red privada.

Antes de adoptarlo como plataforma permanente, evalúa requisitos de disponibilidad, concurrencia, actualización, observabilidad y aislamiento.

Requisitos previos

Necesitarás:

Un servidor Linux con CPU suficiente o GPU compatible.
RAM o VRAM acorde con el modelo y el contexto.
Docker y, para NVIDIA, NVIDIA Container Toolkit.
Un firewall cerrado al exterior.
Un volumen persistente para los modelos.
Un modelo y una licencia evaluados.
Un proxy o gateway si habrá varios clientes.
Datos de prueba sin credenciales ni información personal real.

El tamaño del archivo del modelo no equivale exactamente a la memoria necesaria. El contexto, el paralelismo y los modelos cargados simultáneamente aumentan el consumo.

Arquitectura recomendada

El flujo seguro conecta:

Cliente interno.
Proxy con HTTPS, autenticación y límites.
Red privada de contenedores.
API de Ollama en 11434.
Volumen persistente de modelos.
CPU o GPU.
Logs, métricas y validación de respuestas.

La API local de Ollama no requiere autenticación. Por eso no debe publicarse directamente en Internet. Documentación de autenticación de Ollama.

Paso 1: ejecutar el contenedor sin exposición pública

Para una prueba con CPU:

docker run -d \
  --name ollama \
  --restart unless-stopped \
  --publish 127.0.0.1:11434:11434 \
  --volume ollama-models:/root/.ollama \
  --memory 16g \
  --cpus 8 \
  --env OLLAMA_NO_CLOUD=1 \
  --env OLLAMA_MAX_LOADED_MODELS=1 \
  --env OLLAMA_NUM_PARALLEL=1 \
  --env OLLAMA_MAX_QUEUE=32 \
  --env OLLAMA_KEEP_ALIVE=5m \
  ollama/ollama

El bind 127.0.0.1 impide que Docker publique el puerto en todas las interfaces del host. Compruébalo:

docker port ollama
ss -lnt | grep 11434

Para entornos reproducibles, sustituye la etiqueta implícita de la imagen por una versión o digest revisado.

OLLAMA_NO_CLOUD=1 deshabilita modelos cloud y búsqueda web. Ollama documenta este modo para instalaciones que deben operar solo con capacidades locales. Modo local de Ollama.

Paso 2: habilitar una GPU cuando corresponda

Con una GPU NVIDIA y el runtime correctamente instalado:

docker run -d \
  --name ollama \
  --restart unless-stopped \
  --gpus all \
  --publish 127.0.0.1:11434:11434 \
  --volume ollama-models:/root/.ollama \
  ollama/ollama

Para AMD, Ollama ofrece la imagen ollama/ollama:rocm y requiere acceso a los dispositivos correspondientes:

docker run -d \
  --name ollama \
  --device /dev/kfd \
  --device /dev/dri \
  --publish 127.0.0.1:11434:11434 \
  --volume ollama-models:/root/.ollama \
  ollama/ollama:rocm

La compatibilidad depende de la GPU, los controladores y el runtime del host. Ejecución oficial de Ollama con Docker.

Paso 3: descargar y registrar el modelo

Selecciona un modelo adecuado para la memoria disponible:

export MODEL="gemma3"

docker exec ollama \
  ollama pull "$MODEL"

No se necesita -it para una descarga automatizada.

Confirma que el modelo quedó almacenado:

curl --fail --silent --show-error \
  http://127.0.0.1:11434/api/tags |
jq .

La respuesta de /api/tags incluye nombre, tamaño, formato, cuantización y digest del modelo. Registra ese digest junto con el experimento para detectar cambios posteriores. API para listar modelos.

Conserva como metadatos:

Imagen y digest del contenedor.
Nombre y digest del modelo.
Cuantización.
Tamaño de contexto.
Parámetros de generación.
Fecha del experimento.
Dataset y versión de la evaluación.

Una etiqueta como gemma3 puede apuntar a contenido diferente después de una actualización.

Paso 4: comprobar la API local

Realiza una llamada con contenido ficticio:

curl \
  --fail-with-body \
  --max-time 120 \
  --header 'Content-Type: application/json' \
  --output response.json \
  http://127.0.0.1:11434/api/chat \
  --data '{
    "model": "gemma3",
    "messages": [
      {
        "role": "user",
        "content": "Resume este log ficticio: servicio iniciado correctamente"
      }
    ],
    "stream": false,
    "keep_alive": "5m"
  }'

Valida la respuesta, no solo el código HTTP:

jq -e '
  .done == true
  and (.message.content | type == "string")
  and (.message.content | length > 0)
' response.json

La respuesta del endpoint de chat incluye métricas como duración total, carga del modelo y cantidad de tokens evaluados. API de chat de Ollama.

Para automatizaciones, valida además el contrato esperado. Si el resultado debe ser JSON, solicita una salida estructurada y comprueba su esquema antes de utilizarla.

Paso 5: agregar un proxy interno

Si Nginx se ejecuta en el mismo host, puede reenviar /ollama/api/chat hacia /api/chat:

limit_req_zone $binary_remote_addr
    zone=ollama_api:10m
    rate=2r/s;

server {
    listen 443 ssl;
    server_name ia-interna.ejemplo.com;

    ssl_certificate     /etc/nginx/tls/fullchain.pem;
    ssl_certificate_key /etc/nginx/tls/private-key.pem;

    location /ollama/ {
        allow 10.0.0.0/24;
        deny all;

        auth_basic "API interna";
        auth_basic_user_file /etc/nginx/auth/ollama.htpasswd;

        limit_req zone=ollama_api burst=5 nodelay;

        proxy_pass http://127.0.0.1:11434/;
        proxy_http_version 1.1;
        proxy_buffering off;

        proxy_connect_timeout 5s;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

El control allow limita la red, pero no identifica usuarios. auth_basic agrega autenticación básica y debe utilizarse únicamente sobre HTTPS. Para organizaciones con un proveedor de identidad, conviene delegar autenticación a un gateway con OIDC o mTLS.

Si Nginx también se ejecuta en Docker, 127.0.0.1 apunta al propio contenedor de Nginx. En ese caso utiliza una red privada y el nombre del servicio:

proxy_pass http://ollama:11434/;

No publiques 11434 en el host cuando solo deba accederse desde esa red.

Paso 6: limitar concurrencia y memoria

Ollama permite controlar:

OLLAMA_MAX_LOADED_MODELS: modelos cargados simultáneamente.
OLLAMA_NUM_PARALLEL: solicitudes paralelas por modelo.
OLLAMA_MAX_QUEUE: solicitudes que pueden esperar.
OLLAMA_KEEP_ALIVE: tiempo que un modelo permanece en memoria.
OLLAMA_CONTEXT_LENGTH: contexto predeterminado.

El consumo requerido escala con el paralelismo y el tamaño de contexto. Cuando la cola está completa, Ollama puede responder con HTTP 503. Concurrencia y memoria en Ollama.

Empieza con paralelismo uno. Auméntalo únicamente después de medir RAM, VRAM, tokens por segundo y latencia p95.

Los clientes deben tratar 503 como saturación temporal:

No repetir inmediatamente.
Aplicar espera exponencial con variación aleatoria.
Limitar la cantidad total de intentos.
Enviar trabajos largos a una cola externa.
Evitar que un cliente monopolice toda la capacidad.

Paso 7: monitorear el servicio correcto

Para observar consumo y procesos:

docker stats --no-stream ollama

docker exec ollama \
  ollama ps

docker logs \
  --since 10m \
  --tail 200 \
  ollama

ollama ps indica qué modelos están cargados y si se ejecutan en CPU, GPU o de forma mixta. Modelos cargados en memoria.

Para NVIDIA:

nvidia-smi

journalctl -u docker muestra principalmente eventos del daemon Docker, no sustituye a docker logs para diagnosticar la aplicación dentro del contenedor.

Supervisa al menos:

RAM y VRAM.
CPU y GPU.
Latencia p50, p95 y p99.
Tiempo de carga del modelo.
Tokens procesados por segundo.
Tamaño y espera de la cola.
Errores HTTP, especialmente 503.
Reinicios y terminaciones por falta de memoria.
Espacio utilizado por el volumen.

Paso 8: validar antes de habilitar clientes

Comprueba primero la API y el modelo:

curl --fail \
  http://127.0.0.1:11434/api/tags

curl --fail \
  http://127.0.0.1:11434/api/ps

Después verifica:

Que 11434 no sea accesible desde otro equipo.
Que el proxy rechace clientes sin autenticación.
Que una IP fuera del rango permitido sea bloqueada.
Que el modelo y su digest coincidan con los aprobados.
Que el servicio continúe estable con varias solicitudes.
Que una cola llena produzca un fallo controlado.
Que los clientes respeten timeout y reintentos.
Que los logs no almacenen prompts completos ni secretos.
Que la respuesta cumpla el contrato esperado.
Que el servicio pueda volver a la imagen y modelo anteriores.

Mantén el experimento separado de producción hasta evaluar calidad, seguridad y consumo con casos reales anonimizados.

Problemas frecuentes

La respuesta tarda demasiado

Comprueba con ollama ps si el modelo se ejecuta en CPU, GPU o de forma mixta. Reduce el tamaño del modelo, el contexto o la concurrencia antes de ampliar hardware.

La primera solicitud también puede incluir el tiempo de carga del modelo.

No conecta desde otra aplicación

Si la aplicación está en el mismo host, utiliza 127.0.0.1. Si está en otro contenedor, utiliza una red Docker y el nombre ollama. No cambies el bind a todas las interfaces sin agregar antes un proxy y controles de acceso.

La GPU no aparece

Valida primero el runtime:

docker run --rm --gpus all ubuntu nvidia-smi

Si este comando falla, Ollama tampoco podrá utilizar la GPU. Revisa además docker logs ollama.

El contenedor termina inesperadamente

Comprueba memoria, límites y eventos del runtime:

docker inspect ollama
docker logs --tail 200 ollama
docker stats --no-stream ollama

Un contexto o paralelismo demasiado alto puede provocar falta de RAM o VRAM.

Se reciben respuestas HTTP 503

La capacidad paralela o la cola están completas. Reduce la tasa de entrada, agrega una cola externa o ajusta los límites después de medir la memoria disponible.

Advertencias de seguridad

La API local no incorpora autenticación.
No expongas 11434 directamente a Internet.
Usa TLS cuando el tráfico abandone el host.
Deshabilita funciones cloud si el entorno debe ser estrictamente local.
Trata los modelos descargados como dependencias de software.
Revisa licencia, procedencia, cuantización y digest.
No registres prompts completos con datos personales o secretos.
No confíes en la salida del modelo sin validación.
Aísla herramientas o acciones que el modelo pueda invocar.
El volumen puede contener modelos personalizados y debe protegerse.

Ejecutar localmente evita que Ollama envíe los prompts locales a Ollama.com, según su documentación. Esto no impide que el proxy, el cliente o una integración propia los registre. Privacidad y modo local.

Buenas prácticas para producción

Usa un gateway con autenticación, TLS y límites.
Registra modelo, digest y parámetros por experimento.
Fija la imagen de Ollama a una versión o digest.
Mantén el puerto en una red privada.
Separa modelos por caso de uso y nivel de sensibilidad.
Utiliza colas para tareas largas.
Valida formatos y límites de las respuestas.
Prueba calidad con un dataset versionado.
Implementa timeouts y reintentos acotados.
Supervisa RAM, VRAM, latencia y saturación.
Conserva un rollback de imagen, modelo y configuración.
Reevalúa la arquitectura cuando necesites alta disponibilidad o aislamiento fuerte.