Entradas y tiempos de espera
En esta página
Qué entra en un flujo de trabajo
Todo flujo de trabajo recibe parámetros de entrada que definen su contexto de ejecución. Dado que estos parámetros viajan por la red y se almacenan en el registro de ejecución, deben cumplir una regla estricta: deben ser serializables en JSON. Los tipos primitivos de Python funcionan sin problemas, al igual que las listas, los diccionarios y los valores nulos.
# Tipos primitivos
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True
# Colecciones
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}
# Nullable
commentaire: str | None = None
Sin embargo, datetime, bytes, set, tuple y clases personalizadas que no sean de Pydantic no se admiten directamente. Si tu flujo de trabajo necesita recibir una fecha de factura, conviértela a una cadena ISO 8601 antes de pasarla y reconstruye el objeto dentro de la actividad. Este principio se aplica a todos estos tipos: la conversión es responsabilidad tuya, no de la plataforma.
Estructura y valida con Pydantic
Pasar un diccionario de forma libre funciona, pero pierdes todas las garantías sobre su contenido. Para parámetros estructurados y validados, confía en los modelos de Pydantic, que documentan la interfaz del flujo de trabajo tanto como la protegen.
from pydantic import BaseModel, Field
class ParametresAnalyse(BaseModel):
url_document: str
langue: str = "fr"
max_tokens: int = Field(default=1000, ge=100, le=10000)
inclure_metadata: bool = False
@workflows.workflow.define(name="analyse_documentaire")
class AnalyseDocumentaire:
@workflows.workflow.entrypoint
async def run(self, params: ParametresAnalyse) -> dict:
extraction = await extraire_texte(params.url_document, params.langue)
analyse = await analyser_contenu(extraction["texte"], params.max_tokens)
if params.inclure_metadata:
metadata = await extraire_metadata(params.url_document)
return {**analyse, "metadata": metadata}
return analyse
Por parte del llamador, no hay nada especial que hacer: los campos del BaseModel simplemente se convierten en claves de nivel superior en el diccionario de entrada.
execution = await client.workflows.execute_workflow_async(
workflow_identifier="analyse_documentaire",
input={
"url_document": "https://example.com/rapport.pdf",
"langue": "fr",
"max_tokens": 2000,
"inclure_metadata": True
}
)
Pydantic valida automáticamente los datos recibidos. Si un campo no es válido, el flujo de trabajo falla inmediatamente con un mensaje de error explícito, en lugar de comenzar la ejecución y fallar tres actividades más tarde. Esta validación se ajusta según sea necesario: restricciones de formato para una dirección de correo electrónico, límites numéricos para una prioridad y, sobre todo, extra = "forbid", que rechaza campos desconocidos.
class ParametresStricts(BaseModel):
email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
priorite: int = Field(ge=1, le=5)
class Config:
extra = "forbid" # Rechaza campos desconocidos
Este último punto merece atención. Sin extra="forbid", un error tipográfico en el nombre de un campo pasa desapercibido: el campo esperado toma su valor predeterminado y el flujo de trabajo se ejecuta con parámetros que no son los que pretendías. El fallo es silencioso y, por tanto, costoso.
Cuando un único flujo de trabajo debe aceptar múltiples formas de entrada, los tipos de unión te permiten describir estas variantes sin multiplicar los flujos de trabajo.
from typing import Union
class TraitementTexte(BaseModel):
texte: str
type_traitement: str = "resume"
class TraitementURL(BaseModel):
url: str
type_traitement: str = "resume"
class ParametresFlexibles(BaseModel):
source: Union[TraitementTexte, TraitementURL]
class Config:
extra = "forbid"
Duración de la ejecución
Todo flujo de trabajo tiene una duración máxima de ejecución, establecida por el parámetro execution_timeout. Por defecto, es de una hora: pasado este plazo, el flujo de trabajo se cancela automáticamente, independientemente de su progreso. Para un proceso destinado a durar treinta segundos, este valor es cómodo; para una tubería de datos nocturna, es una trampa.
Ajusta este tiempo de espera a la naturaleza del procesamiento, tanto a la baja como al alza. Un flujo de trabajo de procesamiento rápido se beneficia de un límite estricto, porque un exceso indica entonces un problema real en lugar de una ralentización temporal.
from datetime import timedelta
@workflows.workflow.define(
name="traitement_rapide",
execution_timeout=timedelta(minutes=10)
)
class TraitementRapide:
@workflows.workflow.entrypoint
async def run(self, donnees: dict) -> dict:
return await traiter(donnees)
En el otro extremo, el techo permitido es de 7 días. Esta duración solo tiene sentido para procesos que esperan un evento externo, típicamente una validación humana: un informe recopilado automáticamente pero firmado por un gerente que no volverá de sus vacaciones hasta la semana siguiente.
from datetime import timedelta
@workflows.workflow.define(
name="workflow_longue_duree",
execution_timeout=timedelta(days=7)
)
class WorkflowLongueDuree:
@workflows.workflow.entrypoint
async def run(self, params: dict) -> dict:
# Este flujo de trabajo puede durar hasta 7 días
# Útil para procesos con periodos de espera humana
donnees = await collecter_donnees_multi_sources(params)
validation = await attendre_validation_humaine(donnees)
return await finaliser_rapport(validation)
Para calibrar, utiliza este orden de magnitud por familia de uso.
| Caso de uso | Tiempo de espera recomendado |
|---|---|
| Procesamiento en tiempo real | 1-5 minutos |
| Tubería de datos | 15-60 minutos |
| Generación de informes complejos | 1-4 horas |
| Flujo de trabajo con validación humana | 1-7 días |
Dos niveles de tiempo de espera que no debes confundir
execution_timeout limita todo el flujo de trabajo; start_to_close_timeout limita una única actividad. Ambos coexisten y se complementan: el primero te protege de un flujo de trabajo que nunca se completa, el segundo de una actividad colgada en un servicio silencioso. Observa en el ejemplo siguiente que el tiempo de espera del cliente HTTP (240 segundos) es intencionadamente inferior al start_to_close_timeout (5 minutos), para que el error aparezca limpiamente antes de que la plataforma corte la conexión.
from datetime import timedelta
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
# Esta actividad tiene 5 minutos para completarse
async with httpx.AsyncClient(timeout=240) as client:
response = await client.post(params["url"], json=params["data"])
return response.json()
@workflows.workflow.define(
name="pipeline_multi_etapes",
execution_timeout=timedelta(hours=2)
)
class PipelineMultiEtapes:
@workflows.workflow.entrypoint
async def run(self, sources: list) -> dict:
# Todo el flujo de trabajo tiene 2 horas
# Pero cada actividad individual tiene su propio tiempo de espera
resultats = []
for source in sources:
resultat = await appel_api_externe(source)
resultats.append(resultat)
return {"résultats": resultats}
Un último reflejo para tus entradas: mantenlas ligeras. El límite es de 2 MB y nada te obliga a acercarte a él. Pasa la URL de un documento en lugar de su contenido, un ID de pedido en lugar del pedido completo, y deja que las actividades recuperen los datos. Define valores predeterminados para todo lo opcional, documenta cada campo con Field(description="...") y confía la validación a Pydantic en lugar de sentencias if dispersas por todo el flujo de trabajo.
Puntos clave
- Las entradas del flujo de trabajo deben ser serializables en JSON (str, int, float, bool, list, dict)
- Usa Pydantic BaseModel para entradas estructuradas con validación automática
- El tiempo de espera predeterminado es de 1 hora, configurable hasta un máximo de 7 días
- Distingue el tiempo de espera del flujo de trabajo (
execution_timeout) del tiempo de espera de la actividad (start_to_close_timeout) - Mantén las entradas ligeras: IDs y URLs en lugar de grandes datos en bruto