Bemenetek és időtúllépések
Ezen az oldalon
Mi kerül egy munkafolyamatba
Minden munkafolyamat bemeneti paramétereket kap, amelyek meghatározzák a végrehajtási kontextust. Mivel ezek a paraméterek a hálózaton utaznak és elmentésre kerülnek a végrehajtási naplóban, egy szigorú szabályt kell követniük: JSON-szerializálhatónak kell lenniük. A Python primitív típusok gond nélkül működnek, akárcsak a listák, szótárak és null értékek.
# Primitív típusok
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True
# Gyűjtemények
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}
# Nullázható
commentaire: str | None = None
Ugyanakkor a datetime, bytes, set, tuple és a nem-Pydantic egyedi osztályok nem támogatottak közvetlenül. Ha a munkafolyamatodnak számla dátumot kell fogadnia, alakítsd át ISO 8601 formátumú sztringgé a továbbítás előtt, és a tevékenységen belül állítsd vissza az objektumot. Ez az elv minden ilyen típusra vonatkozik: az átalakítás a te felelősséged, nem a platformé.
Struktúra és validálás Pydantic segítségével
Egy kötetlen szótár átadása működik, de elveszíted a garanciákat a tartalmára vonatkozóan. A strukturált, validált paraméterekhez támaszkodj a Pydantic modellekre, amelyek ugyanúgy dokumentálják a munkafolyamat interfészét, mint ahogy védik is azt.
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
A hívó oldalon nincs külön teendő: a BaseModel mezői egyszerűen felső szintű kulcsokká válnak a bemeneti szótárban.
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
}
)
A Pydantic automatikusan validálja a fogadott adatokat. Ha egy mező érvénytelen, a munkafolyamat azonnal megszakad egy egyértelmű hibaüzenettel, ahelyett, hogy elindulna, és három tevékenységgel később összeomlana. Ez a validálás szükség szerint szigorodik: formátum-korlátozások egy e-mail címre, numerikus határok egy prioritásra, és mindenekelőtt az extra = "forbid", amely elutasítja az ismeretlen mezőket.
class ParametresStricts(BaseModel):
email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
priorite: int = Field(ge=1, le=5)
class Config:
extra = "forbid" # Elutasítja az ismeretlen mezőket
Ez az utóbbi pont figyelmet érdemel. Az extra="forbid" nélkül egy elgépelés a mező nevében észrevétlen marad: a várt mező felveszi az alapértelmezett értékét, és a munkafolyamat olyan paraméterekkel fut, amelyek nem azok, amiket szántál. A hiba csendes, ezért költséges.
Amikor egyetlen munkafolyamatnak többféle bemeneti formát kell elfogadnia, a union típusok lehetővé teszik ezeknek a variánsoknak a leírását anélkül, hogy megszoroznád a munkafolyamatok számát.
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"
Végrehajtási élettartam
Minden munkafolyamatnak van egy maximális végrehajtási ideje, amelyet az execution_timeout paraméter állít be. Alapértelmezés szerint ez egy óra: ezen a határidőn túl a munkafolyamat automatikusan megszakad, függetlenül az előrehaladástól. Egy harminc másodpercig tartó folyamatnál ez az érték kényelmes; egy éjszakai pipeline esetén csapda.
Állítsd be ezt az időtúllépést a feldolgozás jellegéhez igazodva, lefelé és felfelé is. Egy gyors feldolgozású munkafolyamatnak előnyös a szigorú limit, mert egy túllépés ekkor valódi problémát jelez, nem pedig egy ideiglenes lassulást.
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)
A másik végleten a megengedett felső határ 7 nap. Ennek az időtartamnak csak akkor van értelme, ha a folyamatok külső eseményre várnak, tipikusan emberi jóváhagyásra: egy automatikusan gyűjtött jelentés, amelyet egy menedzser ír alá, aki csak a következő héten tér vissza szabadságról.
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:
# Ez a munkafolyamat akár 7 napig is tarthat
# Hasznos olyan folyamatokhoz, amelyek emberi várakozási időt tartalmaznak
donnees = await collecter_donnees_multi_sources(params)
validation = await attendre_validation_humaine(donnees)
return await finaliser_rapport(validation)
A kalibráláshoz használd ezt a nagyságrendet a használati családok szerint.
| Használati eset | Ajánlott időtúllépés |
|---|---|
| Valós idejű feldolgozás | 1-5 perc |
| Adatpipeline | 15-60 perc |
| Komplex jelentésgenerálás | 1-4 óra |
| Emberi jóváhagyást igénylő munkafolyamat | 1-7 nap |
Két időtúllépési szint, amit nem szabad összekeverni
Az execution_timeout az egész munkafolyamatra vonatkozik; a start_to_close_timeout egyetlen tevékenységre korlátozódik. A kettő együtt létezik és kiegészíti egymást: az első megvéd attól, hogy egy munkafolyamat sose fejeződjön be, a második pedig attól, hogy egy tevékenység ráakadjon egy néma szolgáltatásra. Figyeld meg az alábbi példában, hogy a HTTP kliens időtúllépése (240 másodperc) szándékosan alacsonyabb, mint a start_to_close_timeout (5 perc), így a hiba tisztán felszínre kerül, mielőtt a platform megszakítaná a kapcsolatot.
from datetime import timedelta
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
# Ennek a tevékenységnek 5 perce van a befejezésre
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:
# Az egész munkafolyamatnak 2 órája van
# De minden egyes tevékenységnek megvan a saját időtúllépése
resultats = []
for source in sources:
resultat = await appel_api_externe(source)
resultats.append(resultat)
return {"résultats": resultats}
Egy utolsó reflex a bemeneteidhez: tartsd őket könnyedén. A limit 2 MB, és semmi sem kényszerít, hogy megközelítsd. Add át egy dokumentum URL-jét a tartalma helyett, egy rendelés azonosítóját a teljes rendelés helyett, és hagyd, hogy a tevékenységek lekérjék az adatokat. Definálj alapértelmezett értékeket minden opcionális dologhoz, dokumentáld az egyes mezőket a Field(description="...") segítségével, és bízd a validálást a Pydanticra, ahelyett, hogy if utasításokat szórnál szét a munkafolyamatban.
Főbb megállapítások
- A munkafolyamat bemeneteinek JSON-szerializálhatónak kell lenniük (str, int, float, bool, list, dict)
- Használj Pydantic BaseModel-t strukturált bemenetekhez automatikus validálással
- Az alapértelmezett időtúllépés 1 óra, konfigurálható maximum 7 napig
- Különböztesd meg a munkafolyamat időtúllépését (
execution_timeout) a tevékenység időtúllépésétől (start_to_close_timeout) - Tartsd könnyedén a bemeneteket: azonosítók és URL-ek a nagy nyers adatok helyett