Краткий ответ
- Выбор между потоковой передачей и обычным режимом полностью определяется вашим кодом — полем
streamв теле запроса. Тот же ключ, та же модель, тот же эндпоинт: если режим меняется, значит, переключение происходит в вашем клиентском коде (или в используемом SDK / фреймворке). Шлюз никогда не переключает его произвольно. - Оба режима возвращают одинаковый итоговый контент и тарифицируются одинаково. Единственные различия — когда вы получаете текст и как вы его разбираете. Исключением является фильтрация безопасности контента: запросы без потоковой передачи автоматически переключаются на другой маршрут, в то время как потоковые запросы обрываются; см. Чем отличаются потоковые запросы и запросы без потоковой передачи при фильтрации контента?.
- Как выбрать: за экраном наблюдает человек → потоковая передача; результат обрабатывается программой (парсинг JSON, пакетные задачи, вызовы инструментов) → без потоковой передачи.
Различия в сравнении
Почему мои запросы переключаются между потоковой передачей и непотоковым режимом?
Это самый частый вопрос, и ответ такой: что-то на вашей стороне это меняет. Пройдитесь по этому списку — почти всегда совпадает один из пунктов:1. stream — это переменная или значение конфигурации в вашем коде
1. stream — это переменная или значение конфигурации в вашем коде
stream=config.get("stream", False) или stream=is_web_request. Разные точки входа вызывают одну и ту же функцию с разными значениями, и по логам кажется, будто режим переключается случайно.Как проверить: выведите фактическое тело запроса, которое вы отправляете, и посмотрите на поле stream.2. У разных SDK и фреймворков разные значения по умолчанию
2. У разных SDK и фреймворков разные значения по умолчанию
- OpenAI SDK
chat.completions.create(): без потоковой передачи по умолчанию client.chat.completions.stream()илиwith_streaming_response: потоковая передача- Обёртки вроде LangChain / LlamaIndex: зависит от того, вызываете ли вы
invokeилиstream, и передавали ли выstreaming=Trueпри создании объекта модели - Настольные клиенты, инструменты агентов, платформы рабочих процессов: обычно в настройках есть переключатель «потоковый вывод», а значения по умолчанию отличаются
3. Один ключ используется несколькими приложениями
3. Один ключ используется несколькими приложениями
4. Промежуточное устройство сгладило потоковую передачу
4. Промежуточное устройство сгладило потоковую передачу
stream: true, но Nginx, корпоративный gateway или какой-то proxy буферизовал ответ — сервер отправлял его порциями, proxy удержал его и выпустил весь сразу, и это ощущается как отсутствие потоковой передачи.Как проверить: один раз протестируйте, обойдя proxy; отключите буферизацию в Nginx (proxy_buffering off;). Обратите внимание, что в этом случае лог консоли по-прежнему показывает is_stream = true, потому что gateway действительно выполнил потоковую передачу.Выбор по сценарию
Используйте потоковую передачу
- Чат-интерфейсы и боты поддержки — пользователям нужна немедленная обратная связь
- Плагины для IDE и ассистенты программирования (Claude Code, Cursor и т. д.)
- Генерация длинных материалов (длинные статьи, длинные переводы, большие блоки кода)
- Длительные задачи моделей рассуждения — по крайней мере, вы можете видеть прогресс
- Везде, где пользователь может нажать «остановить» во время генерации
Используйте потоковую передачу
- Структурированный вывод: вам нужен весь JSON для
json.loads() - Разбор аргументов вызова функций и инструментов
- Пакетная обработка, автономные задания, запланированные задачи
- Серверные процессы, где важен только итоговый результат и никто не ждёт
- Быстрая проверка, отладка, написание тестовых случаев
Затраты на интеграцию: одна и та же задача в обе стороны
- Python без потоковой передачи
- Python с потоковой передачей
- Node.js с потоковой передачей
- cURL в сравнении
/v1/messages) использует другой протокол потоковой передачи: SSE с именованными событиями Anthropic (message_start / content_block_delta / message_delta и т. д.), а не единообразные чанки OpenAI data:, и usage разбивается между событиями message_start и message_delta. Полное руководство по парсингу: Нативный формат Claude: ответы с потоковой передачей и без нее.Тарификация и использование: одинаково в любом случае
Два подводных камня, связанных сusage:
- streaming по умолчанию не возвращает usage. На endpoint, совместимых с OpenAI, вы должны передать
stream_options: {"include_usage": true}; после этого usage приходит в финальном чанке (чей массивchoicesпуст — проверьте перед индексированием). На APIYI это подтверждено на нескольких моделях. - Не сверяйте ваш счет с
usage, которые возвращает API, особенно с полями, связанными с кэшем. Возвращаемые значения не всегда совпадают с тем, что было фактически тарифицировано; факт попадания в кэш определяется по «деталям тарификации кэша» в логах консоли. См. Как объясняется тарификация кэша.
Шесть распространенных заблуждений
1. Потоковая передача означает, что можно игнорировать таймауты
1. Потоковая передача означает, что можно игнорировать таймауты
2. Потоковая передача работает быстрее
2. Потоковая передача работает быстрее
3. Потоковая передача дешевле или тарифицирует только то, что вы получили
3. Потоковая передача дешевле или тарифицирует только то, что вы получили
4. Любая модель и эндпоинт поддерживают потоковую передачу
4. Любая модель и эндпоинт поддерживают потоковую передачу
stream, либо отклонят запрос.Некоторые модели имеют дополнительные ограничения на определенные комбинации параметров при потоковой передаче. Если вы не уверены, сначала добейтесь корректной работы вызова без потоковой передачи, а затем добавьте stream: true.5. Работа без потоковой передачи надежнее
5. Работа без потоковой передачи надежнее
- Риски без потоковой передачи: соединение простаивает без передачи данных на протяжении всей генерации, поэтому прокси, CDN и корпоративные шлюзы могут разорвать его по таймауту неактивности. При очень больших телах ответов (вывод изображений в base64 легко достигает десятков МБ) вы также можете столкнуться с зависанием завершающего символа — см. Запросы, завершившие передачу данных, но так и не вернувшие ответ и В логах отображается успешное завершение, но клиент ничего не получает.
- Риски потоковой передачи: не подходит для промежуточных сетевых узлов (middlebox), которые не поддерживают SSE или принудительно включают буферизацию; парсинг на стороне клиента сложнее, и в нем легко допустить незаметные ошибки.
api-cf.apiyi.com (эндпоинт CDN) имеет ограничение длительности запроса около 100 секунд, которое влияет на оба режима. Для длительных запросов используйте api.apiyi.com или b.apiyi.com — см. Руководство по настройке базового URL.6. Из потока нельзя получить полный ответ
6. Из потока нельзя получить полный ответ
delta.content каждого чанка дает в точности message.content из режима без потоковой передачи.Если собранный текст выглядит неполным, проверьте три вещи: не проигнорировали ли вы finish_reason, не вышли ли из цикла до получения data: [DONE], и не урезал ли ответ промежуточный сетевой узел (middlebox).Потоковая передача не работает? Четыре шага
Убедитесь, что тело запроса действительно содержит stream: true
Проверьте напрямую с помощью curl -N
Проверьте буферизацию промежуточного устройства
proxy_buffering off; в Nginx. Корпоративные шлюзы и средства безопасности могут сканировать text/event-stream как единый полезный груз — попросите сетевого администратора разрешить его прохождение.Проверьте логику разбора
:, и останавливайтесь на data: [DONE]. Последний фрагмент, содержащий usage, имеет пустой массив choices — не обращайтесь к нему по индексу.