Inputs en time-outs
Op deze pagina
Wat gaat er in een workflow
Elke workflow ontvangt invoerparameters die de uitvoeringscontext definiëren. Omdat deze parameters via het netwerk worden verzonden en in het uitvoeringslogboek worden opgeslagen, moeten ze één strikte regel volgen: ze moeten JSON-serialiseerbaar zijn. Python-primitieven werken zonder problemen, evenals lijsten, dictionaries en null-waarden.
# Primitieve types
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True
# Collecties
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}
# Nullable
commentaire: str | None = None
datetime, bytes, set, tuple en niet-Pydantic aangepaste klassen worden echter niet direct ondersteund. Als uw workflow een factuurdatum moet ontvangen, converteer deze dan naar een ISO 8601-tekenreeks voordat u deze doorgeeft, en reconstrueer het object binnen de activiteit. Dit principe geldt voor al dergelijke types: conversie is uw verantwoordelijkheid, niet die van het platform.
Structureren en valideren met Pydantic
Het doorgeven van een vrij gevormde dictionary werkt, maar u verliest alle garanties over de inhoud. Voor gestructureerde, gevalideerde parameters vertrouwt u op Pydantic-modellen, die de workflow-interface documenteren én beschermen.
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
Aan de kant van de aanroeper is er niets bijzonders nodig: de velden van het BaseModel worden simpelweg top-level sleutels in de invoerdictionary.
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 valideert ontvangen gegevens automatisch. Als een veld ongeldig is, faalt de workflow onmiddellijk met een expliciete foutmelding, in plaats van de uitvoering te starten en pas drie activiteiten later te crashen. Deze validatie wordt zo streng als nodig: formaatbeperkingen op een e-mailadres, numerieke grenzen op een prioriteit, en bovenal extra = "forbid", wat onbekende velden weigert.
class ParametresStricts(BaseModel):
email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
priorite: int = Field(ge=1, le=5)
class Config:
extra = "forbid" # Weigert onbekende velden
Dit laatste punt verdient aandacht. Zonder extra="forbid" blijft een typefout in een veldnaam onopgemerkt: het verwachte veld neemt zijn standaardwaarde aan en de workflow draait met parameters die niet zijn wat u bedoelde. De fout is stil, en dus kostbaar.
Wanneer één workflow meerdere vormen van invoer moet accepteren, laten union-types u toe deze varianten te beschrijven zonder workflows te vermenigvuldigen.
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"
Levensduur van de uitvoering
Elke workflow heeft een maximale uitvoeringsduur, ingesteld via de parameter execution_timeout. Standaard is dit één uur: na deze deadline wordt de workflow automatisch geannuleerd, ongeacht de voortgang. Voor een proces dat dertig seconden moet duren, is deze waarde comfortabel; voor een nachtelijke pipeline is het een valstrik.
Pas deze time-out aan op de aard van de verwerking, zowel naar beneden als naar boven. Een snel verwerkende workflow heeft baat bij een strakke limiet, omdat een overschrijding dan een echt probleem signaleert in plaats van een tijdelijke vertraging.
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)
Aan de andere kant is het toegestane maximum 7 dagen. Deze duur is alleen zinvol voor processen die wachten op een externe gebeurtenis, typisch menselijke validatie: een rapport dat automatisch wordt verzameld maar ondertekend moet worden door een manager die pas volgende week terugkomt van verlof.
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:
# Deze workflow kan tot 7 dagen duren
# Nuttig voor processen met wachttijden voor menselijke tussenkomst
donnees = await collecter_donnees_multi_sources(params)
validation = await attendre_validation_humaine(donnees)
return await finaliser_rapport(validation)
Gebruik voor de kalibratie deze orde van grootte per gebruiksfamilie.
| Use case | Aanbevolen time-out |
|---|---|
| Real-time verwerking | 1-5 minuten |
| Data-pipeline | 15-60 minuten |
| Genereren van complexe rapporten | 1-4 uur |
| Workflow met menselijke validatie | 1-7 dagen |
Twee time-out niveaus die u niet mag verwarren
execution_timeout begrenst de volledige workflow; start_to_close_timeout begrenst een enkele activiteit. De twee bestaan naast elkaar en vullen elkaar aan: de eerste beschermt u tegen een workflow die nooit voltooid wordt, de tweede tegen een activiteit die blijft hangen op een stille service. Merk in het onderstaande voorbeeld op dat de time-out van de HTTP-client (240 seconden) bewust lager is dan de start_to_close_timeout (5 minuten), zodat de fout netjes boven water komt voordat het platform de verbinding verbreekt.
from datetime import timedelta
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
# Deze activiteit heeft 5 minuten om te voltooien
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:
# De volledige workflow heeft 2 uur
# Maar elke individuele activiteit heeft zijn eigen time-out
resultats = []
for source in sources:
resultat = await appel_api_externe(source)
resultats.append(resultat)
return {"résultats": resultats}
Eén laatste reflex voor uw inputs: houd ze licht. De limiet is 2 MB, en niets dwingt u om deze te benaderen. Geef de URL van een document door in plaats van de inhoud, een bestel-ID in plaats van de volledige bestelling, en laat de activiteiten de data ophalen. Definieer standaardwaarden voor alles wat optioneel is, documenteer elk veld met Field(description="..."), en vertrouw de validatie toe aan Pydantic in plaats van aan if-statements die door de workflow verspreid staan.
Belangrijkste punten
- Workflow-invoer moet JSON-serialiseerbaar zijn (str, int, float, bool, list, dict)
- Gebruik Pydantic BaseModel voor gestructureerde invoer met automatische validatie
- De standaard time-out is 1 uur, configureerbaar tot maximaal 7 dagen
- Onderscheid de time-out van de workflow (
execution_timeout) van die van de activiteit (start_to_close_timeout) - Houd inputs licht: ID’s en URL’s in plaats van grote ruwe data