O que o streaming oferece
Sem streaming, a API mantém toda a resposta até que o modelo termine, então a envia como um corpo JSON único. Para uma resposta longa, isso pode significar vários segundos de tela em branco. Com stream: true, o servidor envia a mesma resposta como uma série de pequenos eventos, cada um carregando alguns caracteres da resposta, e sua interface pode imprimi-los conforme chegam.
O formato de rede são eventos enviados pelo servidor (SSE) sobre uma resposta HTTP normal. Cada evento é uma linha começando com data: seguida por um chunk JSON, e o stream termina com data: [DONE]. Raramente você analisa isso manualmente, porque os SDKs da OpenAI fazem isso para você. Se quiser ver os bytes brutos, a visão geral para desenvolvedores mostra o layout do endpoint e a documentação da API lista todos os parâmetros.
Duas coisas valem a decisão antes de escrever código. Primeiro, quem lê o stream: um browser falando com seu servidor, ou apenas seu servidor. Segundo, o que fazer quando a conexão quebra no meio. O resto desta página cobre ambos.
Python: stream com o SDK OpenAI
Instale o SDK com pip install openai, crie um cliente com nossa URL base e passe stream=True. O ID do modelo é 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)
Observe o guard chunk.choices and .... O último chunk que carrega o uso pode ter uma lista choices vazia, e indexá-la geraria um erro. Coletar os pedaços em uma lista e juntá-los no final também é mais barato do que a concatenação repetida de strings em longas respostas.
Node: a mesma chamada em JavaScript
Com o pacote oficial openai para Node, o stream é um iterador assíncrono. Este exemplo usa módulos 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);
Se você não quiser o SDK, fetch também funciona: envie o mesmo corpo JSON com stream: true, depois leia response.body com um TextDecoder e divida por linhas em branco. O SDK evita que você precise lidar com eventos cortados ao meio no limite de um chunk, que é o bug comum em parsers escritos à mão.
Lendo uso e saldo
O uso é relatado no final do stream. Esse é o número para registrar no log para rastreamento de custos, porque é isso contra o qual seu saldo é cobrado. A $0,15 por 1M tokens de entrada e $0,50 por 1M tokens de saída, uma resposta com 1.200 tokens de entrada e 800 tokens de saída custa 1.200 x 0,15 / 1.000.000 + 800 x 0,50 / 1.000.000 = $0,00018 + $0,0004 = $0,00058.
Cada resposta também carrega um cabeçalho X-Balance-USD com seu crédito restante, então você pode mostrar um aviso de saldo baixo sem uma segunda requisição. Você também pode chamar GET /v1/balance em um temporizador. Requisições falhas ou recusadas não são cobradas, o que significa que um erro antes do primeiro token não custa nada.
Os mesmos response headers incluem X-Request-Id. Armazene-o junto com sua própria linha de log para cada stream. Se um stream se comportar estranhamente, esse ID é o que você dá ao suporte para que a requisição possa ser encontrada.
Streams caídos e o que fazer sobre eles
Streams quebram. Um telefone muda de Wi-Fi para dados móveis, um proxy fecha uma conexão ociosa, um usuário fecha a aba. Planeje isso desde o início.
Mantenha o texto parcial
Anexe cada peça a um buffer conforme chega e salve o buffer quando o loop terminar ou lançar. Se o stream falhou, você tem uma meia-resposta utilizável. Mostre-a com um botão de nova tentativa em vez de descartá-la.
Nova tentativa ou continue
A recuperação mais simples é reenviar a requisição original. Para uma resposta curta, isso é bom. Para uma longa, você pode enviar o texto parcial salvo como uma mensagem de assistente e pedir ao modelo para continuar de onde parou. O resultado pode não corresponder ao que o primeiro stream teria produzido, então trate como um melhor esforço e rotule na sua interface se exatidão importar.
Feche o que abandonar
Uma requisição em streaming ocupa seu slot de concorrência até que o stream termine. Uma chave completa permite 8 requisições ao mesmo tempo, e uma chave de teste apenas 2. Se seu servidor continua lendo um stream para um usuário que já foi embora, aquele slot permanece ocupado. Cancele a requisição quando o cliente desconectar. Em Python, chame stream.close(); em Node, chame stream.controller.abort().
Repassando um stream para um browser
Nunca coloque sua chave de API no código do navegador. A configuração usual é um pequeno endpoint em seu próprio servidor que chama a API com stream: true e encaminha cada peça para a página. Em Node com Express, defina Content-Type: text/event-stream, escreva cada peça como data: ... seguido de uma linha em branco, e escute o evento close no request para abortar a chamada upstream. Na página, EventSource lida com endpoints GET, enquanto fetch com um reader lida com bodies POST, que é o que você precisa quando envia um histórico de mensagens.
Mantenha o histórico de mensagens no seu servidor ou no corpo da requisição, e corte as voltas mais antigas quando a conversa ficar longa. A janela de contexto é de 100.000 tokens para prompt mais conclusão, o que é muito chat, mas uma sessão de longa duração eventualmente atingirá esse limite.
Limites de requisições durante streaming
Os limites são 300 requisições por minuto e 8 requisições simultâneas em uma chave completa, e 60 por minuto e 2 simultâneas em uma chave de teste. Ir além retorna HTTP 429. O código de erro diz qual limite você atingiu: rate_limited significa muitas requisições por minuto, e concurrency significa muitas ao mesmo tempo. Em sobrecarga temporária, a API também retorna 429 com um cabeçalho Retry-After: 5.
Como um 429 chega antes de qualquer token ser transmitido, lide com ele antes de começar a ler. Um pequeno wrapper de retry é suficiente:
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")
Para aplicativos de chat com muitos usuários, a solução real para erros de concurrency é uma pequena fila do seu lado que permite no máximo 8 streams ao vivo ao mesmo tempo.
Checklist antes de lançar um chat com streaming
- Proteja-se contra
choicesvazio no último chunk. - Buffer texto parcial e persista em erro.
- Aborte a requisição upstream quando o browser desconectar.
- Limite streams ao vivo no seu limite de concurrency.
- Registre uso e o ID da requisição por stream.
- Desative o buffer de resposta em qualquer reverse proxy na frente do seu servidor, ou tokens chegarão em rajadas.
O último ponto confunde muitos primeiros deployments. O Nginx, por exemplo, faz buffer de respostas proxyadas por padrão, então o stream funciona no localhost e parece congelado na produção até que o buffer seja desativado para essa rota. Para saída JSON em vez de texto livre, veja as notas sobre modo JSON. Para testar o código acima, crie uma chave de API; novas contas podem reivindicar $0,50 de crédito de teste com um clique, válido por 7 dias. Recargas são apenas cripto (USDT em TRC20 ou USDC em Base), a partir de $20.
