Patrones avanzados
En esta página
Actualizado el 3 de noviembre de 2026: El subflujo de trabajo devolvía anteriormente
execution.output, que falta en la versión 3.7.0 del SDKmistralai. Ahora el resultado se lee desderesult, utilizandowait_for_result=Truepara esperar a la finalización.
Más allá de los flujos de trabajo lineales
Hasta ahora, hemos examinado flujos de trabajo que ejecutan actividades de forma secuencial. En la práctica, los casos de uso reales requieren patrones más sofisticados: encadenar flujos de trabajo, ejecutar actividades en paralelo o tomar decisiones condicionales complejas. Estos cuatro patrones —encadenamiento, continuación, paralelismo y dispersión/agregación (fan-out/fan-in)— cubren casi toda arquitectura que necesites construir.
Encadenamiento de flujos de trabajo
Un flujo de trabajo puede desencadenar otro. Esta capacidad sirve a dos objetivos distintos: dividir la lógica compleja en subflujos de trabajo reutilizables y eludir el límite de 51.200 eventos por ejecución, ya que cada flujo de trabajo hijo obtiene su propio presupuesto. El mecanismo depende de una actividad, que es el único lugar donde el SDK puede realizar legítimamente una llamada de red.
import mistralai.workflows as workflows
from mistralai.client import Mistral
@workflows.activity()
async def launch_sub_workflow(workflow_name: str, input_data: dict) -> dict:
"""Lanza un flujo de trabajo hijo y espera su resultado."""
client = Mistral()
execution = await client.workflows.execute_workflow_async(
workflow_identifier=workflow_name,
input=input_data,
wait_for_result=True, # espera al resultado del flujo de trabajo hijo
)
return execution.result
@workflows.workflow.define(name="main_pipeline")
class MainPipeline:
@workflows.workflow.entrypoint
async def run(self, params: dict) -> dict:
# Paso 1: Recopilación de datos (subflujo de trabajo dedicado)
data = await launch_sub_workflow(
"data_collection",
{"sources": params["sources"]}
)
# Paso 2: Análisis (subflujo de trabajo dedicado)
analysis = await launch_sub_workflow(
"content_analysis",
{"data": data}
)
# Paso 3: Generación de informes (subflujo de trabajo dedicado)
report = await launch_sub_workflow(
"report_generation",
{"analysis": analysis, "format": params["format"]}
)
return report
La ventaja va más allá de la simple legibilidad: data_collection se convierte en un flujo de trabajo independiente, comprobable de forma aislada y reutilizable por otros pipelines, con sus propias políticas de tiempo de espera y reintentos.
El mismo mecanismo, aplicado a un flujo de trabajo que se llama a sí mismo, crea el patrón de continuación. En lugar de procesar cien mil elementos en una única ejecución —lo que prohíbe el límite de eventos—, el flujo de trabajo procesa un lote y delega el resto en una nueva instancia.
@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 el lote actual
batch = await retrieve_batch(offset, batch_size)
if not batch["items"]:
# Todos los lotes procesados
return {"status": "completed", "total_processed": offset}
# Procesar el lote actual
await process_batch(batch["items"])
# Lanzar el siguiente lote mediante un nuevo flujo de trabajo
next_batch = await launch_sub_workflow(
"batch_processing",
{"offset": offset + batch_size}
)
return next_batch
Cada nueva ejecución comienza con un diario limpio. El número de elementos procesables se vuelve ilimitado, siendo la condición de parada simplemente un lote vacío.
Paralelización con asyncio.gather
Cuando múltiples actividades son independientes entre sí, no hay razón para ejecutarlas en secuencia. asyncio.gather las envía a la plataforma simultáneamente, y el tiempo total se aproxima al de la actividad más lenta en lugar de a la suma de todas ellas.
import asyncio
import mistralai.workflows as workflows
@workflows.activity()
async def analyze_source(url: str) -> dict:
"""Analiza una fuente de datos."""
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:
# Lanzar todos los análisis en paralelo
results = await asyncio.gather(
*[analyze_source(url) for url in urls]
)
return {
"source_count": len(results),
"results": list(results)
}
Sin embargo, hay un matiz importante: por defecto, gather propaga la primera excepción encontrada y aborta todo el conjunto. Si estás analizando cuarenta fuentes externas, que solo una esté fuera de línea hace que pierdas las otras treinta y nueve. El parámetro return_exceptions=True cambia este comportamiento: los errores se devuelven como valores ordinarios, dejándote a ti la tarea de gestionarlos.
@workflows.workflow.define(name="fault_tolerant_analysis")
class FaultTolerantAnalysis:
@workflows.workflow.entrypoint
async def run(self, urls: list) -> dict:
# return_exceptions=True evita que un error bloquee a los demás
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 flujo de trabajo devuelve un resultado parcial acompañado de una tasa de éxito, lo que permite a los procesos posteriores decidir si la calidad es suficiente o si es necesario un reintento.
Toma de decisiones en el flujo de trabajo
Las ramificaciones complejas no solo están permitidas, sino que a menudo son la razón principal para usar flujos de trabajo, siempre que las condiciones se deriven de los resultados de las actividades. El caso de moderación de contenido ilustra bien esta lógica en cascada: decisión automática cuando el modelo tiene alta confianza, una segunda opinión cuando la confianza es moderada y escalado humano en caso de desacuerdo o baja confianza.
@workflows.workflow.define(name="content_moderation")
class ContentModeration:
@workflows.workflow.entrypoint
async def run(self, content: dict) -> dict:
# Paso 1: Análisis automático
analysis = await auto_analyze_content(content["text"])
if analysis["confidence_score"] > 0.95:
# Alta confianza: decisión 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:
# Confianza moderada: segundo análisis con un modelo diferente
second_analysis = await analyze_content_model_b(content["text"])
if analysis["category"] == second_analysis["category"]:
# Ambos modelos coinciden
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:
# Desacuerdo: escalado humano
await escalate_moderation(content["id"], analysis, second_analysis)
return {"decision": "pending", "method": "human_escalation"}
else:
# Baja confianza: escalado directo
await escalate_moderation(content["id"], analysis, None)
return {"decision": "pending", "method": "human_escalation"}
Observa el campo method devuelto en cada punto de salida: te permite medir retrospectivamente qué proporción de contenido se procesó sin intervención humana y, por tanto, ajustar los umbrales en consecuencia.
Dispersión y agregación (Fan-out / Fan-in)
El patrón final combina los anteriores: distribuir el trabajo en paralelo y luego agregar los resultados en un único punto. Aquí, un documento se traduce simultáneamente a tres idiomas, cada traducción se analiza en paralelo y todo converge en un resumen.
@workflows.workflow.define(name="multi_language_analysis")
class MultiLanguageAnalysis:
@workflows.workflow.entrypoint
async def run(self, document: dict) -> dict:
# Fan-out: traducir en paralelo a 3 idiomas
translations = await asyncio.gather(
translate(document["text"], "en"),
translate(document["text"], "de"),
translate(document["text"], "es")
)
# Fan-out: analizar cada traducción en 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
Las dos oleadas de paralelismo son sucesivas porque la segunda depende de los resultados de la primera. En secuencia estricta, este flujo de trabajo requeriría siete llamadas encadenadas; aquí, solo cuesta tres pasos de orquestación.
En resumen, divide los flujos de trabajo complejos en subflujos reutilizables, paraleliza siempre que las actividades sean independientes, habilita return_exceptions=True cuando los fallos parciales sean tolerables, mantén la continuación en reserva para trabajos de procesamiento muy largos y asegúrate siempre de que tus ramificaciones dependan de los resultados de las actividades y no de valores no deterministas.
Puntos clave
- Un flujo de trabajo puede desencadenar otros flujos mediante una actividad que llama al SDK
- El patrón de continuación permite procesar un número ilimitado de elementos en lotes sucesivos
asyncio.gatherte permite ejecutar actividades en paralelo para reducir el tiempo total- Se admiten ramificaciones condicionales complejas siempre que dependan de los resultados de las actividades
- El patrón de dispersión y agregación (fan-out / fan-in) distribuye el trabajo y luego agrega los resultados