Syötteet ja aikakatkaisut
Tällä sivulla
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ötapa | Suositeltu aikakatkaisu |
|---|---|
| Reaaliaikainen käsittely | 1–5 minuuttia |
| Dataputkisto | 15–60 minuuttia |
| Monimutkainen raportin generointi | 1–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