Потоковые ответы ИИ API: SSE и тайм-ауты

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

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

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

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.","stream":true}'

Сначала повторите запрос без streaming, чтобы отделить валидацию от parser. Используйте ID из раздела Модели и цены.

Считайте SSE протоколом

Server-Sent Events — это оформленные записи, а не произвольные куски JSON. Клиент должен отключить буферизацию в HTTP, proxy и UI, собирать частичные чтения, обрабатывать текст, reasoning, инструменты, завершение и ошибки, сохранять отмену и итоговое использование и закрываться после terminal event.

Измеряйте разные фазы

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

Вызов инструмента может быть полезным до текста. Для эксплуатации важнее первый полезный результат, для UX — также первый видимый текст.

Timeout по фазам

Разделяйте timeout соединения, заголовков или первого результата, простоя потока и общий deadline. Reasoning и инструменты могут дольше не давать видимый текст. Настраивайте бюджеты по реальным нагрузкам, а не одним коротким глобальным значением.

Если клиент, браузер или proxy закрывается раньше, Modelflare может записать 499. Это доказывает отмену downstream, но не сбой модели или канала. Сравните Abort, proxy timeout, первый результат, модель, группу и время.

Если текста нет

1. Повторите с "stream": false.
2. Подтвердите поддержку endpoint моделью.
3. Сохраните сырые события до UI.
4. Ищите tool или reasoning без текста.
5. Исключите промежуточную буферизацию.
6. Проверьте terminal event в parser.
7. Сравните статус, время и отмену.

Если обычный запрос работает и события приходят, ошибка обычно в разборе или отображении. Иначе используйте руководство по ошибкам. Выбор формата: Responses API или Chat Completions.

Проверить оба endpoint без буферизации

Кроме примера Responses, проверьте Chat Completions в его собственном формате:

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": "Объясни SSE в трёх пунктах."}],
    "stream": true
  }'

Парсер должен:

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

Контрольный список для production-потока

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

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

Потоковый режим ускоряет генерацию модели?

Не обязательно. Он раньше показывает вывод; ожидание первого события и дальнейшая скорость всё ещё зависят от модели, маршрута, контекста, рассуждения и инструментов.

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

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

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

Только если операцию безопасно повторять. Работа upstream или инструмент могли уже выполниться; ограничьте повторы и требуйте идемпотентность при побочных эффектах.