Transmissão SSE
Nesta página
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=Trueativa a transmissão- A resposta é um iterador de objetos
chunk(fragmentos) - Cada chunk contém um
deltacom o novo conteúdo end=""impede quebras de linha entre fragmentosflush=Trueforç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=Truepara 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
-Npara desativar o buffering - Reserve a transmissão para casos em que a apresentação progressiva agrega valor