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 inTaskHandle 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 sofortTaskHandlezurück, der Anwendungscode entscheidet selbst, wann gepollt wird.wait=True: SDK ruft intern direkthandle.wait()auf, die Funktion gibt die Antwort nach Abschluss zurück. Verwenden Sie dies nur, wenn Sie sicher sind, dass die Ziel-API das Feldstatus: succeededzurückgibt — einige Anbieter halten sich nicht an diese Vereinbarung, was dazu führt, dasswaitbismax_waitweiterläuft, bevorTimeoutErrorausgelöst wird.
Einheitliche Unterschiede (⚠️ Unbedingt beachten)
Die Einheiten vonpoll_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 Pythonpoll_interval=3000umwandeln, wird das SDK 50 Minuten warten, bevor es das zweite Mal abfragt.
Beispiel: Python explizites Polling für Midjourney
images.generate(..., wait=False)reicht daspromptan die Midjourney API ein und erhält sofort dashandle, ohne zu blockieren.handle.wait(poll_interval=3.0, max_wait=180.0)sendet intern alle 3 Sekunden eine POST-Anfrage an/midjourney/tasks, bisstatussucceededoderfailedwird oder die Gesamtdauer 180 Sekunden überschreitet undTimeoutErrorausgelöst wird.- 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 Siewait nicht an:
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:
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
Python
Go
Struktur der Streaming-Chunks
Jeder Chunk ist ein OpenAI-kompatibleschat.completion.chunk:
- Der erste Chunk hat normalerweise
delta.role: "assistant"abercontentist leer. - Die mittleren Chunks haben jeweils
delta.content, die direkt zusammengefügt werden können. - Der letzte Chunk hat
deltaleer,finish_reasoniststop/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
- Synchroner Provider sollte kein
waitübergeben: NanoBanana / Flux / Seedream sind alle synchron, das Erzwingen vonwait=Truelässt das SDK einetasks-Schnittstelle abfragen, die sich nicht aktualisiert. - Unterschiede in der Einheit von TaskHandle: Python ist in Sekunden, TS in Millisekunden, beim Übertragen zwischen Sprachen unbedingt umrechnen.
wait=Truekann dennochTimeoutErrorauslösen: Die Antwort mussstatus in ('succeeded','failed')erfüllen, um die Schleife zu verlassen; wenn der Provider andere Feldnamen verwendet, muss der Geschäftscode selbsthandle.get()analysieren.- Streaming-Abbruch: Bereits generierte Tokens vor dem Abbruch wurden abgerechnet.
- Wiederverwendung des Clients innerhalb desselben Prozesses: Das SDK hat einen eigenen Verbindungspool, häufiges
new AceDataCloud()/AceDataCloud()kann das TLS-Handshake zum Flaschenhals machen.

