Questo articolo si concentra sulle ultime due categorie: Polling di TaskHandle per attività asincrone e dettagli, insidie e differenze tra lingue per risposte in streaming chat.
I. TaskHandle — Astrazione unificata per attività asincrone
Tutti e tre gli SDK incapsulano le attività asincrone inTaskHandle, fornendo gli stessi 4 metodi:
Due modalità di chiamata per creare attività
Ogni risorsa asincrona (images.generate / video.generate / audio.generate) ha un parametro wait:
wait=False(predefinito): restituisce immediatamenteTaskHandle, il codice dell’applicazione decide quando effettuare il polling.wait=True: l’SDK chiama direttamentehandle.wait(), la funzione restituisce la risposta dopo il completamento. Usa solo se sei sicuro che l’API di destinazione restituirà sempre il campostatus: succeeded— alcuni provider non rispettano questa convenzione, causando chewaitcontinui fino amax_waitprima di sollevareTimeoutError.
Differenze di unità (⚠️ Da leggere)
Le unità dipoll_interval e max_wait sono diverse tra le tre lingue, un comune punto di errore durante la migrazione tra lingue:
Trattare{ pollInterval: 3000 }di TS come secondi e tradurlo in Pythonpoll_interval=3000farà sì che l’SDK attenda 50 minuti prima di effettuare il secondo polling.
Esempio: Polling esplicito di Midjourney in Python
images.generate(..., wait=False)invia ilpromptall’API di Midjourney, ottenendo immediatamente ilhandle, senza bloccare.handle.wait(poll_interval=3.0, max_wait=180.0)effettua un POST ogni 3 secondi su/midjourney/tasks, fino a quandostatusnon diventasucceededofailed, o il tempo totale supera i 180 secondi sollevandoTimeoutError.- Una volta completato,
result["response"]["data"]di solito contiene 4 immagini (Midjourney di default 2x2 grid).
Esempio: Polling esplicito di TypeScript
Scelte tra generazione sincrona e attività asincrona
Se il tuo provider genera immagini in modo sincrono (NanoBanana / Flux / Seedream), non passarewait:
task_id + /tasks, allora è generazione sincrona; la risposta della generazione sincrona contiene già il risultato finale nel campo data.
Protocollo interno di TaskHandle
TaskHandle.get() chiama:
response — legge direttamente il status di livello superiore, quindi il passaggio tra risposte di versione nuova e vecchia non influisce sul codice dell’applicazione.
II. Risposta in streaming SSE (chat.completions)
chat.completions.create(stream=True) è attualmente l’unica interfaccia in streaming nell’SDK (streaming audio / video non è ancora supportato). Gli stili di iterazione delle tre lingue sono nativi:
TypeScript
Python
Go
Struttura del chunk in streaming
Ogni chunk è unchat.completion.chunk compatibile con OpenAI:
- Il primo chunk di solito ha
delta.role: "assistant"macontentè vuoto. - I chunk intermedi portano ciascuno
delta.content, che può essere concatenato direttamente. - L’ultimo chunk ha
deltavuoto,finish_reasonèstop/length/content_filter.
Annullamento a metà
L’annullamento dei token già fatturati - i token generati prima del momento dell’annullamento verranno comunque addebitati.
Tre, Timeout e Riprova
Tre SDK condividono la stessa strategia di riprova:
Per disabilitare le riprova: passare
max_retries=0 / maxRetries: 0 / WithMaxRetries(0) durante la costruzione del client.
Il polling delle attività asincrone (TaskHandle) non è influenzato da max_retries - il suo ciclo è a livello di business e non a livello HTTP, controllato da max_wait per la durata totale.
Quattro, Trappole comuni
- Non passare
waitai provider sincroni: NanoBanana / Flux / Seedream sono tutti generati in modo sincrono, forzarewait=Truefarà sì che l’SDK polli un’interfacciatasksche non si aggiornerà mai. - Differenze nelle unità di TaskHandle: Python è in secondi, TS è in millisecondi, assicurarsi di convertire quando si porta il codice tra lingue.
wait=Truepuò comunque generareTimeoutError: La risposta deve soddisfarestatus in ('succeeded','failed')per uscire dal ciclo; se il provider utilizza nomi di campo diversi, il codice di business deve gestirehandle.get()per l’analisi.- Annullamento in streaming: I token generati prima dell’annullamento sono già fatturati.
- Riutilizzare il client all’interno dello stesso processo: L’SDK include un pool di connessioni, frequenti
new AceDataCloud()/AceDataCloud()faranno diventare il handshake TLS un collo di bottiglia.

