Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Luo työnkulku

Oppitunti 5 / 14 Päivitetty 2. marraskuuta 2026 Edistynyt
Tällä sivulla
  1. Työnkulun rooli
  2. Työnkulun rakenne
  3. Täydellinen esimerkki: käsittelyputki
  4. Työnkulun kestävyys
  5. Työnkulku ehdollisilla haaroilla
  6. Syötteet Pydanticilla
  7. Parhaat käytännöt
  8. Keskeiset asiat

Työnkulun rooli

Työnkulku on sovelluksesi orkestrointikerros. Se määrittelee, mitä tapahtuu, missä järjestyksessä ja millä ehdoilla – suorittamatta itse työtä. Konkreettisesti se koordinoi aktiviteetteja, odottaa ulkoisia tapahtumia, hallinnoi ajastimia ja ehdollisia haaroja, mutta se ei koskaan käytä verkkoa tai levyä.

Voit tiivistää tämän yhteen lauseeseen, joka kannattaa pitää mielessä aina koodia tarkastellessa: aktiviteetit tekevät työn, työnkulku ohjaa. Jos näet httpx:n tai open():n työnkulkuluokan sisällä, jotain täytyy siirtää muualle.

Työnkulun rakenne

Työnkulku on Python-luokka, jota koristaa @workflows.workflow.define() ja joka sisältää käynnistysmetodin, jota koristaa @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

Dekoraattori @workflows.workflow.define(name="...") rekisteröi luokan työnkulkuksi. Sille annettu name on yksilöllinen tunniste, jota käytät suorituksen käynnistämiseen – kutsuja näkee tämän merkkijonon, ei Python-luokan nimeä. Dekoraattori @workflows.workflow.entrypoint merkitsee käynnistyksessä kutsuttavan metodin. Ensimmäinen parametri, self, on luokkainstanssi kuten missä tahansa Python-oliossa, ja jokainen aktiviteettikutsu käyttää await:ia.

Täydellinen esimerkki: käsittelyputki

Tässä on realistinen työnkulku, joka orkestroi useita aktiviteetteja asiakirjan käsittelyyn. Huomaa työnjako: kolme ylintä funktiota sisältävät kaiken ulkomaailmaa koskevan koodin, kun taas alin luokka vain ketjuttaa await-kutsuja ja kokoaa tuloksen.

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"]
        }

Jokainen työnkulun await on pysyvyyspiste. Tämä kannattaa varmentaa mielessä yllä olevalla esimerkillä: jos prosessi epäonnistuu vaiheen 2 ja 3 välillä, asiakirjaa ei ladata uudelleen eikä mallia kutsuta uudelleen – joten ylimääräisiä token-kuluja ei synny. Työnkulku jatkaa suoraan tallennusvaiheesta.

Työnkulun kestävyys

Työnkulut selviävät uudelleenkäynnistyksistä, infrastruktuurivioista ja ohimenevistä virheistä, koska alusta tallentaa jokaisen tapahtuman ja rekonstruoi työnkulun tilan toistettaessa. Tämä rekonstruktio on luotettava vain yhden ehdon täyttyessä, kuten aiemmin mainittiin: työnkulkukoodin on aina tuotettava sama operaatioiden sarja samoilla syötteillä. Tämä on determinismi-rajoite. Käymme yksityiskohdat läpi oppitunnilla 8.

Työnkulku ehdollisilla haaroilla

Työnkulku ei rajoitu lineaariseen sekvenssiin. Se voi sisältää ehdollista logiikkaa, kuten tässä tilausesimerkissä, jossa polku riippuu varastotilanteesta:

@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-haarat ovat täysin tuettuja. Ainoa rajoite koskee päätöksenteossa käytettävää materiaalia: haaran lopputulon on perustuttava aktiviteetin palautusarvoon – arvoon, joka on kirjattu lokiin ja toistetaan identtisenä – eikä työnkulun suorittamaan suoraan ulkoisen palvelun kutsuun. Tässä verifier_stock kysyy varastoa aktiviteetin sisällä, ja if-lause lukee vain sanakirjaa, joka on jo pysytetty.

Syötteet Pydanticilla

Työnkulku, joka ottaa vastaan kuusi positionaalista parametria, muuttuu nopeasti lukukelvottomaksi. Jäsenneltyjä syötteitä varten käytä Pydantic-malleja, jotka tarjoavat myös tyyppivalidoinnin suorituksen alussa:

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"]}

Yksi varoitussana tämän työnkulun käynnistämisessä: kun käytät BaseModel:ia, kentistä tulee työnkululle lähetetyn JSON-syötteen ylimmän tason avaimia. Lähetät {"type_rapport": ..., "date_debut": ...}, et params-avaimen alle pesitettyä objektia.

Parhaat käytännöt

Neljä tapaa tekevät eron pitkällä aikavälillä. Ensinnäkin, pidä kiinni yhdestä vastuusta työnkulkua kohden: laskutuksen ja myynnin seurannan sekoittaminen samaan luokkaan tekee mahdottomaksi toistaa toista ilman toista. Seuraavaksi kiinnitä huomiota nimeämiseen, sillä työnkulun name on julkinen tunniste, jota muut järjestelmät kutsuvat – "traitement_commande" on ylläpidettävä, "workflow_1" ei ole. Älä tuo työnkulkuun mitään I/O-toimintoja: jokainen verkkokutsu, tiedostokäyttö tai tietokantakysely kuuluu aktiviteettiin. Lopuksi pidä työnkulkukoodi yksinkertaisena siirtämällä monimutkainen logiikka – jäsennys, muunnokset, raskaat laskennat – aktiviteetteihin, joissa sitä voidaan testata eristettynä ilman determinismirajoitteita.

Keskeiset asiat

  • Työnkulku on luokka, jota koristaa @workflows.workflow.define() ja joka orkestroi aktiviteetteja
  • @workflows.workflow.entrypoint-metodi on käynnistyksessä kutsuttava entry point
  • Jokainen aktiviteetin await on pysyvyyspiste (automaattinen jatkaminen virhetilanteessa)
  • Ehdolliset haarat ja silmukat ovat tuettuja
  • Käytä Pydantic-malleja jäsenneltyihin syöteparametreihin
  • Työnkulun sisällä ei saa olla suoria I/O-operaatioita