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

Streaming SSE

Aula 5 de 16 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Respostas em tempo real com Server-Sent Events
  2. Streaming vs. sem streaming
  3. O protocolo SSE em detalhe
  4. Ativar o streaming em Python
  5. Estrutura de um chunk
  6. Reconstruir a resposta completa
  7. Quando utilizar o streaming
  8. Pontos-chave

Respostas em tempo real com Server-Sent Events

Por predefinição, a API de Completions de Chat aguarda que o modelo termine de gerar toda a sua resposta antes de a enviar. Para uma pergunta curta, ninguém nota o atraso. No entanto, para um relatório de mil palavras, isso significa vários segundos de ecrã em branco, deixando o utilizador a questionar-se se a aplicação travou. O streaming resolve este problema ao enviar tokens à medida que são gerados, criando o familiar efeito de máquina de escrever visto em interfaces conversacionais.

O protocolo utilizado é o Server-Sent Events (SSE), um padrão HTTP que permite ao servidor enviar dados continuamente para o cliente através de uma ligação persistente. Não há nada de exótico aqui: não é necessário instalar WebSockets nem dependências extra.

Streaming vs. sem streaming

No modo sem streaming, que é o predefinido, o cliente envia o pedido e aguarda a resposta completa:

Client ──── request ────► Server
         (wait 3-10s)
Client ◄── complete response ── Server

A vantagem é a simplicidade: a resposta é atómica, um único objeto JSON fácil de processar, validar e armazenar. A desvantagem é igualmente clara: a latência percecionada é elevada, pois o utilizador não vê nada durante todo o processo de geração.

No modo de streaming, o servidor envia tokens um a um, ou em pequenos grupos:

Client ──── request ────► Server
Client ◄── chunk 1 ─────── Server  (after ~200ms)
Client ◄── chunk 2 ─────── Server  (after ~250ms)
Client ◄── chunk 3 ─────── Server  (after ~300ms)
...
Client ◄── [DONE] ──────── Server

A latência percecionada diminui drasticamente — o primeiro caractere aparece em algumas centenas de milissegundos — melhorando significativamente a experiência do utilizador. Em contrapartida, terá de reconstruir a mensagem no lado do cliente e gerir um estado que já não chega num único bloco.

O protocolo SSE em detalhe

Eis o aspeto real do fluxo HTTP que recebe:

data: {"id":"cmpl-abc","choices":[{"delta":{"content":"Hello"}}],"usage":null}

data: {"id":"cmpl-abc","choices":[{"delta":{"content":" "}}],"usage":null}

data: {"id":"cmpl-abc","choices":[{"delta":{"content":"!"}}],"usage":null}

data: [DONE]

Cada linha começa por data: seguido de um objeto JSON, e as linhas em branco servem de separadores entre eventos. Note o detalhe que apanha toda a gente na primeira implementação: o fragmento de texto encontra-se no campo delta, e não em message como no modo clássico. O fluxo termina com um evento data: [DONE], que sinaliza explicitamente o fim. Sem ele, não conseguiria distinguir uma geração terminada de uma ligação interrompida.

Ativar o streaming em Python

Com o SDK da Mistral, ativa o streaming chamando chat.stream() em vez de chat.complete():

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

stream = client.chat.stream(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "Explain how an electric motor works."}
    ]
)

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

print()  # Final newline

O argumento flush=True merece uma explicação, pois esquecê-lo é a causa clássica de um streaming que “não funciona”. Sem ele, o Python mantém os caracteres no buffer e exibe-os em blocos. Isto cancela visualmente todos os benefícios do streaming, mesmo que os chunks estejam a chegar corretamente.

Estrutura de um chunk

Um chunk de streaming não se lê como uma resposta completa, e os caminhos de acesso diferem:

# Non-streaming: response.choices[0].message.content
# Streaming:     chunk.data.choices[0].delta.content

# The first chunk often contains the role
# chunk.data.choices[0].delta.role == "assistant"

# Subsequent chunks contain text fragments
# chunk.data.choices[0].delta.content == "Hello"

# The last chunk contains finish_reason
# chunk.data.choices[0].finish_reason == "stop"

O primeiro chunk transporta geralmente a função (role) sem texto, os seguintes transportam os fragmentos e o último fornece o finish_reason. É por isso que a verificação if content: no código anterior não é uma precaução desnecessária: concatenar um valor None faria o loop falhar na primeira iteração.

Reconstruir a resposta completa

Exibir fragmentos não é suficiente quando precisa de manter a resposta — por exemplo, para a adicionar ao histórico da conversa, registá-la ou armazená-la numa base de dados. Deve, portanto, acumular o texto em paralelo com a sua exibição:

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

stream = client.chat.stream(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "List 5 programming languages."}]
)

full_response = ""
finish_reason = None

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

    if chunk.data.choices[0].finish_reason:
        finish_reason = chunk.data.choices[0].finish_reason

print(f"\n\nFinish reason: {finish_reason}")
print(f"Complete response ({len(full_response)} characters)")

A variável finish_reason é capturada no mesmo loop pela mesma razão que no modo clássico: uma resposta truncada por max_tokens aparece no ecrã exatamente como uma resposta completa, e apenas este campo lhe indicará a diferença.

Quando utilizar o streaming

O streaming nem sempre é melhor. É indicado sempre que um humano está a observar o ecrã, mas é supérfluo ou mesmo prejudicial quando uma máquina processa a saída.

Caso de usoRecomendação
Chatbot interativoStreaming (melhor UX)
Processamento em loteSem streaming (mais simples)
API backend para frontendStreaming (SSE para o navegador)
Pipeline de dadosSem streaming (processamento atómico)
Extração estruturadaSem streaming (parsing JSON mais fiável)

O último caso é o mais instrutivo. Se espera JSON, o streaming não acrescenta nada: não pode analisar um objeto incompleto e terá de aguardar o último fragmento na mesma. Mais vale manter a chamada atómica e o código simples.

Pontos-chave

  • O streaming reduz a latência percecionada ao enviar tokens à medida que são gerados
  • O protocolo SSE é um padrão HTTP simples e robusto
  • No modo de streaming, utilize delta.content em vez de message.content
  • Acumule os fragmentos no lado do cliente para reconstruir a resposta completa
  • Prefira o streaming para interfaces de utilizador e o modo sem streaming para processamento automatizado