Puntos clave
- Context windows combine prompt and completion, so long histories drain limits faster than expected.
- El streaming requiere manejar los eventos SSE con cuidado para evitar JSON corrupto o pérdida de tokens.
- JSON mode demands strict schema adherence; malformed responses cause silent parsing failures.
- La facturación de criptomonedas prepagadas significa que los errores son gratuitos, pero el conteo de tokens debe ser preciso para evitar sorpresas.
Por qué tu clave de API podría ser rechazada
Las claves de API se rechazan cuando el cliente envía encabezados malformados o excede los límites del cuerpo de la solicitud. El servidor valida el encabezado de autenticación antes de procesar cualquier lógica. Si falta el encabezado o contiene espacios en blanco adicionales, la solicitud falla inmediatamente.
Otra causa común es enviar un payload que exceda el límite de tamaño de cuerpo de 8 MB. Las ventanas de contexto grandes con muchos mensajes pueden superar fácilmente este umbral. Verifica la longitud de tu matriz de mensajes y el recuento de tokens antes de enviar.
- Asegúrate de que el encabezado Authorization utilice correctamente el prefijo 'Bearer'.
- Verify the request body size stays under 8 MB.
- Verifica que la clave de la API esté activa y no haya caducado.
Comprender los límites de la ventana de contexto
La ventana de contexto incluye tanto el prompt de entrada como la completación generada. Nuestra API admite una ventana de 100,000 tokens, pero debes tener en cuenta ambos lados. Si envías 80,000 tokens de contexto, solo te quedan 20,000 para la respuesta.
La mayoría de los modelos tienen un límite de salida pequeño por defecto si no especificas max_tokens. Esto puede truncar respuestas largas de forma inesperada. Establece max_tokens a la longitud deseada solo si quieres un límite. Recuerda que el límite se aplica a la solicitud completa, no solo al prompt.
Manejo correcto de interrupciones en streaming
La transmisión mediante Eventos Enviados por Servidor (SSE) requiere un manejo de errores robusto. Si la conexión se interrumpe, podrías perder el último token o los metadatos de uso. Siempre almacena en búfer los fragmentos entrantes y reconstruye la respuesta completa en el lado del cliente.
Los datos de uso de tokens suelen enviarse en el último fragmento del flujo. Si cierras la conexión antes de tiempo, podrías perder el conteo exacto de tokens. Esto afecta la precisión de la facturación en sistemas prepagados. Implementa un mecanismo de reintento con retroceso exponencial para manejar problemas de red transitorios.
Utilice un cliente de streaming dedicado que gestione automáticamente el análisis de SSE. Esto reduce el riesgo de errores de análisis y garantiza que capture todos los datos.
Errores de análisis del modo JSON
Al utilizar response_format: {"type": "json_object"}, el modelo debe devolver JSON válido. Cualquier desviación provoca errores de análisis en tu aplicación. Asegúrate de que el prompt instruya explícitamente al modelo para que devuelva únicamente JSON.
A veces el modelo incluye bloques de código markdown alrededor del JSON, lo que rompe los analizadores estrictos. Elimina los envoltorios antes de analizar. Además, valida la estructura del JSON en el lado del cliente antes de usar los datos.
Utiliza una biblioteca de validación de esquemas para detectar errores de forma temprana. Esto evita fallos cuando el modelo devuelve claves o tipos inesperados.
Sorpresas con el conteo de tokens y facturación
La facturación prepagada solo cobra por el uso real de tokens. Los errores y las denegaciones son gratuitos, lo que representa una ventaja significativa frente a los modelos de suscripción. Sin embargo, el conteo de tokens puede ser complicado si no se tiene en cuenta el contexto completo.
Cada mensaje en el historial de la conversación cuenta para el límite de tokens de entrada. Las conversaciones largas agotan tu saldo prepagado más rápido de lo que podrías esperar. Monitorea tu uso regularmente para evitar quedarte sin créditos a mitad de la sesión.
Configura alertas para saldos bajos de créditos. Esto asegura que puedas recargar antes de que tus solicitudes fallen. Recuerda que los créditos nunca caducan, así que puedes recargar cuando te sea conveniente.
Evitar las negativas suaves en las solicitudes NSFW
Las respuestas suaves ocurren cuando el modelo duda o proporciona una respuesta parcial en lugar de una respuesta directa. Esto suele ocurrir con temas controvertidos o para adultos. Incluso en un modelo sin censura, ciertos desencadenantes pueden causar dudas.
Ajusta el parámetro temperature para reducir la aleatoriedad. Una temperatura más baja hace que el modelo sea más determinista y menos propenso a dar rodeos. Además, asegúrate de que tu prompt sea claro y directo. Evita un lenguaje ambiguo que pueda confundir al modelo.
Si te encuentras con rechazos suaves frecuentes, intenta reformular ligeramente la solicitud. Pequeños cambios en la redacción a menudo pueden evitar la vacilación y obtener una respuesta directa.
Picos en los límites de frecuencia y estrategias de retroceso
La API permite 300 solicitudes por minuto y 8 solicitudes concurrentes por clave. Los picos de tráfico pueden alcanzar rápidamente estos límites. Implementa una retroalimentación exponencial para manejar los errores de límite de tasa de forma elegante.
Cuando recibas un código de estado 429, espera antes de reintentar. Comienza con una breve demora y aumentala con cada reintento. Esto evita sobrecargar el servidor durante los momentos de mayor actividad.
Monitorea tu tasa de solicitudes y ajusta tus niveles de concurrencia en consecuencia. Si estás realizando muchas solicitudes simultáneas, considera distribuirlas a lo largo del tiempo. Esto garantiza un rendimiento constante sin superar los límites.
Estructuras de carga útil de llamadas a funciones
La llamada a funciones requiere una estructura de carga útil específica. Define tus funciones en el parámetro tools y especifica el tool_choice. El modelo devolverá una llamada a función si determina que esa es la respuesta adecuada.
Asegúrate de que las definiciones de tus funciones sean precisas y completas. La falta de parámetros o tipos incorrectos pueden hacer que el modelo genere llamadas inválidas. Siempre valida los argumentos de la llamada a la función antes de ejecutarla.
Utiliza el parámetro tool_choice para controlar cuándo el modelo llama a funciones. Puedes forzar una llamada a función, permitir que el modelo decida o deshabilitar por completo la llamada a funciones. Esto te brinda un control detallado sobre el comportamiento del modelo.
Depuración de errores 400 frente a 500
Los errores 400 indican problemas del lado del cliente, como JSON inválido o parámetros faltantes. Los errores 500 sugieren problemas del lado del servidor, como errores internos o tiempos de espera agotados. Distinguir entre ambos te ayuda a depurar más rápido.
Para errores 400, revisa el mensaje de error proporcionado en la respuesta. Por lo general, señala directamente el problema. Para errores 500, vuelve a intentar la solicitud después de una breve demora. Si el error persiste, contacta a soporte con el ID de la solicitud.
Registra tanto los detalles de la solicitud como de la respuesta para cada error. Esto ayuda a identificar patrones y problemas recurrentes. Utiliza un servicio de registro para rastrear errores a lo largo del tiempo y mejorar tu integración con la API.
