Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Inputs og timeouts

Lektion 9 af 14 Opdateret 29. juli 2026 Avanceret
På denne side
  1. Hvad går ind i et workflow
  2. Strukturér og valider med Pydantic
  3. Eksekveringens levetid
  4. To timeout-niveauer, du ikke må forveksle
  5. Vigtige pointer

Hvad går ind i et workflow

Ethvert workflow modtager inputparametre, der definerer dets eksekveringskontekst. Da disse parametre rejser over netværket og gemmes i eksekveringsloggen, skal de overholde én streng regel: de skal være JSON-serialiserbare. Python-primitivtyper fungerer uden problemer, det samme gør lister, ordbøger og null-værdier.

# Primitive typer
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True

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

# Nullable
commentaire: str | None = None

datetime, bytes, set, tuple og ikke-Pydantic brugerdefinerede klasser understøttes dog ikke direkte. Hvis dit workflow skal modtage en fakturadato, skal du konvertere den til en ISO 8601-streng, før du sender den videre, og rekonstruere objektet inde i aktiviteten. Dette princip gælder for alle sådanne typer: konverteringen er dit ansvar, ikke platformens.

Strukturér og valider med Pydantic

Det fungerer at sende en frit formet ordbog, men du mister alle garantier for dens indhold. Til strukturerede, validerede parametre bør du stole på Pydantic-modeller, som dokumenterer workflow-grænsefladen lige så meget, som de beskytter den.

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

På kaldersiden er der intet særligt at gøre: felterne i BaseModel bliver blot til topnøgle i input-ordbogen.

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 validerer automatisk modtagne data. Hvis et felt er ugyldigt, fejler workflowet øjeblikkeligt med en eksplicit fejlmeddelelse i stedet for at starte eksekveringen og crashe tre aktiviteter senere. Denne validering strammes efter behov: formatbegrænsninger på en e-mailadresse, numeriske grænser for en prioritet og frem for alt extra = "forbid", som afviser ukendte felter.

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

    class Config:
        extra = "forbid"  # Afviser ukendte felter

Dette sidste punkt fortjener opmærksomhed. Uden extra="forbid" går en stavefejl i et feltnavn ubemærket hen: det forventede felt får sin standardværdi, og workflowet kører med parametre, der ikke er dem, du intendede. Fejlen er tavs og derfor dyr.

Når et enkelt workflow skal acceptere flere former for input, lader unionstyper dig beskrive disse varianter uden at gange workflows op.

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"

Eksekveringens levetid

Ethvert workflow har en maksimal eksekveringsvarighed, indstillet via parameteren execution_timeout. Som standard er den én time: efter denne frist annulleres workflowet automatisk, uanset dets fremskridt. For en proces, der er beregnet til at vare tredive sekunder, er denne værdi komfortabel; for en overnight-pipeline er det en fælde.

Juster denne timeout til behandlingens art, både nedad og opad. Et hurtigt bearbejdende workflow drager fordel af en stram grænse, fordi en overskridelse så signalerer et reelt problem snarere end en midlertidig afmatning.

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)

I den anden ende er det tilladte loft 7 dage. Denne varighed giver kun mening for processer, der venter på en ekstern begivenhed, typisk menneskelig validering: en rapport indsamlet automatisk, men underskrevet af en leder, der først vender tilbage fra ferie ugen efter.

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:
        # Dette workflow kan vare op til 7 dage
        # Nyttigt til processer med menneskelige venteperioder
        donnees = await collecter_donnees_multi_sources(params)
        validation = await attendre_validation_humaine(donnees)
        return await finaliser_rapport(validation)

Brug denne størrelsesorden efter brugskategori til kalibrering.

BrugssagAnbefalet timeout
Realtidsbehandling1-5 minutter
Datapipeline15-60 minutter
Generering af komplekse rapporter1-4 timer
Workflow med menneskelig validering1-7 dage

To timeout-niveauer, du ikke må forveksle

execution_timeout afgrænser hele workflowet; start_to_close_timeout afgrænser en enkelt aktivitet. De to sameksisterer og supplerer hinanden: den første beskytter dig mod et workflow, der aldrig fuldføres, den anden mod en aktivitet, der hænger på en tavs tjeneste. Bemærk i eksemplet nedenfor, at HTTP-klientens timeout (240 sekunder) bevidst er lavere end start_to_close_timeout (5 minutter), så fejlen kommer tydeligt frem, før platformen afbryder forbindelsen.

from datetime import timedelta

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
    # Denne aktivitet har 5 minutter til at fuldføre
    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:
        # Hele workflowet har 2 timer
        # Men hver enkelt aktivitet har sin egen timeout
        resultats = []
        for source in sources:
            resultat = await appel_api_externe(source)
            resultats.append(resultat)
        return {"résultats": resultats}

Én sidste refleks for dine inputs: hold dem lette. Grænsen er 2 MB, og intet tvinger dig til at nærme dig den. Send URL’en til et dokument i stedet for dets indhold, en ordre-ID i stedet for hele ordren, og lad aktiviteterne hente dataene. Definer standardværdier for alt valgfrit, dokumentér hvert felt med Field(description="..."), og overlad valideringen til Pydantic frem for if-sætninger spredt ud over workflowet.

Vigtige pointer

  • Workflow-input skal være JSON-serialiserbare (str, int, float, bool, list, dict)
  • Brug Pydantic BaseModel til strukturerede inputs med automatisk validering
  • Standard-timeout er 1 time, konfigurerbar op til maksimalt 7 dage
  • Skel mellem workflow-timeout (execution_timeout) og aktivitets-timeout (start_to_close_timeout)
  • Hold inputs lette: ID’er og URL’er frem for store rådata