Intrări și timeout-uri
Pe această pagină
Ce intră într-un workflow
Fiecare workflow primește parametri de intrare care definesc contextul său de execuție. Deoarece acești parametri circulă prin rețea și sunt stocați în jurnalul de execuție, trebuie să respecte o regulă strictă: trebuie să fie serializabili în JSON. Tipurile primitive Python trec fără probleme, la fel ca listele, dicționarele și valorile null.
# Tipuri primitive
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True
# Colecții
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}
# Nullable
commentaire: str | None = None
Totuși, datetime, bytes, set, tuple și clasele personalizate non-Pydantic nu sunt suportate direct. Dacă workflow-ul dumneavoastră trebuie să primească o dată de facturare, convertiți-o într-un șir ISO 8601 înainte de a o transmite și reconstruiți obiectul în interiorul activității. Acest principiu se aplică tuturor acestor tipuri: conversia este responsabilitatea dumneavoastră, nu a platformei.
Structurarea și validarea cu Pydantic
Transmiterea unui dicționar liber funcționează, dar pierdeți orice garanție privind conținutul său. Pentru parametri structurați și validați, bazați-vă pe modelele Pydantic, care documentează interfața workflow-ului la fel de bine cum o protejează.
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
În partea apelantului, nu este nimic special de făcut: câmpurile din BaseModel devin pur și simplu chei de nivel superior în dicționarul de intrare.
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 validează automat datele primite. Dacă un câmp este invalid, workflow-ul eșuează imediat cu un mesaj de eroare explicit, în loc să înceapă execuția și să se blocheze trei activități mai târziu. Această validare se strânge după nevoie: constrângeri de format pentru o adresă de email, limite numerice pentru o prioritate și, mai presus de toate, extra = "forbid", care respinge câmpurile necunoscute.
class ParametresStricts(BaseModel):
email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
priorite: int = Field(ge=1, le=5)
class Config:
extra = "forbid" # Respinge câmpurile necunoscute
Acest ultim punct merită atenție. Fără extra="forbid", o greșeală de tastare într-un nume de câmp trece neobservată: câmpul așteptat își ia valoarea implicită, iar workflow-ul rulează cu parametri care nu sunt cei pe care îi intenționați. Eșecul este silențios, deci costisitor.
Când un singur workflow trebuie să accepte multiple forme de intrare, tipurile union vă permit să descrieți aceste variante fără a multiplica workflow-urile.
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 de viață a execuției
Fiecare workflow are o durată maximă de execuție, setată prin parametrul execution_timeout. Implicit, este de o oră: după acest termen limită, workflow-ul este anulat automat, indiferent de progresul său. Pentru un proces menit să dureze treizeci de secunde, această valoare este confortabilă; pentru un pipeline peste noapte, este o capcană.
Ajustați acest timeout în funcție de natura procesării, atât în jos, cât și în sus. Un workflow de procesare rapidă beneficiază de o limită strictă, deoarece o depășire semnalează atunci o problemă reală, nu o încetinire temporară.
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)
La celălalt capăt, plafonul permis este de 7 zile. Această durată are sens doar pentru procesele care așteaptă un eveniment extern, tipic o validare umană: un raport colectat automat, dar semnat de un manager care nu se va întoarce din concediu decât săptămâna viitoare.
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:
# Acest workflow poate dura până la 7 zile
# Util pentru procesele cu perioade de așteptare umană
donnees = await collecter_donnees_multi_sources(params)
validation = await attendre_validation_humaine(donnees)
return await finaliser_rapport(validation)
Pentru calibrare, folosiți acest ordin de mărime pe familii de utilizare.
| Caz de utilizare | Timeout recomandat |
|---|---|
| Procesare în timp real | 1-5 minute |
| Pipeline de date | 15-60 minute |
| Generare de rapoarte complexe | 1-4 ore |
| Workflow cu validare umană | 1-7 zile |
Două niveluri de timeout de nu confundat
execution_timeout limitează întregul workflow; start_to_close_timeout limitează o singură activitate. Cele două coexistă și se completează reciproc: primul vă protejează de un workflow care nu se termină niciodată, al doilea de o activitate blocată pe un serviciu silențios. Observați în exemplul de mai jos că timeout-ul clientului HTTP (240 de secunde) este intenționat mai mic decât start_to_close_timeout (5 minute), astfel încât eroarea să apară clar înainte ca platforma să taie conexiunea.
from datetime import timedelta
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
# Această activitate are 5 minute pentru a se finaliza
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:
# Întregul workflow are 2 ore
# Dar fiecare activitate individuală are propriul său timeout
resultats = []
for source in sources:
resultat = await appel_api_externe(source)
resultats.append(resultat)
return {"résultats": resultats}
Un ultim reflex pentru intrările dumneavoastră: mențineți-le ușoare. Limita este de 2 MB și nimic nu vă obligă să vă apropiați de ea. Transmiteți URL-ul unui document în loc de conținutul său, un ID de comandă în loc de comanda completă și lăsați activitățile să preia datele. Definiți valori implicite pentru tot ce este opțional, documentați fiecare câmp cu Field(description="...") și încredințați validarea lui Pydantic în loc de instrucțiuni if împrăștiate în tot workflow-ul.
Puncte cheie
- Intrările în workflow trebuie să fie serializabile JSON (str, int, float, bool, list, dict)
- Folosiți Pydantic BaseModel pentru intrări structurate cu validare automată
- Timeout-ul implicit este de 1 oră, configurabil până la maximum 7 zile
- Distingeți timeout-ul workflow-ului (
execution_timeout) de timeout-ul activității (start_to_close_timeout) - Mențineți intrările ușoare: ID-uri și URL-uri în loc de date brute voluminoase