Oħloq workflow
F'din il-paġna
Ir-rwol tal-workflow
Il-workflow huwa s-saff ta’ orkestrazzjoni tal-applikazzjoni tiegħek. Jiddefinixxi x’għandu jiġri, f’liema ordni, u taħt liema kundizzjonijiet—mingħajr ma jeżegwixxi x-xogħol innifsu. Konkretament, jikkoordina l-attivitajiet, jistenna avvenimenti esterni, jimmaniġġja timers u fergħat kondizzjonali, iżda qatt ma jmiss in-network jew id-disk.
Tista’ tgħaqqad dan f’frażi waħda biex iżżomm f’moħħok kull darba li tirrevedi l-kodiċi: l-attivitajiet jagħmlu x-xogħol, il-workflow jidderieġi. Jekk tara httpx jew open() ġewwa klassi ta’ workflow, hemm xi ħaġa li trid tiġi mċaqalqa.
L-istruttura tal-workflow
Workflow huwa klassi Python imżejna b’@workflows.workflow.define(), li fiha metodu ta’ dħul imżejjen b’@workflows.workflow.entrypoint:
import mistralai.workflows as workflows
@workflows.workflow.define(name="mon_premier_workflow")
class MonPremierWorkflow:
@workflows.workflow.entrypoint
async def run(self, nom: str) -> dict:
"""Workflow entry point."""
resultat = await saluer(nom)
return resultat
Id-dekoratur @workflows.workflow.define(name="...") jirreġistra l-klassi bħala workflow. L-name li jirċievi huwa l-identifikatur uniku li se tuża biex tħaffer eżekuzzjoni—din l-istringa, mhux l-isem tal-klassi Python, hija dak li jara s-sejjaħ. Id-dekoratur @workflows.workflow.entrypoint jimmarka l-metodu msejjaħ fil-bidu. L-ewwel parametru, self, jibqa’ l-istanza tal-klassi, bħal f’kull oġġett Python, u kull sejħa ta’ attività tuża await.
Eżempju sħiħ: pipeline ta’ ipproċessar
Hawnhekk hemm workflow realistiku li jorkestra attivitajiet multipli biex jipproċessa dokument. Innota d-diviżjoni tax-xogħol: it-tliet funzjonijiet fil-quċċata fihom il-kodiċi kollu li jmiss id-dinja ta’ barra, filwaqt li l-klassi fil-qiegħ sempliċiment tgħaqqad sejħiet await u jfassal riżultat.
import mistralai.workflows as workflows
from mistralai.client import Mistral
# --- Activities ---
@workflows.activity()
async def extraire_texte(url_document: str) -> dict:
"""Download and extract text from a document."""
async with httpx.AsyncClient() as client:
response = await client.get(url_document)
texte = response.text
return {"texte": texte, "longueur": len(texte)}
@workflows.activity()
async def analyser_avec_mistral(texte: str) -> dict:
"""Analyze text with Mistral to extract key points."""
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Extract the 5 key points from this text."},
{"role": "user", "content": texte}
]
)
return {"analyse": response.choices[0].message.content}
@workflows.activity()
async def sauvegarder_resultat(analyse: dict) -> dict:
"""Save the analysis result."""
async with httpx.AsyncClient() as client:
response = await client.post(
"https://api.example.com/rapports",
json=analyse
)
return {"id_rapport": response.json()["id"]}
# --- Workflow ---
@workflows.workflow.define(name="pipeline_analyse_document")
class PipelineAnalyseDocument:
@workflows.workflow.entrypoint
async def run(self, url_document: str) -> dict:
"""Orchestrate extraction, analysis, and saving."""
# Step 1: Extract text
extraction = await extraire_texte(url_document)
# Step 2: Analyze with Mistral
analyse = await analyser_avec_mistral(extraction["texte"])
# Step 3: Save
sauvegarde = await sauvegarder_resultat(analyse)
return {
"url_source": url_document,
"longueur_texte": extraction["longueur"],
"id_rapport": sauvegarde["id_rapport"]
}
Kull await fil-workflow jikkostitwixxi punt ta’ persistenza. Jiswa li tivverifika dan mentalment bl-eżempju ta’ hawn fuq: jekk il-proċess ifalli bejn il-pass 2 u l-pass 3, id-dokument ma jerġax jitniżżel u l-mudell ma jerġax jissejjaħ—għalhekk l-ebda ħlas addizzjonali ta’ tokens. Il-workflow jerġa’ jibda direttament fil-pass tas-salvataġġ.
Id-durabbiltà tal-workflow
Il-workflows jibqgħu ħajjin wara restarts, fallimenti fl-infrastruttura, u żbalji tranżitorji għax il-pjattaforma tirreġistra kull avveniment u terġa’ tibni l-istat tal-workflow waqt ir-replay. Din ir-rikostruzzjoni hija affidabbli biss taħt kundizzjoni waħda, imsemmija qabel: il-kodiċi tal-workflow irid dejjem jipproduċi l-istess sekwenza ta’ operazzjonijiet għall-istess inputs. Din hija r-restrizzjoni tad-determiniżmu. Se nkopru d-dettalji fil-lezzjoni 8.
Workflow b’fergħat kondizzjonali
Workflow mhux limitat għal sekwenza lineari. Jista’ jkun fih loġika kondizzjonali, bħal f’dan l-eżempju ta’ ipproċessar ta’ ordni fejn il-mogħdija tiddependi mill-istatus tal-istokk:
@workflows.workflow.define(name="traitement_commande")
class OrderProcessing:
@workflows.workflow.entrypoint
async def run(self, order: dict) -> dict:
# Check stock
stock = await check_stock(order["produit_id"])
if stock["disponible"]:
# Standard path
payment = await process_payment(order["montant"])
shipment = await prepare_shipment(order)
await send_confirmation(order["email"], shipment)
return {"status": "confirmée", "tracking": shipment["tracking"]}
else:
# Alternative path
await notify_stockout(order["email"], order["produit_id"])
return {"status": "rupture_stock"}
Il-fergħat if/else huma appoġġjati bis-sħiħ. L-unika restrizzjoni tikkonċerna l-materjal użat għad-deċiżjoni: ir-riżultat tal-fergħa jrid jiddependi mill-valur ta’ ritorn ta’ attività—valur irreġistrat fil-log u rreplikat bl-istess mod—mhux fuq sejħa diretta għal servizz estern mill-workflow. Hawnhekk, verifier_stock jistaqsi l-inventarju ġewwa attività, u l-istatement if jaqra biss dizzjunarju li diġà ġie ppersistit.
Inputs b’Pydantic
Workflow li jieħu sitt parametri pożizzjonali malajr isir mhux leġibbli. Għal inputs strutturati, uża mudelli Pydantic, li jipprovdu wkoll validazzjoni tat-tip fil-bidu tal-eżekuzzjoni:
from pydantic import BaseModel
class ReportParams(BaseModel):
report_type: str
include_details: bool = False
start_date: str
end_date: str
@workflows.workflow.define(name="generation_rapport")
class ReportGeneration:
@workflows.workflow.entrypoint
async def run(self, params: ReportParams) -> dict:
data = await collect_data(params.report_type, params.start_date, params.end_date)
if params.include_details:
data = await enrich_data(data)
report = await generate_pdf_report(data)
return {"url_rapport": report["url"]}
Punt ta’ kawtela meta tħaffer dan il-workflow: meta tuża BaseModel, il-kampijiet isiru ċwievet ta’ livell għoli fl-input JSON mibgħut lill-workflow. Se tibgħat {"type_rapport": ..., "date_debut": ...}, mhux oġġett innestjat taħt ċavetta params.
L-aħjar prattiki
Erba’ drawwiet jagħmlu differenza fit-tul. L-ewwel, imxi ma’ responsabbiltà waħda għal kull workflow: it-taħlit tal-fatturazzjoni u s-segwitu tal-bejgħ fl-istess klassi jagħmilha impossibbli li terġa’ tgħaddi wieħed mingħajr l-ieħor. Imbagħad, agħti attenzjoni lit-tismija, peress li l-name tal-workflow huwa identifikatur pubbliku msejjaħ minn sistemi oħra—"traitement_commande" huwa manutenibbli, "workflow_1" mhux. Mintroduċi l-ebda I/O fil-workflow: kull sejħa tan-network, aċċess għall-fajls, jew mistoqsija tad-database tappartjeni għal attività. Fl-aħħar, żomm il-kodiċi tal-workflow sempliċi billi tħalli loġika kumplessa—parsing, trasformazzjonijiet, kalkoli tqal—lill-attivitajiet, fejn tista’ tiġi ttestjata b’mod iżolat mingħajr restrizzjonijiet ta’ determiniżmu.
Punti Ewlenin
- Workflow huwa klassi mżejna b’
@workflows.workflow.define()li torkestra attivitajiet - Il-metodu
@workflows.workflow.entrypointhuwa l-punt ta’ dħul imsejjaħ fil-bidu - Kull
awaitta’ attività huwa punt ta’ persistenza (rikupru awtomatiku fil-każ ta’ falliment) - Fergħat kondizzjonali u loops huma appoġġjati
- Uża mudelli Pydantic għal parametri ta’ input strutturati
- Il-workflow m’għandux ikun fih l-ebda operazzjoni diretta ta’ I/O