Стриминг ответов 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, который отключает буферизацию вывода:
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]. Значения в примере условные:
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:
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 Completions | Messages | |
|---|---|---|
| Адрес | POST /v1/chat/completions | POST /v1/messages |
| Формат блока | только data: | event: и data: |
| Где текст | choices[0].delta.content | delta.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 и аннотации типов, которые стираются без сборки. Он работает на сервере, а ключ остаётся в переменной окружения, не в браузере:
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:
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 отдаёт готовые строки без символов перевода. Таймаут чтения в примере задан отдельно и с запасом: иначе поток с долгой паузой модели перед первым токеном может оборваться по таймауту клиента.
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 список строк:
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.
Источники
Streaming messages, документация Anthropic, проверено 14 октября 2026 года.
Server-sent events, стандарт HTML, проверено 14 октября 2026 года.
Модуль ngx_http_proxy_module, документация nginx, проверено 14 октября 2026 года.