Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Sisendid ja ajalõpid

Õppetund 9 / 14 Värskendatud 29. juuli 2026 Edasijõudnutele
Sellel lehel
  1. Mis läheb töövoogu
  2. Struktureeri ja valideeri Pydanticuga
  3. Täitmise eluiga
  4. Kaks ajalõpu taset, mida mitte segi ajada
  5. Peamised punktid

Mis läheb töövoogu

Iga töövoog saab sisendparameetreid, mis määravad selle täitmise konteksti. Kuna need parameetrid liiguvad võrgu kaudu ja salvestatakse täitmislogisse, peavad need järgima üht ranget reeglit: need peavad olema JSON-seeritavad. Pythoni primitiivtüübid toimivad probleemideta, samuti loendid, sõnastikud ja nullväärtused.

# Primitiivtüübid
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True

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

# Nullitavad
commentaire: str | None = None

Siiski ei toetata otseselt tüüpe datetime, bytes, set, tuple ega mittemidagi Pydanticu kohandatud klasse. Kui su töövoog peab vastu võtma arve kuupäeva, teisenda see enne edastamist ISO 8601 vormingusse stringiks ja rekonstrueeri objekt tegevuse sees. See põhimõte kehtib kõigi selliste tüüpide kohta: teisendamine on sinu vastutus, mitte platvormi oma.

Struktureeri ja valideeri Pydanticuga

Vabas vormingus sõnastiku edastamine toimib, kuid kaotad kõik garantiid selle sisu osas. Struktureeritud ja valideeritud parameetrite jaoks tugine Pydanticu mudelitele, mis dokumenteerivad töövoogu liidest sama palju, kui nad seda kaitsevad.

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

Kutsuja poolel pole midagi erilist teha: BaseModel väljad muutuvad lihtsalt sisendsõnastiku ülemise taseme võtmeteks.

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 valideerib saadud andmed automaatselt. Kui väli on vigane, ebaõnnestub töövoog kohe selge veateatega, selle asemel et alustada täitmist ja kukkuda läbi kolm tegevust hiljem. See valideerimine muutub vajadusel rangemaks: e-posti aadressi vormingupiirangud, prioriteedi arvvahemikud ja ennekõike extra = "forbid", mis lükkab tagasi tundmatud väljad.

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

    class Config:
        extra = "forbid"  # Lükkab tagasi tundmatud väljad

See viimane punkt väärib tähelepanu. Ilma extra="forbid"-ita jääb väljanimes trükiviga märkamatuks: oodatud väli võtab oma vaikeväärtuse ja töövoog käivitub parameetritega, mis ei ole need, mida sa kavatsesid. Rike on vaikne ja seetõttu kulukas.

Kui üks töövoog peab vastu võtma mitut sisendivormi, võimaldavad liittüübid kirjeldada neid variante ilma töövoogude arvu suurendamata.

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"

Täitmise eluiga

Igal töövoog on maksimaalne täitmise kestus, mis on määratud parameetriga execution_timeout. Vaikimisi on see üks tund: pärast seda tähtaega tühistatakse töövoog automaatselt, sõltumata selle edenemisest. Protsessi jaoks, mis peaks kestma kolmkümmend sekundit, on see väärtus mugav; üleöö kestva torustiku puhul on see lõks.

Kohanda seda ajalõppu töötlemise olemusele, nii allapoole kui ka ülespoole. Kiire töötlemisega töövoog saab kasu kitsast piirangust, sest ületamine annab siis märku reaalsest probleemist, mitte ajutisest aeglustumisest.

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)

Teises otsas on lubatud lagi 7 päeva. See kestus on mõttekas ainult protsesside jaoks, mis ootavad välist sündmust, tüüpiliselt inimlikku kinnitust: näiteks automaatselt kogutud aruanne, mille allkirjastab juht, kes naaseb puhkuselt alles järgmisel nädalal.

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:
        # See töövoog võib kesta kuni 7 päeva
        # Kasulik protsesside jaoks, kus oodatakse inimese sekkumist
        donnees = await collecter_donnees_multi_sources(params)
        validation = await attendre_validation_humaine(donnees)
        return await finaliser_rapport(validation)

Kalibreerimiseks kasuta seda suurusjärku kasutusvaldkondade kaupa.

KasutusjuhtumSoovitatav ajalõpp
Reaalajas töötlemine1–5 minutit
Andmetorustik15–60 minutit
Kompleksse aruande genereerimine1–4 tundi
Inimliku kinnitusega töövoog1–7 päeva

Kaks ajalõpu taset, mida mitte segi ajada

execution_timeout piirab kogu töövoogu; start_to_close_timeout piirab ühte tegevust. Need kaks eksisteerivad kõrvuti ja täiendavad teineteist: esimene kaitseb sind töövoogu eest, mis kunagi ei lõpe, teine tegevuse eest, mis jääb vaikiva teenuse otsa rippuma. Pane allolevas näites tähele, et HTTP-kliendi ajalõpp (240 sekundit) on tahtlikult madalam kui start_to_close_timeout (5 minutit), nii et viga tuleb puhtalt välja enne, kui platvorm ühenduse katkestab.

from datetime import timedelta

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
    # Sellel tegevusel on 5 minutit lõpuleviimiseks
    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:
        # Kogu töövoogul on 2 tundi
        # Kuid igal üksikul tegevusel on oma ajalõpp
        resultats = []
        for source in sources:
            resultat = await appel_api_externe(source)
            resultats.append(resultat)
        return {"résultats": resultats}

Viimane refleks sinu sisendite jaoks: hoia need kerged. Piirang on 2 MB ja miski ei sunni sind sellele lähenema. Edasta dokumendi URL selle sisu asemel, tellimuse ID kogu tellimuse asemel ja lase tegevustel andmed hankida. Määra vaikeväärtused kõigele valikulisele, dokumenteeri iga väli käsuga Field(description="...") ja usalda valideerimine Pydanticule, mitte töövoogu laiali pillutatud if-lauseid.

Peamised punktid

  • Töövoogude sisendid peavad olema JSON-seeritavad (str, int, float, bool, list, dict)
  • Kasuta Pydantic BaseModel-it struktureeritud sisendite jaoks automaatse valideerimisega
  • Vaikimisi ajalõpp on 1 tund, konfigureeritav maksimaalselt 7 päevani
  • Tee vahet töövoogu ajalõpul (execution_timeout) ja tegevuse ajalõpul (start_to_close_timeout)
  • Hoia sisendid kerged: ID-d ja URL-id suurte toorandmete asemel