Sisendid ja ajalõpid
Sellel lehel
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.
| Kasutusjuhtum | Soovitatav ajalõpp |
|---|---|
| Reaalajas töötlemine | 1–5 minutit |
| Andmetorustik | 15–60 minutit |
| Kompleksse aruande genereerimine | 1–4 tundi |
| Inimliku kinnitusega töövoog | 1–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