Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Vnosi in časovne omejitve

Lekcija 9 od 14 Posodobljeno 29. julij 2026 Napredni
Na tej strani
  1. Kaj gre v delovni tok
  2. Strukturiranje in validacija s Pydantic
  3. Življenjska doba izvrševanja
  4. Dve ravni časovnih omejitev, ki ju ne smeš zamenjati
  5. Ključne ugotovitve

Kaj gre v delovni tok

Vsak delovni tok prejme vhodne parametre, ki opredeljujejo njegov izvršilni kontekst. Ker ti parametri potujejo po omrežju in se shranjujejo v dnevnik izvrševanja, morajo upoštevati eno strogo pravilo: biti morajo serializabilni v JSON. Osnovni tipi Python se prenesejo brez težav, prav tako seznami, slovarji in vrednosti null.

# Primitive types
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True

# Collections
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}

# Nullable
commentaire: str | None = None

Vendar tipi datetime, bytes, set, tuple in razredi po meri, ki niso Pydantic, niso neposredno podprti. Če tvoj delovni tok potrebuje datum računa, ga pred posredovanjem pretvori v niz ISO 8601 in objekt rekonstruiraj znotraj dejavnosti. To načelo velja za vse takšne tipe: pretvorba je tvoja odgovornost, ne platforme.

Strukturiranje in validacija s Pydantic

Posredovanje slovarja proste oblike deluje, vendar izgubiš vsa jamstva glede njegove vsebine. Za strukturirane in validirane parametre se zanesi na modele Pydantic, ki vmesnik delovnega toka dokumentirajo enako dobro, kot ga ščitijo.

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

Na strani klicatelja ni treba storiti ničesar posebnega: polja razreda BaseModel preprosto postanejo ključi najvišje ravni v vhodnem slovarju.

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 samodejno validira prejete podatke. Če je polje neveljavno, delovni tok takoj odpove z jasnim sporočilom o napaki, namesto da bi se začel izvajati in sesul tri dejavnosti kasneje. Ta validacija se po potrebi zaostruje: omejitve oblike za e-poštni naslov, numerične meje za prioriteto in predvsem extra = "forbid", ki zavrača neznana polja.

class ParametresStricts(BaseModel):
    email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
    priorite: int = Field(ge=1, le=5)

    class Config:
        extra = "forbid"  # Rejects unknown fields

Zadnja točka si zasluži pozornost. Brez extra="forbid" tipkarska napaka v imenu polja ostane neopažena: pričakovano polje prevzame privzeto vrednost in delovni tok se izvaja s parametri, ki niso tisti, ki si jih želel. Napaka je tiha, zato draga.

Ko mora en sam delovni tok sprejeti več oblik vnosa, ti tipi unije omogočajo opis teh variant brez množenja delovnih tokov.

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"

Življenjska doba izvrševanja

Vsak delovni tok ima največjo trajanje izvrševanja, določeno s parametrom execution_timeout. Privzeto je to ena ura: po tem roku se delovni tok samodejno prekliče, ne glede na njegov napredek. Za proces, ki naj bi trajal trideset sekund, je ta vrednost udobna; za cevovod, ki teče čez noč, pa je past.

To časovno omejitev prilagodi naravi obdelave, tako navzdol kot navzgor. Delovni tok za hitro obdelavo ima korist od stroge omejitve, saj prekoračitev takrat signalizira resnično težavo in ne zgolj začasnega upočasnitve.

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)

Na drugem koncu je dovoljena zgornja meja 7 dni. To trajanje ima smisel le za procese, ki čakajo na zunanji dogodek, običajno na človeško validacijo: poročilo, zbrano samodejno, ki pa ga mora podpisati vodja, ki se iz dopusta ne vrne do naslednjega tedna.

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:
        # This workflow can last up to 7 days
        # Useful for processes with human waiting periods
        donnees = await collecter_donnees_multi_sources(params)
        validation = await attendre_validation_humaine(donnees)
        return await finaliser_rapport(validation)

Za umerjanje uporabi ta red velikosti glede na družino uporabe.

Primer uporabePriporočena časovna omejitev
Obdelava v realnem času1–5 minut
Podatkovni cevovod15–60 minut
Generiranje kompleksnih poročil1–4 ure
Delovni tok s človeško validacijo1–7 dni

Dve ravni časovnih omejitev, ki ju ne smeš zamenjati

execution_timeout omejuje celoten delovni tok; start_to_close_timeout omejuje posamezno dejavnost. Obe sobivata in se dopolnjujeta: prva te ščiti pred delovnim tokom, ki se nikoli ne konča, druga pred dejavnostjo, ki visi na tihi storitvi. V spodnjem primeru opazi, da je časovna omejitev odjemalca HTTP (240 sekund) namerno nižja od start_to_close_timeout (5 minut), tako da se napaka čisto izpiše, preden platforma prekine povezavo.

from datetime import timedelta

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
    # This activity has 5 minutes to complete
    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:
        # The entire workflow has 2 hours
        # But each individual activity has its own timeout
        resultats = []
        for source in sources:
            resultat = await appel_api_externe(source)
            resultats.append(resultat)
        return {"résultats": resultats}

Še en zadnji refleks za tvoje vnose: ohrani jih lahke. Omejitev je 2 MB in nič te ne sili, da se ji približaš. Posreduj URL dokumenta namesto njegove vsebine, ID naročila namesto celotnega naročila in prepusti dejavnostim, da pridobijo podatke. Za vse izbirno določi privzete vrednosti, vsako polje dokumentiraj z Field(description="...") in validacijo prepusti Pydanticu namesto stavkom if, raztresenim po delovnem toku.

Ključne ugotovitve

  • Vnosi v delovni tok morajo biti serializabilni v JSON (str, int, float, bool, list, dict)
  • Za strukturirane vnose z samodejno validacijo uporabi Pydantic BaseModel
  • Privzeta časovna omejitev je 1 ura, nastavljiva do največ 7 dni
  • Razlikuj časovno omejitev delovnega toka (execution_timeout) od časovne omejitve dejavnosti (start_to_close_timeout)
  • Ohrani vnose lahke: ID-ji in URL-ji namesto velikih surovih podatkov