Ievades un noilgumi
Šajā lapā
Kas nonāk darbplūsmā
Katra darbplūsma saņem ievades parametrus, kas definē tās izpildes kontekstu. Tā kā šie parametri pārvietojas pa tīklu un tiek glabāti izpildes žurnālā, tiem jāievēro viens stingrs noteikums: tiem ir jābūt JSON-serializējamiem. Python primitīvie tipi tiek pieņemti bez problēmām, tāpat kā saraksti, vārdnīcas un nulles vērtības.
# Primitīvie tipi
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True
# Kolekcijas
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}
# Nullable
commentaire: str | None = None
Tomēr datetime, bytes, set, tuple un pielāgotas klases, kas nav Pydantic, netiek atbalstītas tieši. Ja tavai darbplūsmai ir jāsaņem rēķina datums, pirms tā nodošanas pārveido to par ISO 8601 virkni un rekonstruē objektu aktivitātes ietvaros. Šis princips attiecas uz visiem šādiem tipiem: konvertēšana ir tava atbildība, nevis platformas.
Strukturēšana un validēšana ar Pydantic
Brīvas formas vārdnīcas nodošana darbojas, taču tu zaudē visas garantijas par to saturu. Strukturētiem un validētiem parametriem paļaujies uz Pydantic modeļiem, kas dokumentē darbplūsmas saskarni tikpat daudz, cik to aizsargā.
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
Izsaucošajā pusē nav jādara nekas īpašs: BaseModel lauki vienkārši kļūst par augšējā līmeņa atslēgām ievades vārdnīcā.
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 automātiski validē saņemtos datus. Ja lauks ir nederīgs, darbplūsma nekavējoties neizdodas ar skaidru kļūdas ziņojumu, nevis sāk izpildi un sabojājas trīs aktivitātes vēlāk. Šī validācija pastiprinās pēc vajadzības: e-pasta adreses formāta ierobežojumi, skaitliskās robežas prioritātei un, pats galvenais, extra = "forbid", kas noraida nezināmus laukus.
class ParametresStricts(BaseModel):
email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
priorite: int = Field(ge=1, le=5)
class Config:
extra = "forbid" # Noraida nezināmus laukus
Šis pēdējais punkts ir pelnījis uzmanību. Bez extra="forbid" kļūda lauka nosaukumā paliek nepamanīta: paredzētais lauks iegūst savu noklusējuma vērtību, un darbplūsma darbojas ar parametriem, kas nav tādi, kādu tu biji iecerējis. Kļūme ir klusa, līdz ar to dārga.
Kad vienai darbplūsmai ir jāpieņem vairāki ievades veidi, apvienojuma tipi (union types) ļauj aprakstīt šīs variācijas, nepavairojot darbplūsmas.
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"
Izpildes ilgums
Katrai darbplūsmai ir maksimālais izpildes ilgums, ko nosaka parametrs execution_timeout. Pēc noklusējuma tas ir viena stunda: pēc šī termiņa beigām darbplūsma tiek automātiski atcelta neatkarīgi no tās progresa. Procesam, kam paredzēts ilgt trīsdesmit sekundes, šī vērtība ir ērta; nakts cauruļvadam tā ir slazds.
Pielāgo šo noilgumu apstrādes dabai gan uz leju, gan uz augšu. Ātri apstrādājoša darbplūsma gūst labumu no stingra limita, jo tā pārsniegšana tad signalizē par reālu problēmu, nevis pagaidu palēninājumu.
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)
Otrā galā pieļaujamais griesti ir 7 dienas. Šis ilgums ir jēdzīgs tikai procesiem, kas gaida ārēju notikumu, parasti cilvēka apstiprinājumu: ziņojums, kas automātiski savākts, bet ko paraksta vadītājs, kurš neatgriezīsies no atvaļinājuma līdz nākamajai nedēļai.
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:
# Šī darbplūsma var ilgt līdz 7 dienām
# Noderīga procesiem ar cilvēka gaidīšanas periodiem
donnees = await collecter_donnees_multi_sources(params)
validation = await attendre_validation_humaine(donnees)
return await finaliser_rapport(validation)
Lai veiktu kalibrēšanu, izmanto šo lieluma kārtību pēc lietojuma veida.
| Lietojuma gadījums | Ieteicamais noilgums |
|---|---|
| Reāllaika apstrāde | 1–5 minūtes |
| Datu cauruļvads | 15–60 minūtes |
| Sarežģītu ziņojumu ģenerēšana | 1–4 stundas |
| Darbplūsma ar cilvēka apstiprinājumu | 1–7 dienas |
Divi noilguma līmeņi, ko nejaukt
execution_timeout ierobežo visu darbplūsmu; start_to_close_timeout ierobežo vienu aktivitāti. Abi pastāv līdzās un papildina viens otru: pirmais pasargā tevi no darbplūsmas, kas nekad nepabeidzas, otrais – no aktivitātes, kas iestrēgusi pie klusa servisa. Zemāk esošajā piemērā ņem vērā, ka HTTP klienta noilgums (240 sekundes) ir apzināti zemāks par start_to_close_timeout (5 minūtes), lai kļūda parādītos tīri, pirms platforma pārtrauc savienojumu.
from datetime import timedelta
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
# Šai aktivitātei ir 5 minūtes, lai pabeigtu darbu
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:
# Visai darbplūsmai ir 2 stundas
# Bet katrai atsevišķai aktivitātei ir savs noilgums
resultats = []
for source in sources:
resultat = await appel_api_externe(source)
resultats.append(resultat)
return {"résultats": resultats}
Vēl viens pēdējais reflekss attiecībā uz tavām ievadēm: uzturi tās vieglas. Limits ir 2 MB, un nekas neliek tev tam tuvoties. Nodo dokumenta URL, nevis tā saturu, pasūtījuma ID, nevis visu pasūtījumu, un ļauj aktivitātēm iegūt datus. Definē noklusējuma vērtības visam, kas ir fakultatīvs, dokumentē katru lauku ar Field(description="...") un uztici validāciju Pydantic, nevis if priekšrakstiem, kas izkaisīti pa visu darbplūsmu.
Galvenās atziņas
- Darbplūsmas ievadēm ir jābūt JSON-serializējamām (str, int, float, bool, list, dict)
- Izmanto Pydantic BaseModel strukturētām ievadēm ar automātisku validāciju
- Noklusējuma noilgums ir 1 stunda, konfigurējams līdz maksimāli 7 dienām
- Nošķir darbplūsmas noilgumu (
execution_timeout) no aktivitātes noilguma (start_to_close_timeout) - Uzturi ievades vieglas: ID un URL, nevis lieli neapstrādāti dati