Skip to main content
Die Dienste auf Ace Data Cloud sind in zwei Antwortmodi unterteilt: Dieser Artikel konzentriert sich auf die letzten beiden Kategorien: TaskHandle-Polling für asynchrone Aufgaben und Details, Fallen und sprachübergreifende Unterschiede bei chat-streaming Antworten.

I. TaskHandle — Einheitliche Abstraktion für asynchrone Aufgaben

Alle drei SDKs kapseln asynchrone Aufgaben in TaskHandle und bieten dieselben 4 Methoden an:

Zwei Aufrufmethoden zur Erstellung von Aufgaben

Jede asynchrone Ressource (images.generate / video.generate / audio.generate) hat den Parameter wait:
  • wait=False (Standard): Gibt sofort TaskHandle zurück, der Anwendungscode entscheidet selbst, wann gepollt wird.
  • wait=True: SDK ruft intern direkt handle.wait() auf, die Funktion gibt die Antwort nach Abschluss zurück. Verwenden Sie dies nur, wenn Sie sicher sind, dass die Ziel-API das Feld status: succeeded zurückgibt — einige Anbieter halten sich nicht an diese Vereinbarung, was dazu führt, dass wait bis max_wait weiterläuft, bevor TimeoutError ausgelöst wird.

Einheitliche Unterschiede (⚠️ Unbedingt beachten)

Die Einheiten von poll_interval und max_wait sind in den drei Sprachen unterschiedlich, was häufig zu Problemen bei der sprachübergreifenden Migration führt:
Wenn Sie TS’s { pollInterval: 3000 } als Sekunden in Python poll_interval=3000 umwandeln, wird das SDK 50 Minuten warten, bevor es das zweite Mal abfragt.

Beispiel: Python explizites Polling für Midjourney

Der gesamte Code macht Folgendes:
  1. images.generate(..., wait=False) reicht das prompt an die Midjourney API ein und erhält sofort das handle, ohne zu blockieren.
  2. handle.wait(poll_interval=3.0, max_wait=180.0) sendet intern alle 3 Sekunden eine POST-Anfrage an /midjourney/tasks, bis status succeeded oder failed wird oder die Gesamtdauer 180 Sekunden überschreitet und TimeoutError ausgelöst wird.
  3. Nach Abschluss enthält result["response"]["data"] normalerweise 4 Bilder (Midjourney standardmäßig 2x2 Grid).

Beispiel: TypeScript explizites Polling

Abwägung zwischen synchroner Generierung und asynchronen Aufgaben

Wenn Ihr Anbieter selbst synchron Bilder generiert (NanoBanana / Flux / Seedream), geben Sie wait nicht an:
Die Methode zur Bestimmung ist einfach: Wenn in der Dokumentation der Ziel-API kein task_id + /tasks Paar vorhanden ist, handelt es sich um eine synchrone Generierung; das data-Feld in der Antwort der synchronen Generierung enthält bereits das endgültige Ergebnis.

Interner Protokoll von TaskHandle

TaskHandle.get() ruft auf:
Die Antwort hat eine einheitliche Struktur:
Das SDK unterstützt auch ältere Antworten ohne äußere response-Hülle — es liest direkt den obersten status, sodass der Wechsel zwischen neuen und alten Antworten den Anwendungscode nicht beeinflusst.

II. SSE Streaming-Antworten (chat.completions)

chat.completions.create(stream=True) ist derzeit die einzige Streaming-Schnittstelle im SDK (Audio / Video-Streaming wird noch nicht unterstützt). Die Iterationsstile der drei Sprachen sind jeweils nativ:

TypeScript

Echte Ausführungsergebnisse:

Python

Echte Ausführungsergebnisse:

Go

Echte Ausführungsergebnisse:

Struktur der Streaming-Chunks

Jeder Chunk ist ein OpenAI-kompatibles chat.completion.chunk:
  • Der erste Chunk hat normalerweise delta.role: "assistant" aber content ist leer.
  • Die mittleren Chunks haben jeweils delta.content, die direkt zusammengefügt werden können.
  • Der letzte Chunk hat delta leer, finish_reason ist stop / length / content_filter.

Vorzeitige Abbruch

Vorzeitig abgebrochene, bereits berechnete Tokens – die vor dem Abbruch generierten Tokens werden weiterhin nach tatsächlichem Verbrauch abgerechnet.

Drei, Zeitüberschreitung und Wiederholungen

Drei SDKs teilen sich dieselbe Wiederholungsstrategie: Um Wiederholungen zu deaktivieren: Übergebe max_retries=0 / maxRetries: 0 / WithMaxRetries(0) beim Erstellen des Clients. Die Abfrage von asynchronen Aufgaben (TaskHandle) wird nicht von max_retries beeinflusst – ihre Schleife ist geschäftsseitig und nicht HTTP-seitig, gesteuert durch max_wait, um die Gesamtdauer zu kontrollieren.

Vier, häufige Fallstricke

  1. Synchroner Provider sollte kein wait übergeben: NanoBanana / Flux / Seedream sind alle synchron, das Erzwingen von wait=True lässt das SDK eine tasks-Schnittstelle abfragen, die sich nicht aktualisiert.
  2. Unterschiede in der Einheit von TaskHandle: Python ist in Sekunden, TS in Millisekunden, beim Übertragen zwischen Sprachen unbedingt umrechnen.
  3. wait=True kann dennoch TimeoutError auslösen: Die Antwort muss status in ('succeeded','failed') erfüllen, um die Schleife zu verlassen; wenn der Provider andere Feldnamen verwendet, muss der Geschäftscode selbst handle.get() analysieren.
  4. Streaming-Abbruch: Bereits generierte Tokens vor dem Abbruch wurden abgerechnet.
  5. Wiederverwendung des Clients innerhalb desselben Prozesses: Das SDK hat einen eigenen Verbindungspool, häufiges new AceDataCloud() / AceDataCloud() kann das TLS-Handshake zum Flaschenhals machen.

Mehr erfahren