API de Ollama: Solución de Problemas de Errores Comunes

Comprender la ventana de contexto de 100k

La primera frase de cada sección responde a la pregunta en su encabezado.

Una ventana de contexto de 100.000 tokens suena masiva, pero se divide por igual entre prompts de entrada y completados de salida. Cuando envías un prompt del sistema largo junto con un historial de conversación extenso, consumes ese presupuesto más rápido de lo que podrías esperar. Muchos desarrolladores asumen que el límite se aplica solo a la entrada, lo que lleva a respuestas truncadas o fallos silenciosos cuando el modelo alcanza su límite.

Considera un escenario donde pasas un documento de 50.000 tokens como contexto. Solo te quedan 50.000 tokens para la generación real. Si no gestionas este equilibrio cuidadosamente, el modelo se cortará a mitad de la oración. Monitorea siempre el recuento total de tokens enviados en cada solicitud para evitar truncamientos inesperados.

Tokens máximos vs. Longitud de salida predeterminada

Cada sección debe responder a la pregunta en su encabezado.

A menos que especifiques un límite, la mayoría de las API tienen por defecto una longitud de salida modesta, a menudo de alrededor de 2.048 tokens. Este valor predeterminado es útil para consultas cortas, pero desastroso para la generación de código o la escritura de formato largo. Si necesitas que el modelo produzca un guion completo o un análisis detallado, debes establecer explícitamente el parámetro max_tokens.

Configurar este valor demasiado alto también puede afectar la latencia y el costo. Estás pagando por cada token generado, ya sea útil o no. Un enfoque pragmático es establecer un límite superior razonable que coincida con tu caso de uso, en lugar de dejarlo en el valor predeterminado o en un infinito arbitrario.

Gestión correcta de fragmentos SSE en streaming

El streaming requiere un manejo cuidadoso de Server-Sent Events para evitar la pérdida de datos.

Cuando habilitas la transmisión (streaming), la API devuelve una serie de fragmentos pequeños en lugar de una respuesta completa única. Cada fragmento contiene un delta de texto, pero detalles cruciales como las estadísticas de uso de tokens suelen estar presentes solo en el fragmento final. Si dejas de analizar los datos demasiado pronto, perderás los datos de uso necesarios para la facturación o el seguimiento de límites de velocidad.

Además, el streaming introduce complejidad en el manejo de errores. Una interrupción de red podría dejarte con texto parcial. Necesitas un analizador robusto que pueda reconstruir el mensaje completo a partir de estos fragmentos. Esto es especialmente cierto al integrar con componentes de interfaz de usuario que renderizan texto en tiempo real.

Errores de Definición de Herramientas en la Llamada de Función

La llamada a funciones falla cuando los esquemas de herramientas no coinciden con las expectativas del modelo.

El modelo espera una estructura JSON específica para las definiciones de herramientas. Si omites los campos obligatorios o usas tipos incorrectos, el modelo podría ignorar la herramienta por completo o devolver una respuesta con formato incorrecto. Este es un problema común para los desarrolladores que construyen agentes que necesitan interactuar con APIs externas.

Valida siempre el esquema de tus herramientas frente a la documentación de la API antes de enviar solicitudes. Incluso pequeñas desviaciones, como usar un entero en lugar de una cadena para un parámetro, pueden romper la llamada a la función. Depurar esto requiere inspeccionar la respuesta JSON en bruto para ver si el modelo intentó llamar a la herramienta en absoluto.

Problemas con el formato de respuesta del modo JSON

El modo JSON obliga al modelo a generar JSON válido, pero aún puede alucinar.

Cuando configuras response_format como json_object, el modelo está restringido a producir solo JSON. Sin embargo, esto no garantiza que el contenido sea semánticamente correcto. El modelo podría producir una sintaxis JSON válida pero con claves incorrectas o campos faltantes. Aún necesitas un analizador para validar la estructura antes de usar los datos.

Además, el modo JSON a veces puede reducir la creatividad o flexibilidad del modelo. Si tu prompt es demasiado complejo, el modelo podría tener dificultades para ajustar la narrativa a una estructura JSON rígida. Usa este modo principalmente para la extracción de datos estructurados o argumentos de funciones donde la consistencia es más importante que el matiz.

Límites de Tasa y Solicitudes Concurrentes

Los límites de tasa se aplican por clave de API, no por usuario o dirección IP.

La mayoría de las APIs imponen un límite de solicitudes por minuto y conexiones concurrentes. Si excedes estos límites, recibirás un error 429 Too Many Requests. Esto es crítico para aplicaciones que generan múltiples hilos o procesos para manejar solicitudes de usuarios. Una sola clave solo puede manejar un número limitado de solicitudes en paralelo.

Para gestionarlo, implementa una retroexponencial en el código de tu cliente. Cuando recibas un error 429, espera un breve periodo antes de reintentar. Esto evita sobrecargar el servidor y garantiza una experiencia de usuario más fluida. Comprueba siempre las cabeceras de respuesta para obtener los valores de retry-after y optimizar tus tiempos de espera.

Comportamiento de reemplazo de clave API

Regenerar una clave API invalida la anterior inmediatamente.

Algunas plataformas permiten solo una clave activa por cuenta. Si generas una nueva clave, la antigua deja de funcionar instantáneamente. Esto puede causar interrupciones si tienes múltiples servicios o scripts utilizando la clave antigua. Actualiza siempre todas las instancias de tu clave antes de rotarla.

Este comportamiento está diseñado para la seguridad, asegurando que una clave filtrada no pueda usarse indefinidamente. Sin embargo, requiere una gestión cuidadosa en sistemas distribuidos. Usa variables de entorno o gestores de secretos para almacenar tu clave, facilitando las actualizaciones y reduciendo la propensión a errores.

Límites de tamaño del cuerpo de la solicitud

Las cargas útiles grandes pueden exceder el límite de cuerpo de solicitud de 8 MB.

Al enviar documentos largos o imágenes codificadas en base64, el cuerpo de la solicitud puede crecer rápidamente. Si superas el límite de tamaño, el servidor rechazará la solicitud con un error 413 Payload Too Large (Carga útil demasiado grande). Este es un límite estricto que no se puede aumentar mediante la actualización de tu plan en muchos casos.

Para evitar esto, comprime tu entrada o divide los documentos grandes en fragmentos más pequeños. También puedes utilizar un método de codificación más eficiente para las imágenes. Supervisa siempre el tamaño de tus solicitudes, especialmente cuando tratas con contenido multimedia.