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

Respostas em Streaming em Python

Aula 6 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. O problema que o streaming resolve
  2. Utilizar chat.stream()
  3. O que contém um bloco
  4. Apresentar e guardar simultaneamente
  5. A variante assíncrona
  6. Quando usar streaming e quando prescindir dele
  7. Pontos-chave

O problema que o streaming resolve

Com chat.complete(), aguarda que o modelo gere toda a resposta antes de receber qualquer carácter. Para uma resposta curta, este atraso passa despercebido. No entanto, para uma análise detalhada, um excerto de código extenso ou um raciocínio em vários parágrafos, o utilizador fica a olhar para um ecrã em branco durante vários segundos. Numa interface de chat, mesmo alguns segundos de silêncio podem fazer com que a aplicação pareça bloqueada.

O streaming altera esta perceção: a resposta chega de forma incremental, bloco a bloco, e é apresentada progressivamente, tal como nas interfaces de chat que conhece. O tempo total de geração não diminui nem um milissegundo, mas a primeira palavra surge quase imediatamente. É esse atraso inicial que o utilizador realmente sente.

Utilizar chat.stream()

O Mistral SDK V2 expõe o método chat.stream(), que devolve um iterador de blocos em vez de um único objeto:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

stream = client.chat.stream(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": "Describe the steps to deploy a Flask application on a Linux server."
        }
    ]
)

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

# Final newline
print()

Dois detalhes fazem toda a diferença neste ciclo. A verificação if content é essencial porque alguns blocos chegam sem texto e, caso contrário, imprimiriam None. Além disso, flush=True força o Python a escrever imediatamente na saída, em vez de aguardar que o buffer fique cheio. Sem isto, todo o texto apareceria num único bloco no final, anulando completamente o benefício que procura obter.

Aspetochat.complete()chat.stream()
RetornoObjeto completoIterador de blocos
Latência percecionadaElevada (espera total)Baixa (primeiro token rápido)
Acesso ao textoresponse.choices[0].message.contentchunk.data.choices[0].delta.content
Utilização de tokensDisponível na respostaDisponível no último bloco

O que contém um bloco

Cada bloco transporta um delta, ou seja, um fragmento da resposta em construção. Ao inspecioná-lo, acede tanto ao texto como aos metadados de fim de fluxo:

for chunk in stream:
    delta = chunk.data.choices[0].delta

    # Conteúdo de texto (pode ser None para alguns blocos)
    text = delta.content

    # Motivo de paragem (None exceto no último bloco)
    end = chunk.data.choices[0].finish_reason

    if text:
        print(text, end="", flush=True)

    if end:
        print(f"\n[Stream end: {end}]")

O fluxo segue sempre a mesma coreografia: o primeiro bloco transporta geralmente a função assistant, os blocos intermédios entregam o texto em pequenos pedaços e o último fornece o finish_reason. Verificando este último bloco, determina se a resposta terminou normalmente ou se foi cortada por max_tokens.

Apresentar e guardar simultaneamente

O streaming tem uma desvantagem: o texto desfila no ecrã, mas não o retém em lado nenhum. Contudo, uma aplicação real necessita frequentemente de arquivar a resposta numa base de dados para manter o histórico da conversa. A solução consiste em acumular os fragmentos enquanto os apresenta:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

stream = client.chat.stream(
    model="mistral-small-latest",
    messages=[
        {"role": "user", "content": "List five Python web frameworks."}
    ]
)

full_response = []

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

print()

# A resposta completa reconstituída
final_text = "".join(full_response)
print(f"\nTotal length: {len(final_text)} characters")

Note a utilização de uma lista seguida de um "".join() final, em vez da concatenação de strings em cada iteração do ciclo. Para uma resposta longa, esta última abordagem copia todo o texto acumulado para cada fragmento recebido, o que é ineficiente.

A variante assíncrona

Num servidor web (FastAPI, aiohttp), a versão síncrona bloqueia o thread durante toda a geração, congelando outros pedidos em curso. Por isso, o SDK fornece chat.stream_async():

import asyncio
import os
from mistralai.client import Mistral

async def generate_response():
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

    stream = await client.chat.stream_async(
        model="mistral-small-latest",
        messages=[
            {"role": "user", "content": "Explain the concept of a coroutine in Python."}
        ]
    )

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

    print()

asyncio.run(generate_response())

A estrutura é idêntica à versão síncrona, exceto pelas palavras-chave await e async for. Assim que o seu código é executado num servidor web, esta é a variante que deve utilizar.

Quando usar streaming e quando prescindir dele

Numa interface de chat, o streaming é sempre obrigatório: está em jogo o conforto de leitura. Do lado da API de backend, vale a pena ativá-lo desde que o seu frontend consiga consumir Server-Sent Events. Para qualquer resposta mais longa do que algumas frases, o ganho em latência percecionada justifica a complexidade acrescida. Pelo contrário, num script de lote que processa mil documentos e escreve os resultados num ficheiro, ninguém está a olhar para o ecrã: chat.complete() mantém-se mais simples e perfeitamente adequado.

Pontos-chave

  • chat.stream() devolve um iterador de blocos para apresentação progressiva
  • O conteúdo encontra-se em chunk.data.choices[0].delta.content
  • Utilize flush=True nas suas chamadas print() para apresentação em tempo real
  • Reconstrua a resposta completa acumulando os blocos, se necessário
  • A versão assíncrona chat.stream_async() é recomendada para aplicações web