AI API — Искусственный интеллект

Справочник AI API: генерация контента, скоринг, сегментация, предиктивные модели, A/B тест-предсказания, рекомендации, эмбеддинги.

Обзор AI-модуля

AI-модуль Trigly предоставляет инструменты машинного обучения и генеративного AI для маркетинга: от генерации текстов до предсказания оттока клиентов. 26 эндпоинтов, 9 подмодулей.

Технологии:

  • OpenAI GPT-4o-mini — генерация текстов, анализ, рекомендации
  • scikit-learn — предиктивные модели (GradientBoosting)
  • OpenAI text-embedding-3-small — семантический поиск
  • Redis — кэширование результатов AI

API prefix: /api/v1/ai

Провайдер AI

Trigly использует двухуровневую систему провайдеров:

  1. OpenAIProvider — реальные вызовы GPT-4o-mini через AsyncOpenAI. Используется при наличии OPENAI_API_KEY в настройках.
  2. MockProvider — захардкоженные ответы для тестирования. Автоматически активируется, если API-ключ отсутствует или при ошибке OpenAI.

Все результаты кэшируются в Redis: текст — 1 час, рекомендации — 4 часа. Ключ кэша: ai:{type}:{sha256(params)}.

Генерация контента

Генерация темы письма

POST /api/v1/ai/generate/subject

Тело запроса:

{
  "product_description": "Весенняя коллекция одежды",
  "audience": "Женщины 25-45, средний чек 5000 руб",
  "tone": "friendly",
  "count": 5
}

Ответ:

{
  "subjects": [
    "Весна начинается с обновления гардероба",
    "Новая коллекция уже ждёт вас",
    "5 трендов весны, которые вы полюбите",
    "Ваш весенний look готов — осталось выбрать",
    "Только для вас: первый доступ к весенней коллекции"
  ],
  "generation_id": "uuid",
  "model_used": "gpt-4o-mini",
  "tokens_used": 250
}

Генерация тела письма

POST /api/v1/ai/generate/email-body

Тело запроса:

{
  "subject": "Весенняя коллекция уже здесь",
  "product_description": "Новая коллекция женской одежды",
  "audience": "Женщины 25-45",
  "tone": "professional",
  "cta": "Перейти в каталог",
  "include_html": true
}

Возвращает HTML-тело письма с инлайн-стилями, готовое для отправки.

Генерация SMS

POST /api/v1/ai/generate/sms

Тело запроса:

{
  "offer": "Скидка 20% на весеннюю коллекцию",
  "brand": "FashionStore",
  "max_length": 70,
  "include_stop": true
}

Генерирует SMS-текст с учётом ограничения длины (70 символов кириллицей = 1 сегмент).

Генерация вариантов

POST /api/v1/ai/generate/variants

Генерирует несколько вариантов контента для A/B тестирования. Возвращает 3-5 вариантов с разным тоном, длиной и CTA.

Рекомендации по сегменту

POST /api/v1/ai/generate/segment-suggestion

AI анализирует данные организации и предлагает новые сегменты для кампаний.

Рекомендации по кампании

POST /api/v1/ai/generate/campaign-suggestion

Предложения по типу кампании, каналу, времени отправки на основе текущих данных.

Текст для попапа

POST /api/v1/ai/generate/popup-text

Генерирует заголовок, описание и CTA для pop-up виджета конверсий.

Еженедельный дайджест

POST /api/v1/ai/generate/digest

AI формирует еженедельный отчёт с ключевыми метриками и рекомендациями.

Лучшее время отправки

POST /api/v1/ai/generate/best-send-time

Анализ паттернов активности аудитории и рекомендация оптимального времени отправки.

Скоринг

Скоринг темы письма

POST /api/v1/ai/scoring/subject

Тело запроса:

{
  "subject": "Не пропустите! Скидка 50% только сегодня!!!"
}

Ответ:

{
  "score": 35,
  "factors": {
    "spam_words": -20,
    "excessive_punctuation": -15,
    "urgency": +5,
    "length": -5,
    "personalization": -10,
    "clarity": +10
  },
  "recommendations": [
    "Уберите восклицательные знаки — более 1 снижает доверие",
    "Слова 'Не пропустите' часто попадают в спам-фильтры",
    "Добавьте персонализацию: имя получателя или конкретный продукт",
    "Оптимальная длина темы: 30-50 символов"
  ]
}

AI-скоринг контактов

POST /api/v1/ai/scoring/customers

Тело запроса:

{
  "customer_ids": ["uuid1", "uuid2", "uuid3"]
}

Пересчитывает ai_score (0-100) для указанных контактов. Композитный показатель:

Компонент Вес (без CH) Вес (с CH) Описание
Engagement 30% 25% Открытия, клики, визиты
Monetary 30% 25% Выручка, средний чек
Recency 20% 20% Давность последней активности
Loyalty 20% 15% Длительность отношений
Diversity — 15% Разнообразие каналов и событий

Результат сохраняется в customers.ai_score и customers.ai_score_updated_at.

Массовый пересчёт скоринга

POST /api/v1/ai/scoring/recalculate-all

Запускает Celery-задачу recalculate_ai_scores для всех контактов организации. Асинхронная операция.

Сегментация (K-Means)

Кластеризация

POST /api/v1/ai/segmentation/cluster

Тело запроса:

{
  "min_clusters": 4,
  "max_clusters": 8,
  "features": ["rfm_recency", "rfm_frequency", "rfm_monetary"]
}

Ответ:

{
  "optimal_k": 5,
  "silhouette_score": 0.72,
  "clusters": [
    {
      "cluster_id": 0,
      "name": "VIP-покупатели",
      "size": 500,
      "centroid": {"rfm_recency": 4.8, "rfm_frequency": 4.5, "rfm_monetary": 4.9},
      "description": "Активные клиенты с высоким чеком и частыми покупками"
    },
    {
      "cluster_id": 1,
      "name": "Новички",
      "size": 3000,
      "centroid": {"rfm_recency": 4.2, "rfm_frequency": 1.2, "rfm_monetary": 1.5},
      "description": "Недавние клиенты с 1-2 покупками"
    }
  ]
}

Алгоритм: K-Means на RFM-признаках. Оптимальное k определяется по silhouette score (перебор от min_clusters до max_clusters). Названия кластеров генерируются через LLM.

Создание сегментов из кластеров

POST /api/v1/ai/segmentation/create-segments

Создаёт реальные CDP-сегменты из результатов кластеризации. Каждый кластер → статический сегмент.

Предиктивные модели

Предсказание оттока

POST /api/v1/ai/predictions/churn

Тело запроса:

{
  "customer_ids": ["uuid1", "uuid2"]
}

Ответ:

{
  "predictions": [
    {
      "customer_id": "uuid1",
      "churn_probability": 0.82,
      "risk_level": "high",
      "top_factors": [
        {"factor": "days_since_last_purchase", "value": 75, "impact": 0.35},
        {"factor": "purchase_frequency_days", "value": 120, "impact": 0.25},
        {"factor": "email_open_rate_30d", "value": 0.05, "impact": 0.20}
      ]
    }
  ]
}

Модель: GradientBoostingClassifier. Целевая переменная: нет активности 60 дней.

12 признаков:

  1. days_since_last_purchase
  2. purchase_frequency_days
  3. total_orders
  4. total_revenue
  5. avg_order_value
  6. Дни с регистрации
  7. event_count_30d (ClickHouse)
  8. unique_event_types (ClickHouse)
  9. avg_events_per_day (ClickHouse)
  10. days_since_last_event (ClickHouse)
  11. page_view_count (ClickHouse)
  12. session_count (ClickHouse)

Признаки 7-12 — опциональные (ClickHouse event features). Модель работает и без них (backward compatible).

Предсказание LTV

POST /api/v1/ai/predictions/ltv

Ответ:

{
  "predictions": [
    {
      "customer_id": "uuid1",
      "predicted_ltv": 25000.0,
      "confidence": 0.75,
      "current_revenue": 8000.0,
      "growth_potential": 3.1
    }
  ]
}

Модель: GradientBoostingRegressor. Предсказывает total_revenue на основе текущего поведения.

Предсказание следующей покупки

POST /api/v1/ai/predictions/next-purchase

Ответ:

{
  "predictions": [
    {
      "customer_id": "uuid1",
      "predicted_days": 12,
      "predicted_date": "2026-03-23",
      "confidence": 0.68
    }
  ]
}

Модель: GradientBoostingRegressor. Предсказывает количество дней до следующей покупки на основе среднего интервала между покупками.

Обучение моделей

POST /api/v1/ai/predictions/train

Тело запроса:

{
  "model_type": "churn"
}

Запускает обучение модели на данных организации. model_type: churn, ltv, next_purchase, all.

Обучение выполняется асинхронно через Celery. Модели хранятся in-memory (пересоздаются при перезапуске сервера).

A/B тест-предсказания

Байесовское предсказание

POST /api/v1/ai/ab-test/predict

Тело запроса:

{
  "variants": [
    {"name": "A", "sends": 5000, "conversions": 150},
    {"name": "B", "sends": 5000, "conversions": 180}
  ],
  "confidence_threshold": 0.95
}

Ответ:

{
  "winner": "B",
  "confidence": 0.92,
  "is_significant": false,
  "probabilities": {
    "A": 0.08,
    "B": 0.92
  },
  "expected_rates": {
    "A": {"mean": 0.030, "ci_lower": 0.025, "ci_upper": 0.035},
    "B": {"mean": 0.036, "ci_lower": 0.031, "ci_upper": 0.041}
  },
  "recommendation": "Вариант B лидирует с вероятностью 92%. Для достижения порога 95% нужно ещё ~2000 отправок."
}

Алгоритм: бета-распределения + Монте-Карло симуляция (10 000 итераций). Каждый вариант моделируется как Beta(conversions+1, sends-conversions+1).

Калькулятор размера выборки

POST /api/v1/ai/ab-test/sample-size

Тело запроса:

{
  "baseline_rate": 0.03,
  "minimum_detectable_effect": 0.005,
  "significance_level": 0.05,
  "power": 0.80
}

Ответ:

{
  "sample_size_per_variant": 15000,
  "total_sample_size": 30000,
  "estimated_duration_days": 5
}

Рекомендации

Что запускать

GET /api/v1/ai/recommendations/what-to-launch

AI анализирует данные организации (сегменты, кампании, метрики) и предлагает конкретные кампании для запуска.

Ответ:

{
  "recommendations": [
    {
      "type": "reactivation",
      "segment": "at_risk",
      "channel": "email",
      "reason": "1200 клиентов в сегменте at_risk. Средний LTV = 15000 руб. Потенциальная выручка при 10% реактивации: 1.8M руб.",
      "priority": "high",
      "estimated_roi": 450
    }
  ]
}

Лучшее время отправки

GET /api/v1/ai/recommendations/best-send-time

Анализ паттернов открытий и кликов по часам и дням недели.

Ответ:

{
  "best_times": [
    {"day": "tuesday", "hour": 10, "score": 0.92},
    {"day": "thursday", "hour": 14, "score": 0.88}
  ],
  "worst_times": [
    {"day": "sunday", "hour": 3, "score": 0.05}
  ]
}

Эмбеддинги

Семантический поиск клиентов

POST /api/v1/ai/embeddings/search

Тело запроса:

{
  "query": "Активные покупатели электроники с высоким чеком из Москвы",
  "limit": 20
}

Преобразует текстовое описание в эмбеддинг (OpenAI text-embedding-3-small), затем находит клиентов с наиболее похожими профилями по косинусному расстоянию.

Lookalike-аудитория

POST /api/v1/ai/embeddings/lookalike

Тело запроса:

{
  "seed_customer_ids": ["uuid1", "uuid2", "uuid3"],
  "limit": 100
}

Находит клиентов, похожих на указанных «seed»-клиентов. Используется для расширения аудитории: загрузите ID лучших клиентов → получите 100 похожих.

Примечание: эмбеддинги вычисляются на лету (не предрассчитаны). Для больших баз может потребовать значительного времени.

Автоматизации

Предложения по автоматизациям

POST /api/v1/ai/automations/suggest

Тело запроса:

{
  "business_type": "e-commerce",
  "current_automations": ["welcome_series", "abandoned_cart"]
}

Ответ:

{
  "suggestions": [
    {
      "name": "Post-purchase Review Request",
      "trigger": "purchase",
      "delay": "7 days",
      "actions": ["send_email"],
      "expected_impact": "Увеличение отзывов на 30%, что повысит конверсию на 5-10%",
      "priority": "medium",
      "flow_preset": "post_purchase"
    }
  ]
}

AI анализирует текущие автоматизации и предлагает новые на основе best practices для данного типа бизнеса.

История генераций

Список генераций

GET /api/v1/ai/generations?page=1&per_page=20&type=subject

Все AI-генерации сохраняются в модели AIGeneration:

  • generation_type — тип (subject, email_body, sms, scoring и т.д.)
  • prompt — исходный промпт
  • result — результат генерации
  • model_used — модель (gpt-4o-mini или mock)
  • tokens_used — количество токенов
  • generation_time_ms — время генерации

Получение генерации

GET /api/v1/ai/generations/{generation_id}

Celery-задачи

Задача Описание
train_churn_model Обучение модели оттока
train_ltv_model Обучение модели LTV
train_next_purchase_model Обучение модели следующей покупки
train_all_models Обучение всех моделей
recalculate_ai_scores Пересчёт ai_score для всех контактов

Ограничения и рекомендации

  1. Минимум данных для ML: предиктивные модели требуют минимум 100 контактов с покупками для обучения. При меньшем объёме данных модели дают неточные результаты.
  2. Модели in-memory: обученные модели хранятся в памяти worker-а. При перезапуске сервера модели переобучаются при первом вызове predict.
  3. Эмбеддинги on-the-fly: вычисляются при каждом запросе. Для баз > 10 000 контактов запрос может занимать 30+ секунд.
  4. Промпты на русском: все LLM-промпты написаны на русском языке для максимального качества генерации маркетинговых текстов на русском.
  5. Fallback на MockProvider: при недоступности OpenAI API все генеративные эндпоинты продолжают работать с захардкоженными ответами.
  6. Кэширование: результаты кэшируются в Redis (1-4 часа). Повторный запрос с теми же параметрами вернёт кэшированный результат.
Назад
Campaigns API
Далее
Analytics API

Не нашли ответ?

Swagger UI с интерактивной документацией и поддержка в Telegram.

Swagger UIНаписать в поддержку