Loo töövoog
Sellel lehel
Töövoogu roll
Töövoog on sinu rakenduse orkestreerimiskiht. See määratleb, mis peab toimuma, millises järjekorras ja millistel tingimustel – ilma tööd ise teostamata. Konkreetsemalt koordineerib see tegevusi, ootab väliseid sündmusi, haldab taimereid ja tingimuslikke harusid, kuid ei puuduta kunagi võrku ega ketast.
Seda saab kokku võtta ühe lausega, mida tasub meeles pidada iga koodiülevaatuse ajal: tegevused teevad töö ära, töövoog annab suunda. Kui näed töövoogu klassis httpx-i või open()-i, tuleb midagi ümber paigutada.
Töövoo struktuur
Töövoog on Pythoni klass, mida kaunistab @workflows.workflow.define() ja mis sisaldab sisenemismeetodit, mida kaunistab @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
Dekoraator @workflows.workflow.define(name="...") registreerib klassi töövoona. Sellele antud name on unikaalne identifikaator, mida kasutad käivitamiseks – just seda stringi, mitte Pythoni klassi nime, näeb väljakutsuja. Dekoraator @workflows.workflow.entrypoint märgib meetodi, mida kutsutakse käivitamisel. Esimene parameeter self jääb klassi instantsiks, nagu igal Pythoni objektil, ja iga tegevuse väljakutse kasutab await.
Täielik näide: töötlemistorustik
Siin on realistlik töövoog, mis orkestreerib mitut tegevust dokumendi töötlemiseks. Pane tähele tööjaotust: kolm ülemist funktsiooni sisaldavad kogu koodi, mis puudutab välist maailma, samas kui alumine klass lihtsalt aheldab await-väljakutseid ja koostab tulemuse.
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"]
}
Iga await töövoos moodustab püsivuspunkti. Seda tasub ülaltoodud näite põhjal vaimselt kontrollida: kui protsess ebaõnnestub sammu 2 ja 3 vahel, ei laadita dokumenti uuesti alla ega kutsuta mudelit uuesti – seega lisanduvad tokenikulud puuduvad. Töövoog jätkub otse salvestamise sammust.
Töövoo vastupidavus
Töövood jäävad ellu pärast taaskäivitusi, taristu tõrkeid ja mööduvaid vigu, sest platvorm salvestab iga sündmuse ja taastab töövoogu oleku taasesituse käigus. See taastamine on usaldusväärne vaid ühel tingimusel, mida mainiti varem: töövoogu kood peab samade sisendite korral alati tootma sama toimingute jada. See on determinismi nõue. Arutleme detaile lähemalt 8. õppetükis.
Tingimuslike harudega töövoog
Töövoog ei piirdu lineaarse jadaga. See võib sisaldada tingimuslikku loogikat, nagu selles tellimuse töötlemise näites, kus tee sõltub laoseisust:
@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"}
if/else harud on täielikult toetatud. Ainus piirang puudutab otsuse tegemiseks kasutatavat materjali: haru tulemus peab sõltuma tegevuse tagastusväärtusest – väärtusest, mis on logisse salvestatud ja identselt taasesitatav –, mitte töövoost tehtud otsesest välise teenuse väljakutsest. Siin pärib verifier_stock laoinfot tegevuse sees ja if-lause loeb ainult juba püsivustatud sõnastikku.
Sisendid Pydanticuga
Töövoog, mis võtab vastu kuut positsioonilist parameetrit, muutub kiiresti loetamatuks. Struktureeritud sisendite jaoks kasuta Pydanticu mudeleid, mis pakuvad ka tüübivalideerimist täitmise alguses:
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"]}
Üks ettevaatusabinõu selle töövoogu käivitamisel: kui kasutad BaseModel-i, muutuvad väljad töövoole saadetava JSON-sisendi ülemise taseme võtmeteks. Saadad {"type_rapport": ..., "date_debut": ...}, mitte objekti, mis on pesastatud võtme params alla.
Parimad tavad
Neli harjumust teevad pikas perspektiivis suure erinevuse. Esiteks, püsi ühe vastutuse juures töövoogu kohta: arvelduse ja müügijäreltegevuste segamine samasse klassi muudab võimatuks ühe taasesitamise ilma teiseta. Järgmiseks pööra tähelepanu nimevalikule, kuna töövoogu name on avalik identifikaator, mida kutsutakse teistest süsteemidest – "traitement_commande" on hoitav, "workflow_1" mitte. Ära too töövoogu sisse ühtegi sisend/väljundoperatsiooni: iga võrgukõne, failile juurdepääs või päring andmebaasi kuulub tegevusse. Lõpuks hoia töövoogu kood lihtsana, suunates keerulise loogika – parsimise, teisenduste, mahukate arvutuste – tegevustesse, kus seda saab testida isoleeritult ilma determinismi piiranguteta.
Peamised punktid
- Töövoog on klass, mida kaunistab
@workflows.workflow.define()ja mis orkestreerib tegevusi - Meetod
@workflows.workflow.entrypointon käivitamisel kutsutav sisenemispunkt - Iga tegevuse
awaiton püsivuspunkt (automaatne jätkamine tõrke korral) - Tingimuslikud harud ja tsüklid on toetatud
- Kasuta Pydanticu mudeleid struktureeritud sisendparameetrite jaoks
- Töövoog ei tohi sisaldada otseseid sisend/väljundoperatsioone