Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Vstupy a časové limity

Lekcia 9 z 14 Aktualizované 29. júla 2026 Pokročilý
Na tejto strane
  1. Čo vstupuje do workflow
  2. Štruktúrovanie a validácia pomocou Pydantic
  3. Životnosť vykonávania
  4. Dve úrovne časových limitov, ktoré si nesmieš pomýliť
  5. Kľúčové poznatky

Čo vstupuje do workflow

Každé workflow dostáva vstupné parametre, ktoré definujú jeho kontext vykonávania. Keďže tieto parametre cestujú po sieti a ukladajú sa do logu vykonávania, musia dodržiavať jedno prísne pravidlo: musia byť serializovateľné do formátu JSON. Primitívne typy Pythonu prechádzajú bez problémov, rovnako ako zoznamy, slovníky a hodnoty null.

# Primitívne typy
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True

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

# Nullable
commentaire: str | None = None

Typy datetime, bytes, set, tuple a vlastné triedy, ktoré nie sú založené na Pydantic, však nie sú priamo podporované. Ak tvoje workflow potrebuje prijímať dátum faktúry, pred odovzdaním ho skonvertuj na reťazec ISO 8601 a objekt zrekonštruuj až vo vnútri aktivity. Tento princíp platí pre všetky takéto typy: konverzia je tvojou zodpovednosťou, nie platformy.

Štruktúrovanie a validácia pomocou Pydantic

Odovzdanie voľného slovníka funguje, ale strácaš všetky záruky týkajúce sa jeho obsahu. Pre štruktúrované a validované parametre sa spoliehaj na modely Pydantic, ktoré dokumentujú rozhranie workflow rovnako dobre, ako ho chránia.

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 strane volajúceho nie je potrebné robiť nič špeciálne: polia modelu BaseModel sa jednoducho stanú kľúčmi najvyššej úrovne vo vstupnom slovníku.

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 automaticky validuje prijaté údaje. Ak je pole neplatné, workflow okamžite zlyhá s explicitnou chybovou správou, namiesto toho, aby sa spustilo vykonávanie a o tri aktivity neskôr spadlo. Táto validácia sa podľa potreby sprísňuje: obmedzenia formátu pre e-mailovú adresu, číselné hranice pre prioritu a predovšetkým extra = "forbid", ktoré odmieta neznáme polia.

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

    class Config:
        extra = "forbid"  # Odmietne neznáme polia

Tento posledný bod si zaslúži pozornosť. Bez extra="forbid" preklep v názve poľa zostane nepovšimnutý: očakávané pole prijme svoju predvolenú hodnotu a workflow beží s parametrami, ktoré nie sú tým, čo si zamýšľal. Zlyhanie je tiché, a preto nákladné.

Keď jedno workflow musí akceptovať viacero foriem vstupu, zjednotené typy (union types) ti umožnia opísať tieto varianty bez násobenia počtu workflow.

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"

Životnosť vykonávania

Každé workflow má maximálnu dobu trvania vykonávania, nastavenú parametrom execution_timeout. Predvolene je to jedna hodina: po uplynutí tejto lehoty sa workflow automaticky zruší, bez ohľadu na jeho postup. Pre proces určený na tridsať sekúnd je táto hodnota pohodlná; pre pipeline bežiace cez noc je to pasca.

Prispôsob tento časový limit povahe spracovania, smerom nadol aj nahor. Workflow rýchleho spracovania ťaží z prísneho limitu, pretože jeho prekročenie potom signalizuje skutočný problém, a nie dočasné spomalenie.

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 druhom konci je povolený strop 7 dní. Táto dĺžka dáva zmysel len pre procesy čakajúce na externú udalosť, typicky na ľudské schválenie: správa získaná automaticky, ale podpísaná manažérom, ktorý sa z dovolenky vráti až budúci týždeň.

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:
        # Toto workflow môže trvať až 7 dní
        # Užitočné pre procesy s čakacími lehotami na ľudský zásah
        donnees = await collecter_donnees_multi_sources(params)
        validation = await attendre_validation_humaine(donnees)
        return await finaliser_rapport(validation)

Na kalibráciu použi tento rádový poriadok podľa rodiny použitia.

Prípad použitiaOdporúčaný časový limit
Spracovanie v reálnom čase1 – 5 minút
Dátové pipeline15 – 60 minút
Generovanie komplexných správ1 – 4 hodiny
Workflow s ľudským schválením1 – 7 dní

Dve úrovne časových limitov, ktoré si nesmieš pomýliť

execution_timeout ohraničuje celé workflow; start_to_close_timeout ohraničuje jednu aktivitu. Obe koexistujú a dopĺňajú sa: prvá ťa chráni pred workflow, ktoré sa nikdy nedokončí, druhá pred aktivitou, ktorá visí na tichej službe. Všimni si v príklade nižšie, že časový limit klienta HTTP (240 sekúnd) je zámerne nižší ako start_to_close_timeout (5 minút), aby sa chyba objavila čisto skôr, než platforma preruší spojenie.

from datetime import timedelta

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
    # Táto aktivita má na dokončenie 5 minút
    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:
        # Celé workflow má 2 hodiny
        # Ale každá jednotlivá aktivita má svoj vlastný časový limit
        resultats = []
        for source in sources:
            resultat = await appel_api_externe(source)
            resultats.append(resultat)
        return {"résultats": resultats}

Ešte jedna reflexia pre tvoje vstupy: udržuj ich ľahké. Limit je 2 MB a nič ťa nenúti sa k nemu približovať. Odovzdaj URL dokumentu namiesto jeho obsahu, ID objednávky namiesto celej objednávky a nechaj aktivity, aby si údaje stiahli. Definuj predvolené hodnoty pre všetko voliteľné, zdokumentuj každé pole pomocou Field(description="...") a zver validáciu Pydanticu namiesto príkazov if roztrúsených po celom workflow.

Kľúčové poznatky

  • Vstupy workflow musia byť serializovateľné do JSON (str, int, float, bool, list, dict)
  • Na štruktúrované vstupy s automatickou validáciou používaj Pydantic BaseModel
  • Predvolený časový limit je 1 hodina, nastaviteľný maximálne na 7 dní
  • Rozlišuj časový limit workflow (execution_timeout) od časového limitu aktivity (start_to_close_timeout)
  • Udržuj vstupy ľahké: ID a URL namiesto veľkých surových dát