Създаване на дейност
На тази страница
Какво представлява дейността?
Дейността е основната оперативна единица в един работен поток. Тук се извършва реалната работа: външни 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 за вход и изход на всяка дейност