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

Streaming SSE

Aula 13 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Respostas em tempo real
  2. Ativar o streaming
  3. Tipos de eventos
  4. Streaming em Python
  5. Streaming com ferramentas
  6. Integração no frontend
  7. Streaming e faturação
  8. Pontos-chave

Respostas em tempo real

No modo normal, aguarda que o modelo termine de gerar a resposta completa antes de a receber. Com o streaming SSE (Server-Sent Events), os tokens chegam à medida que são gerados. Isto é essencial para interfaces conversacionais onde os utilizadores desejam ver a resposta a aparecer progressivamente.

SSE
Server-Sent Events
~50ms
Primeiro token visível
text/event-stream
Content-Type
stream: true
Parâmetro único

Ativar o streaming

Adicione "stream": true ao seu pedido:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20-0309-reasoning",
    "input": "Write a poem about programming.",
    "stream": true
  }'

A resposta chega como um fluxo SSE:

data: {"type": "response.created", "response": {...}}
data: {"type": "response.output_item.added", ...}
data: {"type": "response.content_part.added", ...}
data: {"type": "response.output_text.delta", "delta": "La "}
data: {"type": "response.output_text.delta", "delta": "programmation "}
data: {"type": "response.output_text.delta", "delta": "est "}
...
data: {"type": "response.completed", "response": {...}}

Tipos de eventos

EventoDescrição
response.createdInício da geração
response.output_item.addedNovo item na saída
response.content_part.addedNova parte de conteúdo
response.output_text.deltaFragmento de texto (mais frequente)
response.output_text.doneTexto completo de um item
response.completedResposta finalizada com utilização
response.failedErro durante a geração

Streaming em Python

stream = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Explain how a compiler works.",
    stream=True
)

full_text = ""
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
        full_text += event.delta
    elif event.type == "response.completed":
        usage = event.response.usage
        print(f"\n\nTokens: {usage.total_tokens}")
        print(f"Cost: {usage.cost_in_nano_usd / 1e9:.6f} USD")

flush=True força a exibição imediata de cada fragmento.

Streaming com ferramentas

Quando o modelo utiliza ferramentas no modo de streaming, recebe eventos adicionais:

data: {"type": "response.output_item.added", "item": {"type": "web_search_call"}}
data: {"type": "response.web_search_call.in_progress", ...}
data: {"type": "response.web_search_call.completed", ...}
data: {"type": "response.output_text.delta", "delta": "Selon les résultats..."}

Para chamadas de funções do cliente, recebe os argumentos progressivamente:

data: {"type": "response.function_call.arguments.delta", "delta": "{\"city\""}
data: {"type": "response.function_call.arguments.delta", "delta": ": \"Paris\"}"}
data: {"type": "response.function_call.arguments.done", ...}

Integração no frontend

Para uma aplicação web, envie o fluxo SSE para o navegador através de um endpoint do servidor:

const response = await fetch('/api/chat', {
  method: 'POST',
  body: JSON.stringify({ message: userInput })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  outputElement.textContent += text;
}

Streaming e faturação

O streaming não altera a faturação. O custo é idêntico quer esteja ativado ou não; apenas o modo de entrega difere. O objeto usage completo está disponível no evento response.completed.

Pontos-chave

  • stream: true ativa o streaming SSE — os tokens chegam à medida que são gerados
  • O evento response.output_text.delta contém cada fragmento de texto
  • O evento response.completed contém a resposta final com metadados de utilização
  • O streaming funciona com ferramentas (web_search, funções)
  • O custo é idêntico com ou sem streaming