Salt la conținutul principal
Română— Alege o limbă
Meniu

Intrări și timeout-uri

Lecția 9 din 14 Actualizată 29 iulie 2026 Avansat
Pe această pagină
  1. Ce intră într-un workflow
  2. Structurarea și validarea cu Pydantic
  3. Durata de viață a execuției
  4. Două niveluri de timeout de nu confundat
  5. Puncte cheie

Ce intră într-un workflow

Fiecare workflow primește parametri de intrare care definesc contextul său de execuție. Deoarece acești parametri circulă prin rețea și sunt stocați în jurnalul de execuție, trebuie să respecte o regulă strictă: trebuie să fie serializabili în JSON. Tipurile primitive Python trec fără probleme, la fel ca listele, dicționarele și valorile null.

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

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

# Nullable
commentaire: str | None = None

Totuși, datetime, bytes, set, tuple și clasele personalizate non-Pydantic nu sunt suportate direct. Dacă workflow-ul dumneavoastră trebuie să primească o dată de facturare, convertiți-o într-un șir ISO 8601 înainte de a o transmite și reconstruiți obiectul în interiorul activității. Acest principiu se aplică tuturor acestor tipuri: conversia este responsabilitatea dumneavoastră, nu a platformei.

Structurarea și validarea cu Pydantic

Transmiterea unui dicționar liber funcționează, dar pierdeți orice garanție privind conținutul său. Pentru parametri structurați și validați, bazați-vă pe modelele Pydantic, care documentează interfața workflow-ului la fel de bine cum o protejează.

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

În partea apelantului, nu este nimic special de făcut: câmpurile din BaseModel devin pur și simplu chei de nivel superior în dicționarul de intrare.

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 validează automat datele primite. Dacă un câmp este invalid, workflow-ul eșuează imediat cu un mesaj de eroare explicit, în loc să înceapă execuția și să se blocheze trei activități mai târziu. Această validare se strânge după nevoie: constrângeri de format pentru o adresă de email, limite numerice pentru o prioritate și, mai presus de toate, extra = "forbid", care respinge câmpurile necunoscute.

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

    class Config:
        extra = "forbid"  # Respinge câmpurile necunoscute

Acest ultim punct merită atenție. Fără extra="forbid", o greșeală de tastare într-un nume de câmp trece neobservată: câmpul așteptat își ia valoarea implicită, iar workflow-ul rulează cu parametri care nu sunt cei pe care îi intenționați. Eșecul este silențios, deci costisitor.

Când un singur workflow trebuie să accepte multiple forme de intrare, tipurile union vă permit să descrieți aceste variante fără a multiplica workflow-urile.

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"

Durata de viață a execuției

Fiecare workflow are o durată maximă de execuție, setată prin parametrul execution_timeout. Implicit, este de o oră: după acest termen limită, workflow-ul este anulat automat, indiferent de progresul său. Pentru un proces menit să dureze treizeci de secunde, această valoare este confortabilă; pentru un pipeline peste noapte, este o capcană.

Ajustați acest timeout în funcție de natura procesării, atât în jos, cât și în sus. Un workflow de procesare rapidă beneficiază de o limită strictă, deoarece o depășire semnalează atunci o problemă reală, nu o încetinire temporară.

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)

La celălalt capăt, plafonul permis este de 7 zile. Această durată are sens doar pentru procesele care așteaptă un eveniment extern, tipic o validare umană: un raport colectat automat, dar semnat de un manager care nu se va întoarce din concediu decât săptămâna viitoare.

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:
        # Acest workflow poate dura până la 7 zile
        # Util pentru procesele cu perioade de așteptare umană
        donnees = await collecter_donnees_multi_sources(params)
        validation = await attendre_validation_humaine(donnees)
        return await finaliser_rapport(validation)

Pentru calibrare, folosiți acest ordin de mărime pe familii de utilizare.

Caz de utilizareTimeout recomandat
Procesare în timp real1-5 minute
Pipeline de date15-60 minute
Generare de rapoarte complexe1-4 ore
Workflow cu validare umană1-7 zile

Două niveluri de timeout de nu confundat

execution_timeout limitează întregul workflow; start_to_close_timeout limitează o singură activitate. Cele două coexistă și se completează reciproc: primul vă protejează de un workflow care nu se termină niciodată, al doilea de o activitate blocată pe un serviciu silențios. Observați în exemplul de mai jos că timeout-ul clientului HTTP (240 de secunde) este intenționat mai mic decât start_to_close_timeout (5 minute), astfel încât eroarea să apară clar înainte ca platforma să taie conexiunea.

from datetime import timedelta

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
    # Această activitate are 5 minute pentru a se finaliza
    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:
        # Întregul workflow are 2 ore
        # Dar fiecare activitate individuală are propriul său timeout
        resultats = []
        for source in sources:
            resultat = await appel_api_externe(source)
            resultats.append(resultat)
        return {"résultats": resultats}

Un ultim reflex pentru intrările dumneavoastră: mențineți-le ușoare. Limita este de 2 MB și nimic nu vă obligă să vă apropiați de ea. Transmiteți URL-ul unui document în loc de conținutul său, un ID de comandă în loc de comanda completă și lăsați activitățile să preia datele. Definiți valori implicite pentru tot ce este opțional, documentați fiecare câmp cu Field(description="...") și încredințați validarea lui Pydantic în loc de instrucțiuni if împrăștiate în tot workflow-ul.

Puncte cheie

  • Intrările în workflow trebuie să fie serializabile JSON (str, int, float, bool, list, dict)
  • Folosiți Pydantic BaseModel pentru intrări structurate cu validare automată
  • Timeout-ul implicit este de 1 oră, configurabil până la maximum 7 zile
  • Distingeți timeout-ul workflow-ului (execution_timeout) de timeout-ul activității (start_to_close_timeout)
  • Mențineți intrările ușoare: ID-uri și URL-uri în loc de date brute voluminoase