К содержимому
Блог

Стриминг ответов Claude через SSE: код на TypeScript и Python

Стриминг ответов Claude через SSE: код на TypeScript и Python

Потоковый ответ - это обычный HTTP-ответ с типом text/event-stream: события идут блоками, а блок заканчивается пустой строкой. Читайте тело построчно, склеивайте строки data: одного блока и считайте ответ законченным только после data: [DONE] в Chat Completions или события message_stop в Messages. Всё, что пришло раньше, может оказаться обрывком.

Коротко

  • Включите "stream": true. В Chat Completions добавьте stream_options: { include_usage: true }, если нужен расход токенов в потоке.

  • Сетевой чанк не равен событию: один блок может прийти в двух чанках, а в одном чанке может быть три блока. Парсеру нужен буфер.

  • Поток без [DONE] или message_stop неполный, даже если статус был 200.

Как посмотреть поток без кода?

Самый быстрый способ увидеть события такими, какими их получит клиент, это curl с флагом -N, который отключает буферизацию вывода:

bash
curl -N https://relay-llm.ru/v1/chat/completions \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","stream":true,"stream_options":{"include_usage":true},"messages":[{"role":"user","content":"Привет"}]}'

Поля запроса описаны в документации Chat Completions, а события потока Relay разбирает руководство по streaming.

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

Формат определяет стандарт HTML. Блок состоит из строк поле: значение. Строка, начинающаяся с двоеточия, комментарий, её пропускают. Поле event задаёт имя события, поле data несёт данные, несколько строк data склеиваются через \n. Пустая строка отправляет накопленный блок получателю, а блок, не дошедший до пустой строки, при обрыве отбрасывается. Так сказано в спецификации, и этих правил хватает для рабочего парсера.

Chat Completions присылает блоки из одних data:. Текст лежит в choices[0].delta.content, поток кончается строкой [DONE]. Значения в примере условные:

text
data: {"id":"chatcmpl-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"При"}}]}

data: {"id":"chatcmpl-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"вет"},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-1","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":9,"completion_tokens":2,"total_tokens":11}}

data: [DONE]

Messages присылает именованные события. Поток открывает message_start, текст приходит в content_block_delta, закрывают его message_delta с причиной остановки и message_stop. Между ними может попасться ping:

text
event: message_start
data: {"type":"message_start","message":{"id":"msg_1","type":"message","role":"assistant","content":[],"model":"claude-sonnet-5","usage":{"input_tokens":9,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type":"ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Привет"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":2}}

event: message_stop
data: {"type":"message_stop"}

Чем отличаются потоки Chat Completions и Messages?

Chat CompletionsMessages
АдресPOST /v1/chat/completionsPOST /v1/messages
Формат блокатолько data:event: и data:
Где текстchoices[0].delta.contentdelta.text в событии content_block_delta с типом text_delta
Конец потокастрока data: [DONE]событие message_stop
Расход токеновотдельный блок с usage и пустым choices, только при include_usageв самих событиях, stream_options не нужен
Служебноестроки-комментарии с двоеточия, при сбое событие errorсобытие ping, при сбое событие error

Anthropic уточняет, что токены в поле usage события message_delta накопительные, и что набор событий со временем может расширяться, поэтому незнакомое событие нужно пропускать, а не падать. Это взято со страницы стриминга вендора на 14 октября 2026 года. У Relay есть оговорка: протокол Messages проверен замером на модели claude-sonnet-5, для остальных моделей Claude он проверяется перед выпуском, а моделям других вендоров запросы отправляйте в формате Chat Completions.

Каталог моделей

Как разобрать SSE на TypeScript?

Нужны три вещи: буфер, декодер с флагом stream и поиск границы блока. Флаг stream: true у TextDecoder нужен, потому что многобайтный символ, например русская буква, может разорваться между двумя чанками. Без флага вместо буквы появится знак замены.

Зависимостей у кода нет: это встроенный fetch и аннотации типов, которые стираются без сборки. Он работает на сервере, а ключ остаётся в переменной окружения, не в браузере:

ts
type SseEvent = { event: string; data: string }

function parseBlock(block: string): SseEvent | null {
  let event = 'message'
  const data: string[] = []
  for (const line of block.split(/\r?\n/)) {
    if (line === '' || line.startsWith(':')) continue
    const colon = line.indexOf(':')
    const field = colon === -1 ? line : line.slice(0, colon)
    const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
    if (field === 'event') event = value
    else if (field === 'data') data.push(value)
  }
  return data.length > 0 ? { event, data: data.join('\n') } : null
}

async function* sseEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<SseEvent> {
  const decoder = new TextDecoder()
  let buffer = ''
  for await (const chunk of body) {
    buffer += decoder.decode(chunk, { stream: true })
    let match: RegExpExecArray | null
    while ((match = /\r?\n\r?\n/.exec(buffer)) !== null) {
      const event = parseBlock(buffer.slice(0, match.index))
      buffer = buffer.slice(match.index + match[0].length)
      if (event) yield event
    }
  }
}

async function openStream(path: string, headers: Record<string, string>, payload: object) {
  const response = await fetch(`https://relay-llm.ru${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', ...headers },
    body: JSON.stringify(payload),
  })
  const requestId = response.headers.get('x-request-id')
  if (!response.ok || !response.body) {
    const failure = await response.json().catch(() => ({}))
    throw new Error(`HTTP ${response.status} ${failure?.error?.code} request_id=${requestId}`)
  }
  return { body: response.body, requestId }
}

async function streamChat(prompt: string): Promise<void> {
  const { body, requestId } = await openStream(
    '/v1/chat/completions',
    { Authorization: `Bearer ${process.env.RELAY_API_KEY}` },
    {
      model: 'claude-sonnet-5',
      stream: true,
      stream_options: { include_usage: true },
      messages: [{ role: 'user', content: prompt }],
    },
  )
  let finished = false
  for await (const { event, data } of sseEvents(body)) {
    if (event === 'error') throw new Error(`error в потоке: ${data} request_id=${requestId}`)
    if (data === '[DONE]') {
      finished = true
      break
    }
    const chunk = JSON.parse(data)
    const text = chunk.choices?.[0]?.delta?.content
    if (text) process.stdout.write(text)
    if (chunk.usage) console.error('\nusage:', chunk.usage)
  }
  if (!finished) throw new Error(`поток закончился без data: [DONE], request_id=${requestId}`)
}

streamChat('Привет').catch((error) => {
  console.error(error)
  process.exit(1)
})

Для Messages меняется потребитель. Запрос идёт на /v1/messages с заголовком x-api-key и с max_tokens, который модель может потребовать, а цикл разбирает события по имени. Функция добавляется к тому же файлу и использует те же openStream и sseEvents:

ts
async function streamMessages(prompt: string): Promise<void> {
  const { body, requestId } = await openStream(
    '/v1/messages',
    { 'x-api-key': process.env.RELAY_API_KEY ?? '' },
    {
      model: 'claude-sonnet-5',
      max_tokens: 1024,
      stream: true,
      messages: [{ role: 'user', content: prompt }],
    },
  )
  let finished = false
  for await (const { event, data } of sseEvents(body)) {
    const payload = JSON.parse(data)
    if (event === 'content_block_delta' && payload.delta.type === 'text_delta') {
      process.stdout.write(payload.delta.text)
    } else if (event === 'message_delta') {
      console.error('\nstop_reason:', payload.delta.stop_reason, 'usage:', payload.usage)
    } else if (event === 'message_stop') {
      finished = true
    } else if (event === 'error') {
      throw new Error(`error в потоке: ${data} request_id=${requestId}`)
    }
  }
  if (!finished) throw new Error(`поток закончился без message_stop, request_id=${requestId}`)
}

Как разобрать SSE на Python?

В Python тот же разбор короче, потому что httpx отдаёт готовые строки без символов перевода. Таймаут чтения в примере задан отдельно и с запасом: иначе поток с долгой паузой модели перед первым токеном может оборваться по таймауту клиента.

python
import json
import os

import httpx

URL = "https://relay-llm.ru/v1/chat/completions"
HEADERS = {"Authorization": f"Bearer {os.environ['RELAY_API_KEY']}"}


def sse_events(lines):
    event, data = "message", []
    for line in lines:
        if line == "":
            if data:
                yield event, "\n".join(data)
            event, data = "message", []
        elif line.startswith(":"):
            continue
        else:
            field, _, value = line.partition(":")
            value = value.removeprefix(" ")
            if field == "event":
                event = value
            elif field == "data":
                data.append(value)


def stream_chat(prompt):
    body = {
        "model": "claude-sonnet-5",
        "stream": True,
        "stream_options": {"include_usage": True},
        "messages": [{"role": "user", "content": prompt}],
    }
    timeout = httpx.Timeout(10.0, read=120.0)
    with httpx.stream("POST", URL, headers=HEADERS, json=body, timeout=timeout) as response:
        request_id = response.headers.get("x-request-id")
        if response.status_code != 200:
            response.read()
            error = response.json().get("error", {})
            raise RuntimeError(f"HTTP {response.status_code} {error.get('code')} request_id={request_id}")
        finished = False
        for event, data in sse_events(response.iter_lines()):
            if event == "error":
                raise RuntimeError(f"error в потоке: {data} request_id={request_id}")
            if data == "[DONE]":
                finished = True
                break
            chunk = json.loads(data)
            if chunk["choices"] and chunk["choices"][0]["delta"].get("content"):
                print(chunk["choices"][0]["delta"]["content"], end="", flush=True)
            if chunk.get("usage"):
                print("\nusage:", chunk["usage"])
        if not finished:
            raise RuntimeError(f"поток закончился без data: [DONE], request_id={request_id}")


if __name__ == "__main__":
    stream_chat("Привет")

Свой парсер оправдан в трёх случаях: рантайм без SDK, прокси, который ретранслирует события, и клиент, которому нужны сырые события для логов. Во всех остальных я бы брал SDK. Клиент OpenAI собирает чанки сам, а официальный SDK Anthropic даёт text_stream и итоговое сообщение в одном вызове. Адрес для SDK OpenAI оканчивается на /v1, для SDK Anthropic берут корень без /v1, как описано в документации Messages.

Как проверить парсер без сети?

Парсер SSE ломается на границах, а не на обычных данных, поэтому тесты строят из крайних случаев. Хватит шести: многобайтный символ, разорванный между чанками; разделитель \r\n\r\n вместо \n\n; строка-комментарий посреди потока; блок из нескольких строк data:; событие error; поток, оборванный без завершающей пустой строки. Проверять удобно на готовых строках, без сети. Для версии на Python достаточно подать в sse_events список строк:

python
def test_comment_multiline_data_and_error():
    lines = [": keepalive", "", "event: error", 'data: {"a":', "data: 1}", ""]
    assert list(sse_events(lines)) == [("error", '{"a":\n1}')]


def test_truncated_block_is_dropped():
    assert list(sse_events(["data: one", "", "data: two"])) == [("message", "one")]

Второй тест фиксирует правило стандарта: блок без пустой строки в конце не отправляется получателю. Поэтому после цикла всегда проверяйте [DONE] или message_stop, иначе хвост потеряется молча.

Что делать с ошибкой посреди потока?

Ошибок три вида, и ловятся они в разных местах.

  • До начала потока. Ответ приходит обычным JSON с HTTP-кодом, как у запроса без потока. Проверяйте статус до разбора, как в примерах выше. Коды описаны в справочнике ошибок.

  • После начала потока. Статус 200 уже отправлен, поэтому сбой выглядит как обрыв соединения или как событие error, которое присылает модель. Обработчик должен считать error ошибкой так же, как исключение.

  • Тихий конец. Соединение закрылось штатно, но [DONE] или message_stop не пришли. Это тоже неполный ответ.

Заголовок x-request-id приходит вместе с заголовками ответа, до первого события, поэтому сохраняйте его сразу: при обрыве другого способа получить идентификатор для поддержки у вас не будет. Оборванный поток продолжить нельзя, повтор будет новым запросом со своей стоимостью. Закрытый вами или упавший поток тарифицируется по расходу, который шлюз успел получить, а недостающее он оценивает. Что делать с частичным текстом и как корректно отменять запрос, подробно разобрано в статье про обрыв и отмену потока. Серверную часть на Node.js, которая отдаёт поток браузеру, описывает статья про Node.js и streaming.

Почему текст приходит одним куском?

Если в браузере ответ появляется целиком, а не по частям, проверьте слои между Relay и браузером. Один из них: ваш сервер ретранслирует поток через nginx. По умолчанию nginx буферизует ответ прокси, а отключить это можно заголовком ответа X-Accel-Buffering: no или директивой proxy_buffering off (документация nginx на 14 октября 2026 года). Для диагностики запустите curl -N напрямую к Relay и сравните с тем, что видит браузер: если curl показывает поток по частям, буферизует ваш слой.

Нужен ли stream_options для расхода токенов?

В Chat Completions да: без stream_options: { include_usage: true } шлюз не передаёт блок с usage. Расход при этом учитывается в любом случае, поле решает только, увидите ли вы его в потоке. В Messages расход приходит в самих событиях.

Почему статус 200, а ответа нет?

Статус отправляется до первого токена. Если сбой случился позже, код не изменится: он проявится обрывом соединения или событием error. Поэтому ориентируйтесь на [DONE] и message_stop, а не на статус.

Можно ли продолжить оборванный поток?

Нет. Поток не возобновляется с места обрыва, а повтор запроса будет самостоятельным. Решайте по ситуации: показать полученный текст с пометкой или отправить новый запрос.

Стримят ли модели изображений и видео?

Нет. По каталогу Relay на 14 октября 2026 года потоковый режим отмечен у текстовых моделей, а у моделей изображений и видео нет. Для них запрос синхронный или асинхронный, без SSE.

Источники

Открыть модель в каталоге

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.