BroadRouter

Стриминг LLM: чанки SSE, дельты, usage и отмена

Команда BroadNet Inference · 4 мин чтения · Опубликовано · Обновлено

LLM API передаёт chat completion потоком Server-Sent Events: каждая строка data содержит JSON-чанк, в котором choices[0].delta несёт следующий кусок текста. Склеивайте дельты, останавливайтесь на data: [DONE] и задайте stream_options include_usage, чтобы получить счётчики токенов в финальном чанке с пустым списком choices. Чтобы отменить поток, закройте соединение.

Без стриминга chat completion ничего не возвращает, пока не готов весь ответ. Ответ на 600 токенов при скорости около 100 токенов в секунду — это несколько секунд тишины. Со стримингом первые слова появляются, как только модель их пишет. В этой статье — что на самом деле передаётся по сети, как это разбирать, как достать из потока статистику по токенам и как корректно его остановить. Правила, специфичные для BroadNet, в кратком виде собраны в справочном руководстве по стримингу.

Как выглядит поток SSE на уровне протокола?

Server-Sent Events — это обычный HTTP-ответ с Content-Type: text/event-stream. Сервер держит соединение открытым и пишет события. Каждое событие — одна или несколько строк data:, за которыми следует пустая строка. OpenAI-совместимые API кладут в каждое событие один JSON-чанк и завершают поток буквальным [DONE]:

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"One, "},"finish_reason":null}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"two, three."},"finish_reason":"stop"}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":6,"total_tokens":20}}

data: [DONE]

Структура выше упрощена и сокращена для иллюстрации. Настоящие чанки также содержат model и created, а модели с рассуждениями могут сообщать в usage токены рассуждений.

Что содержится в чанке?

Поле Где Что означает
choices[0].delta.role Первый чанк Обычно assistant. Отправляется один раз.
choices[0].delta.content Большинство чанков Следующий кусок текста. Может быть пустым.
choices[0].delta.tool_calls Вызовы инструментов Фрагменты имени функции и JSON-аргументов, которые склеиваются по index.
choices[0].finish_reason Последний чанк с контентом stop, length или tool_calls. До этого — null.
usage Финальный чанк, если запрошен Итоги по всему запросу. Во всех остальных — null.

Главная идея — дельта, а не снимок. Каждый чанк содержит только новое. Сообщение собирается склейкой кусков по порядку. Вызовы инструментов стримятся так же: аргументы приходят строковыми фрагментами, которые не являются валидным JSON, пока не придёт последний, поэтому разбирайте их только после того, как finish_reason станет tool_calls.

Как получить usage из потока?

Нестриминговый ответ всегда содержит usage. Поток — нет, если не попросить. Задайте stream_options: {"include_usage": true}, и сервер отправит перед [DONE] ещё один чанк. В нём итоговые суммы и пустой массив choices. В BroadNet Inference usage может также содержать prompt_tokens_details.cached_tokens и completion_tokens_details.reasoning_tokens, если модель их сообщает, — это именно то, что нужно для логирования расходов.

Типичная ошибка: код, который читает chunk.choices[0] на каждом чанке, падает с ошибкой индекса на чанке с usage. Сначала проверяйте choices.

Python: стриминг, сбор usage, отмена

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash",  # DeepSeek V4.1 Flash, a reasoning model
    messages=[{"role": "user", "content": "Explain SSE in three sentences."}],
    stream=True,
    stream_options={"include_usage": True},
    max_tokens=2000,  # reasoning counts toward this limit
)

def user_pressed_stop():  # replace with your own condition
    return False

parts, usage, finish = [], None, None
try:
    for chunk in stream:
        if chunk.choices:
            choice = chunk.choices[0]
            if choice.delta.content:
                parts.append(choice.delta.content)
                print(choice.delta.content, end="", flush=True)
            if choice.finish_reason:
                finish = choice.finish_reason
        if chunk.usage:
            usage = chunk.usage
        if user_pressed_stop():  # your own condition
            break
finally:
    stream.close()  # closes the HTTP connection

text = "".join(parts)

Один break останавливает чтение, но сокет остаётся открытым, пока его не соберёт сборщик мусора. Закрывайте его явно, чтобы сервер увидел отключение.

Node: стриминг с AbortController

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY });
const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // hard stop after 30 s

const stream = await client.chat.completions.create(
  {
    model: "broadnet/deepseek-v4.1-flash",
    messages: [{ role: "user", content: "Explain SSE in three sentences." }],
    stream: true,
    stream_options: { include_usage: true },
  },
  { signal: controller.signal },
);

let text = "";
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) text += delta;
  if (chunk.usage) console.log(chunk.usage);
}

README openai-node документирует опцию signal, и она работает, пока тело ответа ещё читается. В веб-сервере привяжите controller.abort() к событию close клиентского запроса, чтобы пользователь, покинувший страницу, заодно останавливал генерацию. Подробнее о настройке — в руководстве по Node SDK.

curl: смотрим «сырые» события

curl -N https://inference.broadnet.ai/v1/chat/completions \
  -H "Authorization: Bearer $BROADNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"broadnet/gemma-4-26b-a4b","stream":true,"stream_options":{"include_usage":true},"messages":[{"role":"user","content":"Count to five."}]}'

-N отключает буферизацию вывода, чтобы события печатались по мере поступления. Нажмите Ctrl+C для отмены — это закроет соединение. Конструктор API-запросов генерирует этот запрос, а также версии для Python и Node, для любой модели и базового URL.

Как отменить поток и сколько это стоит?

Отмена в SSE — это просто закрытие соединения. Сообщения «стоп» не существует. Что будет дальше, решает сервер: корректно работающий сервер замечает закрытый сокет и прекращает генерацию. Токены, выданные до этого момента, — реально проделанная работа. Справочник API BroadNet не документирует тарификацию отменённых потоков, поэтому исходите из того, что при оплате по факту сгенерированные до отключения токены оплачиваются, и сверяйтесь с записями об использовании. На тарифе с фиксированной ценой отменённый поток ничего дополнительно не стоит, но сессия освобождается только тогда, когда сервер остановится.

Пять ошибок стриминга, которые стоит проверить

  1. Буферизующие прокси. Nginx и некоторые CDN буферизуют ответы, и клиент получает всё разом. Отключите буферизацию прокси для маршрута со стримингом.
  2. Нет проверки [DONE]. Оборванное соединение выглядит как короткий ответ. Считайте отсутствие [DONE] признаком неполного ответа и записывайте X-Request-ID, как описано в руководстве по ошибкам.
  3. Повтор посреди потока. SDK не повторяют запрос, когда тело ответа уже начало приходить. Повтор — это новый запрос и, при оплате по факту, новый счёт.
  4. Игнорирование finish_reason: length. У моделей с рассуждениями, таких как DeepSeek V4.1 Flash, размышления входят в max_tokens, и при маленьком лимите поток может остановиться ещё до видимого текста. Сколько стоят токены рассуждений.
  5. Неправильное разбиение строк. Если вы разбираете SSE вручную, накапливайте байты, пока не увидите пустую строку. Чтение из TCP может закончиться посреди JSON-чанка.

Место BroadNet Inference

BroadNet Inference использует стандартный формат стриминга OpenAI-совместимых API, так что SDK для Python и Node разбирают его без изменений. Usage в финальном чанке включает кэшированные токены и токены рассуждений, если модель их сообщает. В документации сказано, что стриминг всё же стоит проверить на каждой модели перед использованием в продакшене, поэтому прогоните код выше на той самой модели, с которой выходите в продакшен. Если вас в первую очередь волнует, как быстро приходит первый токен, читайте дальше TTFT и пропускная способность. Если нужен голос в реальном времени через WebSockets, этот API для этого не предназначен: он предлагает chat completions и распознавание речи из файлов.

Вопросы и ответы

Чем SSE отличается от WebSockets для стриминга LLM?

SSE — односторонний канал от сервера к клиенту поверх обычного HTTP-ответа. Для chat completion больше и не нужно, поэтому OpenAI-совместимые API используют SSE. WebSockets двусторонние и требуют апгрейда протокола; их используют для голоса в реальном времени, а не для chat completions.

Почему в чанках стриминга usage равен null?

Usage отправляется, только если вы его запросили. Добавьте stream_options с include_usage, равным true. Тогда во всех чанках, кроме последнего, usage будет null, а последний чанк принесёт итоговые суммы с пустым списком choices.

Платите ли вы, если отменили поток?

У провайдеров по-разному, и многие это не документируют. Исходите из того, что токены, сгенерированные до того, как сервер заметил закрытое соединение, оплачиваются. Логируйте X-Request-ID и сверяйте с записями об использовании.

Как понять, что поток завершился нормально?

Вы получили data: [DONE], а в последнем чанке с контентом был finish_reason, например stop. finish_reason length означает, что ответ обрезан по max_tokens. Отсутствие [DONE] означает, что соединение оборвалось.

Стриминг ускоряет модель?

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

Открыть в MarkdownСпросить ChatGPTСпросить ClaudeСпросить Perplexity