Inputs u timeouts
F'din il-paġna
X’jidħol f’workflow
Kull workflow jirċievi parametri tal-input li jiddefinixxu l-kuntest ta’ eżekuzzjoni tiegħu. Peress li dawn il-parametri jivvjaġġaw fuq in-netwerk u jinħażnu fil-log tal-eżekuzzjoni, iridu jsegwu regola waħda stretta: iridu jkunu JSON-serializzabbli. It-tipi primitivi ta’ Python jgħaddu mingħajr problemi, kif ukoll il-listi, id-dizzjunarji, u l-valuri null.
# Tipi primitivi
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True
# Kollezjonijiet
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}
# Nullable
commentaire: str | None = None
Madankollu, datetime, bytes, set, tuple, u klassijiet personalizzati mhux Pydantic mhumiex appoġġjati direttament. Jekk il-workflow tiegħek jeħtieġ li jirċievi data ta’ fattura, ikkonvertiha f’string ISO 8601 qabel ma tgħaddiha, u rrikostruwixxi l-oġġett ġewwa l-attività. Dan il-prinċipju japplika għat-tipi kollha bħal dawn: il-konverżjoni hija r-responsabbiltà tiegħek, mhux tal-pjattaforma.
Iddeskrivi u vvalida b’Pydantic
L-għaddi ta’ dizzjunarju b’forma ħielsa jaħdem, iżda titlef il-garanziji kollha dwar il-kontenut tiegħu. Għal parametri strutturati u vvalidati, اعتمد fuq mudelli Pydantic, li jiddokumentaw l-interfaċċa tal-workflow daqs kemm jipproteġuha.
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
Fuq in-naħa ta’ min isejjaħ, m’hemm xejn speċjali x’tagħmel: il-kampi tal-BaseModel sempliċiment isiru ċwievet ta’ livell għoli fid-dizzjunarju tal-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 tivvalida awtomatikament id-data li tasal. Jekk kamp ikun invalidu, il-workflow ifalli immedjatament b’messaġġ ta’ żball espliċitu, minflok ma jibda l-eżekuzzjoni u jaqa’ tliet attivitajiet wara. Din il-validazzjoni tissikka skont il-ħtieġa: restrizzjonijiet tal-format fuq indirizz email, limiti numeriċi fuq prijorità, u fuq kollox extra = "forbid", li jiċħad kampijiet mhux magħrufa.
class ParametresStricts(BaseModel):
email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
priorite: int = Field(ge=1, le=5)
class Config:
extra = "forbid" # Jiċħad kampijiet mhux magħrufa
Dan l-aħħar punt jistħoqqilhom attenzjoni. Mingħajr extra="forbid", żball fit-typing f’isem kamp jgħaddi inosservat: il-kamp mistenni jieħu l-valur predefinit tiegħu u l-workflow jimxi b’parametri li mhumiex dawk li ħsibt. Il-falliment ikun silenzjuż, għalhekk għali.
Meta workflow wieħed irid jaċċetta forom multipli ta’ input, it-tipi ta’ union jħalluk tiddeskrivi dawn il-varjanti mingħajr ma timmultiplika l-workflows.
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"
Ħajja tal-eżekuzzjoni
Kull workflow għandu tul massimu ta’ eżekuzzjoni, stabbilit mill-parametru execution_timeout. B’mod predefinit, huwa siegħa: wara din l-iskadenza, il-workflow jiġi kkanċellat awtomatikament, irrispettivament mill-progress tiegħu. Għal proċess maħsub biex idum tletin sekonda, dan il-valur huwa komdu; għal pipeline matul il-lejl, huwa nassa.
Aġġusta dan it-timeout għan-natura tal-ipproċessar, kemm ‘l isfel kif ukoll ‘l fuq. Workflow ta’ pproċessar mgħaġġel jibbenefika minn limitu strett, għax eċċess imbagħad jissinjala problema reali minflok tnaqqis temporanju fil-veloċità.
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)
Fit-tarf l-ieħor, is-soqfa permessa hija 7 ijiem. Din id-durata tagħmel sens biss għal proċessi li jistennew avveniment estern, tipikament validazzjoni umana: rapport miġbur awtomatikament iżda ffirmat minn maniġer li mhux se jerġa’ lura mill-vaganzi qabel il-ġimgħa d-dieħla.
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:
# Dan il-workflow jista' jdum sa 7 ijiem
# Utli għal proċessi b'perjodi ta' stennija umana
donnees = await collecter_donnees_multi_sources(params)
validation = await attendre_validation_humaine(donnees)
return await finaliser_rapport(validation)
Biex tikkalibra, uża din l-ordni ta’ kobbs skont il-familja tal-użu.
| Każ ta’ użu | Timeout rakkomandat |
|---|---|
| Ipproċessar f’ħin reali | 1-5 minuti |
| Pipeline tad-data | 15-60 minuta |
| Ġenerazzjoni ta’ rapport kumpless | 1-4 sigħat |
| Workflow b’validazzjoni umana | 1-7 ijiem |
Żewġ livelli ta’ timeout li m’għandekx tħawwad
execution_timeout jillimita l-workflow kollu; start_to_close_timeout jillimita attività waħda. It-tnejn jeżistu flimkien u jikkomplementaw lil xulxin: l-ewwel jipproteġik minn workflow li qatt ma jitlesta, it-tieni minn attività mwaqqfa fuq servizz silenzjuż. Innota fl-eżempju hawn taħt li t-timeout tal-klijent HTTP (240 sekonda) huwa intenzjonalment aktar baxx mill-start_to_close_timeout (5 minuti), sabiex l-iżball joħroġ fid-dieher b’mod nadif qabel ma l-pjattaforma taqta’ l-konnessjoni.
from datetime import timedelta
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
# Din l-attività għandha 5 minuti biex titlesta
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:
# Il-workflow kollu għandu sagħtejn
# Iżda kull attività individwali għandha t-timeout tagħha
resultats = []
for source in sources:
resultat = await appel_api_externe(source)
resultats.append(resultat)
return {"résultats": resultats}
Rifless aħħari għall-inputs tiegħek: żommhom ħfief. Il-limitu huwa 2 MB, u xejn ma jfurzak toqrob lejh. Għaddi l-URL ta’ dokument minflok il-kontenut tiegħu, ID ta’ ordni minflok l-ordni sħiħa, u ħalli l-attivitajiet iġibu d-data. Iddefinixxi valuri predefiniti għal kollox li huwa opzjonali, iddokumenta kull kamp b’Field(description="..."), u fda l-validazzjoni lil Pydantic minflok istatamenti if mifruxa fil-workflow kollu.
Punti Ewlenin
- L-inputs tal-workflow iridu jkunu JSON-serializzabbli (str, int, float, bool, list, dict)
- Uża Pydantic BaseModel għal inputs strutturati b’validazzjoni awtomatika
- It-timeout predefinit huwa siegħa, konfigurabbli sa massimu ta’ 7 ijiem
- Agħmel distinzjoni bejn it-timeout tal-workflow (
execution_timeout) u t-timeout tal-attività (start_to_close_timeout) - Żomm l-inputs ħfief: IDs u URLs minflok data kbira mhux ipproċessata