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

Streaming: Receber Respostas em Tempo Real

Aula 8 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Streaming: Receber Respostas em Tempo Real
  2. Por Que Usar Streaming
  3. Eventos Tipados, Não um Fluxo Indiferenciado
  4. Streaming e Chamadas de Função
  5. O Caso Assíncrono
  6. Erros a Meio do Fluxo
  7. Pontos-chave

Streaming: Receber Respostas em Tempo Real

O streaming permite receber a resposta token a token, em vez de aguardar o fim de toda a geração. Isto não é apenas um polimento de interface: é o que separa um chatbot que parece lento de um que parece ágil, mesmo quando o desempenho do servidor é idêntico.

Por Que Usar Streaming

Sem streaming, os utilizadores ficam por vezes a olhar para um ecrã em branco durante dez a trinta segundos antes de a resposta completa aparecer de uma só vez. Com streaming, as primeiras palavras surgem em menos de um segundo e a leitura começa enquanto a geração continua. A duração total é a mesma; a perceção, não. Ativar esta funcionalidade requer apenas um parâmetro, stream=True, que transforma o valor de retorno de create() num iterador de eventos.

from openai import OpenAI
client = OpenAI()

# SEM streaming — aguardar tudo
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Write a paragraph about artificial intelligence."
)
print(response.output_text)  # Aparece tudo de uma vez após a espera

# COM streaming — token a token
stream = client.responses.create(
    model="gpt-5.6-terra",
    input="Write a paragraph about artificial intelligence.",
    stream=True
)

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

Eventos Tipados, Não um Fluxo Indiferenciado

O fluxo não transporta apenas texto. Notifica-o quando a resposta é criada, quando cada item de saída é adicionado, quando chegam fragmentos e quando a conclusão ocorre — o evento final inclui métricas de utilização. Filtra por event.type para saber o que está a tratar. Esta estrutura permite-lhe, por exemplo, exibir um indicador de carregamento assim que response.created é acionado e somar os tokens no final sem uma segunda chamada à API.

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

for event in stream:
    match event.type:
        case "response.created":
            print(f"[Response created] ID: {event.response.id}")
        case "response.output_item.added":
            print(f"[New output item]")
        case "response.output_text.delta":
            print(f"[Text] {event.delta}", end="")
        case "response.output_text.done":
            print(f"\n[Text complete]")
        case "response.completed":
            print(f"[Done] Tokens: {event.response.usage.total_tokens}")

# Output:
# [Response created] ID: resp_abc123
# [New output item]
# [Text] Hello[Text] ! [Text] How[Text] can[Text] I...
# [Text complete]
# [Done] Tokens: 25

Numa aplicação real, quererá quase sempre fazer duas coisas em simultâneo: exibir os fragmentos e reconstruir o texto completo para poder arquivá-lo ou devolvê-lo ao chamador. A regra é simples: acumule à medida que itera, pois uma vez consumido o fluxo, este não pode ser rebobinado.

def stream_and_collect(prompt: str) -> str:
    """Transmite a resposta enquanto a recolhe."""
    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
            print(event.delta, end="", flush=True)

    print()  # Nova linha
    return full_text

result = stream_and_collect("List 3 European capitals.")
print(f"\nCollected text ({len(result)} characters)")

Streaming e Chamadas de Função

As chamadas de função também são transmitidas em fluxo, com os seus próprios eventos: os argumentos chegam em fragmentos via response.function_call_arguments.delta, e response.function_call_arguments.done sinaliza que o JSON está completo. Isto tem uma consequência prática importante: nunca tente desserializar os argumentos antes do evento done, caso contrário, terá apenas um JSON truncado.

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="What time is it in Tokyo?",
    tools=[{
        "type": "function",
        "name": "get_time",
        "description": "Get the time in a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }],
    stream=True
)

for event in stream:
    match event.type:
        case "response.output_text.delta":
            print(event.delta, end="")
        case "response.function_call_arguments.delta":
            print(f"[Args] {event.delta}", end="")
        case "response.function_call_arguments.done":
            print(f"\n[Function call complete]")

# Output:
# [Args] {"city": "Tokyo"}
# [Function call complete]

O Caso Assíncrono

Assim que a sua aplicação servir múltiplos utilizadores em simultâneo, mude para AsyncOpenAI: o cliente síncrono bloquearia o ciclo de eventos durante toda a geração, fazendo com que os seus outros pedidos ficassem à espera. A sintaxe difere apenas em duas palavras-chave — await na criação e async for na iteração.

from openai import AsyncOpenAI
import asyncio

async_client = AsyncOpenAI()

async def stream_async(prompt: str):
    """Transmissão assíncrona da resposta."""
    stream = await async_client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        stream=True
    )

    async for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
    print()

asyncio.run(stream_async("Tell a short joke."))

Na web, o streaming é inútil se parar no seu servidor: precisa de o estender até ao navegador. O FastAPI permite isto com StreamingResponse, alimentado por um gerador que retransmite os fragmentos à medida que chegam.

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

app = FastAPI()
client = OpenAI()

@app.get("/chat")
async def chat(question: str):
    def generate():
        stream = client.responses.create(
            model="gpt-5.6-terra",
            input=question,
            stream=True
        )
        for event in stream:
            if event.type == "response.output_text.delta":
                yield event.delta

    return StreamingResponse(generate(), media_type="text/plain")

Erros a Meio do Fluxo

Um detalhe merece a sua atenção: no streaming, um erro pode ocorrer depois de alguns fragmentos já terem sido exibidos. O utilizador vê então uma resposta que começa mas é interrompida. Por isso, envolva a própria iteração, e não apenas a criação do fluxo, para poder sinalizar limpa e claramente a interrupção, em vez de deixar uma frase suspensa.

from openai import APIError

def stream_with_errors(prompt: str):
    """Streaming com tratamento robusto de erros."""
    try:
        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)
        print()

    except APIError as e:
        print(f"\nAPI error during streaming: {e.message}")
    except Exception as e:
        print(f"\nUnexpected error: {e}")

stream_with_errors("Explain streaming in 2 sentences.")

Pontos-chave

  • Ative o streaming com stream=True para uma experiência em tempo real
  • Filtre os eventos por event.type para tratar corretamente cada tipo de dados
  • response.output_text.delta contém fragmentos de texto
  • response.completed sinaliza o fim e inclui métricas de utilização
  • Utilize AsyncOpenAI para streaming em aplicações assíncronas
  • Trate sempre os erros, mesmo no modo de streaming