Skip to main content
Les services sur Ace Data Cloud se divisent en deux catégories selon le mode de réponse : Cet article se concentre sur les deux dernières catégories : Polling de TaskHandle pour les Tâches Asynchrones et les détails, pièges et différences entre les langues pour les réponses en flux de chat.

I. TaskHandle — Abstraction Unifiée des Tâches Asynchrones

Les trois SDK encapsulent les tâches asynchrones dans TaskHandle, offrant les mêmes 4 méthodes :

Deux Façons d’Appeler pour Créer une Tâche

Chaque ressource asynchrone (images.generate / video.generate / audio.generate) a un paramètre wait :
  • wait=False (par défaut) : Retourne immédiatement TaskHandle, le code métier décide quand interroger.
  • wait=True : Le SDK appelle directement handle.wait(), la fonction retourne la réponse après achèvement. Utilisez-le uniquement si vous êtes certain que l’API cible renverra toujours le champ status: succeeded — quelques fournisseurs ne respectent pas cette convention, ce qui fera que wait tournera jusqu’à max_wait avant de lever TimeoutError.

Différences d’Unités (⚠️ À Lire Absolument)

Les unités de poll_interval et max_wait sont différentes dans les trois langues, ce qui est un point de chute courant lors de la migration entre langues :
Prendre { pollInterval: 3000 } de TS comme secondes et le traduire en Python poll_interval=3000 fera que le SDK attendra 50 minutes avant de faire la deuxième interrogation.

Exemple : Polling Explicite de Midjourney en Python

Ce code effectue les actions suivantes :
  1. images.generate(..., wait=False) soumet le prompt à l’API Midjourney, obtient immédiatement le handle, sans blocage.
  2. handle.wait(poll_interval=3.0, max_wait=180.0) envoie une requête POST à /midjourney/tasks toutes les 3 secondes, jusqu’à ce que status devienne succeeded ou failed, ou que le temps total dépasse 180 secondes, levant TimeoutError.
  3. Une fois terminé, result["response"]["data"] contient généralement 4 images (Midjourney par défaut 2x2 grid).

Exemple : Polling Explicite de TypeScript

Choix entre Génération Synchrone et Tâches Asynchrones

Si votre fournisseur génère des images de manière synchrone (NanoBanana / Flux / Seedream), ne passez pas wait :
La méthode de jugement est simple : si la documentation de l’API cible ne contient pas task_id + /tasks, c’est une génération synchrone ; le champ data de la réponse de génération synchrone contient déjà le résultat final.

Protocole Interne de TaskHandle

L’appel de TaskHandle.get() est :
La réponse a une structure uniforme :
Le SDK est également compatible avec les anciennes réponses qui n’ont pas de response englobant — il lit directement le status de niveau supérieur, donc le passage entre les anciennes et nouvelles versions de réponse n’affecte pas le code métier.

II. Réponse en Flux SSE (chat.completions)

chat.completions.create(stream=True) est actuellement la seule interface en flux dans le SDK (le flux audio / vidéo n’est pas encore pris en charge). Les styles d’itération des trois langues sont natifs :

TypeScript

Résultat réel :

Python

Résultat réel :

Go

Résultat réel :

Structure des chunks en streaming

Chaque chunk est un chat.completion.chunk compatible avec OpenAI :
  • Le premier chunk a généralement delta.role: "assistant" mais content est vide.
  • Les chunks intermédiaires contiennent chacun delta.content, qui peut être directement concaténé.
  • Le dernier chunk a delta vide, finish_reason est stop / length / content_filter.

Annulation en cours

L’annulation des tokens déjà facturés — les tokens générés avant le moment de l’annulation seront toujours facturés selon la consommation réelle.

Trois, délais et réessais

Les trois SDK partagent la même stratégie de réessai : Pour désactiver les réessais : passer max_retries=0 / maxRetries: 0 / WithMaxRetries(0) lors de la construction du client. Le polling des tâches asynchrones (TaskHandle) n’est pas affecté par max_retries — sa boucle est de niveau métier et non de niveau HTTP, contrôlée par max_wait pour la durée totale.

Quatre, pièges courants

  1. Ne pas passer wait aux fournisseurs synchrones : NanoBanana / Flux / Seedream sont tous générés de manière synchrone, forcer wait=True amènera le SDK à interroger une interface tasks qui ne sera pas mise à jour.
  2. Différences d’unités de TaskHandle : Python est en secondes, TS est en millisecondes, il est impératif de convertir lors du portage entre langages.
  3. wait=True peut toujours provoquer un TimeoutError : La réponse doit satisfaire status in ('succeeded','failed') pour sortir de la boucle ; si le fournisseur utilise d’autres noms de champs, le code métier doit lui-même analyser handle.get().
  4. Annulation en streaming : Les tokens générés avant l’annulation ont déjà été facturés.
  5. Réutiliser le client dans le même processus : Le SDK dispose d’un pool de connexions, créer fréquemment new AceDataCloud() / AceDataCloud() peut rendre la poignée TLS un goulot d’étranglement.

En savoir plus