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

Transmissão SSE

Aula 10 de 14 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Receba respostas em tempo real
  2. Como funciona a transmissão
  3. Transmissão em Python com o SDK da OpenAI
  4. Transmissão com o endpoint /v1/responses
  5. Transmissão com cURL
  6. Quando utilizar a transmissão
  7. Tratamento de erros na transmissão
  8. Pontos-chave

Receba respostas em tempo real

Por predefinição, a API aguarda que a resposta completa seja gerada antes de a devolver. Com a transmissão (streaming), recebe os tokens à medida que são gerados. Esta técnica reduz o tempo de espera percecionado pelo utilizador e permite apresentar as respostas progressivamente, tal como a interface do Grok faz.

Como funciona a transmissão

A transmissão utiliza o protocolo Server-Sent Events (SSE). Em vez de uma única resposta HTTP, o servidor envia um fluxo contínuo de eventos. Cada evento contém um fragmento da resposta e o cliente monta-os para reconstruir o texto completo.

O parâmetro stream: true ativa este modo para qualquer endpoint de geração.

Transmissão em Python com o SDK da OpenAI

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

stream = client.chat.completions.create(
    model="grok-4.5",
    messages=[
        {"role": "user", "content": "Explain the SOLID principles in programming."}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

print()  # Final line break

Como funciona o código

  • stream=True ativa a transmissão
  • A resposta é um iterador de objetos chunk (fragmentos)
  • Cada chunk contém um delta com o novo conteúdo
  • end="" impede quebras de linha entre fragmentos
  • flush=True força a apresentação imediata

Transmissão com o endpoint /v1/responses

stream = client.responses.create(
    model="grok-4.5",
    input="Describe the steps to deploy a web application.",
    stream=True
)

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

print()

O endpoint /v1/responses utiliza eventos tipados. O tipo response.output_text.delta contém os fragmentos de texto.

Transmissão com cURL

O cURL suporta nativamente a transmissão SSE. Adicione "stream": true ao corpo do pedido:

curl -N https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

A opção -N desativa o buffering do cURL para que os eventos sejam apresentados assim que chegarem.

Cada linha do fluxo SSE começa com data: seguido de um objeto JSON. O último evento é data: [DONE], que sinaliza o fim da geração.

Quando utilizar a transmissão

A decisão resume-se a uma questão: há alguém a observar a resposta a chegar? Se sim (um chatbot, um assistente, uma ferramenta de escrita), a transmissão é quase obrigatória: os utilizadores veem o texto a aparecer palavra por palavra em vez de ficarem perante um ecrã congelado e, numa resposta longa, a diferença entre «primeira palavra em 300 ms» e «todo o texto após 8 segundos» transforma toda a experiência percecionada.

Se ninguém estiver a observar, a transmissão não acrescenta nada e apenas complica o código. Um trabalho em lote que preenche uma base de dados, um pipeline automatizado que tem de analisar a resposta completa antes de agir, ou uma chamada que devolve apenas algumas palavras: em todos estes casos, a chamada clássica (um pedido, uma resposta completa) continua a ser mais simples de escrever, testar e depurar.

Tratamento de erros na transmissão

No modo de transmissão, os erros podem ocorrer a meio do fluxo. O seu código tem de lidar com essas interrupções:

try:
    stream = client.chat.completions.create(
        model="grok-4.5",
        messages=[{"role": "user", "content": "Test"}],
        stream=True
    )
    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="")
except Exception as e:
    print(f"\nError during streaming: {e}")

Pontos-chave

  • Adicione stream=True para receber tokens à medida que são gerados
  • O protocolo utilizado é o SSE (Server-Sent Events)
  • Em Python, itere sobre os chunks e imprima delta.content
  • Com cURL, utilize -N para desativar o buffering
  • Reserve a transmissão para casos em que a apresentação progressiva agrega valor