Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Syötteet ja aikakatkaisut

Oppitunti 9 / 14 Päivitetty 29. heinäkuuta 2026 Edistynyt
Tällä sivulla
  1. Mitä workflow vastaanottaa
  2. Rakenne ja validointi Pydanticilla
  3. Suorituksen elinkaari
  4. Kaksi aikakatasutasoa, joita ei saa sekoittaa
  5. Keskeiset asiat

Mitä workflow vastaanottaa

Jokainen workflow vastaanottaa syöteparametreja, jotka määrittävät sen suoritusympäristön. Koska nämä parametrit kulkevat verkon yli ja tallennetaan suorituslokiin, niiden on noudatettava yhtä tiukkaa sääntöä: niiden on oltava JSON-serialisoitavia. Pythonin primitiiviset tyypit toimivat ongelmitta, samoin listat, sanakirjat ja null-arvot.

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

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

# Tyhjä arvo mahdollinen
commentaire: str | None = None

Kuitenkin datetime, bytes, set, tuple ja ei-Pydantic-mukautetut luokat eivät ole suoraan tuettuja. Jos workflowsi tarvitsee vastaanottaa laskun päivämäärän, muunna se ISO 8601 -merkkijonoksi ennen välittämistä ja muodosta olio uudelleen activityn sisällä. Tämä periaate pätee kaikkiin vastaaviin tyyppeihin: muunnos on sinun vastuullasi, ei alustan.

Rakenne ja validointi Pydanticilla

Vapaamuotoisen sanakirjan välittäminen toimii, mutta menetat kaikki takuut sen sisällöstä. Jäsenneltyjen ja validoituja parametreja varten luota Pydantic-malleihin, jotka dokumentoivat workflown rajapinnan yhtä paljon kuin suojaavatkin sitä.

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

Kutsujan puolella ei tarvitse tehdä mitään erityistä: BaseModel-kentistä tulee yksinkertaisesti ylintason avaimia syötesanakirjassa.

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 validoi vastaanotetut tiedot automaattisesti. Jos kenttä on virheellinen, workflow epäonnistuu välittömästi selkeällä virheilmoituksella sen sijaan, että suoritus alkaisi ja kaatuisi kolme activityä myöhemmin. Tämä validointi kiristyy tarpeen mukaan: sähköpostiosoitteen muotorajoitukset, prioriteetin numeeriset rajat ja ennen kaikkea extra = "forbid", joka hylkää tuntemattomat kentät.

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

    class Config:
        extra = "forbid"  # Hylkää tuntemattomat kentät

Tämä viimeinen kohta ansaitsee huomiota. Ilman extra="forbid"-asetusta kirjoitusvirhe kentän nimessä jää huomaamatta: odotettu kenttä saa oletusarvonsa ja workflow suoritetaan parametreilla, jotka eivät ole niitä, mitä aioit. Virhe on hiljainen, joten se tulee kalliiksi.

Kun yhden workflown on hyväksyttävä useita syötemuotoja, unionityypit mahdollistavat näiden variaatioiden kuvaamisen ilman workflowjen määrän kasvattamista.

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"

Suorituksen elinkaari

Jokaisella workflowlla on enimmäissuoritusaika, jonka asettaa execution_timeout-parametri. Oletusarvoisesti se on yksi tunti: tämän takarajan jälkeen workflow peruutetaan automaattisesti etenemisestä riippumatta. Prosessille, jonka on tarkoitus kestää kolmekymmentä sekuntia, tämä arvo on mukava; yön yli jatkuvalle putkistolle se on ansa.

Säädä tämä aikakatkaisu käsittelyn luonteen mukaan sekä alaspäin että ylöspäin. Nopeasti käsittelevä workflow hyötyy tiukasta rajasta, koska ylitys merkitsee silloin todellista ongelmaa eikä väliaikaista hidastumista.

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)

Toisessa ääripäässä sallittu katto on 7 päivää. Tämä kesto on järkevä vain prosesseille, jotka odottavat ulkoista tapahtumaa, tyypillisesti ihmisen hyväksyntää: raportti kerätään automaattisesti, mutta sen allekirjoittaa johtaja, joka ei palaa lomalta ennen ensi viikkoa.

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:
        # Tämä workflow voi kestää jopa 7 päivää
        # Hyödyllinen prosesseille, joissa odotetaan ihmisen toimia
        donnees = await collecter_donnees_multi_sources(params)
        validation = await attendre_validation_humaine(donnees)
        return await finaliser_rapport(validation)

Kalibrointiin käytä tätä suuruusluokkaa käyttötarkoituksen mukaan.

KäyttötapaSuositeltu aikakatkaisu
Reaaliaikainen käsittely1–5 minuuttia
Dataputkisto15–60 minuuttia
Monimutkainen raportin generointi1–4 tuntia
Workflow ihmisen hyväksynnällä1–7 päivää

Kaksi aikakatasutasoa, joita ei saa sekoittaa

execution_timeout rajoittaa koko workflowta; start_to_close_timeout rajoittaa yhtä activityä. Nämä kaksi esiintyvät rinnakkain ja täydentävät toisiaan: ensimmäinen suojaa sinua workflowlta, joka ei koskaan valmistu, toinen activityltä, joka jumittuu hiljaiseen palveluun. Huomaa alla olevassa esimerkissä, että HTTP-asiakkaan aikakatkaisu (240 sekuntia) on tarkoituksellisesti pienempi kuin start_to_close_timeout (5 minuuttia), jotta virhe nousee puhtaasti esiin ennen kuin alusta katkaisee yhteyden.

from datetime import timedelta

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
    # Tällä activityllä on 5 minuuttia aikaa valmistua
    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:
        # Koko workflowlla on 2 tuntia aikaa
        # Mutta jokaisella yksittäisellä activityllä on oma aikakatkaisunsa
        resultats = []
        for source in sources:
            resultat = await appel_api_externe(source)
            resultats.append(resultat)
        return {"résultats": resultats}

Viimeinen refleksi syötteillesi: pidä ne kevyinä. Raja on 2 Mt, eikä mikään pakota sinua lähestymään sitä. Välitä dokumentin URL sen sisällön sijaan, tilauksen ID koko tilauksen sijaan, ja anna activityjen hakea data. Määritä oletusarvot kaikelle valinnaiselle, dokumentoi jokainen kenttä käyttämällä Field(description="...") ja usko validointi Pydanticille eikä workflowhun hajautetuille if-lauseille.

Keskeiset asiat

  • Workflow-syötteiden on oltava JSON-serialisoituvia (str, int, float, bool, list, dict)
  • Käytä Pydantic BaseModel -mallia jäsenneltyihin syötteisiin automaattisella validoinnilla
  • Oletusaikakatkaisu on 1 tunti, säädettävissä enintään 7 päivään asti
  • Erota workflown aikakatkaisu (execution_timeout) activityn aikakatkaisusta (start_to_close_timeout)
  • Pidä syötteet kevyinä: ID:t ja URL-osoitteet suurten raakadatojen sijaan