Implementar streaming em Python
Nesta página
Do protótipo à produção
A lição anterior cobriu os conceitos de streaming SSE. A parte mais difícil permanece: transformar um loop de demonstração num cliente que resista à carga, sobreviva a erros de rede e alimente uma interface web. Esta lição segue a trajetória real de um projeto: primeiro o esqueleto, depois o tratamento de erros, em seguida o assincronismo, a exposição HTTP e, finalmente, a medição.
O padrão básico
Tudo começa com este esqueleto de dez linhas, que irá adaptar para cada projeto. Faz duas coisas em simultâneo: exibe os tokens à medida que chegam e acumula-os para o retorno da função.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
def stream_chat(messages: list, model: str = "mistral-large-latest") -> str:
"""Envia um pedido de streaming e exibe tokens em tempo real."""
stream = client.chat.stream(
model=model,
messages=messages
)
full_text = ""
for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
full_text += content
print(content, end="", flush=True)
print() # Nova linha
return full_text
Esta versão funciona para um script local. Tem uma falha fatal em produção: imprime no terminal, pelo que não pode fazer nada além de trabalho de terminal.
Tratamento abrangente de erros
Erros de rede, tempos limite e limites de taxa não são hipotéticos: são certezas à escala de tráfego real. O cliente abaixo resolve ambos os problemas. Reenvia automaticamente erros 429 com espera exponencial (backoff) e já não imprime nada: emite eventos tipados via yield, deixando ao chamador a decisão do que fazer com eles — exibi-los, enviá-los para um WebSocket ou gravá-los numa base de dados.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import os
import time
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
def stream_with_retry(
messages: list,
model: str = "mistral-large-latest",
max_retries: int = 3,
max_tokens: int = 2000
) -> dict:
"""Streaming com reenvio automático e métricas."""
for attempt in range(max_retries):
try:
stream = client.chat.stream(
model=model,
messages=messages,
max_tokens=max_tokens
)
full_text = ""
finish_reason = None
chunk_count = 0
for chunk in stream:
delta = chunk.data.choices[0].delta
if delta.content:
full_text += delta.content
chunk_count += 1
yield {"type": "token", "content": delta.content}
if chunk.data.choices[0].finish_reason:
finish_reason = chunk.data.choices[0].finish_reason
yield {
"type": "done",
"full_text": full_text,
"finish_reason": finish_reason,
"chunks": chunk_count
}
return
except SDKError as e:
if e.status_code == 429 and attempt < max_retries - 1:
wait_time = 2 ** attempt # Espera exponencial
yield {"type": "retry", "wait": wait_time, "attempt": attempt + 1}
time.sleep(wait_time)
else:
yield {"type": "error", "message": str(e), "status": e.status_code}
return
except Exception as e:
yield {"type": "error", "message": str(e), "status": None}
return
A espera exponencial 2 ** attempt aguarda 1 segundo, depois 2, depois 4. Esta progressão não é decorativa: se todos os seus clientes reenviassem pedidos ao mesmo ritmo fixo, atingiriam a API em rajadas sincronizadas e prolongariam exatamente a saturação de que sofrem. Note também que apenas o erro 429 desencadeia um reenvio; reenviar um 401 devido a uma chave inválida apenas atrasaria o diagnóstico.
Do lado do chamador, o consumo torna-se uma simples leitura de eventos:
messages = [
{"role": "system", "content": "You are a technical assistant."},
{"role": "user", "content": "Explain design patterns in Python."}
]
for event in stream_with_retry(messages):
if event["type"] == "token":
print(event["content"], end="", flush=True)
elif event["type"] == "retry":
print(f"\n[Reenvio {event['attempt']}, a aguardar {event['wait']}s...]")
elif event["type"] == "done":
print(f"\n\n--- Concluído ({event['chunks']} fragmentos, {event['finish_reason']})")
elif event["type"] == "error":
print(f"\n[Erro: {event['message']}]")
Streaming assíncrono com asyncio
O cliente síncrono bloqueia o seu thread durante toda a geração. Num servidor web que deve lidar com cinquenta conversas simultâneas, isso significa imobilizar cinquenta threads apenas para esperar. O cliente assíncrono levanta esta restrição:
from mistralai.client import Mistral
import asyncio
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
async def async_stream_chat(messages: list) -> str:
"""Streaming assíncrono para aplicações concorrentes."""
stream = await client.chat.stream_async(
model="mistral-large-latest",
messages=messages
)
full_text = ""
async for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
full_text += content
print(content, end="", flush=True)
print()
return full_text
# Execução
async def main():
messages = [{"role": "user", "content": "Hello, introduce yourself."}]
result = await async_stream_chat(messages)
print(f"\nTotal: {len(result)} caracteres")
asyncio.run(main())
A lógica é idêntica à versão síncrona; apenas mudam o stream_async, o await na chamada e o async for no loop.
Integração com FastAPI
De seguida, precisa de tirar este stream do seu processo Python e levá-lo para o navegador. O FastAPI trata disto com StreamingResponse, desde que reformate cada fragmento para o formato SSE visto na lição anterior:
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from mistralai.client import Mistral
import os
import json
app = FastAPI()
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
async def generate_stream(prompt: str):
"""Gerador SSE para FastAPI."""
stream = await client.chat.stream_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
async for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
data = json.dumps({"content": content})
yield f"data: {data}\n\n"
yield "data: [DONE]\n\n"
@app.get("/chat/stream")
async def chat_stream(prompt: str):
return StreamingResponse(
generate_stream(prompt),
media_type="text/event-stream"
)
Dois detalhes determinam se este endpoint funciona corretamente. A dupla quebra de linha \n\n que termina cada yield é o que separa os eventos no protocolo SSE: sem ela, o navegador espera indefinidamente por um evento que considera inacabado. E media_type="text/event-stream" é o que permite ao cliente JavaScript consumir a resposta com um EventSource em vez de um fetch padrão.
Medição de desempenho
Uma vez implementado o stream, vai querer saber como ele se desempenha. Duas métricas são suficientes para orientar a otimização:
import time
start = time.perf_counter()
first_token_time = None
token_count = 0
stream = client.chat.stream(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a paragraph about Paris."}]
)
for chunk in stream:
if chunk.data.choices[0].delta.content:
if first_token_time is None:
first_token_time = time.perf_counter() - start
token_count += 1
total_time = time.perf_counter() - start
print(f"Time to First Token (TTFT): {first_token_time:.3f}s")
print(f"Tokens generated: {token_count}")
print(f"Total time: {total_time:.3f}s")
print(f"Tokens/second: {token_count / total_time:.1f}")
TTFT (Time to First Token) — o tempo entre o envio do pedido e a exibição do primeiro caractere — é a métrica mais importante para a experiência do utilizador. Tem precedência sobre o tempo total: uma geração de quinze segundos cuja primeira palavra aparece em três décimos de segundo parecerá rápida, enquanto uma geração de cinco segundos entregue num único bloco parecerá lenta. Meça isto nos seus prompts reais, incluindo a mensagem de sistema; uma mensagem de sistema de duas páginas alonga o TTFT antes mesmo de o primeiro token ser gerado.
Pontos-chave
- Utilize um padrão de gerador (
yield) para propagar tokens de streaming - Implemente espera exponencial para erros 429 (limite de taxa)
- Prefira
stream_asyncpara aplicações web concorrentes - Meça o TTFT e tokens/segundo para otimizar o desempenho
- Com FastAPI,
StreamingResponse+text/event-streampropaga SSE para o navegador