РУКОВОДСТВО · ОБНОВЛЕНО 2026-09-15
Streaming в AI API: SSE, токены и обработка ошибок
Поток позволяет показывать части ответа раньше завершения, но клиенту всё равно нужно собрать финальное состояние и корректно обработать обрыв.
Включите streaming, читайте события SSE, накапливайте текст и структурированные deltas, а завершение подтверждайте только финальным событием. Добавьте AbortController, idle timeout, обработку duplicate/reconnect и отдельный статус incomplete; частичный текст не считается готовым результатом.
1. Выберите транспорт и контракт
Многие AI endpoints используют Server-Sent Events поверх HTTP, но типы событий различаются. Прочитайте схему конкретного API: текст, reasoning, tool calls, usage, error и done могут приходить отдельно. Прокси должен отключать нежелательную буферизацию и поддерживать долгий ответ. Не парсите поток простым split по произвольному фрагменту сети.
2. Соберите состояние на сервере или клиенте
Декодируйте UTF-8 инкрементально, разбирайте полные SSE-события и применяйте delta по id. Аргументы tool call могут быть незавершённым JSON до финала. Храните конечный объект отдельно от видимого текста. Обновляйте UI с ограниченной частотой, иначе тысячи мелких render снижают производительность.
3. Обработайте отмену и таймаут
Пользовательская кнопка вызывает abort и закрывает upstream, если возможно. Различайте общий deadline и idle timeout без новых событий. После обрыва покажите, что ответ неполный, и не выполняйте действие из его последней строки. Автоматический retry целого запроса может продублировать tools или списание, поэтому учитывает идемпотентность.
4. Продумайте безопасность и модерацию
Поток показывает текст до возможности оценить весь ответ, что усложняет фильтрацию. Для чувствительного сценария буферизуйте достаточный блок или модерируйте вход и части с понятной политикой. Экранируйте вывод как недоверенный контент. Ссылки, HTML и команды не становятся безопасными из-за постепенной доставки.
5. Измерьте UX и стоимость
Фиксируйте time to first event, time to first visible text, полное время, обрывы и p95. Streaming не гарантирует меньшую цену и не заменяет usage финального ответа. Проверьте медленную сеть, закрытую вкладку и обратное давление. Accessibility требует, чтобы частые обновления не заставляли screen reader озвучивать каждую часть.
Частые вопросы
Streaming делает модель быстрее?
Он раньше показывает части, но полное вычисление может занять столько же.
Что такое SSE?
Однонаправленный поток событий сервера по HTTP.
Можно парсить каждый chunk как JSON?
Нет, сетевой chunk и полное SSE-событие не обязаны совпадать.
Что делать при обрыве?
Отметить ответ incomplete и безопасно предложить повтор.
Когда streaming не нужен?
Для короткого JSON или batch-задачи без интерактивного ожидания.