Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Vstupy a časové limity

Lekce 9 z 14 Aktualizováno 29. července 2026 Pokročilý
Na této stránce
  1. Co vstupuje do workflow
  2. Struktura a validace s Pydantic
  3. Životnost provádění
  4. Dvě úrovně časových limitů, které si nesmíš plést
  5. Klíčové poznatky

Co vstupuje do workflow

Každé workflow přijímá vstupní parametry, které definují jeho kontext provádění. Protože tyto parametry cestují po síti a jsou ukládány do logu provádění, musí splňovat jedno přísné pravidlo: musí být serializovatelné do formátu JSON. Primitivní typy Pythonu projdou bez problémů, stejně jako seznamy, slovníky a hodnoty 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

Typy datetime, bytes, set, tuple a vlastní třídy, které nejsou založeny na Pydantic, však nejsou přímo podporovány. Pokud tvoje workflow potřebuje přijmout datum faktury, před předáním ji převeď na řetězec ve formátu ISO 8601 a objekt zrekonstruuj až uvnitř aktivity. Tento princip platí pro všechny takové typy: konverze je tvou odpovědností, ne platformy.

Struktura a validace s Pydantic

Předávání volného slovníku funguje, ale ztrácíš jakoukoli záruku ohledně jeho obsahu. Pro strukturované a validované parametry se spolehněte na modely Pydantic, které dokumentují rozhraní workflow stejně dobře, jako jej chrání.

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 straně volajícího není třeba dělat nic zvláštního: pole modelu BaseModel se jednoduše stanou klíči nejvyšší úrovně ve vstupním 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 přijatá data. Pokud je pole neplatné, workflow okamžitě selže s explicitní chybovou zprávou, místo aby se spustilo provádění a o tři aktivity později spadlo. Tato validace se zpřísňuje podle potřeby: omezení formátu pro e-mailovou adresu, číselné meze pro prioritu a především extra = "forbid", které odmítá neznámá pole.

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

Tento poslední bod si zaslouží pozornost. Bez extra="forbid" zůstane překlep v názvu pole bez povšimnutí: očekávané pole přijme svou výchozí hodnotu a workflow běží s parametry, které nejsou tím, co jsi zamýšlel. Selhání je tiché, a proto nákladné.

Když musí jedno workflow přijímat více forem vstupu, umožňují ti typy union popsat tyto varianty bez nutnosti násobit počet 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"

Životnost provádění

Každé workflow má maximální dobu provádění nastavenou parametrem execution_timeout. Ve výchozím nastavení je to jedna hodina: po uplynutí této lhůty je workflow automaticky zrušeno, bez ohledu na jeho postup. Pro proces určený k běhu třicet sekund je tato hodnota pohodlná; pro noční pipeline je to past.

Přizpůsob tento časový limit povaze zpracování, a to jak směrem dolů, tak nahoru. Workflow pro rychlé zpracování těží z přísného limitu, protože jeho překročení pak signalizuje skutečný problém, nikoli dočasné zpomalení.

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 druhém konci je povolený strop 7 dní. Tato délka dává smysl pouze pro procesy čekající na externí událost, typicky na lidské schválení: zpráva nasbíraná automaticky, ale podepsaná manažerem, který se z dovolené nevrátí dříve než příští týden.

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)

Pro kalibraci použij tento řádový odhad podle rodiny použití.

Případ použitíDoporučený časový limit
Zpracování v reálném čase1–5 minut
Datový pipeline15–60 minut
Generování komplexních reportů1–4 hodiny
Workflow s lidskou validací1–7 dní

Dvě úrovně časových limitů, které si nesmíš plést

execution_timeout ohraničuje celé workflow; start_to_close_timeout ohraničuje jednu aktivitu. Oba koexistují a doplňují se: první tě chrání před workflow, které se nikdy nedokončí, druhý před aktivitou zaseknutou na mlčící službě. Všimni si v níže uvedeném příkladu, že časový limit klienta HTTP (240 sekund) je úmyslně nižší než start_to_close_timeout (5 minut), aby se chyba čistě projevila dříve, než platforma přeruší spojení.

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}

Ještě jedna reflexe pro tvé vstupy: udržuj je lehké. Limit je 2 MB a nic tě nenutí se mu přibližovat. Předávej URL dokumentu místo jeho obsahu, ID objednávky místo celé objednávky a nech aktivity, aby data stáhly. Definuj výchozí hodnoty pro vše volitelné, zdokumentuj každé pole pomocí Field(description="...") a svěř validaci Pydanticu místo příkazů if rozházených po celém workflow.

Klíčové poznatky

  • Vstupy workflow musí být serializovatelné do JSON (str, int, float, bool, list, dict)
  • Pro strukturované vstupy s automatickou validací používej Pydantic BaseModel
  • Výchozí časový limit je 1 hodina, konfigurovatelný až na maximum 7 dní
  • Rozlišuj časový limit workflow (execution_timeout) od časového limitu aktivity (start_to_close_timeout)
  • Udržuj vstupy lehké: ID a URL místo velkých surových dat