Guida allo Streaming GPT-6 Astra: Eventi API delle Risposte, Strumenti e Gestione degli Errori

Lo streaming migliora la latenza percepita consegnando gli eventi mentre GPT-6 Astra sta lavorando. Non rende gratuita la computazione sottostante né elimina i casi di errore. Un client di produzione deve assemblare l'output incrementale, visualizzare l'avanzamento degli strumenti, distinguere gli stati terminali e recuperare quando una connessione fallisce.

Inizia con eventi tipizzati

Imposta stream: true e itera sul flusso di eventi tipizzato dell’SDK.

const stream = await client.responses.create({
  model: "gpt-6-astra",
  input: "Spiega il piano di migrazione in cinque passi.",
  stream: true
});

for await (const event of stream) {
  switch (event.type) {
    "risposta.output_testo.delta"
      process.stdout.write(event.delta);
      break;
    "risposta.completata"
      console.log("\nCompletato");
      break;
    .caso "response.failed":
      console.error("Fallito", event.response.error);
      break;
    case "error":
      console.error(event.message);
      break;
  }
}

Eventi comuni del ciclo di vita del testo includono response.created, response.output_text.delta, response.completed e error. L'unione completa degli eventi contiene anche eventi di output-item, content-part, annotation, refusal, failure e altri. Gestisci in modo sicuro i tipi di evento sconosciuti in modo che un evento appena aggiunto non causi il crash di un client più vecchio.

Costruisci un assemblatore, non un ciclo di aggiunta di testo

Una risposta può contenere più elementi di output e parti di contenuto. Indicizza lo stato per risposta, elemento di output e parte di contenuto, invece di aggiungere ogni delta a una singola stringa globale. Deduplica utilizzando identificatori documentati o dati di sequenza quando disponibili, e renderizza solo lo stato locale confermato.

Annotazioni e citazioni possono arrivare separatamente dal testo. Preserva i loro offset o associazioni piuttosto che rimuoverli durante la concatenazione. Tratta un oggetto di risposta finale come autorevole quando disponibile.

Gli stati terminali non sono intercambiabili

response.completed significa completamento riuscito. response.failed indica un fallimento. response.incomplete può riflettere limiti di token o un'altra ragione e può contenere output parziale utile. Un error a livello di trasporto può verificarsi senza un evento terminale di risposta normale.

Non segnare mai una richiesta come riuscita solo perché il socket si è chiuso. Persisti l'ID della risposta non appena arriva response.created, poi salva lo stato terminale separatamente.

Monitora onestamente l'attività dello strumento di streaming

Le chiamate agli strumenti introducono fasi: pianificazione del modello, generazione degli argomenti, esecuzione lato server o client, risultato dello strumento e generazione ripresa. La tua interfaccia utente dovrebbe mostrare "Ricerca in corso" o "In attesa di approvazione" solo quando esiste l'evento/stato corrispondente. Non inventare percentuali di avanzamento.

Per funzioni eseguite dal client, assemblare gli argomenti completi prima dell'analisi sintattica, a meno che il contratto API non supporti esplicitamente il consumo incrementale. Validarli, eseguirli una volta e restituire il risultato utilizzando l'ID della chiamata. Lo streaming di un evento duplicato non deve innescare un effetto collaterale duplicato.

Backpressure e prestazioni dell'interfaccia utente

I delta di dimensione token possono arrivare più velocemente di quanto un browser dovrebbe renderizzare. Fai un breve buffering e aggiorna l'interfaccia utente a una cadenza controllata. Questo riduce il lavoro di layout senza danneggiare sostanzialmente la latenza percepita. Limita i buffer in memoria e metti in pausa l'elaborazione a valle se il tuo framework lo supporta.

Separa il registro degli eventi grezzi dal modello di visualizzazione. Il registro degli eventi supporta il debug; il modello di visualizzazione combina i delta in contenuti stabili visibili all'utente. Oscura i payload sensibili degli strumenti prima della registrazione.

Disconnessioni, timeout e cancellazione

In caso di disconnessione, classifica l'operazione come sconosciuta finché non recuperi lo stato. Una risposta del modello potrebbe essere proseguita lato server e uno strumento esterno potrebbe già aver agito. Evita di riprodurre automaticamente le scritture.

Utilizza scadenze delle richieste e timer per flussi inattivi, ma distingui "nessun delta di testo" da "nessuna attività"; una lunga chiamata a uno strumento potrebbe comunque essere in buono stato. L'annullamento dovrebbe propagarsi ai tuoi stessi strumenti annullabili. Non può garantire il rollback degli effetti completati.

Se continui attraverso lo stato della risposta, preserva l'ultima risposta committata e i risultati degli strumenti. Il recupero specifico di WebSocket può riportare previous_response_not_found; la guida ufficiale agli errori consiglia di riprovare con il contesto di input completo e previous_response_id: null quando lo stato non può essere risolto.

Osservabilità

Registra il tempo fino a response.created, primo delta di testo, primo evento strumento ed evento terminale; durata totale; conteggi degli eventi; stato terminale; disconnessioni; tentativi; e annullamento da parte dell'utente. Correla tutti gli eventi con un ID di richiesta dell'applicazione e l'ID di risposta di OpenAI.

Test ordine malformato, consegna duplicata, eventi sconosciuti, timeout di uno strumento, fallimento tardivo dopo testo visibile e perdita di connessione dopo una scrittura. La correttezza dello streaming è la correttezza della macchina a stati.

Modello di implementazione per browser e server

In molti prodotti, il server applicativo dovrebbe gestire la connessione OpenAI e inoltrare un flusso di eventi ripulito al browser. Ciò mantiene le credenziali API lontane dal client, centralizza l'autorizzazione e consente al server di nascondere gli argomenti interni degli strumenti. Il browser riceve solo gli eventi necessari per il rendering: stato, delta di testo sicuri, citazioni, richieste di approvazione e risultato finale.

Persistere i checkpoint grossolani piuttosto che ogni carattere. Salvare ogni delta crea scritture eccessive; salvare solo al completamento perde troppo in caso di disconnessione. Un intervallo breve o un confine di parte del contenuto è solitamente un compromesso migliore. Al momento della riconnessione, invia la vista più recente confermata e continua dal prossimo evento noto secondo il design del tuo trasporto.

Moderazione e sicurezza richiedono una policy di streaming. Il testo parziale raggiunge gli utenti prima che esista la risposta finale, quindi una revisione a valle che viene eseguita solo al completamento potrebbe essere troppo tardi. Scegli controlli pre-generazione, salvaguardie incrementali, buffering o streaming limitato in base al rischio. I flussi di lavoro ad alto rischio potrebbero intenzionalmente sacrificare un po' di immediatezza per la revisione.

Infine, assicurati che gli analytics non conteggino due volte una risposta ripresa dopo un aggiornamento del browser. L'ID di risposta di OpenAI e il tuo ID di richiesta stabile dell'applicazione dovrebbero unire ogni segmento in un unico compito logico.

FAQ

Lo streaming riduce il costo dei token?

No. Cambia la consegna, non il numero di token generati.

Posso mostrare un output parziale immediatamente?

Sì, ma segnalalo come in corso e preparati a possibili rifiuti, risultati incompleti o fallimenti.

Dovrei riprovare quando la connessione si chiude?

Recupera o riconcilia prima, specialmente se gli strumenti possono causare effetti collaterali. Una riproduzione cieca può duplicare le azioni.

La gestione degli eventi SSE e WebSocket è identica?

Condividono i concetti di Risposte, ma il comportamento di trasporto e continuazione differisce. Segui la guida per la modalità selezionata.

Conclusione

Lo streaming affidabile di GPT-6 Astra richiede la gestione tipizzata degli eventi, un assemblatore strutturato, stati terminali espliciti, esecuzione idempotente degli strumenti, contropressione e ripristino. Ottimizza la percezione del progresso da parte dell'utente senza trasformare un testo parziale o una connessione chiusa in una falsa affermazione di successo.