PT ▾
Obter chave de API
API sem censura compatível com OpenAI para desenvolvedores.Atualizado

Streaming da API compatível com OpenAI em Python e Node

O streaming da API compatível com OpenAI funciona da mesma forma aqui quanto contra a OpenAI: defina stream: true, aponte o SDK para nossa base URL e leia server-sent events conforme chegam. Esta página tem código Python e Node funcional, além do que fazer quando um stream cai.

Blocos brilhantes fluindo um por um de um servidor para um laptop, ilustrando streaming de tokens

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 choices vazio 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.

Perguntas e respostas

Preciso de um SDK especial para stream?

Não. Os pacotes padrão do Python e do Node da OpenAI funcionam. Altere a URL base, a chave e o nome do modelo para uncensored, depois passe stream: true.

Posso fazer streaming de tool calls e do modo JSON?

Sim para tool calls: elas são enviadas como deltas de tool_calls, e você une as partes antes de analisar os argumentos. Teste qualquer stream no modo JSON da mesma forma, analisando apenas após o último chunk.

Sou cobrado por um stream que cancelo?

Requisições com falha ou recusadas não são cobradas. Para um stream que você cancela no meio, verifique os valores de usage e X-Balance-USD nos seus próprios logs para ver o que foi cobrado.

Por que meu stream chega de uma vez só?

Um proxy ou CDN na frente do seu aplicativo provavelmente está fazendo buffer da resposta. Desative o buffer para a rota de streaming e verifique novamente.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.