Solución de problemas en la API de Ollama

Qué cubre este artículo sobre errores en la API de Ollama

• Errores comunes en la API y sus causas.
• Cómo leer registros.
• Cómo probar con curl.
• Códigos de estado y su significado.
• Timeouts, problemas de conexión y errores de modelo.

Introducción: solución de problemas en la API de Ollama

Cualquiera que utilice Ollama a través de la API eventualmente se encontrará con errores. Las conexiones fallan, las respuestas tardan demasiado o el modelo informa que no se puede cargar. Los mensajes de error suelen ser breves y poco informativos. Con unos pocos pasos de verificación dirigidos es posible acotaremos la mayoría de los problemas rápidamente y resolverlos.

Este artículo reúne los errores típicos de la API de Ollama y muestra caminos para solucionarlos.

Términos importantes

• Código de estado HTTP: Estado de respuesta de la API.
• Timeout: Tiempo de espera excedido en solicitudes.
• Connection refused: Ningún servicio disponible en el puerto.
• CORS: Reglas de origen cruzado para solicitudes web.
• Etiqueta de modelo: Identificación de un modelo con versión.
• Stream: La respuesta se entrega sucesivamente.
• Rate Limit: Limitación del número de solicitudes.
• Log: Archivo de registro del servicio Ollama.

Diagnóstico inicial con curl

curl http://localhost:11434/api/tags

Si obtienes una lista JSON, Ollama funciona y responde correctamente.

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.1",
  "prompt": "Hola",
  "stream": false
}'

Códigos de estado

Código	Significado	Solución
200	Exitoso	Todo está bien.
400	Solicitud inválida	Verifica JSON o parámetros.
404	No encontrado	Modelo no encontrado.
408	Timeout	Aumenta timeout o verifica el modelo.
500	Error del servidor	Lee los logs de Ollama.
502/503	Servicio no disponible	Verifica el proceso de Ollama.

Error: modelo no encontrado

{"error": "model 'llama3.1' not found"}

Solución:

ollama pull llama3.1

Error: conexión rechazada

curl: (7) Failed to connect to localhost port 11434

Causas posibles:

• Ollama no está ejecutándose.
• Dirección de host incorrecta.
• Firewall bloquea el puerto.
• Ollama está vinculado a un puerto diferente.

Solución:

sudo systemctl status ollama
ollama serve

Error: tiempo de espera excedido

curl: (28) Operation timed out

Causas posibles:

• Prompt demasiado grande.
• Modelo demasiado grande para el hardware.
• GPU no detectada.
• Contexto demasiado largo.

Soluciones:

• Aumenta el timeout:

curl --max-time 300 ...

• Prueba con un modelo más pequeño.
• Limita num_predict.
• Verifica VRAM:

nvidia-smi

Error: 404 en /api/generate

Verifica que estés usando el endpoint correcto y el método correcto:

curl -X POST http://localhost:11434/api/generate -d '...'

Error: CORS en el navegador

El frontend reporta error de CORS. Soluciones:

• Coloca un proxy con nginx o Traefik delante.
• Configura los hosts de Ollama.
• Sirve el frontend y Ollama desde el mismo origen.

Error: JSON inválido

No se puede parsear la respuesta. Frecuente en streams:

import json
for line in response.iter_lines():
    if line:
        data = json.loads(line)
        print(data["response"], end="")

Error: el modelo no inicia

Verifica:

ollama list
ollama ps

Si el modelo no está ejecutándose, comprueba:

• Suficiente RAM/VRAM.
• Archivo de modelo no corrupto.
• Versión de Ollama actualizada.

Lectura de registros

Linux:

journalctl -u ollama -f

macOS:

tail -f ~/.ollama/logs/server.log

Windows: En el Visor de eventos o el archivo de registro en %USERPROFILE%\.ollama\logs.

Error: GPU no se utiliza

ollama run llama3.1

Verifica los logs. Causas posibles:

• Falta el controlador de GPU o es demasiado antiguo.
• ROCR_VISIBLE_DEVICES no está configurado en AMD.
• Contenedor sin GPU passthrough.

Error: respuestas lentas

• Verifica el tamaño del modelo.
• Verifica la cuantización.
• Usa CPU vs GPU.
• Configura num_thread.
• Ajusta el tamaño del lote.

Consejos para la solución de problemas

• Siempre prueba primero con curl.
• Observa los logs en paralelo.
• Verifica la integridad del modelo.
• Ten en cuenta los timeouts y recursos.
• Mantén Ollama actualizado.
• Verifica firewall y red.

Enlaces y recursos adicionales

• BotServ.de API REST de Ollama
• BotServ.de Comandos de Ollama
• BotServ.de Rendimiento de Ollama
• BotServ.de GPU Passthrough en Docker

FAQ: solución de problemas en la API de Ollama

¿Cuál es el puerto estándar? 11434.

¿Por qué Ollama no responde? El servicio de Ollama no está ejecutándose, el puerto está bloqueado o el host es incorrecto.

¿Cómo verifico si un modelo está cargado? ollama ps muestra los modelos en ejecución.

¿Qué hacer en caso de timeout? Aumenta el timeout, elige un modelo más pequeño, verifica la GPU.

¿Dónde encuentro los logs? En Linux con journalctl, en macOS en ~/.ollama/logs/server.log.

Fuentes y lecturas adicionales

• API de Ollama: https://github.com/ollama/ollama/blob/main/docs/api.md
• Solución de problemas de Ollama: https://github.com/ollama/ollama/blob/main/docs/troubleshooting.md

Resumen: solución de problemas en la API de Ollama

La mayoría de los errores de la API de Ollama se pueden acotarar con curl, registros y códigos de estado. Los problemas típicos son modelos no cargados, errores de conexión, timeouts y CORS. Una rutina de verificación limpia, recursos suficientes y una versión actual de Ollama resuelven la mayoría de los problemas. Quien presta atención a los logs y códigos HTTP encontrará la causa rápidamente.