Risoluzione degli errori comuni nelle API di chat AI

Comprendere le finestre di contesto

Uno dei motivi più frequenti di fallimento dell'API è il superamento della finestra di contesto. La finestra di contesto definisce il numero totale di token consentiti in una singola richiesta, inclusi sia il prompt di input che il completamento generato. Quando questo limite viene raggiunto, l'API rifiuterà la richiesta con un errore, indicando spesso che la sequenza è troppo lunga.

Gli sviluppatori spesso confondono il conteggio dei caratteri con il conteggio dei token. Una singola parola può rappresentare più token a seconda del tokenizer. Ad esempio, una finestra di contesto da 100.000 token, come quella fornita dal nostro inference api, consente una cronologia di conversazioni sostanziale o l'elaborazione di documenti di grandi dimensioni, ma non è infinita.

• Monitora l'utilizzo dei token: Usa il tokenizer ufficiale per il tuo modello per contare accuratamente i token prima di inviare una richiesta.
• Tronca in modo intelligente: Se superi il limite, rimuovi i messaggi più vecchi dalla cronologia delle conversazioni piuttosto che quelli più recenti.
• Considera l'overhead: Riserva alcuni token per la risposta del modello. Se il tuo prompt utilizza 63.000 token, ti restano solo 1.000 token per il completamento.

La mancata gestione di questo limite comporta connessioni interrotte o risposte incomplete. Verifica sempre i conteggi dei token rispetto alla documentazione del modello prima di distribuire in produzione.

Gestione degli errori di streaming

Le risposte in streaming tramite Server-Sent Events (SSE) sono essenziali per una buona esperienza utente, ma introducono complessità nella gestione degli errori. A differenza delle risposte JSON standard, uno stream può interrompersi a metà. Se si verifica un errore di rete, il tuo client potrebbe ricevere dati parziali, lasciando lo stream in uno stato indefinito.

Quando implementi un consumer di stream, devi gestire attentamente il ciclo di vita dello stream. Controlla il codice di stato HTTP prima di tentare di analizzare lo stream. Se la connessione si interrompe, dovresti registrare l'errore e decidere se riprovare o visualizzare un messaggio all'utente.

Inoltre, assicurati che il tuo client gestisca correttamente il marcatore di fine stream. Alcune librerie si aspettano un evento di chiusura specifico, mentre altre si affidano alla chiusura della connessione. Un'incomprensione di questo aspetto può portare a processi in sospeso o a perdite di memoria.

Implementa sempre un timeout per le tue richieste di stream. Se l'API non invia una risposta entro un tempo ragionevole, interrompi la richiesta per liberare le risorse. Questo è cruciale per mantenere la stabilità in ambienti ad alta concorrenza.

Conteggio e limiti dei token

Il conteggio dei token non riguarda solo il rispetto della finestra di contesto; riguarda anche la gestione dei costi. Ogni token ha un prezzo specifico e un calcolo errato dell'utilizzo può portare a fatture impreviste. Sebbene la nostra tariffazione sia trasparente, con tariffe per token per input e output, devi comunque monitorare l'utilizzo in modo accurato.

La maggior parte degli sviluppatori utilizza una libreria per contare i token, ma è fondamentale utilizzare il tokenizer corretto per il modello che stai usando. Modelli diversi utilizzano tokenizer diversi e l'uso di quello sbagliato può portare a discrepanze significative nei token conteggiati. Ad esempio, un tokenizer addestrato su testo inglese potrebbe gestire la punteggiatura in modo diverso rispetto a uno addestrato sul codice.

Tieni d'occhio i tuoi limiti di utilizzo. La nostra API consente 300 richieste al minuto per chiave. Se li superi, riceverai un errore 429 Troppe richieste. Implementare un semplice contatore nella tua applicazione può aiutarti a rimanere entro questi limiti ed evitare interruzioni del servizio.

Infine, ricorda che i conteggi dei token possono variare leggermente tra diverse implementazioni dello stesso tokenizer. Testa sempre la tua logica di conteggio dei token con alcuni input noti per garantire la coerenza.

Insidie nella configurazione delle intestazioni

Le intestazioni sono lo strato di configurazione delle tue richieste API. Configurarle in modo errato è una causa comune di errori 400 Richiesta non valida o 401 Non autorizzato. Le due intestazioni più critiche sono Content-Type e Authorization.

L'intestazione Content-Type deve essere impostata su application/json. Se manca o è errata, l'API potrebbe non analizzare correttamente il corpo della tua richiesta. L'intestazione Authorization deve includere la tua chiave API nel formato Bearer YOUR_API_KEY. Un errore comune è dimenticare il prefisso Bearer, che provoca un errore di autenticazione.

• Controlla gli errori di battitura: Assicurati che la tua chiave API sia copiata correttamente, inclusi eventuali spazi o a capo finali.
• Verifica le intestazioni: Usa uno strumento come curl o Postman per ispezionare le intestazioni inviate.
• Gestisci la sensibilità al maiuscolo/minuscolo: Alcune API sono sensibili alle maiuscole/minuscole per i nomi delle intestazioni, anche se la maggior parte delle API moderne non lo è.

Verifica sempre le tue intestazioni prima di inviare una richiesta. Un piccolo errore in un'intestazione può far fallire l'intera richiesta, portando a confusione e tempo di debug sprecato.

Gestione del limite di richieste

I limiti di velocità sono impostati per garantire un utilizzo equo e prevenire abusi. La nostra API consente 300 richieste al minuto per chiave. Se superi questo limite, riceverai un errore 429 Troppe richieste. Questo errore include un'intestazione Retry-After, che indica quanto tempo devi attendere prima di effettuare un'altra richiesta.

Per gestire efficacemente i limiti di velocità, implementa una strategia di backoff. Invece di riprovare immediatamente, attendi un periodo che aumenta esponenzialmente con ogni tentativo. Questo impedisce alla tua applicazione di sovraccaricare l'API durante i picchi di traffico.

Monitora le metriche di utilizzo. La maggior parte delle API fornisce una dashboard o un endpoint API per monitorare il volume delle tue richieste. Usa questi dati per ottimizzare il pattern di richiesta della tua applicazione. Se stai effettuando troppe piccole richieste, valuta di raggrupparle insieme.

Ricorda che i limiti di velocità sono per chiave, non per account. Se hai più chiavi, ogni chiave ha il proprio limite. Pianifica la distribuzione delle tue chiavi di conseguenza per evitare di raggiungere i limiti in modo imprevisto.

Interpretazione dei codici di errore

Comprendere i codici di errore è cruciale per il debug. Gli errori più comuni che incontrerai sono 400 Bad Request, 401 Unauthorized, 429 Too Many Requests e 500 Internal Server Error.

• 400 Bad Request: Questo indica solitamente un problema con il corpo della richiesta, come campi mancanti o JSON non valido. Controlla il messaggio di errore per i dettagli su quale campo è errato.
• 401 Unauthorized: Questo indica un problema con la tua chiave API. Verifica che la chiave sia corretta e non sia stata revocata.
• 429 Troppe richieste: Questo indica che hai superato il limite di richieste. Implementa una strategia di backoff per gestire questo caso in modo elegante.
• 500 Internal Server Error: Questo indica un problema lato server. Riprova la richiesta dopo una breve attesa.

Registra sempre il corpo della risposta di errore. Spesso contiene informazioni preziose su cosa è andato storto, come il campo specifico che ha causato l'errore. Questo può farti risparmiare ore di tempo di debug.

Ottimizzazione dei corpi delle richieste

Il corpo della richiesta è il nucleo della tua interazione con l'API. Ottimizzarlo può migliorare le prestazioni e ridurre i costi. Un errore comune è inviare troppi dati in una singola richiesta. Se il tuo prompt è troppo grande, potresti superare la finestra di contesto o sostenere costi più elevati.

Struttura il tuo JSON con cura. Assicurati che tutti i campi obbligatori siano presenti e che i campi opzionali siano inclusi solo quando necessari. Ad esempio, se non hai bisogno dello streaming, non includere il parametro stream. Questo riduce la dimensione del payload e semplifica la risposta.

Usa strumenti come curl o Postman per testare i corpi delle tue richieste. Questo ti permette di verificare che il JSON sia valido e che l'API lo stia interpretando correttamente. Ti aiuta anche a identificare eventuali dati non necessari che vengono inviati.

Infine, valuta la possibilità di memorizzare nella cache le risposte per le richieste identiche. Se stai inviando lo stesso prompt più volte, puoi memorizzare la risposta localmente ed evitare di effettuare nuovamente la chiamata all'API. Questo può ridurre significativamente la latenza e i costi per le attività ripetitive.

Debug della chiamata di funzioni

La chiamata di funzioni permette al modello di eseguire funzioni in base all'input dell'utente. Il debug della chiamata di funzioni può essere complesso perché coinvolge più passaggi: invio della richiesta, ricezione della chiamata di funzione, esecuzione della funzione e invio del risultato al modello.

Assicurati che le definizioni delle tue funzioni siano accurate. Lo schema deve corrispondere alla firma effettiva della funzione. Se lo schema è errato, il modello potrebbe generare argomenti non validi, causando errori quando provi a eseguire la funzione.

Registra gli argomenti della chiamata di funzione e l'output della funzione. Questo ti permette di verificare che il modello stia generando gli argomenti corretti e che la tua funzione venga eseguita come previsto. In caso di errore, il log ti aiuterà a identificare il problema.

Gestisci gli errori in modo elegante. Se l'esecuzione della funzione fallisce, invia un messaggio di errore al modello in modo che possa regolare la sua risposta. Questo migliora l'esperienza utente e permette al modello di riprendersi dagli errori.