Премини към основното съдържание
Български— Изберете език
Меню

Създаване на работен поток

Урок 5 от 14 Обновен 2 ноември 2026 г. Напреднало
На тази страница
  1. Ролята на работния поток
  2. Структура на работния поток
  3. Пълен пример: конвейер за обработка
  4. Издръжливост на работния поток
  5. Работен поток с условно разклоняване
  6. Входни данни с Pydantic
  7. Най-добри практики
  8. Ключови изводи

Ролята на работния поток

Работният поток е оркестрационният слой на Вашето приложение. Той дефинира какво трябва да се случи, в какъв ред и при какви условия – без самият той да изпълнява работата. Конкретно, той координира дейностите, изчаква външни събития, управлява таймери и условни разклонения, но никога не осъществява мрежови връзки или достъп до диска.

Можете да обобщите това в една фраза, която да помните всеки път, когато преглеждате код: дейностите вършат работата, работният поток я направлява. Ако видите httpx или open() вътре в клас на работен поток, нещо трябва да бъде преместено.

Структура на работния поток

Работният поток е Python клас, декориран с @workflows.workflow.define(), съдържащ входен метод, декориран с @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

Декораторът @workflows.workflow.define(name="...") регистрира класа като работен поток. name, което той получава, е уникалният идентификатор, който ще използвате за стартиране на изпълнение – това е низът, а не името на Python класа, което вижда извикващият. Декораторът @workflows.workflow.entrypoint маркира метода, извикван при стартиране. Първият параметър, self, остава екземплярът на класа, както при всеки Python обект, и всяко извикване на дейност използва await.

Пълен пример: конвейер за обработка

Ето един реалистичен работен поток, който оркестрира множество дейности за обработка на документ. Обърнете внимание на разделението на труда: трите функции в началото съдържат целия код, който взаимодейства с външния свят, докато класът в долната част просто свързва извикванията с await и сглобява резултата.

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

Всяко await в работния поток представлява точка на запазване. Струва си да проверите това мислено с горния пример: ако процесът се провали между стъпка 2 и стъпка 3, документът няма да бъде изтеглен отново и моделът няма да бъде извикан пак – следователно няма допълнителни такси за токени. Работният поток ще възобнови изпълнението директно от стъпката за запазване.

Издръжливост на работния поток

Работните потоци оцеляват при рестартирания, сривове в инфраструктурата и преходни грешки, защото платформата записва всяко събитие и реконструира състоянието на работния поток по време на повторното изпълнение. Тази реконструкция е надеждна само при едно условие, споменато по-рано: кодът на работния поток винаги трябва да произвежда една и съща последователност от операции за едни и същи входни данни. Това е ограничението за детерминизъм. Ще разгледаме подробностите в урок 8.

Работен поток с условно разклоняване

Работният поток не се ограничава до линейна последователност. Той може да съдържа условна логика, както в този пример за обработка на поръчки, където пътят зависи от наличността на стока:

@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 са напълно поддържани. Единственото ограничение се отнася до материала, използван за вземане на решение: резултатът от разклонението трябва да зависи от върнатата стойност на дейност – стойност, записана в дневника и възпроизведена идентично – а не от директно извикване на външна услуга от работния поток. Тук verifier_stock заявява инвентара в рамките на дейност, а инструкцията if чете само речник, който вече е запазен.

Входни данни с Pydantic

Работен поток, който приема шест позиционни параметъра, бързо става нечетим. За структурирани входни данни използвайте Pydantic модели, които също осигуряват валидиране на типовете в началото на изпълнението:

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

Една точка на внимание при стартирането на този работен поток: когато използвате BaseModel, полетата стават ключове от най-високо ниво в JSON входа, изпратен до работния поток. Ще изпратите {"type_rapport": ..., "date_debut": ...}, а не обект, вложен под ключ params.

Най-добри практики

Четири навика правят разликата в дългосрочен план. Първо, придържайте се към една отговорност на работен поток: смесването на фактуриране и последващи действия по продажбите в един и същи клас прави невъзможно повторното изпълнение на едното без другото. След това, обърнете внимание на именуването, тъй като name на работния поток е публичен идентификатор, извикван от други системи – "traitement_commande" е поддържаемо, "workflow_1" не е. Не въвеждайте никакъв вход/изход (I/O) в работния поток: всяко мрежово извикване, достъп до файл или заявка към база данни принадлежи в дейност. Накрая, поддържайте кода на работния поток прост, като прехвърляте сложната логика – парсиране, трансформации, тежки изчисления – към дейности, където тя може да бъде тествана изолирано без ограничения за детерминизъм.

Ключови изводи

  • Работният поток е клас, декориран с @workflows.workflow.define(), който оркестрира дейности
  • Методът @workflows.workflow.entrypoint е входната точка, извиквана при стартиране
  • Всяко await на дейност е точка на запазване (автоматично възобновяване в случай на грешка)
  • Условните разклонения и цикли са поддържани
  • Използвайте Pydantic модели за структурирани входни параметри
  • Работният поток не трябва да съдържа никакви директни операции за вход/изход