Инсталиране на Workflows SDK
На тази страница
Технически предпоставки
Преди да напишете първия ред код за работен поток, трябва да осигурите четири неща. Първо, Ви е необходим 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 в отделни файлове за по-добра поддръжка