Streaming SSE
Nesta página
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 uso | Recomendação |
|---|---|
| Chatbot interativo | Streaming (melhor UX) |
| Processamento em lote | Sem streaming (mais simples) |
| API backend para frontend | Streaming (SSE para o navegador) |
| Pipeline de dados | Sem streaming (processamento atómico) |
| Extração estruturada | Sem 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.contentem vez demessage.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