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

Assíncrono e Melhores Práticas

Aula 13 de 14 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. E/S Assíncrona: Um Requisito Técnico
  2. Escolha Bibliotecas Nativamente Assíncronas
  3. Quando Não Existe Versão Assíncrona
  4. Conceção de Atividades Limpas
  5. Pontos-chave

E/S Assíncrona: Um Requisito Técnico

Todas as atividades nos Workflows da Mistral devem utilizar operações de entrada/saída assíncronas. Isto não é uma recomendação de estilo; é uma restrição técnica. Uma chamada síncrona bloqueante, como requests.post(), congela o worker e impede a execução de qualquer outra atividade.

Este requisito decorre da arquitetura do worker, que executa atividades dentro de um loop de eventos asyncio. Quando uma coroutine aguarda uma resposta de rede de forma assíncrona, devolve o controlo ao loop, permitindo que outras atividades prossigam. Uma chamada síncrona, pelo contrário, não devolve nada.

import requests

# INCORRETO: Bloqueia todo o worker
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() é síncrono — bloqueia o loop de eventos
    response = requests.post(url, json={"query": "test"})
    return response.json()

O sintoma em produção pode ser confuso: lança dez atividades em paralelo com asyncio.gather, mas elas acabam por ser executadas uma após a outra. Se cada uma aguardar dois segundos por uma API remota, medirá vinte segundos em vez dos dois esperados, sem que sejam levantados erros.

Escolha Bibliotecas Nativamente Assíncronas

A solução consiste em substituir todas as bibliotecas bloqueantes pelas suas equivalentes assíncronas. Para chamadas HTTP, o httpx é a escolha padrão.

import httpx

# CORRETO: Não bloqueante
@workflows.activity()
async def async_activity(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(url, json={"query": "test"})
    return response.json()

O aiohttp serve o mesmo propósito com uma API ligeiramente diferente baseada em sessões.

import aiohttp

@workflows.activity()
async def aiohttp_activity(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.post(url, json={"query": "test"}) as response:
            return await response.json()

Para bases de dados, o asyncpg substitui o psycopg2 para PostgreSQL. Note o bloco try/finally: a ligação deve ser fechada mesmo que a consulta levante uma exceção. Caso contrário, as tentativas sucessivas esgotarão o pool de ligações.

import asyncpg

# CORRETO: Driver assíncrono para PostgreSQL
@workflows.activity()
async def async_db_query(user_id: str) -> dict:
    conn = await asyncpg.connect("postgresql://user:pass@localhost/db")
    try:
        row = await conn.fetchrow(
            "SELECT * FROM users WHERE id = $1", user_id
        )
        return dict(row) if row else {"error": "user not found"}
    finally:
        await conn.close()

O acesso a ficheiros segue a mesma lógica com aiofiles, mesmo para ficheiros pequenos onde poderia sentir a tentação de continuar a usar open().

import aiofiles

# CORRETO: Leitura assíncrona de ficheiros
@workflows.activity()
async def read_file_async(path: str) -> dict:
    async with aiofiles.open(path, mode="r") as f:
        content = await f.read()
    return {"content": content, "size": len(content)}

O próprio SDK da Mistral não é exceção: todos os métodos têm uma variante com o sufixo _async, e é essa que deve chamar a partir de uma atividade.

from mistralai.client import Mistral

@workflows.activity()
async def call_mistral(prompt: str) -> dict:
    client = Mistral()
    # Use complete_async, NÃO complete
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": prompt}]
    )
    return {"response": response.choices[0].message.content}

Mantenha esta tabela de mapeamento à mão durante as revisões de código: qualquer linha da coluna da esquerda detetada numa atividade é um potencial erro de desempenho.

OperaçãoIncorreto (bloqueante)Correto (assíncrono)
HTTPrequests.get()httpx.AsyncClient().get()
HTTPurllib.request.urlopen()aiohttp.ClientSession().get()
PostgreSQLpsycopg2.connect()asyncpg.connect()
MySQLmysql.connector.connect()aiomysql.connect()
Redisredis.Redis()redis.asyncio.Redis()
Ficheirosopen()aiofiles.open()
Pausatime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Quando Não Existe Versão Assíncrona

Algumas bibliotecas de negócio, como um SDK proprietário ou um cliente legado, simplesmente não oferecem uma variante assíncrona. Nestes casos, asyncio.to_thread() permite executar o código bloqueante num thread separado sem congelar o loop de eventos.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Envolve uma chamada bloqueante num thread."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

Isto é um compromisso, não uma solução equivalente: cada chamada consome um thread do pool, que tem um tamanho finito. Para uma atividade chamada massivamente em paralelo, apenas desloca o gargalo em vez de o remover. Prefira sempre uma biblioteca nativamente assíncrona quando esta existir.

Conceção de Atividades Limpas

Para além da assincronia, quatro hábitos distinguem uma atividade robusta de uma que lhe custará horas de depuração.

O primeiro é o âmbito. Uma atividade deve ter uma e apenas uma responsabilidade, pois é também a unidade de nova tentativa e de persistência: uma atividade «faz-tudo» que falha ao enviar um e-mail fará repetir a extração e a análise desde o início.

# BOM: Cada atividade tem uma responsabilidade clara
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
    # ...
    pass

# MAU: Atividade faz-tudo
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # extração
    sentiment = ...  # análise
    # enviar e-mail
    # guardar na BD
    pass

O segundo diz respeito aos recursos. O gestor de contexto async with garante que o cliente é fechado mesmo que ocorra uma exceção, algo que as chamadas manuais inevitavelmente esquecem mais cedo ou mais tarde.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Use async with para garantir o fecho
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # O cliente é fechado automaticamente aqui
    return response.json()

O terceiro é mais subtil: nem todos os erros merecem uma nova tentativa. Um timeout, um 429 ou um 500 são transitórios e devem propagar-se para desencadear uma nova tentativa. Um erro 4xx, no entanto, indica um pedido inválido que três novas tentativas não resolverão. Em vez disso, devolva um resultado explícito e deixe o workflow decidir.

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=2),
    retry_policy_max_attempts=3,
)
async def robust_activity(params: dict) -> dict:
    async with httpx.AsyncClient(timeout=60) as client:
        try:
            response = await client.post(params["url"], json=params["data"])
            response.raise_for_status()
            return {"status": "success", "data": response.json()}
        except httpx.TimeoutException:
            raise  # Será novamente tentado pela plataforma
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Limite de taxa atingido — será novamente tentado
            elif e.response.status_code >= 500:
                raise  # Erro do servidor — será novamente tentado
            else:
                # Erro do cliente (4xx) — não tentar novamente
                return {"status": "error", "code": e.response.status_code}

Finalmente, o quarto hábito decorre do limite de 2 MB por invocação: devolva apenas o que o workflow realmente precisa para decidir o próximo passo. Uma contagem, uma amostra e o URL para o resultado completo são quase sempre suficientes.

@workflows.activity()
async def extract_data(source: str) -> dict:
    data = await retrieve_large_data(source)

    # Devolva apenas o que o workflow precisa
    return {
        "item_count": len(data),
        "summary": data[:10],  # Apenas os primeiros 10
        "full_url": await upload_results(data)
    }

Pontos-chave

  • E/S assíncrona é obrigatória: use httpx, asyncpg, aiofiles em vez das suas equivalentes síncronas
  • Chamadas bloqueantes (requests, psycopg2, open) congelam todo o worker
  • Use asyncio.to_thread() como último recurso para bibliotecas sem versão assíncrona
  • Cada atividade deve ter uma responsabilidade clara
  • Feche sempre as ligações com async with
  • Trate os erros explicitamente: alguns devem ser novamente tentados, outros não
  • Limite o tamanho dos retornos para se manter abaixo do limite de 2 MB