Краткий ответ
- Streaming и non-streaming полностью определяются вашим собственным кодом — полем
streamв теле запроса. Один и тот же ключ, одна и та же модель, один и тот же endpoint: если оно переключается туда-сюда, это делает ваш код клиента (или SDK / framework, который его оборачивает). Шлюз никогда не переключает это случайным образом. - Оба режима возвращают одинаковый конечный результат и тарифицируются одинаково. Единственные различия — когда вы получаете текст и как вы его разбираете.
- Как выбрать: человек смотрит на экран → streaming; программу потребляет результат (разбор JSON, пакетные задачи, вызовы tools) → non-streaming.
Различия в сравнении
Почему мои запросы переключаются между потоковой передачей и непотоковым режимом?
Это самый частый вопрос, и ответ такой: что-то на вашей стороне это меняет. Пройдитесь по этому списку — почти всегда совпадает один из пунктов: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() - Разбор аргументов function-calling / tool-call
- Пакетная обработка, автономные задачи, запланированные задачи
- Серверные сценарии, где важен только итоговый результат и никто не ждет
- Быстрая проверка, отладка, написание тест-кейсов
Затраты на интеграцию: одна и та же задача в обе стороны
- 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. Потоковая передача предотвращает тайм-ауты
gemini-3.1-pro-preview, gpt-5.6-sol, gpt-5.5-pro и т. д.) могут вообще не выдавать ничего на этапе размышления, что точно так же приводит к срабатыванию тайм-аута чтения у клиента.Правильное решение — задавать значения timeout для каждого сценария — см. Как избежать тайм-аутов API.2. Потоковая передача быстрее
2. Потоковая передача быстрее
3. Потоковая передача дешевле или тарифицирует только то, что вы получили
3. Потоковая передача дешевле или тарифицирует только то, что вы получили
4. Каждая модель и каждый endpoint поддерживают потоковую передачу
4. Каждая модель и каждый endpoint поддерживают потоковую передачу
stream, либо отклонят его.У некоторых моделей есть дополнительные ограничения для определённых сочетаний параметров в режиме потоковой передачи. Если не уверены, сначала добейтесь, чтобы вызов работал без потоковой передачи, а затем добавьте stream: true.5. Без потоковой передачи надёжнее
5. Без потоковой передачи надёжнее
- Риски без потоковой передачи: соединение молчит на протяжении всей генерации, поэтому прокси, CDN и корпоративные шлюзы могут разорвать его по тайм-ауту простоя. При очень больших телах ответа (base64-вывод изображений легко достигает десятков МБ) вы также можете столкнуться с зависшим завершающим обработчиком — см. Запросы, которые полностью передали данные, но так и не вернулись и В журнале указано завершение, но клиент ничего не получает.
- Риски потоковой передачи: она плохо совместима с промежуточными устройствами, которые не поддерживают SSE или принудительно буферизуют данные; разбор на стороне клиента сложнее, и в нём легко допустить малозаметную ошибку.
api-cf.apiyi.com (эндпоинт CDN) имеет примерно 100-секундный предел для запроса, который затрагивает оба режима. Для длительных запросов используйте api.apiyi.com или vip.apiyi.com — см. Руководство по настройке Base URL.6. Нельзя получить полный ответ из stream
6. Нельзя получить полный ответ из stream
delta.content каждого chunk, вы получите в точности тот же message.content, что и без потоковой передачи.Если собранный текст выглядит неполным, проверьте три вещи: не проигнорировали ли вы finish_reason, не вышли ли вы из цикла до получения data: [DONE] и не обрезал ли ответ промежуточный узел.Потоковая передача не работает? Четыре шага
Убедитесь, что тело запроса действительно содержит stream: true
Проверьте напрямую с помощью curl -N
Проверьте буферизацию промежуточного устройства
proxy_buffering off; в Nginx. Корпоративные шлюзы и средства безопасности могут сканировать text/event-stream как единый полезный груз — попросите сетевого администратора разрешить его прохождение.Проверьте логику разбора
:, и останавливайтесь на data: [DONE]. Последний фрагмент, содержащий usage, имеет пустой массив choices — не обращайтесь к нему по индексу.