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

Padrões Avançados

Aula 11 de 14 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. Para Além dos Fluxos de Trabalho Lineares
  2. Encadeamento de Fluxos de Trabalho
  3. Paralelização com asyncio.gather
  4. Tomada de Decisões no Fluxo de Trabalho
  5. Fan-out / Fan-in
  6. Pontos-chave

Atualizado em 3 de novembro de 2026: O subfluxo de trabalho devolvia anteriormente execution.output, que está ausente no SDK mistralai 3.7.0. O resultado é agora lido a partir de result, utilizando wait_for_result=True para aguardar a conclusão.

Para Além dos Fluxos de Trabalho Lineares

Até agora, analisámos fluxos de trabalho que executam atividades sequencialmente. Na prática, os casos de uso reais exigem padrões mais sofisticados: encadeamento de fluxos de trabalho, execução de atividades em paralelo ou tomada de decisões condicionais complexas. Estes quatro padrões — encadeamento, continuação, paralelismo e fan-out/fan-in — cobrem quase todas as arquiteturas que precisará de construir.

Encadeamento de Fluxos de Trabalho

Um fluxo de trabalho pode acionar outro. Esta capacidade serve dois objetivos distintos: decompor lógica complexa em subfluxos de trabalho reutilizáveis e contornar o limite de 51.200 eventos por execução, uma vez que cada fluxo de trabalho filho dispõe do seu próprio orçamento. O mecanismo baseia-se numa atividade, o único local onde o SDK pode legitimamente efetuar uma chamada de rede.

import mistralai.workflows as workflows
from mistralai.client import Mistral

@workflows.activity()
async def launch_sub_workflow(workflow_name: str, input_data: dict) -> dict:
    """Lança um fluxo de trabalho filho e aguarda o seu resultado."""
    client = Mistral()
    execution = await client.workflows.execute_workflow_async(
        workflow_identifier=workflow_name,
        input=input_data,
        wait_for_result=True,  # aguarda o resultado do fluxo de trabalho filho
    )
    return execution.result

@workflows.workflow.define(name="main_pipeline")
class MainPipeline:
    @workflows.workflow.entrypoint
    async def run(self, params: dict) -> dict:
        # Passo 1: Recolha de dados (subfluxo de trabalho dedicado)
        data = await launch_sub_workflow(
            "data_collection",
            {"sources": params["sources"]}
        )

        # Passo 2: Análise (subfluxo de trabalho dedicado)
        analysis = await launch_sub_workflow(
            "content_analysis",
            {"data": data}
        )

        # Passo 3: Geração de relatório (subfluxo de trabalho dedicado)
        report = await launch_sub_workflow(
            "report_generation",
            {"analysis": analysis, "format": params["format"]}
        )

        return report

A vantagem vai além da simples legibilidade: data_collection torna-se um fluxo de trabalho autónomo, testável isoladamente e reutilizável por outros pipelines, com os seus próprios tempos limite e políticas de nova tentativa.

O mesmo mecanismo, aplicado a um fluxo de trabalho que se chama a si próprio, cria o padrão de continuação. Em vez de processar cem mil itens numa única execução — o que o limite de eventos proíbe —, o fluxo de trabalho processa um lote e delega o restante a uma nova instância.

@workflows.workflow.define(name="batch_processing")
class BatchProcessing:
    @workflows.workflow.entrypoint
    async def run(self, params: dict) -> dict:
        offset = params.get("offset", 0)
        batch_size = 100

        # Recuperar o lote atual
        batch = await retrieve_batch(offset, batch_size)

        if not batch["items"]:
            # Todos os lotes processados
            return {"status": "completed", "total_processed": offset}

        # Processar o lote atual
        await process_batch(batch["items"])

        # Lançar o próximo lote através de um novo fluxo de trabalho
        next_batch = await launch_sub_workflow(
            "batch_processing",
            {"offset": offset + batch_size}
        )

        return next_batch

Cada nova execução começa com um registo limpo. O número de itens processáveis torna-se ilimitado, sendo a condição de paragem simplesmente um lote vazio.

Paralelização com asyncio.gather

Quando várias atividades são independentes umas das outras, não há razão para as executar em sequência. asyncio.gather submete-as à plataforma simultaneamente, e o tempo total aproxima-se do da atividade mais lenta, em vez da soma de todas elas.

import asyncio
import mistralai.workflows as workflows

@workflows.activity()
async def analyze_source(url: str) -> dict:
    """Analisa uma fonte de dados."""
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
    return {"url": url, "size": len(response.text)}

@workflows.workflow.define(name="parallel_analysis")
class ParallelAnalysis:
    @workflows.workflow.entrypoint
    async def run(self, urls: list) -> dict:
        # Lançar todas as análises em paralelo
        results = await asyncio.gather(
            *[analyze_source(url) for url in urls]
        )

        return {
            "source_count": len(results),
            "results": list(results)
        }

No entanto, aplica-se uma ressalva: por predefinição, gather propaga a primeira exceção encontrada e aborta todo o conjunto. Se estiver a analisar quarenta fontes externas, basta que uma esteja offline para perder as outras trinta e nove. O parâmetro return_exceptions=True altera este comportamento: os erros são devolvidos como valores comuns, cabendo-lhe a si tratá-los.

@workflows.workflow.define(name="fault_tolerant_analysis")
class FaultTolerantAnalysis:
    @workflows.workflow.entrypoint
    async def run(self, urls: list) -> dict:
        # return_exceptions=True impede que um erro bloqueie os restantes
        results = await asyncio.gather(
            *[analyze_source(url) for url in urls],
            return_exceptions=True
        )

        successes = []
        errors = []
        for i, result in enumerate(results):
            if isinstance(result, Exception):
                errors.append({"url": urls[i], "error": str(result)})
            else:
                successes.append(result)

        return {
            "successes": successes,
            "errors": errors,
            "success_rate": len(successes) / len(urls)
        }

Este fluxo de trabalho devolve um resultado parcial acompanhado de uma taxa de sucesso, permitindo que os processos subsequentes decidam se a qualidade é suficiente ou se é necessária uma nova tentativa.

Tomada de Decisões no Fluxo de Trabalho

A ramificação complexa não é apenas permitida, mas muitas vezes o principal motivo para utilizar fluxos de trabalho, desde que as condições derivem dos resultados das atividades. O caso da moderação de conteúdo ilustra bem esta lógica em cascata: decisão automática quando o modelo tem elevada confiança, uma segunda opinião quando a confiança é moderada e escalonamento humano em caso de desacordo ou baixa confiança.

@workflows.workflow.define(name="content_moderation")
class ContentModeration:
    @workflows.workflow.entrypoint
    async def run(self, content: dict) -> dict:
        # Passo 1: Análise automática
        analysis = await auto_analyze_content(content["text"])

        if analysis["confidence_score"] > 0.95:
            # Elevada confiança: decisão automática
            if analysis["category"] == "acceptable":
                await publish_content(content["id"])
                return {"decision": "published", "method": "automatic"}
            else:
                await reject_content(content["id"], analysis["reason"])
                return {"decision": "rejected", "method": "automatic"}

        elif analysis["confidence_score"] > 0.7:
            # Confiança moderada: segunda análise com um modelo diferente
            second_analysis = await analyze_content_model_b(content["text"])

            if analysis["category"] == second_analysis["category"]:
                # Ambos os modelos concordam
                if analysis["category"] == "acceptable":
                    await publish_content(content["id"])
                    return {"decision": "published", "method": "ai_consensus"}
                else:
                    await reject_content(content["id"], analysis["reason"])
                    return {"decision": "rejected", "method": "ai_consensus"}
            else:
                # Desacordo: escalonamento humano
                await escalate_moderation(content["id"], analysis, second_analysis)
                return {"decision": "pending", "method": "human_escalation"}

        else:
            # Baixa confiança: escalonamento direto
            await escalate_moderation(content["id"], analysis, None)
            return {"decision": "pending", "method": "human_escalation"}

Repare no campo method devolvido em cada ponto de saída: permite-lhe medir retrospetivamente que proporção de conteúdo foi processada sem intervenção humana e, assim, ajustar os limiares em conformidade.

Fan-out / Fan-in

O padrão final combina os anteriores: distribuir o trabalho em paralelo e, em seguida, agregar os resultados num único ponto. Aqui, um documento é traduzido simultaneamente para três idiomas, cada tradução é analisada em paralelo e tudo converge num resumo.

@workflows.workflow.define(name="multi_language_analysis")
class MultiLanguageAnalysis:
    @workflows.workflow.entrypoint
    async def run(self, document: dict) -> dict:
        # Fan-out: traduzir em paralelo para 3 idiomas
        translations = await asyncio.gather(
            translate(document["text"], "en"),
            translate(document["text"], "de"),
            translate(document["text"], "es")
        )

        # Fan-out: analisar cada tradução em paralelo
        analyses = await asyncio.gather(
            *[analyze_sentiment(trad["translated_text"]) for trad in translations]
        )

        # Fan-in: agregar resultados
        summary = await aggregate_analyses(list(analyses))

        return summary

As duas ondas de paralelismo são sucessivas porque a segunda depende dos resultados da primeira. Em sequência estrita, este fluxo de trabalho exigiria sete chamadas encadeadas; aqui, custa apenas três passos de orquestração.

Em suma, decomponha fluxos de trabalho complexos em subfluxos reutilizáveis, paralelize sempre que as atividades forem independentes, ative return_exceptions=True quando falhas parciais forem toleráveis, mantenha a continuação em reserva para tarefas de processamento muito longas e garanta sempre que a sua ramificação depende de resultados de atividades e não de valores não determinísticos.

Pontos-chave

  • Um fluxo de trabalho pode acionar outros fluxos de trabalho através de uma atividade que chama o SDK
  • O padrão de continuação permite processar um número ilimitado de itens em lotes sucessivos
  • asyncio.gather permite executar atividades em paralelo para reduzir o tempo total
  • A ramificação condicional complexa é suportada, desde que dependa dos resultados das atividades
  • O padrão fan-out / fan-in distribui o trabalho e agrega depois os resultados