Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Ulazni podaci i vremenska ograničenja

Lekcija 9 od 14 Ažurirano 29. srpnja 2026. Napredno
Na ovoj stranici
  1. Što ulazi u radni tijek
  2. Strukturiranje i validacija s Pydanticom
  3. Životni vijek izvršavanja
  4. Dvije razine vremenskog ograničenja koje ne smiješ brkati
  5. Ključne točke

Što ulazi u radni tijek

Svaki radni tijek prima ulazne parametre koji definiraju njegov kontekst izvršavanja. Budući da ti parametri putuju mrežom i pohranjuju se u zapisu izvršavanja, moraju slijediti jedno strogo pravilo: moraju biti serializabilni u JSON formatu. Pythonovi primitivni tipovi prolaze bez problema, kao i liste, rječnici te null vrijednosti.

# 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

Međutim, datetime, bytes, set, tuple i prilagođene klase koje nisu Pydantic nisu izravno podržani. Ako tvoj radni tijek treba primiti datum fakture, pretvori ga u ISO 8601 niz prije prosljeđivanja, a objekt rekonstruiraj unutar aktivnosti. Ovo načelo vrijedi za sve takve tipove: konverzija je tvoja odgovornost, a ne platforme.

Strukturiranje i validacija s Pydanticom

Prosljeđivanje rječnika slobodne strukture funkcionira, ali gubiš sve garancije o njegovom sadržaju. Za strukturirane i validirane parametre osloni se na Pydantic modele, koji dokumentiraju sučelje radnog tijeka jednako koliko ga i štite.

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 pozivatelja nema ničeg posebnog za napraviti: polja BaseModel jednostavno postaju ključevi najviše razine u ulaznom rječniku.

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 automatski validira primljene podatke. Ako je polje neispravno, radni tijek odmah fails s eksplicitnom porukom o grešci, umjesto da započne izvršavanje i sruši se tek nakon tri aktivnosti. Ova se validacija pooštrava prema potrebi: ograničenja formata za e-mail adresu, numeričke granice za prioritet i, prije svega, extra = "forbid", koje odbija nepoznata 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

Ova posljednja točka zaslužuje pažnju. Bez extra="forbid", tipfeler u nazivu polja prolazi nezapaženo: očekivano polje uzima svoju zadanu vrijednost, a radni tijek se izvršava s parametrima koji nisu ono što si namjeravao. Neuspjeh je tih, stoga i skup.

Kada jedan radni tijek mora prihvatiti više oblika unosa, unija tipova omogućuje opisivanje tih varijanti bez umnožavanja radnih tijekova.

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"

Životni vijek izvršavanja

Svaki radni tijek ima maksimalno trajanje izvršavanja postavljeno parametrom execution_timeout. Zadano je to jedan sat: nakon tog roka radni tijek se automatski otkazuje, bez obzira na napredak. Za proces predviđen da traje trideset sekundi ta je vrijednost ugodna; za pipeline koji radi preko noći to je zamka.

Prilagodi ovo vremensko ograničenje prirodi obrade, i prema dolje i prema gore. Radni tijek brze obrade ima koristi od strogog limita jer prekoračenje tada signalizira stvarni problem, a ne privremeno usporavanje.

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)

S druge strane, dopušteni maksimum je 7 dana. Ovo trajanje ima smisla samo za procese koji čekaju vanjski događaj, tipično ljudsku validaciju: izvještaj prikupljen automatski, ali koji potpisuje voditelj koji se s godišnjeg odmora vraća tek idući tjedan.

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 kalibraciju koristi ovaj red veličine prema obitelji uporabe.

Slučaj uporabePreporučeno vremensko ograničenje
Obrada u stvarnom vremenu1-5 minuta
Podatkovni pipeline15-60 minuta
Generiranje složenih izvještaja1-4 sata
Radni tijek s ljudskom validacijom1-7 dana

Dvije razine vremenskog ograničenja koje ne smiješ brkati

execution_timeout ograničava cijeli radni tijek; start_to_close_timeout ograničava pojedinačnu aktivnost. Ta dva koegzistiraju i nadopunjuju se: prvo te štiti od radnog tijeka koji se nikad ne završi, drugo od aktivnosti koja visi na tihoj usluzi. Primijeti u donjem primjeru da je vremensko ograničenje HTTP klijenta (240 sekundi) namjerno niže od start_to_close_timeout (5 minuta), tako da se greška čisto pojavi prije nego što platforma prekine vezu.

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}

Još jedan refleks za tvoje ulazne podatke: drži ih laganima. Limit je 2 MB i ništa te ne prisiljava da mu se približiš. Proslijedi URL dokumenta umjesto njegovog sadržaja, ID narudžbe umjesto pune narudžbe i prepusti aktivnostima dohvaćanje podataka. Definiraj zadane vrijednosti za sve opcionalno, dokumentiraj svako polje s Field(description="...") i povjeri validaciju Pydanticu umjesto if naredbi razbacanih po radnom tijeku.

Ključne točke

  • Ulazi u radni tijek moraju biti serializabilni u JSON (str, int, float, bool, list, dict)
  • Koristi Pydantic BaseModel za strukturirane ulaze s automatskom validacijom
  • Zadano vremensko ograničenje je 1 sat, podesivo do maksimuma od 7 dana
  • Razlikuj vremensko ograničenje radnog tijeka (execution_timeout) od vremenskog ograničenja aktivnosti (start_to_close_timeout)
  • Drži ulaze laganima: ID-ovi i URL-ovi umjesto velikih sirovih podataka