Guide de streaming GPT-6 Astra : Événements de l'API Responses, Outils et Gestion des erreurs

Le streaming améliore la latence perçue en délivrant des événements pendant que GPT-6 Astra travaille. Il ne rend pas le calcul sous-jacent gratuit et ne supprime pas les cas d'échec. Un client de production doit assembler la sortie incrémentale, afficher la progression des outils, distinguer les états terminaux et récupérer en cas d'échec de connexion.

Commencez par des événements typés

Définissez stream: true et itérez sur le flux d’événements typé du SDK.

const stream = await client.responses.create({ model: "gpt-6-astra", input: "Expliquez le plan de migration en cinq étapes.", flux : vrai });

pour attendre (const event of stream) { switch (event.type) { "réponse.sortie_texte.delta" process.stdout.write(event.delta); break; "réponse.terminée" console.log("\nTerminé"); break; .échec console.error("Échec", event.response.error); break; cas "erreur" : console.error(event.message); break; } }

Les événements courants du cycle de vie du texte incluent `response.created`, `response.output_text.delta`, `response.completed` et `error`. L'union complète des événements contient également des événements liés aux éléments de sortie, aux parties de contenu, aux annotations, aux refus, aux échecs et autres. Gérez les types d'événements inconnus en toute sécurité afin qu'un événement nouvellement ajouté ne fasse pas planter un client plus ancien.

## Construisez un assembleur, pas une boucle d'ajout de texte

Une réponse peut contenir plusieurs éléments de sortie et parties de contenu. Indexez l’état par réponse, élément de sortie et partie de contenu plutôt que d’ajouter chaque delta à une chaîne globale. Dédupliquez à l’aide d’identifiants documentés ou de données de séquence lorsque disponibles, et ne rendez que l’état local validé.

Les annotations et les citations peuvent arriver séparément du texte. Préservez leurs décalages ou associations plutôt que de les supprimer lors de la concaténation. Traitez un objet de réponse final comme faisant autorité lorsqu'il est disponible.

## Les états terminaux ne sont pas interchangeables

`response.completed` signifie une exécution réussie. `response.failed` indique un échec. `response.incomplete` peut refléter des limites de tokens ou une autre raison et peut contenir une sortie partielle utile. Une `error` au niveau du transport peut survenir sans événement terminal de réponse normal.

Ne marquez jamais une requête comme réussie simplement parce que le socket s'est fermé. Persistez l'ID de réponse dès que `response.created` arrive, puis enregistrez le statut terminal séparément.

## Surveiller honnêtement l'activité de l'outil de streaming

Les appels d'outils introduisent des phases : planification du modèle, génération des arguments, exécution côté serveur ou client, résultat de l'outil et reprise de la génération. Votre interface utilisateur ne doit afficher « Recherche » ou « En attente d'approbation » que lorsque l'événement ou l'état correspondant existe. N'inventez pas de pourcentages de progression.

Pour les fonctions exécutées côté client, assemblez les arguments complets avant l'analyse, sauf si le contrat API prend explicitement en charge une consommation incrémentielle. Validez-les, exécutez une fois et renvoyez le résultat en utilisant l'ID d'appel. La diffusion d'un événement en double ne doit pas déclencher un effet secondaire en double.

## Backpressure et performance de l'interface utilisateur

Les deltas de la taille d'un jeton peuvent arriver plus vite qu'un navigateur ne devrait les afficher. Mettez en mémoire tampon brièvement et mettez à jour l'interface utilisateur à un rythme contrôlé. Cela réduit le travail de mise en page sans nuire matériellement à la latence perçue. Limitez les tampons en mémoire et mettez en pause le traitement en aval si votre framework le permet.

Séparez le journal brut des événements du modèle de vue. Le journal des événements facilite le débogage ; le modèle de vue combine les deltas en contenu stable visible par l'utilisateur. Masquez les charges utiles sensibles des outils avant de les enregistrer.

## Déconnexions, délais d'attente et annulation

Lors de la déconnexion, classifiez l'opération comme inconnue jusqu'à ce que vous récupériez l'état. Une réponse du modèle peut s'être poursuivie côté serveur, et un outil externe peut déjà avoir agi. Évitez de rejouer automatiquement les écritures.

Utilisez des délais de requête et des temporisateurs de flux inactifs, mais distinguez « aucun delta de texte » de « aucune activité » ; un long appel d'outil peut encore être sain. L'annulation doit se propager à vos propres outils annulables. Elle ne peut garantir le retour en arrière des effets déjà réalisés.

Si vous continuez à travers l'état de réponse, conservez la dernière réponse validée et les résultats des outils. La récupération spécifique à WebSocket peut signaler `previous_response_not_found` ; le guide officiel des erreurs recommande de réessayer avec le contexte d'entrée complet et `previous_response_id: null` lorsque l'état ne peut pas être résolu.

## Observabilité

Enregistrez le temps jusqu'à `response.created`, le premier delta de texte, le premier événement d'outil et l'événement terminal ; la durée totale ; les compteurs d'événements ; le statut terminal ; les déconnexions ; les nouvelles tentatives ; et l'annulation par l'utilisateur. Corrélez tous les événements avec un ID de requête d'application et l'ID de réponse OpenAI.

Tester une commande malformée, une livraison en double, des événements inconnus, un délai d'outil, un échec tardif après un texte visible et une perte de connexion après une écriture. La correction du streaming correspond à la correction de la machine à états.

## Modèle d'implémentation navigateur et serveur

Dans de nombreux produits, le serveur d'application doit gérer la connexion OpenAI et relayer un flux d'événements nettoyé vers le navigateur. Cela permet de garder les identifiants API hors du client, de centraliser l'autorisation et de laisser le serveur masquer les arguments internes des outils. Le navigateur ne reçoit que les événements nécessaires au rendu : statut, deltas de texte sécurisés, citations, invites d'approbation et résultat final.

Conserver les points de contrôle grossiers plutôt que chaque caractère. Sauvegarder chaque delta génère des écritures excessives ; ne sauvegarder qu'à la fin entraîne une perte trop importante en cas de déconnexion. Un intervalle court ou une limite de partie de contenu constitue généralement un meilleur compromis. Lors de la reconnexion, envoyez la dernière vue validée et reprenez à partir du prochain événement connu selon la conception de votre transport.

La modération et la sécurité nécessitent une politique de streaming. Un texte partiel parvient aux utilisateurs avant que la réponse finale n'existe, de sorte qu'une vérification en aval effectuée uniquement à la fin peut arriver trop tard. Choisissez des contrôles de pré-génération, des garde-fous incrémentaux, une mise en mémoire tampon ou un streaming restreint en fonction du risque. Les workflows à enjeux élevés peuvent intentionnellement sacrifier une certaine immédiateté au profit de la vérification.

Enfin, assurez-vous que les analyses ne comptent pas deux fois une réponse reprise après un rafraîchissement du navigateur. L'ID de réponse OpenAI et votre ID de demande d'application stable doivent joindre chaque segment en une seule tâche logique.

## FAQ

### Le streaming réduit-il le coût des tokens ?

Non. Cela modifie la livraison, pas le nombre de jetons générés.

### Puis-je afficher une sortie partielle immédiatement ?

Oui, mais marquez-le comme en cours et soyez prêt à faire face à des refus, des résultats incomplets ou des échecs.

### Dois-je réessayer lorsque la connexion se ferme ?

Récupérez ou réconciliez d'abord, surtout si les outils peuvent provoquer des effets secondaires. Une relecture aveugle peut dupliquer des actions.

### La gestion des événements SSE et WebSocket est-elle identique ?

Ils partagent les concepts de Responses, mais le transport et le comportement de continuation diffèrent. Suivez le guide pour le mode sélectionné.

## Conclusion

Un streaming fiable avec GPT‑6 Astra nécessite une gestion typée des événements, un assembleur structuré, des états terminaux explicites, une exécution idempotente des outils, une contre-pression et une récupération. Optimisez la perception de progression par l’utilisateur sans transformer un texte partiel ou une connexion fermée en une fausse affirmation de succès.