Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Izveidot darbību

Nodarbība 4 no 14 Atjaunota 2026. gada 2. novembris Augstākais
Šajā lapā
  1. Kas ir darbība?
  2. Darbības uzbūve
  3. Konkrēti darbību piemēri
  4. Pamatīpašības
  5. Darbības nosaukšana
  6. Izmēra ierobežojumi
  7. Galvenās atziņas

Kas ir darbība?

Darbība ir darbplūsmas pamata operacionālā vienība. Tieši šeit notiek patiesais darbs: ārējo API izsaukumi, datubāzes vaicājumi, e-pastu sūtīšana, failu apstrāde un izsaukumi uz AI modeļiem. Darba sadalījums ir vienkāršs un kalpos kā tavs kompass visā šī kursa laikā: jebkura operācija, kas saistīta ar ievadi/izvadi (I/O) vai blakusparādībām, ir jāiekapsulē darbībā.

Kamēr darbplūsma orchestrē, darbība izpilda. Šī ir fundamentālā atšķirība, un tai ir tiešas sekas: tā kā riskantais darbs ir izolēts darbībās, dzinējs var mēģināt vēlreiz, mērīt un atskaņot, nekad nedublējot blakusparādības.

Darbības uzbūve

Darbība ir Python async funkcija, kas dekorēta ar @workflows.activity():

import mistralai.workflows as workflows

@workflows.activity()
async def get_user_profile(user_id: str) -> dict:
    """Retrieves a user profile from the API."""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/users/{user_id}")
        response.raise_for_status()
        return response.json()

Šajās dažās rindās četri elementi ir pelnījuši tavu uzmanību. Dekorators @workflows.activity() reģistrē funkciju kā darbību dzinējā, padarot to izsaucamu no darbplūsmas. async def ir obligāts: visām darbībām jābūt asinhronām, bez izņēmumiem. Parametriem jābūt JSON-serializējamiem, tas nozīmē vienkārši tipi — str, int, float, bool, list, dict — vai Pydantic modeļi; savienojuma objekta vai faila roktura nodošana kā arguments neizdosies serializācijas dēļ. Tas pats noteikums attiecas uz atgriešanas vērtību, kas ceļo pāri tīklam, pirms tiek ierakstīta notikumu žurnālā.

Konkrēti darbību piemēri

Pirmais gadījums, kas šajā kursā, iespējams, ir visbiežāk sastopamais, iekapsulē izsaukumu uz Mistral modeli. Ņem vērā, ka darbība atgriež arī tokena patēriņu: tiklīdz tas ir žurnālā, šāda veida metadati ļauj tev pēc fakta rekonstruēt izpildes izmaksas.

import mistralai.workflows as workflows
from mistralai.client import Mistral

@workflows.activity()
async def generate_summary(text: str) -> dict:
    """Generates a summary of the provided text via Mistral."""
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "You are an assistant specialized in text summarization."},
            {"role": "user", "content": f"Summarize this text in 3 sentences:\n\n{text}"}
        ]
    )
    return {
        "summary": response.choices[0].message.content,
        "tokens_used": response.usage.total_tokens
    }

Otrais gadījums ilustrē piekļuvi datubāzei. Bloks try/finally nav dekoratīvs: ja darbība neizdodas un tiek mēģināta vēlreiz, savienojuma atstāšana atvērtā stāvoklī katrā mēģinājumā ātri izsmels PostgreSQL kopu.

import mistralai.workflows as workflows
import asyncpg

@workflows.activity()
async def save_report(report: dict) -> dict:
    """Saves a report to PostgreSQL."""
    conn = await asyncpg.connect("postgresql://user:pass@localhost/db")
    try:
        row = await conn.fetchrow(
            "INSERT INTO reports (title, content, created_at) VALUES ($1, $2, NOW()) RETURNING id",
            report["title"],
            report["content"]
        )
        return {"id": row["id"], "status": "saved"}
    finally:
        await conn.close()

Trešais gadījums, e-pasta sūtīšana, ir vieta, kur blakusparādības ir visredzamākās: tiklīdz ziņojums ir nosūtīts, neviens atkārtots mēģinājums to nevar apturēt.

import mistralai.workflows as workflows
import aiosmtplib

@workflows.activity()
async def send_notification(recipient: str, subject: str, body: str) -> dict:
    """Sends a notification email."""
    message = f"Subject: {subject}\nTo: {recipient}\n\n{body}"
    await aiosmtplib.send(
        message,
        hostname="smtp.example.com",
        port=587,
        username="[email protected]",
        password="secret",
        use_tls=True
    )
    return {"status": "sent", "recipient": recipient}

Pamatīpašības

Pirmkārt, patīkama brīvība: atšķirībā no darbplūsmām, darbībām nav determinisma ierobežojumu. Tu vari brīvi izmantot datetime.now(), uuid.uuid4(), random.random() vai jebkuru citu nedeterministisku izsaukumu darbības ietvaros. Tieši tam darbības ir domātas — lai absorbētu visu, ko darbplūsmai darīt nav atļauts.

Platforma tad uztver katru darbības izsaukumu kā atomāru vienību: tā vai nu pilnībā izdodas, vai pilnībā neizdodas, bez darbplūsmai redzama starpstāvokļa. Ja tava darbība veic trīs lietas un otrā sabojājas, darbplūsma redz tikai kļūmi, nevis daļēju panākumu. Tāpēc tev vajadzētu izvairīties no piecu dažādu operāciju sakraušanas vienā funkcijā.

Tiklīdz darbība ir veiksmīga, tās rezultāts tiek pastāvīgi ierakstīts darbplūsmas notikumu žurnālā. Atskaņošanas laikā darbība nekad netiek izpildīta vēlreiz: tiek izmantots tikai ierakstītais rezultāts. Apmaiņā, tā kā darbību kļūmes gadījumā var mēģināt vēlreiz (tīkla noildze, pārejoša kļūda), tai ir jābūt idempotentai: izpildīta vairākas reizes ar tiem pašiem parametriem, tai jārada vienāds rezultāts. Pāreja no POST uz PUT, izmantojot stabilu identifikatoru, bieži vien ir pietiekama, lai sasniegtu šo īpašību, kā šeit, kur e-pasts kalpo kā atslēga:

@workflows.activity()
async def create_or_update_client(email: str, name: str) -> dict:
    """Idempotent: uses an upsert instead of an insert."""
    async with httpx.AsyncClient() as client:
        response = await client.put(
            f"https://api.crm.com/clients/{email}",
            json={"name": name, "email": email}
        )
        return response.json()

Darbības nosaukšana

Dekorators pieņem eksplicītu nosaukumu, kas ievērojami uzlabo izsekojamības lasāmību, ja tehniskā funkcija nes angļu nosaukumu, ko neviens cits komandā nesaista ar biznesa domēnu:

@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
    # ...
    pass

Šis nosaukums parādīsies OpenTelemetry trasēs un atvieglos atkļūdošanu. Pieradini sevi to iestatīt jau no sākuma: tajā dienā, kad meklēsi iemeslu, kāpēc izpilde ilga četrdesmit minūtes, tu lasīsi jēdzīgas etiķetes, nevis funkciju nosaukumu sarakstu.

Izmēra ierobežojumi

Apmaiņu reglamentē divi limiti: maksimums 2 MB ievades parametriem un maksimums 2 MB atgriešanas vērtībai. Tie izriet tieši no notikumu avotu principa (event sourcing), jo šīs vērtības tiek serializētas un saglabātas žurnālā.

Praktiskās sekas ir skaidras. Ja tev jāapstrādā lieli faili — 40 MB skenēts PDF, eksporta arhīvs — nenodod tos no darbības uz darbību. Saglabā tos ārējā servisā (S3, GCS) un apritē izmanto tikai URL vai identifikatoru: darbība lejupielādē failu, apstrādā to, ieraksta rezultātu atpakaļ krātuvē un atgriež atsauces uz dažiem simtiem baitu.

Galvenās atziņas

  • Darbība ir async funkcija, kas dekorēta ar @workflows.activity() un veic patieso darbu (I/O, API, DB)
  • Parametriem un atgriešanas vērtībām jābūt JSON-serializējamām
  • Darbībām nav determinisma ierobežojumu
  • Veiksmīga darbība nekad netiek izpildīta vēlreiz atskaņošanas laikā
  • Darbībām jābūt idempotentām (vienāds rezultāts, ja izpildītas vairākas reizes)
  • 2 MB limits ievadei un izvadei vienā darbībā