Потоковая передача в ИИ-API: SSE и тайм-ауты

Надёжная потоковая передача в ИИ-API: события Chat и Responses, разбор SSE, первый полезный вывод, тайм-ауты по фазам и диагностика 499.

Потоковая передача в ИИ-API: SSE и тайм-ауты

Потоковая передача в ИИ-API отправляет вывод по частям, пока модель его генерирует, не дожидаясь полного тела ответа. Она может улучшить воспринимаемую отзывчивость, но сама по себе не уменьшает задержку модели и добавляет протокольный контракт, который клиент должен правильно разбирать.

Первое правило — парсер должен соответствовать эндпоинту. Chat Completions передаёт поток фрагментов completion, а Responses — типизированные события ответа. Клиент может получить HTTP 200 и при этом ничего не показать, если ожидает события другой структуры.

Начните с запроса без буферизации

Для модели Chat Completions флаг curl -N отключает буферизацию вывода curl:

curl -N -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [{"role": "user", "content": "Explain SSE in three points."}],
    "stream": true
  }'

Для модели, совместимой с Responses:

curl -N -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_RESPONSES_MODEL",
    "input": "Explain SSE in three points.",
    "stream": true
  }'

Используйте точный ID модели из раздела Модели и цены. Сначала один раз отправьте тот же запрос с отключённой потоковой передачей: так вы отделите проверку самого запроса от разбора потока.

Относитесь к потоку событий как к протоколу

Server-Sent Events — это оформленные записи, а не произвольные фрагменты JSON. Клиенту для рабочей среды нужно:

  • не буферизовать тело ответа ни в HTTP-библиотеке, ни в прокси, ни в слое интерфейса;
  • накапливать частично прочитанные из сети данные, пока не будет получено полное событие;
  • разбирать тот тип событий, который использует выбранный эндпоинт;
  • обрабатывать текстовые дельты, события рассуждений и инструментов, события завершения и ошибок;
  • не предполагать, что каждый полезный ответ содержит видимый текст;
  • сохранять возможность отмены и итоговые данные об использовании;
  • закрывать поток после завершающего события, а не ждать бесконечно.

По возможности используйте SDK, который нативно поддерживает выбранный протокол. Собственный парсер нужно протестировать на фрагментированных кадрах, нескольких событиях в одном чтении, выводе только из вызовов инструментов и корректном завершающем событии.

Измеряйте не только время до первого токена

«Время до первого токена» для трафика агентов часто слишком размытая метрика. Разделяйте такие измерения:

Измерение Что оно означает
Подключение и аутентификация Время, чтобы достичь шлюза и проверить ключ
Заголовки ответа поставщика Время до начала ответа по выбранному маршруту
Первый полезный вывод Первый полезный текст, рассуждение или событие инструмента
Первый видимый текст Первый текст, который действительно видит пользователь
Скорость вывода Скорость видимой генерации после начала вывода
Общее время ответа Время до завершения, сбоя или отмены

Вызов инструмента может дать полезный вывод раньше любого видимого текста. Поэтому для эксплуатации надёжнее метрика первого полезного вывода, а первый видимый текст полезен для оценки пользовательского опыта.

Журнал использования Modelflare хранит временные данные каждого запроса, чтобы эти фазы можно было сопоставить с моделью, группой, статусом, токенами и стоимостью.

Задавайте тайм-ауты по фазам

Один короткий общий тайм-аут приводит к неоднозначным сбоям. Потоковый клиент должен учитывать несколько бюджетов времени:

  1. Тайм-аут подключения: не удалось установить HTTP-соединение.
  2. Тайм-аут заголовков или первого вывода: после принятия запроса нет ответа или полезного события.
  3. Тайм-аут простоя: поток начался, но новых событий нет неожиданно долго.
  4. Общий лимит времени: операция целиком превысила бизнес-ограничение для этой нагрузки.

Запросы с объёмными рассуждениями или вызовами инструментов вполне могут дольше ждать видимого текста, чем короткий ответ в чате. Подбирайте бюджеты по наблюдаемому поведению нагрузки и осознанно отменяйте запрос, когда результат пользователю больше не нужен.

Разберитесь с отменой и записями 499

Если клиент, обратный прокси, вкладка браузера или дедлайн вызывающей стороны закрывает соединение на стороне клиента (downstream), шлюз может записать запрос как отменённый клиентом. Метка 499 в записи запроса показывает, что соединение на стороне клиента оборвалось до завершения, но сама по себе не доказывает сбой выбранной модели или канала.

Разбирая отмену, сравните:

  • дедлайн клиента и сигнал отмены (abort);
  • буферизацию и тайм-ауты простоя прокси;
  • время до первого полезного вывода;
  • дошло ли до клиента хоть одно событие;
  • выбранные модель и группу;
  • ID запроса и время отмены.

Диагностика потока без видимого текста

Действуйте в таком порядке:

  1. Повторите запрос с "stream": false.
  2. Убедитесь, что модель поддерживает выбранный эндпоинт.
  3. Сохраните необработанные события до того, как их преобразует интерфейс.
  4. Проверьте, не содержит ли ответ вызов инструмента или событие рассуждения вместо текста.
  5. Убедитесь, что промежуточный узел не буферизует тело ответа.
  6. Проверьте, что парсер обрабатывает завершающее событие этого эндпоинта.
  7. Проверьте в журнале использования статус, время первого вывода, общее время и признак отмены.

Если запрос без потоковой передачи работает и необработанные события потока приходят, проблема обычно в разборе или отображении на клиенте, а не в аутентификации или доступе к модели. Если не приходит ни одного события, продолжите с руководством по ошибкам ИИ-API.

Чек-лист потоковой передачи для рабочей среды

  • Явно сопоставьте парсер с Chat Completions или Responses.
  • Отключите буферизацию в HTTP-клиенте и во всех подконтрольных слоях прокси.
  • Протестируйте используемые приложением события текста, рассуждений, вызовов инструментов без текста и ошибок.
  • Различайте первый полезный вывод и первый видимый текст.
  • Используйте тайм-ауты, соответствующие каждой фазе, и осознанный сигнал отмены.
  • Считайте повторы новыми запросами, если у операции нет безопасной схемы идемпотентности.
  • Сохраняйте для диагностики ID запроса, статус, выбранную модель, группу и время.
  • Сверьте выбор эндпоинта со статьёй Responses API или Chat Completions.

Частые вопросы

Ускоряет ли потоковая передача генерацию модели?

Не обязательно. Потоковая передача раньше показывает вывод, но скорость генерации и время до первого события по-прежнему зависят от модели, маршрута, контекста, рассуждений и инструментов.

Почему curl работает, а приложение ничего не показывает?

Приложение или промежуточный узел может буферизовать тело ответа, либо парсер ожидает фрагменты Chat Completions, а получает события Responses. Прежде чем менять модель или маршрут, сохраните необработанные кадры на границе приложения.

Нужно ли клиенту повторять запрос после обрыва потока?

Только если операцию безопасно повторить. Оборванный поток мог уже запустить работу у поставщика или вызовы инструментов. Используйте ограниченное число повторов и идемпотентность на уровне приложения там, где важны дублирующиеся побочные эффекты.