Punti chiave
- Context windows combine prompt and completion, so long histories drain limits faster than expected.
- Lo streaming richiede di gestire gli eventi SSE con cura per evitare JSON corrotti o token persi.
- JSON mode demands strict schema adherence; malformed responses cause silent parsing failures.
- La fatturazione crypto prepagata significa che gli errori sono gratuiti, ma il conteggio dei token deve essere preciso per evitare sorprese.
Perché la tua chiave API potrebbe essere rifiutata
Le chiavi API vengono rifiutate quando il client invia intestazioni non valide o supera i limiti del corpo della richiesta. Il server convalida l'intestazione di autenticazione prima di elaborare qualsiasi logica. Se l'intestazione è mancante o contiene spazi bianchi extra, la richiesta fallisce immediatamente.
Un'altra causa comune è l'invio di un payload che supera il limite di dimensione del corpo di 8 MB. Finestre di contesto ampie con molti messaggi possono facilmente superare questa soglia. Verifica la lunghezza dell'array dei messaggi e il conteggio dei token prima dell'invio.
- Assicurati che l'intestazione Authorization utilizzi correttamente il prefisso 'Bearer'.
- Verify the request body size stays under 8 MB.
- Verifica che la chiave API sia attiva e non scaduta.
Comprendere i limiti della finestra di contesto
La finestra di contesto include sia il prompt di input che il completamento generato. La nostra API supporta una finestra di 100,000 token, ma devi considerare entrambi i lati. Se invii 80,000 token di contesto, ti restano solo 20,000 per la risposta.
La maggior parte dei modelli prevede un limite di output ridotto se non si specifica max_tokens. Questo può troncare in modo imprevisto le risposte lunghe. Impostare max_tokens alla lunghezza desiderata solo se si vuole un limite. Ricordare che il limite si applica alla richiesta complessiva, non solo al prompt.
Gestione corretta delle interruzioni dello streaming
Lo streaming tramite Server-Sent Events (SSE) richiede una gestione degli errori robusta. Se la connessione si interrompe, potresti perdere il token finale o i metadati di utilizzo. Memorizza sempre i chunk in arrivo e ricostruisci la risposta completa sul lato client.
I dati sull'utilizzo dei token vengono solitamente inviati nell'ultimo chunk dello stream. Se chiudi la connessione in anticipo, potresti perdere il conteggio esatto dei token. Questo influisce sull'accuratezza della fatturazione nei sistemi prepagati. Implementa un meccanismo di retry con backoff esponenziale per gestire i problemi di rete transitori.
Utilizza un client di streaming dedicato che gestisce automaticamente l'analisi SSE. Ciò riduce il rischio di errori di parsing e garantisce che vengano catturati tutti i dati.
Errori di analisi della modalità JSON
Quando si utilizza response_format: {"type": "json_object"}, il modello deve restituire JSON valido. Qualsiasi deviazione causa errori di analisi nell'applicazione. Assicurati che il prompt istruisca esplicitamente il modello a restituire solo JSON.
A volte il modello include blocchi di codice markdown intorno al JSON, il che rompe i parser rigorosi. Rimuovi i wrapper prima dell'analisi. Inoltre, valida la struttura del JSON lato client prima di utilizzare i dati.
Utilizza una libreria di convalida degli schemi per rilevare gli errori precocemente. Questo previene i crash quando il modello restituisce chiavi o tipi imprevisti.
Sorprese nel conteggio dei token e nelle fatturazioni
La fatturazione prepagata addebita solo per l'utilizzo effettivo dei token. Errori e rifiuti sono gratuiti, il che rappresenta un vantaggio significativo rispetto ai modelli in abbonamento. Tuttavia, il conteggio dei token può essere complicato se non si tiene conto dell'intero contesto.
Ogni messaggio nella cronologia delle conversazioni conta per il limite di token di input. Le conversazioni lunghe consumano il tuo credito prepagato più velocemente del previsto. Monitora regolarmente il tuo utilizzo per evitare di rimanere senza crediti a metà sessione.
Configura gli avvisi per saldi crediti bassi. Questo garantisce che tu possa ricaricare prima che le tue richieste falliscano. Ricorda che i crediti non scadono mai, quindi puoi ricaricare quando preferisci.
Evitare i rifiuti soft nei prompt NSFW
I rifiuti soft si verificano quando il modello esita o fornisce una risposta parziale invece di una risposta diretta. Questo accade spesso con argomenti controversi o per adulti. Anche in un modello senza censura, alcuni trigger possono causare esitazione.
Regola il parametro temperature per ridurre la casualità. Una temperatura più bassa rende il modello più deterministico e meno incline a essere vago. Inoltre, assicurati che il tuo prompt sia chiaro e diretto. Evita un linguaggio ambiguo che potrebbe confondere il modello.
Se riscontri frequenti rifiuti soft, prova a riformulare leggermente il prompt. Piccole modifiche al testo possono spesso aggirare l'esitazione e ottenere una risposta diretta.
Picchi di limiti di frequenza e strategie di backoff
L'API consente 300 richieste al minuto e 8 richieste concorrenti per chiave. I picchi di traffico possono superare rapidamente questi limiti. Implementa un backoff esponenziale per gestire in modo elegante gli errori di limite di frequenza.
Quando ricevi un codice di stato 429, attendi prima di riprovare. Inizia con un breve ritardo e aumentalo ad ogni tentativo. Questo evita di sovraccaricare il server durante i picchi di traffico.
Monitora il tasso delle tue richieste e regola di conseguenza i livelli di concorrenza. Se stai effettuando molte richieste simultanee, valuta di distribuirle nel tempo. Questo garantisce un throughput costante senza superare i limiti.
Strutture del payload per il function calling
Il function calling richiede una struttura del payload specifica. Definisce le tue funzioni nel parametro tools e specifica il tool_choice. Il modello restituirà una chiamata a funzione se ritiene che sia la risposta appropriata.
Assicurati che le definizioni delle funzioni siano accurate e complete. Parametri mancanti o tipi errati possono far sì che il modello generi chiamate non valide. Convalida sempre gli argomenti della chiamata di funzione prima di eseguirli.
Utilizza il parametro tool_choice per controllare quando il modello chiama le funzioni. Puoi forzare una chiamata a funzione, lasciare che il modello decida o disabilitare completamente le chiamate a funzione. Questo ti offre un controllo preciso sul comportamento del modello.
Debugging degli errori 400 vs 500
Gli errori 400 indicano problemi lato client, come JSON non valido o parametri mancanti. Gli errori 500 suggeriscono problemi lato server, come errori interni o timeout. Distinguere tra i due ti aiuta a eseguire il debug più rapidamente.
Per gli errori 400, controlla il messaggio di errore fornito nella risposta. Di solito indica direttamente il problema. Per gli errori 500, riprova la richiesta dopo una breve attesa. Se l'errore persiste, contatta il supporto indicando l'ID della richiesta.
Registra i dettagli della richiesta e della risposta per ogni errore. Questo aiuta a identificare modelli e problemi ricorrenti. Utilizza un servizio di logging per monitorare gli errori nel tempo e migliorare la tua integrazione API.
