🏢 ML в продакшене: от бизнес-задачи до мониторинга

Зачем этот гайд

Ты умеешь обучать модели. Знаешь, что такое F1-score и ROC-AUC. Может, даже побеждал на Kaggle. Но в компании тебя ждёт неприятный сюрприз: 80% работы ML-инженера — это НЕ обучение моделей. Это процессы, инфраструктура, командная работа, A/B тесты и бесконечный мониторинг.

Этот гайд — про то, как ML-проект живёт в реальной компании. 10 этапов от "PM пришёл с идеей" до "модель крутится в проде и ты спишь спокойно". С конкретным кодом, инструментами и тремя сквозными примерами.

• 💼 Бизнес-задача → 🔍 Discovery → 📋 Design Doc → 📊 Планирование → 🔧 Разработка
• 👀 Code Review → 🧪 A/B тест → 🚀 Деплой → 📈 Мониторинг → 🔄 Итерация

💼 Блок 1: Бизнес-задача

ML-задача никогда не начинается с "давайте обучим нейронку". Она начинается с бизнес-проблемы: PM приходит с болью, а ты должен понять — это вообще ML-задача или хватит трёх строк regex? Спойлер: в половине случаев хватит regex.

На этом этапе твоя задача — задать правильные вопросы. Какой объём данных? Есть ли разметка? Какой SLA по latency? Сколько стоит ручной процесс? Если не задашь — потратишь 2 месяца на модель, которая никому не нужна.

• Откуда берётся задача: Product Owner/PM приходит с бизнес-проблемой, а не с техническим решением
• Когда правила → ML: когда правила перестают масштабироваться (100 regex-ов и всё равно Recall 30%)
• Stakeholders: PM, Tech Lead, DS Lead, бизнес-заказчик
• Приоритизация: Impact vs Effort matrix, RICE scoring (Reach × Impact × Confidence / Effort)
• Результат этапа: Epic в Jira, чёткая формулировка проблемы, stakeholders согласованы

🎬 День из жизни: NLP модерация

PM показывает дашборд: жалобы на токсичные комментарии выросли на 40% за месяц. 3 модератора обрабатывают 2000 комментариев в день — очередь растёт. Стоимость: $6000/мес. Твоя задача — задать правильные вопросы.

-- Первым делом — понять масштаб проблемы
SELECT 
    date_trunc('week', created_at) AS week,
    count(*) AS total_comments,
    sum(CASE WHEN has_complaint THEN 1 ELSE 0 END) AS complaints,
    round(100.0 * sum(CASE WHEN has_complaint THEN 1 ELSE 0 END) / count(*), 2) AS complaint_rate
FROM moderation.comments
WHERE created_at >= now() - interval '3 months'
GROUP BY 1
ORDER BY 1;
-- Видим: complaint_rate вырос с 0.8% до 1.3% → тренд подтверждён

После встречи создаёшь Epic в Jira и делаешь quick research: Jigsaw competition на Kaggle (BERT-based, F1 ~0.95 на английском), Google Perspective API (не кастомизируется), ruBERT pretrained на toxicity. Фиксируешь всё в Notion.

# Jira Epic
title: "[ML] Автоматическая модерация комментариев"
priority: High
labels: [ml, nlp, moderation]
description: |
      toxic/ok.
  -:    50%,    70%.
   : 6000/   .

• Jira / Linear — трекинг задач, Epic → Stories → Tasks
• Confluence / Notion — документация, Research Notes
• RICE scoring — приоритизация: Reach × Impact × Confidence / Effort
• Miro — визуализация процессов, brainstorming

🔍 Блок 2: Discovery

Discovery — это фаза "а оно вообще работает?". Тут ты получаешь доступы, лезешь в данные, считаешь baseline и пишешь Feasibility Report. Если baseline (TF-IDF + LogReg) даёт 85% accuracy — задача решаема ML. Если regex даёт 95% — забудь про нейронки, иди пить кофе.

Длительность: 3-10 дней. Главное правило — не начинать строить pipeline, пока не доказал, что ML тут вообще нужен.

🎬 День из жизни: Discovery NLP модерации

День 1: получаешь доступы к DWH, настраиваешь окружение.

# Получаешь доступ к DWH
psql -h dwh.company.com -U ml_analyst -d production 
  -c "SELECT count(*) FROM moderation.comments;"
# → 1,247,832

# Настраиваешь ML-окружение
git clone git@github.com:company/ml-models.git && cd ml-models
git checkout -b research/moderation-discovery

# Зависимости
pyenv install 3.11.7 && pyenv local 3.11.7
poetry init
poetry add pandas numpy matplotlib seaborn scikit-learn jupyter sqlalchemy psycopg2-binary
poetry install

Дни 2-3: EDA — выгружаешь данные и ищешь паттерны.

SELECT 
    c.comment_id,
    c.text,
    c.user_id,
    c.created_at,
    m.is_toxic,
    m.toxic_category,  -- insult, threat, spam, etc.
    m.moderator_id,
    u.account_age_days,
    u.total_comments,
    u.total_reports
FROM moderation.comments c
JOIN moderation.labels m ON c.comment_id = m.comment_id
LEFT JOIN users.profiles u ON c.user_id = u.user_id
WHERE c.created_at >= '2024-01-01'
  AND m.moderated_at IS NOT NULL
ORDER BY c.created_at DESC;
-- Результат: ~180K строк

import pandas as pd
from sqlalchemy import create_engine

engine = create_engine('postgresql://ml_analyst:***@localhost:5432/production')
df = pd.read_sql(query, engine)
df.to_parquet('data/moderation_raw.parquet')
print(f"Shape: {df.shape}")  # (183421, 11)

# Базовые статистики
print(df['is_toxic'].value_counts(normalize=True))
# False    0.917
# True     0.083   ← 8.3% toxic — imbalanced!

print(df['toxic_category'].value_counts())
# insult      8234
# spam        3912
# threat      1456
# hate_speech  987
# other        623

import seaborn as sns
import matplotlib.pyplot as plt

fig, axes = plt.subplots(2, 2, figsize=(14, 10))

# Распределение длин текстов
df['text_length'] = df['text'].str.len()
sns.histplot(df['text_length'], bins=50, ax=axes[0, 0])
axes[0, 0].set_title('Распределение длин комментариев')

# Toxic vs Non-toxic длины
sns.boxplot(x='is_toxic', y='text_length', data=df, ax=axes[0, 1])
axes[0, 1].set_title('Длина текста: toxic vs ok')

# Динамика по времени
df.set_index('created_at').resample('W')['is_toxic'].mean().plot(ax=axes[1, 0])
axes[1, 0].set_title('Доля toxic по неделям')

# Категории
df[df['is_toxic']]['toxic_category'].value_counts().plot.bar(ax=axes[1, 1])
axes[1, 1].set_title('Категории токсичности')

plt.tight_layout()
plt.savefig('data/eda_overview.png', dpi=150)

Проверяешь качество разметки: дубликаты, inter-annotator agreement (Cohen's kappa = 0.78 — хорошо), NULL-ы в текстах.

Дни 4-5: строишь baseline модели.

import re
from sklearn.metrics import classification_report

# Baseline 0: Regex + стоп-слова
toxic_patterns = [
    r'\bидиот\b', r'\bдурак\b', r'\bубью\b', r'\bспам\b',
    r'\bдебил\b', r'\bтупой\b',  # ~100 паттернов
]
toxic_regex = re.compile('|'.join(toxic_patterns), re.IGNORECASE)
df['pred_regex'] = df['text'].apply(lambda x: bool(toxic_regex.search(x)))

print(classification_report(df['is_toxic'], df['pred_regex']))
#               precision    recall  f1-score
# toxic             0.71      0.31      0.43   ← Recall ужасный!

from sklearn.model_selection import train_test_split
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import classification_report, roc_auc_score

# Baseline 1: TF-IDF + LogReg
X_train, X_test, y_train, y_test = train_test_split(
    df['text'], df['is_toxic'], test_size=0.2,
    random_state=42, stratify=df['is_toxic']
)

tfidf = TfidfVectorizer(max_features=30000, ngram_range=(1, 2))
X_train_tfidf = tfidf.fit_transform(X_train)
X_test_tfidf = tfidf.transform(X_test)

model = LogisticRegression(class_weight='balanced', max_iter=1000)
model.fit(X_train_tfidf, y_train)

y_pred = model.predict(X_test_tfidf)
y_proba = model.predict_proba(X_test_tfidf)[:, 1]

print(classification_report(y_test, y_pred))
#               precision    recall  f1-score
# toxic             0.82      0.65      0.73

print(f"ROC-AUC: {roc_auc_score(y_test, y_proba):.3f}")
# ROC-AUC: 0.891

Коммитишь ноутбуки и создаёшь Feasibility Report.

git add experiments/moderation/
git commit -m "feat(moderation): EDA + baselines (regex F1=0.43, tfidf+lr F1=0.73)"
git push origin research/moderation-discovery

• Jupyter + pandas — EDA, визуализации, baseline эксперименты
• SQL к DWH — выгрузка и анализ данных
• scikit-learn — быстрые baseline модели (LogReg, RF)
• Confluence / Notion — Feasibility Report
• Git — версионирование ноутбуков и кода

📋 Блок 3: Design Doc

Design Doc — это документ на 3-5 страниц, который отвечает на три вопроса: ЧТО делаем, КАК и ПОЧЕМУ именно так. Если ты пропускаешь Design Doc и идёшь сразу кодить — поздравляю, ты переделаешь архитектуру на третьей неделе. Проверено.

Design Doc ревьюят ML Lead, Tech Lead и PM. Каждый проверяет своё: ML Lead — подход и метрики, Tech Lead — инфраструктуру и SLA, PM — бизнес-метрики и timeline. Без трёх ✅ LGTM — дальше не идёшь.

• Problem Statement — бизнес-проблема в одном абзаце
• Success Metrics — офлайн (F1, AUC) + онлайн (жалобы, конверсия) + guardrail (latency)
• Proposed Approach — модель, фичи, данные, архитектура
• Alternatives Considered — почему не правила, почему не GPT-4 API
• Risks & Mitigations — data drift, bias, latency spikes
• Timeline — оценка в спринтах
• Dependencies — GPU, Feature Store, доступы

🎬 День из жизни: Design Doc для NLP модерации

# ML Design Doc: Auto-Moderation System

**Author:** @your-name  
**Reviewers:** @ml-lead, @tech-lead, @pm  
**Status:** Draft  Approved 

## 1. Problem Statement
    +40%  .
  (3 , 2000 /)  .
    human-in-the-loop  edge cases.

## 2. Success Metrics

### Offline
| Metric | Target | Rationale |
|--------|--------|-----------|
| F1 (toxic) |  0.85 | Baseline TF-IDF+LR = 0.73,    |
| Precision |  0.90 | FP =      UX |
| Latency p95 | <  |    |

### Online (A/B)
| Metric | Target |
|--------|--------|
|    | -50% |
| False Positive Rate | < 5% |
|   | -70% |

### Guardrail
-   > 15%  (  engagement)
- Latency p99 < 

## 3. Proposed Approach

### Model
- **Primary:** ruBERT-tiny2 ( params) fine-tuned   
- **Fallback:** TF-IDF + LogReg ( BERT  )

### Serving Architecture

User Comment  API Gateway  Moderation Service (FastAPI)
                                    
                              ruBERT-tiny2 (ONNX Runtime)
                                    
                  score > 0.85  auto-block
                  0.5 < score < 0.85  moderator queue
                  score < 0.5  auto-approve


## 4. Alternatives Considered
| Approach | Decision | Why |
|----------|----------|-----|
| Regex + - |  | Recall 0.31    |
| GPT-4 API |  | 0.03/req  /day = 1500/day |
| Perspective API |  |  ,   |
| ruBERT-tiny2 ft |  |  quality/speed/cost |

## 5. Risks
| Risk | Mitigation |
|------|-----------|
| Data drift ( ) | Monthly retrain + PSI  |
| Adversarial (l33t speak) | Text normalization pipeline |
| Bias () |   , fairness  |

## 6. Timeline
- Sprint 1: Data pipeline + training (2 )
- Sprint 2: Evaluation + serving (2 )
- Sprint 3: A/B + monitoring + rollout (2 )

Отправляешь на ревью. ML Lead просит обосновать threshold 0.85, Tech Lead предлагает Triton вместо чистого FastAPI, PM согласовывает бизнес-метрики. Вносишь правки → три ✅ → Status: Approved.

• Google Docs / Notion / Confluence — сам документ
• Шаблон ML Design Doc — стандартизация по компании
• Miro — визуализация архитектуры

📊 Блок 4: Планирование

Тут Design Doc превращается в задачи. Scrum или Kanban — зависит от фазы: research лучше ложится на Kanban (поток, без жёстких дедлайнов), production — на Scrum (спринты, story points, чёткие цели). На практике большинство ML-команд используют гибрид.

Главная ловушка ML-планирования: ты не знаешь, сколько займёт "обучить модель". Может 2 дня, может 2 недели. Решение — timeboxing: "3 дня на эксперименты с CatBoost, если не работает — пробуем другой подход". Не уходи в rabbit hole.

• Scrum: 2-недельные спринты, Planning Poker, velocity tracking
• Kanban: непрерывный поток, WIP limits, подходит для research
• Timeboxing: исследование ≠ детерминированная задача, ставь таймеры
• Story Points: Fibonacci (1/2/3/5/8/13), Planning Poker для оценки
• Spike tasks: research-задачи с фиксированным временем (2 дня на исследование подхода X)

🎬 День из жизни: Sprint Planning

Sprint Planning, 2 часа. ML Lead открывает Miro, команда декомпозирует Design Doc на задачи. Каждая задача — карточка с чёткими Acceptance Criteria.

# Sprint 1 — Data & Baseline (2 недели)

ML-101:
  title: "ETL pipeline для модерационных данных"
  story_points: 3
  description: |
       DWH  parquet  S3,
      Airflow DAG, scheduled daily
  acceptance_criteria: "DAG работает, данные обновляются ежедневно"
  assignee: "@you"

ML-102:
  title: "Data quality checks"
  story_points: 2
  description: |
    Great Expectations suite  moderation.comments
    Checks: schema, null rate < 0.1%, text length > 0
  assignee: "@you"

ML-103:
  title: "Baseline TF-IDF + LogReg"
  story_points: 3
  description: |
     baseline,   MLflow
  acceptance_criteria: "classification_report в MLflow, модель в registry"
  assignee: "@you"

ML-104:
  title: "Setup MLflow tracking"
  story_points: 2
  description: |
     MLflow  tracking URI, experiment, artifact store (S3)
  assignee: "@you"

# Sprint 2 — Model Experiments (2 недели)

ML-201:
  title: "Fine-tune ruBERT-tiny"
  story_points: 5
  description: "Fine-tune на наших данных, залогировать в MLflow"

ML-202:
  title: "Feature engineering (user history)"
  story_points: 3
  description: "account_age, total_reports, comment_length → дополнительные фичи"

ML-203:
  title: "Hyperparameter tuning + model selection"
  story_points: 3
  description: "Grid search lr, epochs, class weights. Выбор лучшей модели."

ML-204:
  title: "Offline evaluation report"
  story_points: 2
  description: "classification_report + confusion matrix + error analysis"

# Sprint 3 — Production (2 недели)

ML-301:
  title: "FastAPI serving endpoint"
  story_points: 3

ML-302:
  title: "A/B test infrastructure + canary deploy"
  story_points: 3

ML-303:
  title: "Monitoring dashboards (Grafana)"
  story_points: 2

Planning Poker: ты показываешь 3 за ETL pipeline, коллега — 5 (думает нужна инкрементальная загрузка). Обсуждаете: "для MVP хватит full refresh раз в день" → сходитесь на 3. Итого Sprint 1: 10 SP, velocity команды 12 SP/sprint — ок, с запасом.

Daily Standup (каждое утро, 15 минут). Формат: вчера / сегодня / блокеры.

# Типичный стендап ML-инженера

:  ETL DAG (ML-101),   staging  
    4 . 
:  Great Expectations  (ML-102). 
 .

: baseline   MLflow, F1=0.73. 
:  Sprint 2, fine-tune ruBERT. 
:  GPU-  infra, 
@devops    INFRA-342

• Jira / Linear — борда задач, sprint management
• Planning Poker — оценка story points
• Miro — декомпозиция, визуализация
• Confluence — Sprint Goals, capacity planning

🔧 Блок 5: Разработка

Самый весёлый этап — ты наконец-то пишешь код. Но не как на Kaggle. Тут каждый эксперимент логируется в MLflow, данные версионируются через DVC, конфиги — через Hydra. Если ты обучил модель без логирования — ты её не обучил.

Правило номер один: не уходи в rabbit hole. Timeboxing — твой лучший друг. Если за 3 дня CatBoost не даёт прирост — пробуй другой подход, а не крутишь гиперпараметры до посинения.

• Experiment tracking: MLflow / W&B — каждый run с параметрами, метриками, артефактами
• Data versioning: DVC + S3 — чтобы знать, на каких данных обучена какая модель
• Config management: Hydra — один конфиг, разные эксперименты через override
• Feature branches: feature/toxicity-model-v1 → PR → merge в main
• Timeboxing: 3 дня на подход, не работает — pivot

🎬 День из жизни: Разработка NLP модерации

День 1: настраиваешь MLflow и Hydra конфиг.

# configs/moderation/train.yaml (Hydra)
model:
  name: "cointegrated/rubert-tiny2"
  max_length: 128
  num_labels: 2

training:
  lr: 2e-5
  epochs: 5
  batch_size: 32
  warmup_ratio: 0.1
  weight_decay: 0.01
  class_weight: "balanced"

data:
  train_path: "s3://ml-data/moderation/train.parquet"
  val_path: "s3://ml-data/moderation/val.parquet"
  test_path: "s3://ml-data/moderation/test.parquet"

mlflow:
  tracking_uri: "http://mlflow.internal:5000"
  experiment_name: "moderation-toxic-classifier"

# src/data/prepare_moderation_data.py
import pandas as pd
from sklearn.model_selection import train_test_split

def prepare_data(input_path: str, output_dir: str, seed: int = 42):
    df = pd.read_parquet(input_path)

    # Чистка
    df = df.dropna(subset=['text'])
    df = df[df['text'].str.len() >= 3]
    df = df.drop_duplicates(subset=['comment_id'])

    # Препроцессинг
    df['text_clean'] = (
        df['text']
        .str.lower()
        .str.replace(r'http\S+', '[URL]', regex=True)
        .str.replace(r'@\w+', '[USER]', regex=True)
        .str.strip()
    )

    # Stratified split
    train, temp = train_test_split(
        df, test_size=0.3, stratify=df['is_toxic'], random_state=seed
    )
    val, test = train_test_split(
        temp, test_size=0.5, stratify=temp['is_toxic'], random_state=seed
    )

    print(f"Train: {len(train)} (toxic: {train['is_toxic'].mean():.3f})")
    print(f"Val:   {len(val)} (toxic: {val['is_toxic'].mean():.3f})")
    print(f"Test:  {len(test)} (toxic: {test['is_toxic'].mean():.3f})")

    train.to_parquet(f"{output_dir}/train.parquet")
    val.to_parquet(f"{output_dir}/val.parquet")
    test.to_parquet(f"{output_dir}/test.parquet")

Версионируешь данные через DVC — чтобы через полгода точно знать, на каких данных обучена модель v1.

dvc init
dvc add data/moderation/
dvc push  # → S3
git add data/moderation/.dvc data/moderation/.gitignore
git commit -m "feat(data): versioned moderation dataset v1 (183K samples)"

Дни 2-3: эксперименты с BERT. Запускаешь на GPU-сервере.

# src/train.py — тренировочный скрипт
import hydra
import mlflow
import numpy as np
from transformers import (
    AutoTokenizer,
    AutoModelForSequenceClassification,
    Trainer,
    TrainingArguments,
)
from sklearn.metrics import f1_score, precision_score, recall_score

@hydra.main(config_path="../configs/moderation", config_name="train")
def train(cfg):
    mlflow.set_tracking_uri(cfg.mlflow.tracking_uri)
    mlflow.set_experiment(cfg.mlflow.experiment_name)

    with mlflow.start_run(run_name=f"{cfg.model.name}_lr{cfg.training.lr}"):
        mlflow.log_params({
            "model": cfg.model.name,
            "lr": cfg.training.lr,
            "epochs": cfg.training.epochs,
            "batch_size": cfg.training.batch_size,
        })

        tokenizer = AutoTokenizer.from_pretrained(cfg.model.name)
        model = AutoModelForSequenceClassification.from_pretrained(
            cfg.model.name, num_labels=cfg.model.num_labels
        )

        train_dataset = ModerationDataset(
            cfg.data.train_path, tokenizer, cfg.model.max_length
        )
        val_dataset = ModerationDataset(
            cfg.data.val_path, tokenizer, cfg.model.max_length
        )

        def compute_metrics(eval_pred):
            logits, labels = eval_pred
            preds = np.argmax(logits, axis=-1)
            return {
                "f1_toxic": f1_score(labels, preds, pos_label=1),
                "precision_toxic": precision_score(labels, preds, pos_label=1),
                "recall_toxic": recall_score(labels, preds, pos_label=1),
            }

        training_args = TrainingArguments(
            output_dir="./outputs/moderation",
            num_train_epochs=cfg.training.epochs,
            per_device_train_batch_size=cfg.training.batch_size,
            learning_rate=cfg.training.lr,
            warmup_ratio=cfg.training.warmup_ratio,
            eval_strategy="epoch",
            save_strategy="epoch",
            load_best_model_at_end=True,
            metric_for_best_model="f1_toxic",
            fp16=True,
            report_to="mlflow",
        )

        trainer = Trainer(
            model=model,
            args=training_args,
            train_dataset=train_dataset,
            eval_dataset=val_dataset,
            compute_metrics=compute_metrics,
        )

        trainer.train()

        # Evaluate on test set
        test_dataset = ModerationDataset(
            cfg.data.test_path, tokenizer, cfg.model.max_length
        )
        test_results = trainer.evaluate(test_dataset)
        mlflow.log_metrics({
            f"test_{k}": v for k, v in test_results.items()
        })

        trainer.save_model("./outputs/moderation/best_model")
        mlflow.pytorch.log_model(model, "model")

if __name__ == "__main__":
    train()

Запускаешь серию экспериментов, переопределяя параметры через Hydra CLI.

# Эксперимент 1: базовый
poetry run python src/train.py

# Эксперимент 2: другой learning rate
poetry run python src/train.py training.lr=3e-5 training.epochs=5

# Эксперимент 3: с class weights
poetry run python src/train.py training.lr=3e-5 training.class_weight=balanced

# Эксперимент 4: с user features
poetry run python src/train.py --config configs/moderation/train_with_features.yaml

Смотришь сравнение в MLflow UI:

MLflow: moderation-toxic-classifier

 Run Name             lr     epochs  F1     Prec   Recall 

 rubert_lr2e-5        2e-5   3       0.811  0.867  0.762  
 rubert_lr3e-5        3e-5   5       0.842  0.881  0.806  
 rubert_balanced      3e-5   5       0.862  0.852  0.872  
 rubert+features      3e-5   5       0.881  0.903  0.860    best!

День 4: error analysis — смотришь, где модель ошибается.

# error_analysis.py — анализ ошибок
import pandas as pd
from sklearn.metrics import confusion_matrix, ConfusionMatrixDisplay

test_df = pd.read_parquet("data/moderation/test.parquet")
test_df['pred'] = predictions
test_df['pred_proba'] = probabilities

# False Negatives — пропущенные toxic
fn = test_df[(test_df['is_toxic'] == True) & (test_df['pred'] == False)]
print(f"False Negatives: {len(fn)}")
# Паттерн: модель пропускает завуалированную токсичность
# "ты такой умный, просто гений 🙄" — сарказм

# False Positives — нормальные заблокированы
fp = test_df[(test_df['is_toxic'] == False) & (test_df['pred'] == True)]
print(f"False Positives: {len(fp)}")
# Паттерн: цитирование токсичности
# "он написал мне 'ты идиот', это ненормально"

# Confusion matrix
cm = confusion_matrix(test_df['is_toxic'], test_df['pred'])
ConfusionMatrixDisplay(cm, display_labels=['ok', 'toxic']).plot()

# Регистрируешь лучшую модель в MLflow Model Registry
mlflow models register --model-uri "runs:/<run_id>/model" 
  --name "moderation-toxic-classifier"

mlflow models transition --name "moderation-toxic-classifier" 
  --version 1 --stage Staging

git add src/ configs/ experiments/moderation/
git commit -m "feat(moderation): ruBERT+features F1=0.881, registered in MLflow"
git push origin feature/moderation-model-v1

• MLflow — experiment tracking, model registry, artifact store
• DVC — data versioning (данные в S3, метаданные в Git)
• Hydra — config management, CLI overrides
• W&B (Weights & Biases) — альтернатива MLflow с красивым UI
• PyTorch / HuggingFace Transformers — fine-tuning моделей

👀 Блок 6: Code Review + Testing

Ты написал модель, метрики огонь, всё работает на твоём ноутбуке. Теперь нужно, чтобы это работало у коллег. И через полгода. Code Review в ML — это не только "красиво ли написан код", но и "нет ли data leakage?", "воспроизводим ли результат?", "где тесты?".

ML-код особенный: баги тут часто не ломают программу, а тихо портят метрики. Data leakage — king of silent bugs. Поэтому тесты для ML — это не только unit tests на функции, но и data validation, model quality gates и smoke tests.

• Data leakage — фичи из будущего, утечка таргета → модель "знает" ответ
• Reproducibility — random seed, pinned dependencies, version всего
• Пирамида тестов ML: unit → integration → data validation → model quality → smoke
• Git flow: GitHub Flow (main + feature branches) для команд 3-10 человек
• Pre-commit hooks: black, ruff, mypy — автоматически при каждом коммите

🎬 День из жизни: PR и Code Review

Пишешь тесты: unit tests на preprocessing, integration tests на pipeline, model quality tests.

# tests/test_preprocessing.py
import pytest
from src.data.preprocessing import clean_text

class TestCleanText:
    def test_url_replacement(self):
        assert clean_text("check https://example.com pls") == "check [URL] pls"

    def test_mention_replacement(self):
        assert clean_text("@user123 привет") == "[USER] привет"

    def test_empty_string(self):
        assert clean_text("") == ""

    def test_unicode_handling(self):
        assert clean_text("тест 🔥 эмодзи") == "тест 🔥 эмодзи"

    def test_lowercase(self):
        assert clean_text("КАПС ЛОК") == "капс лок"

# tests/test_model.py
import pytest
import time
from src.model.toxic_classifier import ToxicClassifier

class TestToxicClassifier:
    @pytest.fixture
    def model(self):
        return ToxicClassifier.from_pretrained("outputs/moderation/best_model")

    def test_predict_returns_valid_proba(self, model):
        result = model.predict("тест")
        assert 0 <= result['toxic_probability'] <= 1

    def test_predict_batch(self, model):
        texts = ["привет", "ты идиот", "хорошая статья"]
        results = model.predict_batch(texts)
        assert len(results) == 3

    def test_obviously_toxic(self, model):
        result = model.predict("ты полный идиот, убирайся")
        assert result['toxic_probability'] > 0.7

    def test_obviously_ok(self, model):
        result = model.predict("спасибо за помощь, отличная статья")
        assert result['toxic_probability'] < 0.3

    def test_latency(self, model):
        start = time.time()
        for _ in range(100):
            model.predict("тестовый комментарий для проверки")
        avg_ms = (time.time() - start) / 100 * 1000
        assert avg_ms < 50, f"Avg latency {avg_ms:.1f}ms > 50ms SLA"

# Запуск тестов
poetry run pytest tests/ -v --cov=src --cov-report=html
# ==================== 24 passed in 8.3s ====================
# Coverage: 87%

Настраиваешь pre-commit hooks и создаёшь PR.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/psf/black
    rev: 23.12.0
    hooks:
      - id: black
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.9
    hooks:
      - id: ruff
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        additional_dependencies: [types-requests, pandas-stubs]

## PR: Toxic Comment Classifier v1

### Summary
ruBERT-tiny2 + user features   .

### Metrics
| Metric | Target | Achieved |
|--------|--------|----------|
| F1 (toxic) |  0.85 | **0.881**  |
| Precision |  0.90 | **0.903**  |
| Latency p95 | <  | ****  |

### MLflow
Experiment: moderation-toxic-classifier
Best run: rubert_features_lr3e-5

### Checklist
- [x] Unit tests passing (24 tests, 87% coverage)
- [x] Metrics above threshold
- [x] No data leakage (checked temporal split)
- [x] Model registered in MLflow
- [x] Design Doc approved

ML Lead комментирует PR:

# Добавляешь по результатам ревью: оптимизация threshold
from sklearn.metrics import precision_recall_curve
import numpy as np

def find_optimal_threshold(
    y_true, y_proba, min_precision: float = 0.90
) -> float:
    """Find threshold maximizing F1 while keeping precision >= min_precision."""
    precisions, recalls, thresholds = precision_recall_curve(y_true, y_proba)
    f1_scores = 2 * (precisions * recalls) / (precisions + recalls + 1e-8)
    valid = precisions[:-1] >= min_precision
    if not valid.any():
        return 0.5
    best_idx = np.argmax(f1_scores[:-1] * valid)
    return float(thresholds[best_idx])

# Результат: optimal_threshold = 0.62 → F1 вырос до 0.889

CI проходит (GitHub Actions: lint + tests + model quality gate), ML Lead ставит ✅ → Squash & Merge.

# .github/workflows/ml-ci.yml
name: ML CI
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install poetry && poetry install
      - run: poetry run pytest tests/ -v --tb=short
      - run: poetry run ruff check src/
      - run: poetry run mypy src/ --ignore-missing-imports

  model-quality:
    runs-on: [self-hosted, gpu]
    steps:
      - uses: actions/checkout@v4
      - run: poetry install
      - run: |
          poetry run python src/evaluate.py 
            --model outputs/moderation/best_model 
            --test-data data/moderation/test.parquet 
            --min-f1 0.85 --min-precision 0.90

• GitHub / GitLab — PR review, branch protection rules
• GitHub Actions — CI: lint, tests, model quality gates
• pytest — unit + integration tests
• Great Expectations / Pandera — data validation tests
• pre-commit — автоформатирование и линтинг

🧪 Блок 7: A/B тест

Офлайн метрики — это хорошо, но единственный способ проверить влияние на бизнес — запустить A/B тест на живых пользователях. Offline F1=0.88 не гарантирует, что жалобы упадут. Может, пользователям нравится токсичность (шутка… почти).

Классическая ошибка новичка: "О, на второй день уже значимый результат, выкатываем!" Нет. Жди минимум неделю, а лучше две. Novelty effect, дневные/недельные циклы, Simpson's paradox — всё это может тебя обмануть.

• Сплитование: hash(user_id + experiment) % 100 — детерминированное, один пользователь = одна группа
• Стратегии: Shadow mode → Canary (1-5%) → Partial (10-50%) → Full rollout
• Метрики A/B: Primary (бизнес), Secondary (модельные), Guardrail (не должна деградировать)
• Significance: p-value < 0.05, power analysis для минимального размера выборки
• MDE: Minimum Detectable Effect — какой эффект хочешь увидеть (10%? 20%? 50%?)

🎬 День из жизни: A/B тест NLP модерации

День 1: настраиваешь сплитование и логирование.

# src/serving/experiment.py — детерминированное сплитование
import hashlib

def get_experiment_group(
    user_id: str, experiment_name: str = "moderation_v1"
) -> str:
    """Один и тот же user всегда в одной группе."""
    hash_input = f"{user_id}:{experiment_name}"
    hash_value = int(hashlib.md5(hash_input.encode()).hexdigest(), 16)
    bucket = hash_value % 100

    if bucket < 5:    # 0-4: 5% treatment
        return "treatment"  # ML модель
    else:             # 5-99: 95% control
        return "control"    # ручная модерация (status quo)

# configs/experiments/moderation_v1.yaml
experiment:
  name: "moderation_v1"
  status: "running"
  start_date: "2024-09-15"
  planned_end_date: "2024-09-29"  # 2 недели
  traffic_split:
    treatment: 5   # %
    control: 95

  metrics:
    primary: "complaint_rate"
    secondary: ["latency_p95", "auto_block_rate"]
    guardrail: ["false_positive_rate", "engagement_rate"]

  thresholds:
    min_sample_size: 10000
    significance_level: 0.05
    min_effect_size: 0.15

# src/serving/app.py — A/B модерация
from fastapi import FastAPI
from prometheus_client import Counter, Histogram

app = FastAPI()

moderation_requests = Counter(
    'moderation_requests_total',
    'Total moderation requests',
    ['group', 'decision']
)
moderation_latency = Histogram(
    'moderation_latency_seconds',
    'Moderation latency',
    ['group']
)

@app.post("/moderate")
async def moderate_comment(request: ModerationRequest):
    group = get_experiment_group(request.user_id)

    with moderation_latency.labels(group=group).time():
        if group == "treatment":
            result = ml_model.predict(request.text)
            if result['toxic_probability'] > 0.62:
                decision = "block"
            elif result['toxic_probability'] > 0.3:
                decision = "review"
            else:
                decision = "approve"
        else:
            decision = "review"  # всё идёт к модераторам

    moderation_requests.labels(group=group, decision=decision).inc()

    # Логируем в ClickHouse для офлайн-анализа
    log_to_clickhouse({
        'comment_id': request.comment_id,
        'user_id': request.user_id,
        'group': group,
        'decision': decision,
        'model_score': result.get('toxic_probability'),
    })

    return {"decision": decision, "group": group}

Дни 3-14: мониторишь эксперимент. Каждый день — 5 минут на дашборд.

# scripts/ab_analysis.py — ежедневный анализ A/B
import pandas as pd
from statsmodels.stats.proportion import proportions_ztest

# Данные из ClickHouse
# control:   142000 комментариев, 1847 жалоб (1.30%)
# treatment:   7500 комментариев,   63 жалобы (0.84%)

stat, pvalue = proportions_ztest(
    [63, 1847],        # complaints
    [7500, 142000],    # total
    alternative='smaller'
)
print(f"p-value: {pvalue:.4f}")     # Day 7: p=0.021, Day 14: p=0.003

effect = 1 - (63 / 7500) / (1847 / 142000)
print(f"Effect: {effect:.1%}")       # -35% complaints

День 14: принятие решения. Показываешь результаты PM и ML Lead.

# A/B Results: moderation_v1 (2 weeks)

| Metric          | Control | Treatment |      | p-value |
|-----------------|---------|-----------|-------|---------|
| Complaint rate  | 1.30%   | 0.84%     | -35%  | 0.003  |
| FP rate         | N/A     | 3.2%      | <5%   |       |
| Latency p95     |     |       | + | < |
| Block rate      | 0%      | 11.4%     | <15%  |       |

Decision: ROLLOUT to 100% 

• scipy.stats / statsmodels — Z-test, t-test, p-value
• Prometheus + Grafana — real-time мониторинг эксперимента
• ClickHouse — хранение логов эксперимента для офлайн-анализа
• Split.io / LaunchDarkly — feature flags, traffic splitting
• Custom A/B platform — у крупных компаний своя инфраструктура

🚀 Блок 8: Деплой

Модель обучена, A/B выиграл, теперь нужно выкатить на 100% трафика и не сломать прод. Деплой ML-модели — это Docker + K8s + CI/CD + ONNX оптимизация + canary rollout. Если ты просто делаешь scp model.pkl server:/app/ — мы не друзья.

Три паттерна serving: online (FastAPI, latency < 100ms), batch (Airflow, раз в час/день) и streaming (Kafka + Flink). Выбор зависит от SLA: модерация — online, рекомендации — batch precompute + online reranking, OCR — batch.

• Online serving: FastAPI / Triton / TF Serving, latency < 100ms
• Batch serving: Airflow / Spark, обновление раз в час/день
• Streaming: Kafka + Flink, near real-time
• ONNX export: 3× ускорение inference (PyTorch → ONNX Runtime)
• Canary rollout: 1% → 10% → 50% → 100%, мгновенный rollback при ошибках

🎬 День из жизни: Деплой NLP модерации

День 1: ONNX export и Docker.

# scripts/export_onnx.py — экспорт в ONNX для быстрого inference
import torch
from transformers import AutoTokenizer, AutoModelForSequenceClassification

model = AutoModelForSequenceClassification.from_pretrained(
    "outputs/moderation/best_model"
)
tokenizer = AutoTokenizer.from_pretrained(
    "outputs/moderation/best_model"
)

dummy_input = tokenizer(
    "тестовый комментарий",
    return_tensors="pt",
    max_length=128,
    padding="max_length",
    truncation=True,
)

torch.onnx.export(
    model,
    (dummy_input['input_ids'], dummy_input['attention_mask']),
    "outputs/moderation/model.onnx",
    input_names=['input_ids', 'attention_mask'],
    output_names=['logits'],
    dynamic_axes={
        'input_ids': {0: 'batch', 1: 'seq'},
        'attention_mask': {0: 'batch', 1: 'seq'},
        'logits': {0: 'batch'},
    },
    opset_version=14,
)

# Сравнение latency:
# PyTorch:      avg 38ms
# ONNX Runtime: avg 12ms → 3x faster! ✅

# Dockerfile
FROM python:3.11-slim AS base
WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends 
    libgomp1 && rm -rf /var/lib/apt/lists/*

COPY pyproject.toml poetry.lock ./
RUN pip install poetry && 
    poetry config virtualenvs.create false && 
    poetry install --only main --no-interaction

COPY src/ src/
COPY configs/ configs/
COPY outputs/moderation/model.onnx /models/moderation/model.onnx
COPY outputs/moderation/tokenizer/ /models/moderation/tokenizer/

HEALTHCHECK --interval= --timeout= 
    CMD curl -f http://localhost:8000/health || exit 1

EXPOSE 8000
CMD ["uvicorn", "src.serving.app:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

# src/serving/app.py — production FastAPI
from fastapi import FastAPI
from pydantic import BaseModel
import onnxruntime as ort
from transformers import AutoTokenizer
import numpy as np
from prometheus_client import make_asgi_app, Histogram, Counter
import time

app = FastAPI(title="Moderation Service", version="1.0.0")
metrics_app = make_asgi_app()
app.mount("/metrics", metrics_app)

LATENCY = Histogram('moderation_predict_seconds', 'Prediction latency')
PREDICTIONS = Counter(
    'moderation_predictions_total', 'Total predictions', ['decision']
)

tokenizer = AutoTokenizer.from_pretrained("/models/moderation/tokenizer")
ort_session = ort.InferenceSession(
    "/models/moderation/model.onnx",
    providers=['CPUExecutionProvider'],
)
THRESHOLD = 0.62

class ModerationRequest(BaseModel):
    text: str
    comment_id: str | None = None
    user_id: str | None = None

class ModerationResponse(BaseModel):
    toxic_probability: float
    decision: str
    latency_ms: float

@app.post("/predict", response_model=ModerationResponse)
async def predict(request: ModerationRequest):
    start = time.time()

    inputs = tokenizer(
        request.text, return_tensors="np",
        max_length=128, padding="max_length", truncation=True,
    )

    logits = ort_session.run(None, {
        'input_ids': inputs['input_ids'],
        'attention_mask': inputs['attention_mask'],
    })[0]

    probs = np.exp(logits) / np.exp(logits).sum(axis=-1, keepdims=True)
    toxic_prob = float(probs[0][1])

    if toxic_prob > THRESHOLD:
        decision = "block"
    elif toxic_prob > 0.3:
        decision = "review"
    else:
        decision = "approve"

    latency_ms = (time.time() - start) * 1000
    LATENCY.observe(latency_ms / 1000)
    PREDICTIONS.labels(decision=decision).inc()

    return ModerationResponse(
        toxic_probability=toxic_prob,
        decision=decision,
        latency_ms=round(latency_ms, 1),
    )

@app.get("/health")
async def health():
    return {"status": "ok", "model": "loaded"}

# Build и тест
docker build -t moderation-service:v1.0.0 .

docker run -p 8000:8000 moderation-service:v1.0.0

# Smoke tests
curl -X POST http://localhost:8000/predict 
  -H "Content-Type: application/json" 
  -d '{"text": "отличная статья, спасибо!"}'
# {"toxic_probability": 0.023, "decision": "approve", "latency_ms": 11.3}

curl -X POST http://localhost:8000/predict 
  -d '{"text": "ты полный дебил, убирайся отсюда"}'
# {"toxic_probability": 0.947, "decision": "block", "latency_ms": 12.1}

# Push to registry
docker tag moderation-service:v1.0.0 registry.company.com/ml/moderation-service:v1.0.0
docker push registry.company.com/ml/moderation-service:v1.0.0

День 2: Kubernetes deployment и canary rollout.

# k8s/moderation-service.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: moderation-service
  namespace: ml
spec:
  replicas: 3
  selector:
    matchLabels:
      app: moderation-service
  template:
    metadata:
      labels:
        app: moderation-service
        version: v1.0.0
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "8000"
        prometheus.io/path: "/metrics"
    spec:
      containers:
        - name: moderation
          image: registry.company.com/ml/moderation-service:v1.0.0
          ports:
            - containerPort: 8000
          resources:
            requests:
              memory: "512Mi"
              cpu: "500m"
            limits:
              memory: "1Gi"
              cpu: "1000m"
          readinessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 10
          livenessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 30