Vstupy a časové limity
Na tejto strane
Č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žitia | Odporúčaný časový limit |
|---|---|
| Spracovanie v reálnom čase | 1 – 5 minút |
| Dátové pipeline | 15 – 60 minút |
| Generovanie komplexných správ | 1 – 4 hodiny |
| Workflow s ľudským schválením | 1 – 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