Principais pontos
- Context windows combine prompt and completion, so long histories drain limits faster than expected.
- O streaming exige o tratamento cuidadoso dos eventos SSE para evitar JSON corrompido ou perda de tokens.
- JSON mode demands strict schema adherence; malformed responses cause silent parsing failures.
- A cobrança cripto pré-paga significa que erros são gratuitos, mas a contagem de tokens deve ser precisa para evitar surpresas.
Por que sua chave de API pode ser rejeitada
As chaves de API são rejeitadas quando o cliente envia cabeçalhos malformados ou excede os limites do corpo da solicitação. O servidor valida o cabeçalho de autenticação antes de processar qualquer lógica. Se o cabeçalho estiver ausente ou contiver espaços em branco extras, a solicitação falha imediatamente.
Outra causa comum é enviar um payload que excede o limite de tamanho do corpo de 8 MB. Grandes janelas de contexto com muitas mensagens podem facilmente ultrapassar esse limite. Verifique o comprimento do array de mensagens e a contagem de tokens antes de enviar.
- Certifique-se de que o cabeçalho de Autorização utilize corretamente o prefixo 'Bearer'.
- Verify the request body size stays under 8 MB.
- Verifique se a chave da API está ativa e não expirada.
Compreendendo os limites da janela de contexto
A janela de contexto inclui tanto o prompt de entrada quanto a conclusão gerada. Nossa API suporta uma janela de 100,000 tokens, mas você deve considerar ambos os lados. Se você enviar 80,000 tokens de contexto, restarão apenas 20,000 para a resposta.
A maioria dos modelos define um limite de saída pequeno por padrão se você não especificar max_tokens. Isso pode truncar respostas longas inesperadamente. Defina max_tokens para o comprimento desejado apenas se quiser um limite. Lembre-se de que o limite se aplica à solicitação total, não apenas ao prompt.
Lidando corretamente com interrupções de streaming
O streaming via Server-Sent Events (SSE) requer tratamento de erros robusto. Se a conexão cair, você pode perder o último token ou os metadados de uso. Sempre armazene em buffer os chunks recebidos e reconstrua a resposta completa no lado do cliente.
Os dados de uso de tokens geralmente são enviados no último fragmento do stream. Se você fechar a conexão antecipadamente, pode perder a contagem exata de tokens. Isso afeta a precisão da cobrança em sistemas pré-pagos. Implemente um mecanismo de retry com backoff exponencial para lidar com problemas de rede transitórios.
Use um cliente de streaming dedicado que faz a análise de SSE automaticamente. Isso reduz o risco de erros de análise e garante que você capture todos os dados.
Erros de análise do modo JSON
Ao usar response_format: {"type": "json_object"}, o modelo deve retornar JSON válido. Qualquer desvio causa erros de análise na sua aplicação. Certifique-se de que o prompt instrua explicitamente o modelo a gerar apenas JSON.
Às vezes, o modelo inclui blocos de código markdown ao redor do JSON, o que quebra analisadores rígidos. Remova as tags antes de analisar. Além disso, valide a estrutura do JSON no lado do cliente antes de usar os dados.
Use uma biblioteca de validação de esquema para detectar erros antecipadamente. Isso evita falhas quando o modelo retorna chaves ou tipos inesperados.
Surtos de contagem de tokens e faturamento
A cobrança pré-paga é feita apenas pelo uso real de tokens. Erros e recusas são gratuitos, o que é uma vantagem significativa em relação aos modelos de assinatura. No entanto, a contagem de tokens pode ser complicada se você não considerar todo o contexto.
Cada mensagem no histórico de conversas conta para o limite de tokens de entrada. Conversas longas consomem seu crédito pré-pago mais rápido do que você pode imaginar. Monitore seu uso regularmente para evitar ficar sem créditos no meio da sessão.
Configure alertas para saldos de crédito baixos. Isso garante que você possa recarregar antes que suas solicitações falhem. Lembre-se de que os créditos nunca expiram, então você pode recarregar quando for mais conveniente.
Evitando recusas suaves em prompts NSFW
As recusas suaves ocorrem quando o modelo hesita ou fornece uma resposta parcial em vez de uma resposta direta. Isso geralmente acontece com tópicos controversos ou para adultos. Mesmo em um modelo sem censura, certos gatilhos podem causar hesitação.
Ajuste o parâmetro temperature para reduzir a aleatoriedade. Uma temperatura mais baixa torna o modelo mais determinístico e menos propenso a hesitações. Além disso, garanta que seu prompt seja claro e direto. Evite linguagem ambígua que possa confundir o modelo.
Se você encontrar recusas suaves frequentes, tente reformular o prompt ligeiramente. Pequenas alterações na redação podem frequentemente contornar a hesitação e obter uma resposta direta.
Picos de limite de taxa e estratégias de backoff
A API permite 300 requisições por minuto e 8 requisições simultâneas por chave. Picos de tráfego podem atingir esses limites rapidamente. Implemente backoff exponencial para lidar com erros de limite de taxa de forma elegante.
Quando você receber um código de status 429, aguarde antes de tentar novamente. Comece com um atraso curto e aumente-o a cada nova tentativa. Isso evita sobrecarregar o servidor durante os horários de pico.
Monitore a taxa de solicitações e ajuste os níveis de concorrência de acordo. Se você estiver fazendo muitas solicitações simultâneas, considere distribuí-las ao longo do tempo. Isso garante um throughput constante sem atingir os limites.
Estruturas de payload de function calling
A chamada de função requer uma estrutura de payload específica. Defina suas funções no parâmetro tools e especifique o tool_choice. O modelo retornará uma chamada de função se determinar que essa é a resposta adequada.
Garanta que as definições das suas funções estejam precisas e completas. Parâmetros ausentes ou tipos incorretos podem fazer com que o modelo gere chamadas inválidas. Sempre valide os argumentos da chamada de função antes de executá-los.
Use o parâmetro tool_choice para controlar quando o modelo chama funções. Você pode forçar uma chamada de função, deixar que o modelo decida ou desativar completamente as chamadas de função. Isso oferece controle fino sobre o comportamento do modelo.
Depurando erros 400 vs 500
Erros 400 indicam problemas do lado do cliente, como JSON inválido ou parâmetros ausentes. Erros 500 sugerem problemas do lado do servidor, como erros internos ou tempos limite. Diferenciar entre os dois ajuda você a depurar mais rapidamente.
Para erros 400, verifique a mensagem de erro fornecida na resposta. Ela geralmente aponta diretamente para o problema. Para erros 500, tente novamente a solicitação após um curto atraso. Se o erro persistir, entre em contato com o suporte informando o ID da solicitação.
Registre os detalhes da solicitação e da resposta para cada erro. Isso ajuda a identificar padrões e problemas recorrentes. Use um serviço de registro para monitorar erros ao longo do tempo e melhorar sua integração com a API.
