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

Създаване на дейност

Урок 4 от 14 Обновен 2 ноември 2026 г. Напреднало
На тази страница
  1. Какво представлява дейността?
  2. Анатомия на една дейност
  3. Конкретни примери за дейности
  4. Основни характеристики
  5. Именуване на дейност
  6. Ограничения за размер
  7. Ключови изводи

Какво представлява дейността?

Дейността е основната оперативна единица в един работен поток. Тук се извършва реалната работа: външни API повиквания, заявки към бази данни, изпращане на имейли, обработка на файлове и обаждания към AI модели. Разделението на труда е просто и ще служи като Ваш компас през целия курс: всяка операция, включваща вход/изход (I/O) или странични ефекти, трябва да бъде обособена в дейност.

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

Анатомия на една дейност

Една дейност представлява Python async функция, декорирана с @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()

Четири елемента в тези няколко реда заслужават вниманието Ви. Декораторът @workflows.activity() регистрира функцията като дейност пред движъка, правейки я достъпна за извикване от работен поток. Ключовата дума async def е задължителна: всички дейности трябва да бъдат асинхронни, без изключение. Параметрите трябва да бъдат JSON-сериализируеми, което означава прости типове – str, int, float, bool, list, dict – или Pydantic модели; предаването на обект за връзка или файлов хендъл като аргумент ще доведе до грешка при сериализацията. Същото правило важи и за върнатата стойност, която пътува по мрежата, преди да бъде записана в дневника със събития.

Конкретни примери за дейности

Първият случай, вероятно най-честият в този курс, обособява обаждане към модел на Mistral. Обърнете внимание, че дейността връща и потреблението на токени: веднъж записано в дневника, този вид метаданни Ви позволява да реконструирате цената на изпълнението постфактум.

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
    }

Вторият случай илюстрира достъп до база данни. Блокът try/finally не е декоративен: ако дейността се провали и бъде опитана отново, оставянето на отворена връзка при всеки опит бързо ще изчерпи пула от връзки на PostgreSQL.

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()

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

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}

Основни характеристики

Първо, една желана свобода: за разлика от работните потоци, дейностите нямат ограничения за детерминизъм. Можете свободно да използвате datetime.now(), uuid.uuid4(), random.random() или всяко друго недетерминирано обаждане вътре в дейността. Точно за това служат дейностите – да поемат всичко, което работният поток няма право да прави.

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

След като една дейност успее, нейният резултат се записва постоянно в дневника със събития на работния поток. По време на възпроизвеждане дейността никога не се изпълнява отново: използва се само записаният резултат. В замяна, тъй като една дейност може да бъде опитана отново при неуспех (мрежов таймаут, временна грешка), тя трябва да бъде идемпотентна: изпълнена многократно със същите параметри, тя трябва да произведе същия резултат. Преминаването от POST към PUT върху стабилен идентификатор често е достатъчно за постигане на това свойство, както е тук, където имейлът служи като ключ:

@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()

Именуване на дейност

Декораторът приема изрично име, което значително подобрява четимостта на проследяването, когато техническа функция носи английско име, което никой друг в екипа не свързва с бизнес домейна:

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

Това име ще се появи в OpenTelemetry следите и ще улесни отстраняването на грешки. Направете си навик да го задавате от самото начало: в деня, в който търсите причината защо едно изпълнение е отнело четиридесет минути, ще четете смислени етикети, а не списък с имена на функции.

Ограничения за размер

Два лимита регулират обмена: максимум 2 MB за входните параметри и максимум 2 MB за върнатата стойност. Те произтичат директно от изходното събитие (event sourcing), тъй като тези стойности се сериализират и съхраняват в дневника.

Практическото следствие е ясно. Ако трябва да обработвате големи файлове – 40 MB сканиран PDF, архив с експорт – не ги предавайте от дейност на дейност. Съхранявайте ги във външна услуга (S3, GCS) и циркулирайте само URL адреса или идентификатора: дейността изтегля файла, го обработва, записва резултата обратно в хранилището и връща референция от няколкостотин байта.

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

  • Дейността е async функция, декорирана с @workflows.activity(), която извършва реалната работа (I/O, API, БД)
  • Параметрите и върнатите стойности трябва да бъдат JSON-сериализируеми
  • Дейностите нямат ограничения за детерминизъм
  • Успешна дейност никога не се изпълнява отново по време на възпроизвеждане
  • Дейностите трябва да бъдат идемпотентни (същият резултат при многократно изпълнение)
  • Лимит от 2 MB за вход и изход на всяка дейност