Input e timeout
In questa pagina
Cosa entra in un workflow
Ogni workflow riceve parametri di input che definiscono il suo contesto di esecuzione. Poiché questi parametri viaggiano attraverso la rete e vengono archiviati nel log di esecuzione, devono seguire una regola ferrea: devono essere serializzabili in JSON. I tipi primitivi di Python passano senza problemi, così come liste, dizionari e valori null.
# Tipi primitivi
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True
# Collezioni
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}
# Nullable
commentaire: str | None = None
Tuttavia, datetime, bytes, set, tuple e classi personalizzate non Pydantic non sono supportati direttamente. Se il tuo workflow deve ricevere una data di fatturazione, convertila in una stringa ISO 8601 prima di passarla e ricostruisci l’oggetto all’interno dell’attività. Questo principio si applica a tutti questi tipi: la conversione è responsabilità tua, non della piattaforma.
Struttura e valida con Pydantic
Passare un dizionario libero funziona, ma perdi ogni garanzia sul suo contenuto. Per parametri strutturati e validati, affidati ai modelli Pydantic, che documentano l’interfaccia del workflow tanto quanto la proteggono.
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
Dal lato del chiamante, non c’è nulla di speciale da fare: i campi del BaseModel diventano semplicemente chiavi di primo livello nel dizionario di input.
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 automaticamente i dati ricevuti. Se un campo non è valido, il workflow fallisce immediatamente con un messaggio di errore esplicito, invece di avviare l’esecuzione e crashare tre attività dopo. Questa validazione si stringe secondo le necessità: vincoli di formato su un indirizzo email, limiti numerici su una priorità e, soprattutto, extra = "forbid", che rifiuta i campi sconosciuti.
class ParametresStricts(BaseModel):
email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
priorite: int = Field(ge=1, le=5)
class Config:
extra = "forbid" # Rifiuta i campi sconosciuti
Quest’ultimo punto merita attenzione. Senza extra="forbid", un errore di battitura nel nome di un campo passa inosservato: il campo atteso prende il suo valore predefinito e il workflow gira con parametri diversi da quelli che intendevi. Il fallimento è silenzioso, quindi costoso.
Quando un singolo workflow deve accettare più forme di input, i tipi unione ti permettono di descrivere queste varianti senza moltiplicare i workflow.
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"
Durata dell’esecuzione
Ogni workflow ha una durata massima di esecuzione, impostata dal parametro execution_timeout. Di default, è di un’ora: oltre questa scadenza, il workflow viene automaticamente annullato, indipendentemente dal suo avanzamento. Per un processo destinato a durare trenta secondi, questo valore è comodo; per una pipeline notturna, è una trappola.
Regola questo timeout in base alla natura dell’elaborazione, sia al ribasso che al rialzo. Un workflow a elaborazione rapida beneficia di un limite stretto, perché un superamento segnala allora un problema reale piuttosto che un rallentamento temporaneo.
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)
All’altro estremo, il tetto consentito è di 7 giorni. Questa durata ha senso solo per processi in attesa di un evento esterno, tipicamente una validazione umana: un report raccolto automaticamente ma firmato da un manager che non tornerà dalle ferie prima della settimana successiva.
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:
# Questo workflow può durare fino a 7 giorni
# Utile per processi con periodi di attesa umana
donnees = await collecter_donnees_multi_sources(params)
validation = await attendre_validation_humaine(donnees)
return await finaliser_rapport(validation)
Per calibrare, usa questo ordine di grandezza per famiglia di utilizzo.
| Caso d’uso | Timeout consigliato |
|---|---|
| Elaborazione in tempo reale | 1-5 minuti |
| Pipeline dati | 15-60 minuti |
| Generazione report complessi | 1-4 ore |
| Workflow con validazione umana | 1-7 giorni |
Due livelli di timeout da non confondere
execution_timeout delimita l’intero workflow; start_to_close_timeout delimita una singola attività. I due coesistono e si completano: il primo ti protegge da un workflow che non termina mai, il secondo da un’attività bloccata su un servizio silenzioso. Nota nell’esempio sotto che il timeout del client HTTP (240 secondi) è intenzionalmente inferiore allo start_to_close_timeout (5 minuti), così l’errore emerge pulitamente prima che la piattaforma tagli la connessione.
from datetime import timedelta
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
# Questa attività ha 5 minuti per completarsi
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:
# L'intero workflow ha 2 ore
# Ma ogni singola attività ha il proprio timeout
resultats = []
for source in sources:
resultat = await appel_api_externe(source)
resultats.append(resultat)
return {"résultats": resultats}
Un ultimo riflesso per i tuoi input: mantienili leggeri. Il limite è 2 MB e nulla ti obbliga ad avvicinarti. Passa l’URL di un documento piuttosto che il suo contenuto, un ID ordine piuttosto che l’ordine completo, e lascia che siano le attività a recuperare i dati. Definisci valori predefiniti per tutto ciò che è opzionale, documenta ogni campo con Field(description="...") e affida la validazione a Pydantic piuttosto che a istruzioni if sparse nel workflow.
Punti chiave
- Gli input del workflow devono essere serializzabili in JSON (str, int, float, bool, list, dict)
- Usa Pydantic BaseModel per input strutturati con validazione automatica
- Il timeout predefinito è 1 ora, configurabile fino a un massimo di 7 giorni
- Distingui il timeout del workflow (
execution_timeout) da quello dell’attività (start_to_close_timeout) - Mantieni gli input leggeri: ID e URL invece di grandi dati grezzi