Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Inputs u timeouts

Lezzjoni 9 / 14 Aġġornat 29 ta’ Lulju 2026 Avvanzat
F'din il-paġna
  1. X’jidħol f’workflow
  2. Iddeskrivi u vvalida b’Pydantic
  3. Ħajja tal-eżekuzzjoni
  4. Żewġ livelli ta’ timeout li m’għandekx tħawwad
  5. Punti Ewlenin

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żuTimeout rakkomandat
Ipproċessar f’ħin reali1-5 minuti
Pipeline tad-data15-60 minuta
Ġenerazzjoni ta’ rapport kumpless1-4 sigħat
Workflow b’validazzjoni umana1-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