Skip to main content
I servizi su Ace Data Cloud sono divisi in due categorie in base al modello di risposta: 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 in TaskHandle, 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 immediatamente TaskHandle, il codice dell’applicazione decide quando effettuare il polling.
  • wait=True: l’SDK chiama direttamente handle.wait(), la funzione restituisce la risposta dopo il completamento. Usa solo se sei sicuro che l’API di destinazione restituirà sempre il campo status: succeeded — alcuni provider non rispettano questa convenzione, causando che wait continui fino a max_wait prima di sollevare TimeoutError.

Differenze di unità (⚠️ Da leggere)

Le unità di poll_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 Python poll_interval=3000 farà sì che l’SDK attenda 50 minuti prima di effettuare il secondo polling.

Esempio: Polling esplicito di Midjourney in Python

L’intero codice fa quanto segue:
  1. images.generate(..., wait=False) invia il prompt all’API di Midjourney, ottenendo immediatamente il handle, senza bloccare.
  2. handle.wait(poll_interval=3.0, max_wait=180.0) effettua un POST ogni 3 secondi su /midjourney/tasks, fino a quando status non diventa succeeded o failed, o il tempo totale supera i 180 secondi sollevando TimeoutError.
  3. 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 passare wait:
Il metodo di giudizio è semplice: se nella documentazione dell’API di destinazione non ci sono 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:
La risposta ha una struttura uniforme:
L’SDK è compatibile anche con le risposte di versione precedente senza il pacchetto esterno 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

Risultato reale:

Python

Risultato reale:

Go

Risultato reale:

Struttura del chunk in streaming

Ogni chunk è un chat.completion.chunk compatibile con OpenAI:
  • Il primo chunk di solito ha delta.role: "assistant" ma content è vuoto.
  • I chunk intermedi portano ciascuno delta.content, che può essere concatenato direttamente.
  • L’ultimo chunk ha delta vuoto, 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

  1. Non passare wait ai provider sincroni: NanoBanana / Flux / Seedream sono tutti generati in modo sincrono, forzare wait=True farà sì che l’SDK polli un’interfaccia tasks che non si aggiornerà mai.
  2. Differenze nelle unità di TaskHandle: Python è in secondi, TS è in millisecondi, assicurarsi di convertire quando si porta il codice tra lingue.
  3. wait=True può comunque generare TimeoutError: La risposta deve soddisfare status in ('succeeded','failed') per uscire dal ciclo; se il provider utilizza nomi di campo diversi, il codice di business deve gestire handle.get() per l’analisi.
  4. Annullamento in streaming: I token generati prima dell’annullamento sono già fatturati.
  5. 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.

Scopri di più