Что даёт потоковая передача
Без потоковой передачи API удерживает весь ответ, пока модель не завершит работу, а затем отправляет его одним JSON-объектом. Для длинного ответа это может означать много секунд пустого экрана. С stream: true сервер отправляет тот же ответ серией небольших событий, каждое из которых содержит несколько символов ответа, и ваш интерфейс может выводить их по мере поступления.
Формат передачи — события, отправляемые сервером (SSE) через обычный HTTP-ответ. Каждое событие — это строка, начинающаяся с data:, за которой следует фрагмент JSON, а поток заканчивается с data: [DONE]. Вы редко разбираете это вручную, потому что SDK OpenAI делают это за вас. Если вы хотите увидеть сырые байты, Обзор для разработчиков показывает структуру эндпоинта, а документация API перечисляет каждый параметр.
Есть две вещи, которые стоит решить перед написанием кода. Во-первых, кто читает поток: браузер, общающийся с вашим сервером, или только ваш сервер. Во-вторых, что делать, если соединение прерывается на полпути. Остальная часть этой страницы охватывает оба случая.
Python: потоковая передача с SDK OpenAI
Установите SDK с помощью pip install openai, создайте клиент с нашим базовым URL и передайте stream=True. Идентификатор модели — uncensored.
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredllmapi.com/v1",
api_key="YOUR_KEY",
)
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a four-line poem about rain."}],
stream=True,
)
text = []
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
piece = chunk.choices[0].delta.content
text.append(piece)
print(piece, end="", flush=True)
if getattr(chunk, "usage", None):
usage = chunk.usage
print()
print("tokens:", usage)
Обратите внимание на проверку chunk.choices and .... Последний фрагмент, содержащий использование, может иметь пустой список choices, и обращение к нему вызовет ошибку. Сбор фрагментов в список и объединение в конце также дешевле, чем повторное конкатенирование строк при длинных ответах.
Node: тот же вызов на JavaScript
С официальным пакетом openai для Node поток является асинхронным итератором. Этот пример использует ES-модули.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredllmapi.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three uses for a stream." }],
stream: true,
});
let full = "";
let usage = null;
for await (const chunk of stream) {
const piece = chunk.choices?.[0]?.delta?.content;
if (piece) {
full += piece;
process.stdout.write(piece);
}
if (chunk.usage) usage = chunk.usage;
}
console.log("\nusage:", usage);
Если вы не хотите использовать SDK, подходит и fetch: отправьте то же JSON-тело с stream: true, затем прочитайте response.body с помощью TextDecoder и разбейте по пустым строкам. SDK избавляет вас от необходимости обрабатывать события, разорванные на границе чанка, что является распространённой ошибкой в парсерах, написанных вручную.
Чтение использования и баланса
Данные об использовании сообщаются в конце потока. Это число, которое нужно логировать для отслеживания затрат, потому что именно оно списывается с вашего баланса. По цене $0,15 за 1 млн входных токенов и $0,50 за 1 млн выходных токенов, ответ с 1 200 входными токенами и 800 выходными токенами обойдётся в 1 200 x 0,15 / 1 000 000 + 800 x 0,50 / 1 000 000 = $0,00018 + $0,0004 = $0,00058.
Каждый ответ также содержит заголовок X-Balance-USD с вашим оставшимся балансом, поэтому вы можете показать предупреждение о низком балансе без второго запроса. Вы также можете вызывать GET /v1/balance по таймеру. Неудачные или отклонённые запросы не оплачиваются, что означает, что ошибка до первого токена ничего не стоит.
Те же заголовки ответа включают X-Request-Id. Сохраняйте его рядом со своей строкой журнала для каждого потока. Если поток ведёт себя странно, этот ID — то, что вы дадите поддержке, чтобы запрос можно было найти.
Обрывы потоков и что с ними делать
Потоки обрываются. Телефон переключается с Wi-Fi на мобильные данные, прокси закрывает неактивное соединение, пользователь закрывает вкладку. Планируйте это с самого начала.
Сохраняйте частичный текст
Добавляйте каждый кусок в буфер по мере поступления и сохраняйте его при завершении или ошибке цикла. Если поток прервался, у вас останется частичный ответ. Покажите его с кнопкой повтора, а не отбрасывайте.
Повторная попытка или продолжение
Самый простой способ восстановления — повторная отправка исходного запроса. Для короткого ответа это нормально. Для длинного вы можете отправить сохранённый частичный текст в качестве сообщения ассистента и попросить модель продолжить с того места, где она остановилась. Результат может не совпасть с тем, что выдал бы первый поток, поэтому воспринимайте его как приблизительный результат и пометьте в интерфейсе, если важна точность.
Закрывайте то, чем перестали пользоваться
Запрос потоковой передачи занимает свой слот параллельных запросов до завершения потока. Полный ключ позволяет 8 запросов одновременно, а пробный ключ — только 2. Если ваш сервер продолжает читать поток для пользователя, который ушёл, этот слот остаётся занятым. Отмените запрос, когда клиент отключится. В Python вызовите stream.close(); в Node вызовите stream.controller.abort().
Передача потока в браузер
Никогда не помещайте свой API-ключ в код браузера. Обычная настройка — небольшой эндпоинт на вашем собственном сервере, который вызывает API с stream: true и перенаправляет каждый фрагмент на страницу. В Node с Express установите Content-Type: text/event-stream, запишите каждый фрагмент как data: ..., за которым следует пустая строка, и слушайте событие close на запросе, чтобы отменить вызов на стороне API. На странице EventSource обрабатывает GET-эндпоинты, тогда как fetch с ридером (reader) обрабатывает тела POST, что вам нужно, когда вы отправляете историю сообщений.
Храните историю сообщений на своём сервере или в теле запроса и удаляйте самые старые реплики, когда диалог становится длинным. Контекстное окно составляет 100 000 токенов для промпта плюс генерации, что позволяет вести много диалогов, но в длительной сессии вы в итоге достигнете этого предела.
Лимиты запросов при потоковой передаче
Лимиты составляют 300 запросов в минуту и 8 параллельных запросов для полного ключа, и 60 в минуту и 2 параллельных для пробного ключа. Превышение возвращает HTTP 429. Код ошибки сообщает вам, какой лимит вы достигли: rate_limited означает слишком много запросов в минуту, а concurrency означает слишком много одновременно. При временной перегрузке API также возвращает 429 с заголовком Retry-After: 5.
Поскольку 429 поступает до того, как будут переданы какие-либо токены, обрабатывайте его перед началом чтения. Достаточно небольшой обёртки для повторных попыток:
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.uncensoredllmapi.com/v1", api_key="YOUR_KEY")
def open_stream(messages, tries=4):
for n in range(tries):
try:
return client.chat.completions.create(
model="uncensored", messages=messages, stream=True
)
except RateLimitError as e:
wait = 5 if n == 0 else 5 * (n + 1)
time.sleep(wait)
raise RuntimeError("still rate limited")
Для чат-приложений со многими пользователями настоящим решением для ошибок concurrency является небольшая очередь на вашей стороне, которая позволяет не более 8 активных потоков одновременно.
Чек-лист перед выпуском потокового чата
- Защититесь от пустых
choicesв последнем фрагменте. - Буферизуйте частичный текст и сохраняйте его при ошибке.
- Отменяйте вызов на стороне API, когда браузер отключается.
- Ограничьте живые потоки вашим лимитом параллельных запросов.
- Регистрируйте использование и идентификатор запроса для каждого потока.
- Отключите буферизацию ответа на любом обратном прокси перед вашим сервером, иначе токены будут приходить пакетами.
Последний пункт часто сбивает с толку многие первые развертывания. Nginx, например, по умолчанию буферизует проксируемые ответы, поэтому поток работает на localhost и выглядит замороженным в продакшене, пока буферизация не будет отключена для этого маршрута. Для вывода JSON вместо свободного текста см. заметки о JSON-режиме. Чтобы попробовать приведенный выше код, создайте API-ключ; новые аккаунты могут получить $0,50 пробного баланса в один клик, действительный в течение 7 дней. Пополнение только криптовалютой (USDT на TRC20 или USDC на Base), от $20.
