Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Streaming otimizado

Aula 5 de 20 Atualizada a 28 de julho de 2026 Avancado
Nesta página
  1. O que o streaming realmente altera
  2. Consumir o stream no lado do cliente
  3. Retransmitir o stream para o navegador
  4. Manter a ligação ao longo do tempo
  5. Pontos-chave

O que o streaming realmente altera

O streaming não torna o modelo mais rápido: torna a espera suportável. Para uma resposta que demora cinco segundos a ser gerada, um utilizador sem streaming encara um ecrã em branco durante cinco segundos antes de receber um bloco de texto. Com streaming, vê as primeiras palavras após algumas centenas de milissegundos e lê à medida que o modelo escreve. A duração total é idêntica, mas a perceção é completamente diferente. É por isso que, em produção, omitir o streaming é quase sempre uma falha de conceção e não uma escolha consciente.

No entanto, o fluxo deve percorrer toda a sua cadeia. Um stream gerado corretamente pela API, mas acumulado pelo seu servidor de aplicação ou colocado em buffer pelo seu proxy reverso, chega ao utilizador num único bloco: pagou o preço da complexidade do streaming sem colher os benefícios. Esta lição segue, portanto, o percurso completo, desde a chamada à API até ao navegador.

Consumir o stream no lado do cliente

Com a API de Respostas, definir stream=True transforma a resposta numa sequência de eventos tipados que itera à medida que chegam. Cada fragmento de texto chega num evento response.output_text.delta; o fim do stream é sinalizado por response.completed, que transporta o objeto de resposta completo, útil para recuperar a utilização de tokens.

import openai

client = openai.OpenAI()

def generate_streaming(prompt: str):
    """Geração em streaming com a API de Respostas."""
    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        stream=True,
    )

    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "response.completed":
            print()  # Nova linha no final
            return event.response

A flag flush=True não é cosmética: sem ela, o Python faz buffer da saída por si próprio, e acaba com o comportamento em bloco que tentava evitar. Este detalhe repete-se em todas as camadas da cadeia e constitui a principal dificuldade do streaming.

O mecanismo abrange também chamadas de funções. Os argumentos das ferramentas são construídos progressivamente, e pode exibi-los à medida que são gerados para sinalizar ao utilizador que uma pesquisa está a ser formulada, em vez de o deixar a encarar uma interface congelada enquanto o modelo prepara a sua chamada.

tools = [
    {
        "type": "function",
        "name": "search_product",
        "description": "Searches for a product in the catalog.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "category": {"type": "string"},
            },
            "required": ["query"],
        },
    }
]

def streaming_with_tools(prompt: str):
    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        tools=tools,
        stream=True,
    )

    for event in stream:
        match event.type:
            case "response.output_text.delta":
                print(event.delta, end="", flush=True)
            case "response.function_call_arguments.delta":
                # Argumentos da função a serem gerados atualmente
                print(f"[arg: {event.delta}]", end="")
            case "response.function_call_arguments.done":
                print(f"\n[Chamada de função concluída]")

Retransmitir o stream para o navegador

O seu frontend não fala diretamente com a API da OpenAI; fala com o seu servidor, que deve, portanto, retransmitir o stream. Os Server-Sent Events (SSE) são o formato natural para isto: uma resposta HTTP que permanece aberta, onde cada linha data: transporta um fragmento JSON. O exemplo seguinte retransmite o texto à medida que chega e, em seguida, emite uma mensagem final contendo a contagem de tokens, permitindo faturar ou registar logs sem uma segunda chamada.

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import openai
import json

app = FastAPI()
client = openai.OpenAI()

@app.post("/api/chat")
async def chat_streaming(request: dict):
    prompt = request["message"]

    async def generate():
        stream = client.responses.create(
            model="gpt-5.6-terra",
            input=prompt,
            stream=True,
        )

        for event in stream:
            if event.type == "response.output_text.delta":
                data = json.dumps({"text": event.delta})
                yield f"data: {data}\n\n"
            elif event.type == "response.completed":
                usage = event.response.usage
                data = json.dumps({
                    "end": True,
                    "input_tokens": usage.input_tokens,
                    "output_tokens": usage.output_tokens,
                })
                yield f"data: {data}\n\n"

    return StreamingResponse(
        generate(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "X-Accel-Buffering": "no",  # Importante para nginx
        },
    )

Depois, há o proxy reverso, o suspeito habitual quando «o streaming não funciona em produção, embora funcionasse localmente». Por predefinição, o nginx acumula a resposta do backend antes de a transmitir. A configuração abaixo desativa este comportamento apenas para a rota específica.

location /api/chat {
    proxy_pass http://127.0.0.1:8000;
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header Connection "";
    chunked_transfer_encoding on;
}

Manter a ligação ao longo do tempo

Um stream aberto durante várias dezenas de segundos está mais exposto do que uma chamada curta: uma queda de rede, um limite de quota atingido, e a geração para a meio de uma frase. A sua estratégia de repetição deve distinguir entre estes dois casos, pois exigem abordagens diferentes. Um erro de ligação deve ser repetido com backoff exponencial, dando tempo à rede para recuperar sem sobrecarregar a API; um excedente de quota deve ser repetido após uma espera fixa, uma vez que a janela do limite de taxa repõe em intervalos regulares.

import openai

def resilient_streaming(prompt: str, max_attempts: int = 3):
    """Streaming com tratamento de erros e repetição."""
    for attempt in range(max_attempts):
        try:
            stream = client.responses.create(
                model="gpt-5.6-terra",
                input=prompt,
                stream=True,
            )

            full_text = ""
            for event in stream:
                if event.type == "response.output_text.delta":
                    full_text += event.delta
                    yield event.delta

            return  # Sucesso, sair

        except openai.APIConnectionError:
            if attempt < max_attempts - 1:
                import time
                time.sleep(2 ** attempt)  # Backoff exponencial
            else:
                raise
        except openai.RateLimitError:
            import time
            time.sleep(5)  # Espera fixa para limite de taxa

Um último ajuste melhora o conforto de leitura. Emitir cada token produz um texto aos solavancos, especialmente se a sua interface aplicar uma animação ou se o resultado for para síntese de voz. Acumular até ao final de uma frase confere um ritmo mais próximo da leitura humana, ao custo de um ligeiro atraso adicional no primeiro fragmento.

def streaming_by_sentence(prompt: str):
    """Acumula e produz por frase completa."""
    buffer = ""

    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        stream=True,
    )

    for event in stream:
        if event.type == "response.output_text.delta":
            buffer += event.delta
            # Procurar fim de frase
            for separator in [".\n", "!\n", "?\n", ". ", "! ", "? "]:
                if separator in buffer:
                    parts = buffer.split(separator, 1)
                    yield parts[0] + separator.rstrip()
                    buffer = parts[1] if len(parts) > 1 else ""

    if buffer.strip():
        yield buffer.strip()

Note o if buffer.strip() final: sem ele, uma resposta que não termine com pontuação forte perderia as suas últimas palavras. Este tipo de descuido passa despercebido nos testes e manifesta-se em produção em respostas truncadas por max_output_tokens.

Pontos-chave

  • Utilize sempre streaming em produção para reduzir a latência percecionada
  • Configure o nginx com proxy_buffering off para SSE
  • Trate erros com repetição e backoff exponencial
  • Acumule por frase para uma exibição mais natural