Ulazni podaci i vremenska ograničenja
Na ovoj stranici
Što ulazi u radni tijek
Svaki radni tijek prima ulazne parametre koji definiraju njegov kontekst izvršavanja. Budući da ti parametri putuju mrežom i pohranjuju se u zapisu izvršavanja, moraju slijediti jedno strogo pravilo: moraju biti serializabilni u JSON formatu. Pythonovi primitivni tipovi prolaze bez problema, kao i liste, rječnici te null vrijednosti.
# Primitive types
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True
# Collections
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}
# Nullable
commentaire: str | None = None
Međutim, datetime, bytes, set, tuple i prilagođene klase koje nisu Pydantic nisu izravno podržani. Ako tvoj radni tijek treba primiti datum fakture, pretvori ga u ISO 8601 niz prije prosljeđivanja, a objekt rekonstruiraj unutar aktivnosti. Ovo načelo vrijedi za sve takve tipove: konverzija je tvoja odgovornost, a ne platforme.
Strukturiranje i validacija s Pydanticom
Prosljeđivanje rječnika slobodne strukture funkcionira, ali gubiš sve garancije o njegovom sadržaju. Za strukturirane i validirane parametre osloni se na Pydantic modele, koji dokumentiraju sučelje radnog tijeka jednako koliko ga i štite.
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
Na strani pozivatelja nema ničeg posebnog za napraviti: polja BaseModel jednostavno postaju ključevi najviše razine u ulaznom rječniku.
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 automatski validira primljene podatke. Ako je polje neispravno, radni tijek odmah fails s eksplicitnom porukom o grešci, umjesto da započne izvršavanje i sruši se tek nakon tri aktivnosti. Ova se validacija pooštrava prema potrebi: ograničenja formata za e-mail adresu, numeričke granice za prioritet i, prije svega, extra = "forbid", koje odbija nepoznata polja.
class ParametresStricts(BaseModel):
email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
priorite: int = Field(ge=1, le=5)
class Config:
extra = "forbid" # Rejects unknown fields
Ova posljednja točka zaslužuje pažnju. Bez extra="forbid", tipfeler u nazivu polja prolazi nezapaženo: očekivano polje uzima svoju zadanu vrijednost, a radni tijek se izvršava s parametrima koji nisu ono što si namjeravao. Neuspjeh je tih, stoga i skup.
Kada jedan radni tijek mora prihvatiti više oblika unosa, unija tipova omogućuje opisivanje tih varijanti bez umnožavanja radnih tijekova.
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"
Životni vijek izvršavanja
Svaki radni tijek ima maksimalno trajanje izvršavanja postavljeno parametrom execution_timeout. Zadano je to jedan sat: nakon tog roka radni tijek se automatski otkazuje, bez obzira na napredak. Za proces predviđen da traje trideset sekundi ta je vrijednost ugodna; za pipeline koji radi preko noći to je zamka.
Prilagodi ovo vremensko ograničenje prirodi obrade, i prema dolje i prema gore. Radni tijek brze obrade ima koristi od strogog limita jer prekoračenje tada signalizira stvarni problem, a ne privremeno usporavanje.
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)
S druge strane, dopušteni maksimum je 7 dana. Ovo trajanje ima smisla samo za procese koji čekaju vanjski događaj, tipično ljudsku validaciju: izvještaj prikupljen automatski, ali koji potpisuje voditelj koji se s godišnjeg odmora vraća tek idući tjedan.
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:
# This workflow can last up to 7 days
# Useful for processes with human waiting periods
donnees = await collecter_donnees_multi_sources(params)
validation = await attendre_validation_humaine(donnees)
return await finaliser_rapport(validation)
Za kalibraciju koristi ovaj red veličine prema obitelji uporabe.
| Slučaj uporabe | Preporučeno vremensko ograničenje |
|---|---|
| Obrada u stvarnom vremenu | 1-5 minuta |
| Podatkovni pipeline | 15-60 minuta |
| Generiranje složenih izvještaja | 1-4 sata |
| Radni tijek s ljudskom validacijom | 1-7 dana |
Dvije razine vremenskog ograničenja koje ne smiješ brkati
execution_timeout ograničava cijeli radni tijek; start_to_close_timeout ograničava pojedinačnu aktivnost. Ta dva koegzistiraju i nadopunjuju se: prvo te štiti od radnog tijeka koji se nikad ne završi, drugo od aktivnosti koja visi na tihoj usluzi. Primijeti u donjem primjeru da je vremensko ograničenje HTTP klijenta (240 sekundi) namjerno niže od start_to_close_timeout (5 minuta), tako da se greška čisto pojavi prije nego što platforma prekine vezu.
from datetime import timedelta
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
# This activity has 5 minutes to complete
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:
# The entire workflow has 2 hours
# But each individual activity has its own timeout
resultats = []
for source in sources:
resultat = await appel_api_externe(source)
resultats.append(resultat)
return {"résultats": resultats}
Još jedan refleks za tvoje ulazne podatke: drži ih laganima. Limit je 2 MB i ništa te ne prisiljava da mu se približiš. Proslijedi URL dokumenta umjesto njegovog sadržaja, ID narudžbe umjesto pune narudžbe i prepusti aktivnostima dohvaćanje podataka. Definiraj zadane vrijednosti za sve opcionalno, dokumentiraj svako polje s Field(description="...") i povjeri validaciju Pydanticu umjesto if naredbi razbacanih po radnom tijeku.
Ključne točke
- Ulazi u radni tijek moraju biti serializabilni u JSON (str, int, float, bool, list, dict)
- Koristi Pydantic BaseModel za strukturirane ulaze s automatskom validacijom
- Zadano vremensko ograničenje je 1 sat, podesivo do maksimuma od 7 dana
- Razlikuj vremensko ograničenje radnog tijeka (
execution_timeout) od vremenskog ograničenja aktivnosti (start_to_close_timeout) - Drži ulaze laganima: ID-ovi i URL-ovi umjesto velikih sirovih podataka