Руководство по быстрому старту

git clone <repository-url>
cd engineering_practices_ml

# Автоматическая установка (рекомендуется)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Добавить в PATH для текущей сессии
export PATH="$HOME/.local/bin:$PATH"

# Или добавить в ~/.bashrc для постоянного использования
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Проверка установки
uv --version

pip install uv

# Создание виртуального окружения
uv venv

# Активация виртуального окружения
# Для Linux/macOS:
source .venv/bin/activate

# Для Windows:
# .venv\Scripts\activate

# После активации в начале строки терминала должно появиться (.venv)
which python  # Должен показать путь к .venv/bin/python
python --version  # Должен показать Python 3.10+

# Запустить скрипт автоматической настройки
./scripts/setup/setup.sh

# Скрипт автоматически:
# 1. Создаст виртуальное окружение (.venv)
# 2. Установит все зависимости
# 3. Настроит pre-commit hooks

source .venv/bin/activate  # Linux/macOS
# или
.venv\Scripts\activate  # Windows

# Убедитесь, что виртуальное окружение активировано
# (см. Шаг 3)

# Установка зависимостей через UV (включая dev зависимости)
uv sync --all-extras

# Проверка установки
python --version
pip list

deactivate

# Установка hooks
pre-commit install

# Проверка всех файлов (рекомендуется после установки)
pre-commit run --all-files

# Инициализация DVC (если еще не инициализирован)
dvc init --no-scm

# Если DVC уже инициализирован, будет ошибка - это нормально
# Используйте -f для переинициализации: dvc init --no-scm -f

dvc remote add local storage/local

# Запуск MinIO
docker compose up -d minio

# Проверка статуса (должен быть "healthy")
docker compose ps minio

# Автоматическая настройка (если скрипт существует)
# ./scripts/setup/setup_minio.sh

# Или вручную:
dvc remote add minio s3://engineering-practices-ml/dvc
dvc remote modify minio endpointurl http://localhost:9000
dvc remote modify minio access_key_id minioadmin --local
dvc remote modify minio secret_access_key minioadmin --local
dvc remote default minio

docker compose exec -T minio sh -c "
  mc alias set local http://localhost:9000 minioadmin minioadmin && \
  mc mb local/engineering-practices-ml 2>/dev/null || echo 'Bucket уже существует'
"

dvc remote add s3 s3://engineering-practices-ml/dvc

# Настройка credentials через переменные окружения или .dvc/config.local
# AWS_ACCESS_KEY_ID=your_key
# AWS_SECRET_ACCESS_KEY=your_secret

# Список всех remote storage
dvc remote list

# Проверка текущего default remote
dvc remote default

# Просмотр конфигурации
cat .dvc/config

# Автоматически через скрипт (если существует)
./scripts/data/track_data.sh data/raw/WineQT.csv

# Или вручную
dvc add data/raw/WineQT.csv
git add data/raw/WineQT.csv.dvc .gitignore
git commit -m "data: add WineQT dataset"

# Запуск стадии prepare_data
dvc repro prepare_data

# Проверка статуса
dvc status

# Просмотр графа зависимостей
dvc dag

# Запуск стадии validate_data
dvc repro validate_data

# Проверка результата
cat reports/metrics/data_validation.json

# Запуск стадии train_model (использует модель из конфигурации)
dvc repro train_model

# Проверка результата
ls -lh models/model.pkl
cat reports/metrics/model_metrics.json

# Использование утилиты для изменения параметров и запуска
python scripts/pipeline/run_with_params.py train_model -S model_type=ridge
python scripts/pipeline/run_with_params.py train_model -S model_type=rf
python scripts/pipeline/run_with_params.py train_model -S model_type=gb

# Изменить model_type в params.yaml
# Затем запустить
dvc repro train_model

# config/train_params.yaml
model:
  model_type: rf  # или linear, ridge, lasso, elasticnet, knn, svr, dt, rf, ada, gb
  params:
    n_estimators: 100
    max_depth: 10

# Запуск стадии evaluate_model
dvc repro evaluate_model

# Проверка результата
cat reports/metrics/evaluation.json
cat reports/plots/confusion_matrix.json

# Запуск стадии monitor_pipeline (автоматически после evaluate_model)
dvc repro monitor_pipeline

# Или запуск полного пайплайна с мониторингом
python scripts/pipeline/run_pipeline.py --config config/train_params.yaml --monitor

# Просмотр последнего отчета
cat reports/monitoring/pipeline_report.json

# Или через Python
python -c "
import json
from pathlib import Path
report = json.load(open('reports/monitoring/pipeline_report.json'))
print('Статус:', report['summary'])
"

# Установить local как default remote (для локальной разработки)
dvc remote default local

# Или установить minio как default remote (если MinIO запущен)
dvc remote default minio

# Проверить текущий default remote
dvc remote default

# Отправка в default remote
dvc push

# Отправка в конкретный remote (без установки default)
dvc push --remote local
dvc push --remote minio

# Загрузка из default remote
dvc pull

# Загрузка из конкретного remote (без установки default)
dvc pull --remote local
dvc pull --remote minio

The Access Key Id you provided does not exist in our records.

docker compose up -d minio

export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export AWS_DEFAULT_REGION=us-east-1

dvc push -r minio

The specified bucket does not exist.

engineering-practices-ml

dvc push -r minio

# Автоматическая настройка (если скрипт существует)
# ./scripts/setup/setup_experiments.sh

# Или вручную - конфигурации экспериментов создаются при первом запуске
# Это создаст:
# - Конфигурации экспериментов в config/experiments/
# - Необходимые директории

# Запуск всех 26 экспериментов
python scripts/experiments/run_all_experiments.py

# Или запуск одного эксперимента
python scripts/experiments/run_experiment.py \
  --model rf \
  --config config/experiments/exp_018_rf_100_10.yaml

# Список всех экспериментов
python scripts/experiments/compare_experiments.py --list

# Сравнение двух экспериментов
python scripts/experiments/compare_experiments.py \
  --compare exp_001_linear exp_002_ridge_1.0

# Фильтрация по модели
python scripts/experiments/compare_experiments.py --filter-model rf

# Фильтрация по метрикам
python scripts/experiments/compare_experiments.py \
  --min-r2 0.5 --max-rmse 0.8

# Поиск экспериментов
python scripts/experiments/compare_experiments.py --search ridge

# Экспорт в CSV
python scripts/experiments/compare_experiments.py --export experiments.csv

from src.data_science_project import experiment_tracker

# Создание трекера
tracker = experiment_tracker.DVCExperimentTracker()

# Логирование параметров
tracker.log_params("exp_001", {"alpha": 1.0, "max_depth": 10})

# Логирование метрик
tracker.log_metrics("exp_001", {"test_r2": 0.85, "test_rmse": 0.5})

# Использование декоратора
from src.data_science_project.experiment_tracker import track_experiment

@track_experiment(experiment_id="exp_001")
def train_model(**params):
    # Код обучения
    return {"test_r2": 0.85}

# Использование контекстного менеджера
from src.data_science_project.experiment_tracker import experiment

with experiment("exp_001", params={"alpha": 1.0}) as tracker:
    # Код эксперимента
    tracker.log_metrics("exp_001", metrics)

# Запуск всех стадий последовательно
dvc repro

# Это выполнит:
# 1. prepare_data - подготовка данных
# 2. validate_data - валидация данных
# 3. train_model - обучение модели
# 4. evaluate_model - оценка модели
# 5. monitor_pipeline - мониторинг выполнения

# DVC автоматически определит независимые стадии и выполнит их параллельно
dvc repro --jobs 4

# Например, validate_data и train_model могут выполняться параллельно
# после завершения prepare_data

# Изменение нескольких параметров одновременно
python scripts/pipeline/run_with_params.py train_model \
  -S model_type=ridge \
  -S enable_validation=true

# Или изменение params.yaml напрямую
# 1. Отредактировать params.yaml (изменить model_type)
# 2. dvc repro train_model

# Запуск через скрипт с полным мониторингом
python scripts/pipeline/run_pipeline.py \
  --config config/train_params.yaml \
  --monitor

# Запуск конкретных стадий с мониторингом
python scripts/pipeline/run_pipeline.py \
  --config config/train_params.yaml \
  --monitor \
  --stages prepare_data validate_data train_model

# Результат:
# - Выполнение всех стадий
# - Отслеживание времени выполнения каждой стадии
# - Сохранение отчета мониторинга в reports/monitoring/
# - Уведомление о завершении
# - Детальная сводка выполнения

# Визуализация зависимостей между стадиями
dvc dag

# Вывод покажет:
# - Порядок выполнения стадий
# - Зависимости между стадиями
# - Возможности параллельного выполнения

# Проверка, какие стадии нужно перезапустить
dvc status

# Вывод покажет:
# - Измененные зависимости
# - Стадии, требующие перезапуска
# - Статус кэширования

# Black
black src tests scripts

# isort
isort src tests scripts

# Ruff (check + format)
ruff check src tests scripts
ruff format src tests scripts

# Или через Makefile
make format

# MyPy (проверка типов)
mypy src

# Bandit (проверка безопасности)
bandit -r src

# Ruff (проверка стиля)
ruff check src tests scripts

# Или через Makefile
make lint

# Запуск всех тестов
pytest

# С покрытием кода
pytest --cov=src --cov-report=html

# Или через Makefile
make test
make test-cov

docker build -t engineering-practices-ml .

# Простой запуск
docker run -it engineering-practices-ml

# С монтированием директорий
docker run -it \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/src:/app/src \
  engineering-practices-ml

# Запуск MinIO и проекта
docker compose up -d

# Просмотр логов
docker compose logs -f

# Остановка
docker compose down

# Остановка с удалением volumes
docker compose down -v

# Основные ветки
git checkout main      # Стабильная версия
git checkout develop   # Ветка разработки

# Создание веток для работы
git checkout -b feature/new-feature    # Новая функция
git checkout -b bugfix/fix-name        # Исправление ошибки
git checkout -b hotfix/urgent-fix     # Срочное исправление

# Pre-commit hooks запустятся автоматически
git add .
git commit -m "feat: описание изменений"

# Если нужно пропустить hooks (не рекомендуется)
git commit --no-verify -m "message"

# Если нужно переинициализировать
dvc init --no-scm -f

# Или просто используйте существующую конфигурацию
dvc status

# Убедитесь, что все стадии pipeline выполнены
dvc repro

# Затем попробуйте pull снова
dvc pull

# Проверка статуса
docker compose ps minio

# Просмотр логов
docker compose logs minio

# Перезапуск
docker compose restart minio

# Полная переустановка
docker compose down -v
docker compose up -d minio

# Переустановка hooks
pre-commit uninstall
pre-commit install

# Обновление hooks
pre-commit autoupdate

# Проверка вручную
pre-commit run --all-files

# Проверка конкретного файла
mypy src/data_science_project/experiment_tracker.py

# Игнорирование отсутствующих импортов (если нужно)
mypy src --ignore-missing-imports

# Запуск pipeline для создания модели
dvc repro train_model

# Или принудительное обновление
dvc commit -f

# Проверка статуса всех сервисов
docker compose ps

# Просмотр логов конкретного сервиса
docker compose logs clearml-server
docker compose logs clearml-webserver
docker compose logs clearml-mongo
docker compose logs clearml-elastic
docker compose logs clearml-redis

# Если сервер показывает "unhealthy", но работает (возвращает HTTP коды):
# Healthcheck был исправлен в docker-compose.yml
# Просто перезапустите сервер:
docker compose up -d --force-recreate clearml-server

# Перезапуск всех сервисов ClearML
docker compose restart clearml-mongo clearml-elastic clearml-redis clearml-server clearml-webserver

# Полная переустановка
docker compose down -v
docker compose up -d clearml-mongo clearml-elastic clearml-redis clearml-server clearml-webserver

# Ожидание готовности (может занять 1-2 минуты)
sleep 60
curl http://localhost:8080
curl http://localhost:8008

# Проверьте, что все сервисы запущены
docker compose ps

# Убедитесь, что API Server и Web UI работают
# API Server может возвращать 400 для корневого пути - это нормально
curl http://localhost:8008
curl http://localhost:8080

# Проверьте логи на наличие ошибок
docker compose logs clearml-server | tail -50

# Если сервер показывает "unhealthy", но отвечает на запросы:
# Это может быть проблема с healthcheck (исправлено в docker-compose.yml)
# Попробуйте перезапустить:
docker compose up -d --force-recreate clearml-server

# Проверьте credentials
clearml-init

# Или установите переменные окружения
export CLEARML_API_HOST=http://localhost:8008
export CLEARML_WEB_HOST=http://localhost:8080
export CLEARML_API_ACCESS_KEY=<your-key>
export CLEARML_API_SECRET_KEY=<your-key>

# После создания credentials, проверьте их:
clearml-init

# Или установите переменные окружения:
export CLEARML_API_HOST=http://localhost:8008
export CLEARML_API_SECRET_KEY=<your-secret-key>
export CLEARML_API_ACCESS_KEY=<your-access-key>

# Статус pipeline
dvc status

# Запуск всего pipeline
dvc repro

# Запуск конкретной стадии
dvc repro prepare_data
dvc repro validate_data
dvc repro train_model
dvc repro evaluate_model
dvc repro monitor_pipeline

# Запуск нескольких стадий
dvc repro prepare_data validate_data train_model

# Запуск с изменением параметров через утилиту
python scripts/pipeline/run_with_params.py train_model -S model_type=ridge
python scripts/pipeline/run_with_params.py train_model -S model_type=gb

# Или изменение params.yaml и запуск
# 1. Изменить model_type в params.yaml
# 2. dvc repro train_model

# Сравнение метрик
dvc metrics diff

# Сравнение параметров
dvc params diff

# Просмотр метрик
dvc metrics show

# Информация об окружении
uv --version

# Список зависимостей
uv pip list

# Обновление зависимостей
uv sync --upgrade

# Добавление новой зависимости
uv add package-name

# Добавление dev зависимости
uv add --group dev package-name

# Показать все доступные команды
make help

# Установка зависимостей
make install

# Форматирование кода
make format

# Линтинг
make lint

# Тесты
make test
make test-cov

# Очистка временных файлов
make clean

# Docker команды
make docker-build
make docker-run

# 1. Проверка установки зависимостей
python --version
dvc --version

# 2. Проверка качества кода
pre-commit run --all-files

# 3. Проверка DVC
dvc status
dvc remote list

# 4. Проверка Docker (если используется)
docker compose ps

# 5. Запуск тестов
pytest

# 6. Запуск основного pipeline
dvc repro

# 7. Проверка мониторинга
ls -lh reports/monitoring/
cat reports/monitoring/pipeline_report.json

# 8. Проверка Pydantic моделей
python -c "from src.data_science_project.config_models import TrainingConfig; print('✅ Pydantic models OK')"

# 9. Проверка ClearML (если настроен)
python -c "from src.data_science_project.clearml_tracker import ClearMLTracker; print('✅ ClearML OK')" 2>/dev/null || echo "⚠️ ClearML не настроен (опционально)"

# Запуск всех сервисов ClearML
docker compose up -d clearml-mongo clearml-elastic clearml-redis clearml-server clearml-fileserver clearml-webserver

# Или запуск всех сервисов сразу
docker compose up -d

# Проверка статуса
docker compose ps

# Просмотр логов
docker compose logs -f clearml-server
docker compose logs -f clearml-webserver

# ClearML Web UI: http://localhost:8080
# ClearML API: http://localhost:8008
# ClearML File Server: http://localhost:8081
# MongoDB: mongodb://localhost:27017
# Redis: redis://localhost:6379
# Elasticsearch: http://localhost:9200
# Transport-порт Elasticsearch: 9300 (для внешних агентов)
# Примеры проверок:
#   curl http://localhost:9200/_cluster/health?pretty
#   mongo --host localhost --eval "db.runCommand({ping:1})"
#   redis-cli -h localhost ping

PROJECT="Engineering Practices ML"

# Создать все шаблонные задачи одной командой
python scripts/clearml/create_task_templates.py \
  --project "$PROJECT" \
  --queue default \
  --all

# Или создать задачи по одной (интерактивный режим)
python scripts/clearml/create_task_templates.py --project "$PROJECT"

python scripts/clearml/compare_experiments.py --list --limit 10

# Через скрипт (с указанием credentials)
python scripts/clearml/init_clearml.py \
  --api-host http://localhost:8008 \
  --web-host http://localhost:8080 \
  --access-key <your-access-key> \
  --secret-key <your-secret-key>

# Или через переменные окружения
export CLEARML_API_HOST=http://localhost:8008
export CLEARML_WEB_HOST=http://localhost:8080
export CLEARML_API_ACCESS_KEY=<your-access-key>
export CLEARML_API_SECRET_KEY=<your-secret-key>
clearml-init

# Или запустите скрипт без параметров - он покажет инструкции
python scripts/clearml/init_clearml.py

# Проверьте, что ClearML может подключиться
python -c "from clearml import Task; print('✅ ClearML подключен')"

# Обучение модели с трекингом
python scripts/clearml/train_with_clearml.py \
  --config config/train_params.yaml \
  --model-type ridge \
  --experiment-name ridge_experiment_001

# Список экспериментов
python scripts/clearml/compare_experiments.py --list

# Сравнение
python scripts/clearml/compare_experiments.py \
  --compare <task_id_1> <task_id_2>

# Список моделей
python scripts/clearml/manage_models.py --list

# Регистрация модели
python scripts/clearml/manage_models.py \
  --register models/model.pkl \
  --name wine_quality_model

# Создание и запуск пайплайна
python scripts/clearml/ml_pipeline.py \
  --model-type rf \
  --queue default

from src.data_science_project.clearml_tracker import ClearMLTracker

# Создание трекера
tracker = ClearMLTracker(
    project_name="Engineering Practices ML",
    task_name="my_experiment",
    tags=["ridge", "training"]
)

# Логирование параметров
tracker.log_params({"alpha": 1.0, "max_depth": 10})

# Логирование метрик
tracker.log_metrics({"test_r2": 0.85, "test_rmse": 0.5})

# Регистрация модели
tracker.log_model(
    model_path="models/model.pkl",
    model_name="wine_quality_model",
    metadata={"version": "1.0.0"}
)

# Закрытие задачи
tracker.close()

notifications {
    slack {
        url = "https://hooks.slack.com/services/XXX/YYY/ZZZ"
        channel = "#mlops-alerts"
        notify_failed = true
        notify_completed = true
    }
}