Skip to main content
Usługi na Ace Data Cloud dzielą się na dwa rodzaje w zależności od trybu odpowiedzi: Artykuł koncentruje się na dwóch ostatnich kategoriach: polling TaskHandle dla zadań asynchronicznych oraz szczegóły, pułapki i różnice językowe w odpowiedziach strumieniowych czatu.

I. TaskHandle — jednolita abstrakcja zadań asynchronicznych

Trzy SDK opakowują zadania asynchroniczne w TaskHandle, oferując te same 4 metody:

Dwa sposoby wywołania do tworzenia zadań

Każdy zasób asynchroniczny (images.generate / video.generate / audio.generate) ma parametr wait:
  • wait=False (domyślnie): natychmiast zwraca TaskHandle, kod biznesowy decyduje, kiedy przeprowadzić polling.
  • wait=True: SDK wewnętrznie wywołuje handle.wait(), funkcja zwraca odpowiedź po zakończeniu. Używaj tylko wtedy, gdy masz pewność, że docelowe API na pewno zwróci pole status: succeeded — nieliczni dostawcy nie przestrzegają tej zasady, co sprawi, że wait będzie czekać do max_wait, zanim zgłosi TimeoutError.

Różnice jednostek (⚠️ Konieczne do przeczytania)

Jednostki poll_interval i max_wait są różne w trzech językach, co jest powszechnym punktem zapalnym podczas migracji między językami:
Przekształcenie { pollInterval: 3000 } z TS na sekundy w Pythonie jako poll_interval=3000 spowoduje, że SDK będzie czekać 50 minut, zanim przeprowadzi drugie polling.

Przykład: Python jawny polling Midjourney

Cały kod wykonuje:
  1. images.generate(..., wait=False) przesyła prompt do API Midjourney, natychmiast uzyskując handle, bez blokowania.
  2. handle.wait(poll_interval=3.0, max_wait=180.0) wewnętrznie co 3 sekundy wykonuje POST do /midjourney/tasks, aż status zmieni się na succeeded lub failed, lub całkowity czas przekroczy 180 sekund, zgłaszając TimeoutError.
  3. Po zakończeniu result["response"]["data"] zazwyczaj zawiera 4 obrazy (domyślnie 2x2 grid w Midjourney).

Przykład: TypeScript jawny polling

Wybór między synchronizacją a zadaniami asynchronicznymi

Jeśli twój dostawca sam w sobie generuje obrazy synchronnie (NanoBanana / Flux / Seedream), nie przekazuj wait:
Metoda oceny jest prosta: jeśli w dokumentacji API docelowego nie ma pary task_id + /tasks, to jest to generacja synchronna; w odpowiedzi generacji synchronnej pole data już zawiera ostateczny wynik.

Protokół wewnętrzny TaskHandle

TaskHandle.get() wywołuje:
Odpowiedź ma jednolitą strukturę:
SDK obsługuje również stare odpowiedzi bez zewnętrznego opakowania response — odczytuje bezpośrednio górny poziom status, więc przełączanie między nowymi a starymi odpowiedziami nie wpływa na kod biznesowy.

II. SSE odpowiedź strumieniowa (chat.completions)

chat.completions.create(stream=True) jest obecnie jedynym interfejsem strumieniowym w SDK (strumienie audio / wideo jeszcze nie są obsługiwane). Styl iteracji w trzech językach jest różny:

TypeScript

真实运行结果:

Python

真实运行结果:

Go

真实运行结果:

流式 chunk 的结构

每一帧 chunk 都是一个 OpenAI 兼容的 chat.completion.chunk:
  • 第一个 chunk 通常带 delta.role: "assistant" 但 content 为空。
  • 中间的 chunk 每个带 delta.content,可以直接拼接。
  • 最后一个 chunk delta 为空、finish_reason 是 stop / length / content_filter。

中途取消

提前取消已经计费的 token —— 取消时刻之前生成的 token 还是会按实际消耗扣费。

三、超时和重试

三种 SDK 共享同一套重试策略: 要禁用重试:构造客户端时传 max_retries=0 / maxRetries: 0 / WithMaxRetries(0)。 异步任务(TaskHandle)的轮询本身不受 max_retries 影响——它的循环是业务级的而不是 HTTP 级的,靠 max_wait 控制总时长。

四、常见陷阱

  1. 同步 provider 不要传 wait:NanoBanana / Flux / Seedream 都是同步生成,强行 wait=True 会让 SDK 去轮询一个根本不会更新的 tasks 接口。
  2. TaskHandle 单位差异:Python 是秒、TS 是毫秒,跨语言移植时一定换算。
  3. wait=True 仍可能 TimeoutError:响应必须满足 status in ('succeeded','failed') 才会退出循环;如果 provider 用了别的字段名,需要业务代码自己 handle.get() 解析。
  4. 流式取消:取消前生成的 token 已经计费。
  5. 同一 process 内复用 client:SDK 自带连接池,频繁 new AceDataCloud() / AceDataCloud() 会让 TLS 握手成为瓶颈。

了解更多