Skip to main content
Сервіси на Ace Data Cloud поділяються на дві категорії за режимом відповіді: Ця стаття зосереджена на двох останніх категоріях: опитування TaskHandle асинхронних завдань та деталі, пастки і міжмовні відмінності потокових відповідей чату.

I. TaskHandle — єдина абстракція асинхронних завдань

Усі три SDK обгортають асинхронні завдання в TaskHandle, надаючи однакові 4 методи:

Два способи виклику для створення завдання

Кожен асинхронний ресурс (images.generate / video.generate / audio.generate) має параметр wait:
  • wait=False (за замовчуванням): негайно повертає TaskHandle, бізнес-код сам вирішує, коли опитувати.
  • wait=True: SDK внутрішньо викликає handle.wait(), функція повертає відповідь після завершення. Використовуйте лише тоді, коли ви впевнені, що цільовий API обов’язково поверне поле status: succeeded — деякі постачальники не дотримуються цієї угоди, що призведе до того, що wait буде продовжуватися до max_wait, перш ніж викине TimeoutError.

Різниця в одиницях (⚠️ Обов’язково до прочитання)

Одиниці poll_interval та max_wait відрізняються в трьох мовах, що є поширеною проблемою при міжмовній міграції:
Якщо ви спробуєте перевести { pollInterval: 3000 } з TS як секунди в Python poll_interval=3000, SDK чекатиме 50 хвилин, перш ніж опитувати вдруге.

Приклад: Явне опитування Midjourney на Python

Весь код виконує наступне:
  1. images.generate(..., wait=False) передає prompt до Midjourney API, негайно отримуючи handle, не блокуючи.
  2. handle.wait(poll_interval=3.0, max_wait=180.0) внутрішньо кожні 3 секунди виконує POST запит до /midjourney/tasks, поки status не зміниться на succeeded або failed, або загальний час не перевищить 180 секунд, викинувши TimeoutError.
  3. Після завершення result["response"]["data"] зазвичай містить 4 зображення (за замовчуванням Midjourney 2x2 grid).

Приклад: Явне опитування Midjourney на TypeScript

Вибір між синхронним генеруванням та асинхронними завданнями

Якщо ваш постачальник сам по собі є синхронним (NanoBanana / Flux / Seedream), не передавайте wait:
Метод визначення дуже простий: якщо в документації цільового API немає пари task_id + /tasks, це синхронне генерування; у відповіді синхронного генерування поле data вже містить остаточний результат.

Внутрішній протокол TaskHandle

Виклик TaskHandle.get() виглядає так:
Відповідь має єдину структуру:
SDK також сумісний з старими відповідями без зовнішнього обгортання response — безпосередньо читаючи верхній рівень status, тому перехід між новими та старими відповідями не вплине на бізнес-код.

II. SSE потокова відповідь (chat.completions)

chat.completions.create(stream=True) є наразі єдиним потоковим інтерфейсом у SDK (потоки аудіо / відео ще не підтримуються). Стилі ітерації трьох мов є рідними:

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.

Скасування на півдорозі

Передчасне скасування вже нарахованих токенів — токени, згенеровані до моменту скасування, все ще будуть нараховані.

Три, тайм-аут і повторна спроба

Три SDK ділять одну і ту ж стратегію повторних спроб: Щоб вимкнути повторні спроби: передати max_retries=0 / maxRetries: 0 / WithMaxRetries(0) під час створення клієнта. Опитування асинхронних завдань (TaskHandle) не підлягає впливу max_retries — його цикл є бізнес-рівнем, а не HTTP-рівнем, контролюється max_wait.

Чотири, поширені пастки

  1. Синхронному провайдеру не передавати wait: NanoBanana / Flux / Seedream є синхронними, примусове wait=True змусить SDK опитувати інтерфейс tasks, який взагалі не оновлюється.
  2. Різниця в одиницях TaskHandle: Python — секунди, TS — мілісекунди, при переносі між мовами обов’язково перераховуйте.
  3. wait=True все ще може викликати TimeoutError: відповідь повинна відповідати status in ('succeeded','failed'), щоб вийти з циклу; якщо провайдер використовує інші назви полів, бізнес-код повинен самостійно handle.get() розпарсити.
  4. Потокове скасування: токени, згенеровані до скасування, вже нараховані.
  5. Повторне використання клієнта в одному процесі: SDK має власний пул з’єднань, часте new AceDataCloud() / AceDataCloud() може зробити TLS-рукопожаття вузьким місцем.

Дізнатися більше