Guía de Solución de Problemas de la API de Ollama

Comprender la estructura del endpoint de la API de Ollama

El ollama endpoint sigue un patrón RESTful estricto que refleja la estructura de la API de OpenAI. Interactúa con él enviando solicitudes POST a /v1/chat/completions y consultando los modelos disponibles a través de GET /v1/models. Esta estandarización te permite cambiar los modelos subyacentes sin reescribir el código del cliente.

Muchos desarrolladores asumen que el endpoint admite incrustaciones o generación de imágenes de forma predeterminada. No lo hace. Nuestro servicio alojado, por ejemplo, sirve solo finalizaciones de texto con un único modelo sin censura. Verifica siempre la GET /v1/models respuesta para ver exactamente qué capacidades se exponen. Si ves una lista de modelos, verifica sus IDs antes de enviar solicitudes.

Al usar una instancia local, el punto final normalmente se ejecuta en http://localhost:11434. Para proveedores de nube, usarás una URL base personalizada. Asegúrate de que tu cliente HTTP maneje los encabezados correctamente, especialmente Content-Type: application/json. Un encabezado faltante a menudo causa fallos silenciosos que parecen errores del modelo.

Elementos estructurales clave:

• model: El identificador de cadena para el LLM específico.
• messages: Una matriz de objetos de contenido basados en roles.
• stream: Una bandera booleana que habilita Server-Sent Events (SSE).

Por qué tus llamadas a la API de ollama podrían fallar

Las llamadas a la API suelen fallar debido a URLs base incorrectas, claves expiradas o cargas útiles JSON mal formadas. El error más común es una respuesta 401 Unauthorized, lo que significa que tu clave API está faltando o es inválida. Otro problema frecuente es un 404 Not Found, lo que indica que el endpoint no admite la ruta o el ID de modelo solicitados.

Verifica cuidadosamente el cuerpo de tu solicitud. Si envías un parámetro que el endpoint no admite, como modalities para un modelo solo de texto, el servidor puede rechazar la solicitud. Nuestro servicio, por ejemplo, no admite entrada de imagen. Enviarla resulta en un error inmediato.

Los tiempos de espera de red también causan fallos. Si tu instancia local de Ollama está inactiva, puede descargar el modelo de la VRAM. La primera solicitud después de un arranque en frío puede tardar varios segundos. Establece un tiempo de espera generoso en tu cliente HTTP para evitar desconexiones prematuras.

Códigos de error comunes:

• 400: Bad Request (JSON malformado o parámetros inválidos).
• 401: No autorizado (clave API inválida o faltante).
• 429: Demasiadas solicitudes (límite de tasa excedido).
• 500: Error interno del servidor (fallo al cargar el modelo).

Configurando correctamente modelos ollama sin censura

Los modelos sin censura suelen requerir parámetros específicos para comportarse como se espera. La diferencia principal radica en la system prompt. Debes instruir explícitamente al modelo para que omita las negativas estándar. Sin un system prompt sólido, el modelo puede volver a los comportamientos de seguridad predeterminados.

Nuestro endpoint utiliza el ID del modelo uncensored. Envías solicitudes a este ID, y el servidor maneja la selección del modelo subyacente. Esto abstrae la complejidad de gestionar versiones de modelos. No necesitas saber si la arquitectura subyacente se basa en Llama o en Mistral.

Ajusta la temperature el parámetro para controlar la creatividad. Un valor de 0.7 es un buen punto de partida para respuestas equilibradas. Los valores más altos aumentan la aleatoriedad, lo cual es útil para la escritura creativa pero puede reducir la precisión factual. Los valores más bajos hacen que la salida sea más determinista.

Consejos de configuración:

• Usar top_p junto con temperature para un mejor control.
• Establecer stop secuencias para evitar bucles infinitos.
• Incluye siempre un system mensaje para la definición de rol.

Gestión de streaming y límites de tokens

Las respuestas en streaming devuelven datos en fragmentos mediante Eventos Enviados por Servidor (SSE). Cada fragmento contiene una finalización parcial. Debes ensamblar estos fragmentos para obtener la respuesta completa. Nuestro servicio incluye estadísticas de uso de tokens en el último fragmento, lo que te permite rastrear los costos en tiempo real.

Los límites de tokens son críticos para conversaciones largas. Nuestro endpoint admite una ventana de contexto de 100.000 tokens, combinando tanto el prompt como la completación. Sin embargo, la salida máxima por solicitud es de 16.000 tokens. Si no estableces max_tokens, el valor predeterminado es 2,048 tokens. Esto puede truncar respuestas largas inesperadamente.

Al utilizar streaming, gestiona las interrupciones de red de forma elegante. Si la conexión se pierde, puedes reanudar desde el último fragmento recibido si el servidor lo admite. De lo contrario, es posible que debas reintentar toda la solicitud. Monitorea siempre el usage field in the final chunk to avoid billing surprises.

Mejores prácticas de streaming:

• Analiza eventos SSE correctamente, ignorando líneas vacías.
• Acumula fragmentos en la memoria o en un búfer.
• Verifica el usage objeto en el último fragmento para contar los tokens.

Errores de facturación y aritmética de tokens

Los errores de facturación suelen derivar de malentendidos sobre cómo se cuentan los tokens. Los tokens se cobran tanto para la entrada (prompt) como para la salida (completado). Nuestros precios son $0.15 por 1M de tokens de entrada y $0.50 por 1M de tokens de salida. Los errores y las denegaciones son gratuitos, lo que reduce los costos durante la depuración.

Los tokenizers no siempre mapean 1:1 con los caracteres. Una sola palabra puede ser múltiples tokens. Si estimas los costos basándote en el conteo de caracteres, podrías subestimar la factura. Utiliza una biblioteca de tokenizers confiable en tu cliente para obtener conteos precisos antes de enviar solicitudes.

El crédito no caduca. Si recargas con criptomonedas, el saldo permanece hasta que lo uses. Esto es útil para proyectos a largo plazo. Sin embargo, ten en cuenta que cada solicitud consume tokens de tu saldo. Si tu saldo es bajo, las solicitudes posteriores pueden fallar.

Consejos de facturación:

• Rastrea el uso de tokens en cada respuesta.
• Configura alertas para umbrales bajos de saldo.
• Usar max_tokens para limitar los costos potenciales.

Problemas de seguridad y escaneo de puertos

Los endpoints de Ollama local a menudo están expuestos a la red por defecto. Esto los hace vulnerables a escáneres de puertos que buscan cómputo gratuito. Si expones el puerto 11434 sin autenticación, cualquiera puede usar tus recursos GPU. Esto puede provocar facturas eléctricas altas y un rendimiento lento.

Asegura tu endpoint cambiando el puerto por defecto o utilizando un proxy inverso con autenticación. Nuestro servicio alojado se encarga de la seguridad para ti, así que no necesitas preocuparte por la exposición del puerto. Solo necesitas mantener tu clave API en privado.

Para configuraciones locales, utiliza un firewall para restringir el acceso a direcciones IP de confianza. También puedes habilitar la autenticación basada en tokens en el archivo de configuración de Ollama. Esto evita que usuarios no autorizados realicen solicitudes.

Pasos de seguridad:

• Cambia el puerto predeterminado si se expone a internet.
• Usa un proxy inverso con HTTPS y autenticación.
• Monitorea el tráfico de tu red en busca de actividad inusual.

Uso de API ollama Local vs Nube

El uso local te da control total sobre la privacidad de los datos y la selección de modelos. Puedes ejecutar múltiples modelos simultáneamente y cambiar entre ellos al instante. Sin embargo, eres responsable del mantenimiento del hardware, las actualizaciones y la seguridad. El uso en la nube descarga estas responsabilidades al proveedor.

Nuestro servicio en la nube ofrece un modelo sin censura optimizado para la generación de contenido sin restricciones. Obtienes acceso instantáneo sin descargar archivos grandes de modelos. La contrapartida es que tus datos pasan por nuestros servidores. Para datos sensibles, lo local podría ser preferible.

Los servicios en la nube suelen tener una latencia mayor debido a las idas y vueltas de la red. Las instancias locales tienen una latencia cercana a cero si la GPU es lo suficientemente rápida. Sin embargo, las instancias locales requieren una VRAM significativa. Si tu GPU se queda sin memoria, el modelo puede hacer intercambio con la CPU, lo que ralentiza drásticamente las respuestas.

Comparación:

• Local: Privacidad, control, dependencia del hardware.
• En la nube: Comodidad, escalabilidad y transferencia de datos.

Errores comunes del lado del cliente

Los desarrolladores suelen olvidar gestionar los límites de velocidad. Nuestro servicio permite 300 solicitudes por minuto por clave. Si excedes este límite, recibirás un error 429. Implementa retroceso exponencial en tu cliente para manejar estos errores de forma elegante.

Otro error es no establecer el stream parameter correctamente. Si esperas streaming pero no configuras stream: true, esperarás a toda la respuesta antes de recibir cualquier dato. Esto puede hacer que tu aplicación parezca lenta.

Los errores del modo JSON también son comunes. Si estableces response_format: {type: "json_object"}, el modelo debe devolver JSON válido. Si no lo hace, tu analizador fallará. Añade manejo de errores para capturar y reintentar errores de análisis JSON.

Lista de verificación:

• Implementa el manejo de límites de velocidad (rate limits).
• Establecer stream: true para actualizaciones en tiempo real.
• Validar salida JSON al usar modo JSON.