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

Инсталиране на Workflows SDK

Урок 3 от 14 Обновен 29 юли 2026 г. Напреднало
На тази страница
  1. Технически предпоставки
  2. Проверка на версията на Python
  3. Инсталиране на uv
  4. Създаване на проект
  5. Инсталиране на Workflows SDK
  6. Проверка на инсталацията
  7. Конфигуриране на Вашия API ключ
  8. Бързо скелетиране (по желание)
  9. Препоръчителна структура на проекта
  10. Ключови изводи

Технически предпоставки

Преди да напишете първия ред код за работен поток, трябва да осигурите четири неща. Първо, Ви е необходим Python 3.12 или по-нова версия, тъй като работните потоци разчитат на модерни асинхронни функции, въведени в тази версия. Python 3.11 ще се провали още при импортирането, а не по време на изпълнение, което поне прави грешката незабавна. Второ, Ви е необходим uv – мениджърът на пакети, препоръчан от Mistral за Python проекти. Той управлява както виртуалните среди, така и зависимостите. Накрая, Ви е необходим акаунт в Mistral AI. Създайте такъв на console.mistral.ai, ако все още нямате, и генерирайте API ключ в секцията API Keys на конзолата.

Проверка на версията на Python

Започнете с най-честото препятствие: версията на интерпретатора.

python --version
# Трябва да покаже Python 3.12.x или по-висока

Ако Вашата версия е по-ниска от 3.12, актуализирайте Python, преди да продължите. На Ubuntu/Debian:

sudo apt update
sudo apt install python3.12 python3.12-venv

На macOS с Homebrew:

brew install [email protected]

Инсталиране на uv

Ако все още нямате uv, инсталирайте го. Командата варира според системата:

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

След това проверете дали изпълнимият файл е във Вашия PATH. Ако следната команда върне “not found”, отворете нов терминал. Инсталаторът модифицира профила на Вашата обвивка:

uv --version

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

Създайте нов Python проект с uv:

mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init

Това създава файл pyproject.toml и стандартна структура на проекта. Файлът pyproject.toml изброява Вашите зависимости и позволява на колега да възпроизведе точно същата среда.

Инсталиране на Workflows SDK

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

uv add mistralai-workflows

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

uv add "mistralai-workflows[mistralai]"

Вторият вариант инсталира Mistral AI SDK като зависимост и позволява нативна интеграция с моделите на Mistral. Ако не сте сигурни в началото на проекта, основната версия е по-лека. Можете да добавите екстрите по-късно, без да нарушите нищо.

Проверка на инсталацията

Успешното импортиране е по-добро от дълга ръчна проверка:

uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"

Трябва да видите:

Workflows SDK installed successfully!

Ако получите ModuleNotFoundError, не преинсталирайте веднага. Първо проверете дали се намирате в папката на проекта, където сте изпълнили uv add. Командата uv run разрешава виртуалната среда от текущата директория.

Конфигуриране на Вашия API ключ

SDK удостоверява достъпа чрез променливата на средата MISTRAL_API_KEY. Тя се чете автоматично; не е необходимо да я предавате като аргумент. Задайте я във Вашия терминал:

# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"

# За да я направите постоянна, добавете я във Вашия ~/.bashrc или ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc

Този метод работи за локална разработка. За производствени проекти предпочитайте .env файл, зареден чрез python-dotenv, или мениджъра на тайни на Вашата платформа за разполагане. Ключ, съхранен във файл .bashrc, рано или късно ще попадне в архив или споделен екран.

Бързо скелетиране (по желание)

Mistral предоставя CLI инструмент, който генерира цялостен проект за работен поток. Това е полезно, за да видите очакваната структура, преди да напишете своя собствена:

uvx mistralai-workflows-cli setup

Командата създава примерен файл за работен поток, файл за дейности, готов за стартиране worker и основна конфигурация. За секунди получавате работещ проект. След това можете да го разглобите част по част, за да разберете ролята на всеки компонент, преди да започнете от нулата.

Препоръчителна структура на проекта

За производствен проект с работни потоци препоръчваме следната структура:

mon-workflow-mistral/
├── pyproject.toml          # Зависимости (mistralai-workflows)
├── .env                    # API ключ (не комитвайте)
├── activities/
│   ├── __init__.py
│   ├── email.py            # Дейности, свързани с имейли
│   └── data_processing.py  # Дейности за обработка на данни
├── workflows/
│   ├── __init__.py
│   └── pipeline.py         # Дефиниции на работни потоци
└── worker.py               # Входна точка на worker

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

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

  • За Workflows SDK са задължителни Python 3.12+ и uv
  • Два режима на инсталиране: основен (mistralai-workflows) или с AI интеграция (mistralai-workflows[mistralai])
  • Конфигурирайте API ключа чрез променливата на средата MISTRAL_API_KEY
  • Командата uvx mistralai-workflows-cli setup генерира цялостен примерен проект
  • Разделете Вашите дейности, работни потоци и worker в отделни файлове за по-добра поддръжка