Vstupy a časové limity
Na této stránce
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 čase | 1–5 minut |
| Datový pipeline | 15–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