Padrões Avançados
Nesta página
Atualizado em 3 de novembro de 2026: O subfluxo de trabalho devolvia anteriormente
execution.output, que está ausente no SDKmistralai3.7.0. O resultado é agora lido a partir deresult, utilizandowait_for_result=Truepara 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.gatherpermite 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