AI API для анализа данных: от вопроса к отчёту (2026)

«Спросить данные одной фразой» звучит просто, но на практике нужно решить много задач: бизнес-показатели трактуются по-разному, схема таблиц сложна, сгенерированный SQL может ошибаться, права нельзя превышать, а результат должен быть объяснимым. Суть AI API для анализа данных не в том, чтобы модель «умела писать SQL», а в том, чтобы стабильно переводить вопрос на естественном языке в доверенные данные и отчёты.

Ниже — схема внедрения для компании: архитектура, проектирование схемы, промпты, проверки, права, тестирование точности и стоимость.

Примечание: базы данных, BI-платформы и интерфейсы моделей различаются; пример основан на распространённой связке «база только для чтения + OpenAI-совместимый диалоговый интерфейс». Модели и цены смотрите в разделе тарифов.

1. Общая архитектура

Цепочку стоит разбить на наблюдаемые шаги:

Вопрос на естественном языке
  → определение намерения (запрос / объяснение / уточнение)
  → поиск по схеме (таблицы, поля, метрики, примеры)
  → генерация SQL
  → статическая проверка + внедрение прав
  → выполнение только для чтения (тайм-аут, лимит строк)
  → проверка результата
  → конфигурация графика + текстовая интерпретация

Ключевые принципы:

Модель не подключается к продакшен-базе напрямую, только к реплике для чтения или хранилищу.
Права внедряются на сервере, а не через ограничения в промпте.
Каждый шаг оставляет лог: вопрос, найденные таблицы, сгенерированный SQL, время выполнения, число строк.
При сбое пользователь получает понятное объяснение, а не сырой текст ошибки базы.

2. Схема важнее модели

Модель не знает, как в вашей компании определяются «активный пользователь» или «действительный заказ». Эти знания нужно явно передать.

Для каждой таблицы рекомендуется вести «карточку схемы»:

Поле	Пример содержимого
Имя таблицы	dwd_order
Бизнес-смысл	Детализация заказов, одна строка — один товар в заказе
Первичный ключ / гранулярность	order_id + sku_id
Частые поля	Время заказа, сумма оплаты, статус, канал
Определение метрики	Сумма оплаты = фактически оплачено, без возвратов
Связанные таблицы	Пользователи, товары, каналы
Запрет	Не использовать create_time вместо времени оплаты
Пример вопроса	Сумма оплаты по каналам за последние 30 дней

Кроме карточек нужны:

бизнес-синонимы: GMV, выручка и оборот указывают на одну метрику;
словарь метрик: определение, числитель и знаменатель, временные рамки, задержка данных;
несколько примеров «вопрос → SQL» для типовых запросов;
пути join между таблицами, чтобы модель не угадывала ключи связи.

Поиск по схеме можно делать по ключевым словам и векторам, передавая в контекст 5–10 наиболее релевантных таблиц и определений. Передавать всю схему дорого и вредно: она мешает.

3. Как писать промпт

Цель промпта — ограничивать, а не вдохновлять. Рабочий шаблон:

Ты помощник по анализу данных компании. По заданной схеме и определениям метрик переведи вопрос пользователя в SQL.
Требования:
1. Генерируй только один оператор SELECT; INSERT/UPDATE/DELETE/DDL запрещены.
2. Используй только предоставленные таблицы и поля, не придумывай поля.
3. Определения метрик бери из «словаря метрик» и указывай их в assumptions.
4. Если период не указан, по умолчанию бери последние 30 дней и фиксируй это предположение.
5. Если вопрос неоднозначен, сначала верни clarifying_question, не угадывай.
6. Выводи JSON: {"sql": "", "assumptions": [], "clarifying_question": null}

Несколько деталей:

требуйте от модели список допущений, чтобы бизнес мог сверить трактовку;
явное «сначала уточнить, потом запрашивать» заметно снижает число ответов не по теме;
для «год к году / месяц к месяцу / доля» давайте отдельные формулы, не позволяйте модели импровизировать;
в многошаговом диалоге сохраняйте метрики и период предыдущего шага, но не сохраняйте устаревший SQL.

4. Проверка SQL и защитные барьеры

Генерация SQL — только начало. Перед выполнением нужно минимум пять проверок:

Синтаксический разбор: разобрать парсером, отклонить несколько операторов.
Тип оператора: разрешить только SELECT, запретить запись и хранимые процедуры.
Белый список объектов: таблицы и поля должны быть в разрешённом перечне.
Внедрение прав: автоматически добавлять фильтры по арендатору, подразделению, региону.
Контроль стоимости: период, LIMIT, тайм-аут и лимит объёма сканирования.

На уровне выполнения используйте отдельную учётную запись только для чтения, подключайтесь к реплике и задайте:

тайм-аут запроса, например 30 секунд;
максимальное число строк, например 1000;
для больших таблиц сначала EXPLAIN и оценка объёма сканирования;
не более 1–2 повторов, ошибку базы можно вернуть модели для исправления;
кэш одинаковых вопросов, ключ включает область прав пользователя.

5. Права: модель не заменяет систему доступа

Самая частая авария в вопросах к данным — «пользователь увидел то, что видеть не должен». Правильно — переиспользовать модель прав BI/хранилища:

уровень набора данных: к каким таблицам есть доступ;
уровень строк: фильтрация по арендатору, подразделению, региону;
уровень столбцов: телефоны, удостоверения, закупочные цены маскируются или скрываются;
уровень метрик: чувствительные показатели выдаются отдельно;
уровень сессии: при смене пользователя контекст и кэш очищаются.

Модель отвечает только за намерение запроса; права сервер принудительно внедряет на уровне SQL или представлений. В журнале фиксируйте исходный вопрос, финальный SQL, исполнителя и число строк — для аудита. Экспорт разрешайте отдельно, чтобы «может смотреть» не означало «может скачать всё».

6. От результата к графику

Результат запроса — ещё не отчёт. Лучше просить модель выдавать «конфигурацию графика + текстовый вывод», а не готовую картинку:

Форма данных	Рекомендуемый график
Временной ряд	Линейный график
Сравнение категорий	Столбчатая диаграмма
Доли	Круговая или накопительная столбчатая
Корреляция	Точечная диаграмма
Одна метрика	Карточка показателя

Текстовый вывод должен содержать трактовку, период, ключевые числа и аномалии. Например: «За последние 30 дней сумма оплаты снизилась на 8% к предыдущему периоду, основной вклад — канал Восточного Китая», с раскрываемой детализацией. Не ограничивайтесь фразой «данные показывают хорошую динамику».

7. Как измерять точность

Подготовьте 100–300 реальных бизнес-вопросов по уровням сложности:

запросы по одной таблице и агрегаты;
join нескольких таблиц;
год к году, месяц к месяцу, доли;
неоднозначные вопросы, требующие уточнения;
вопросы без данных или без прав.

Оценивайте не похожесть SQL, а совпадение результата выполнения. Фиксируйте:

Метрика	Пояснение
Точность выполнения	Результат совпадает с эталоном
Доля уточнений	Правильно ли задан встречный вопрос
Блокировка превышения прав	Отклонены ли запросы без доступа
Объяснимость сбоев	Превращается ли ошибка в понятный текст
Средняя задержка	От вопроса до графика

Прогоняйте регрессию раз в неделю и обязательно после изменений модели или схемы. На старте оставьте режим «ручное подтверждение SQL», автоматическое выполнение включайте после стабилизации.

8. Стоимость и производительность

Затраты складываются из трёх частей: поиск по схеме, генерация SQL, интерпретация результата.

Векторный поиск сокращает контекст — передавайте только релевантные таблицы.
Определение намерения и простые запросы — небольшой моделью, сложные — сильной.
Кэшируйте частые вопросы и результаты в одинаковой области прав.
Для интерпретации передавайте агрегаты, а не полную детализацию.
Длинные схемы сокращайте, не отправляйте каждый раз полный DDL.

Формула оценки:

Стоимость запроса =
  токены контекста схемы × цена входа
+ токены сгенерированного SQL × цена выхода
+ токены интерпретации × цена
+ стоимость выполнения в базе

Конкретные цены смотрите в разделе тарифов; стоимость базы считайте отдельно, особенно для сканирования больших таблиц.

9. Типовые сбои и решения

Симптом	Частая причина	Что делать
Поле не существует	Схема не найдена или модель придумала поле	Проверка по белому списку + повтор с текстом ошибки
Разная трактовка метрики	Нет определения	Дополнить словарь, требовать assumptions
Раздувание результата join	Неверный ключ или гранулярность	Дать пути join, проверять число строк
Неверный период	Неясны часовой пояс или значение по умолчанию	Единый часовой пояс, явный период по умолчанию
Превышение прав	Только ограничения промпта	Принудительные фильтры на сервере
Ответ не по теме	Неоднозначный вопрос	Сначала уточнить, затем запрашивать

Частые вопросы

Заменит ли AI-анализ данных BI?

Нет. Он лучше подходит для временных вопросов, быстрого получения данных и объяснения отчётов; сложные регулярные отчёты по-прежнему остаются за BI.

Нужно ли передавать модели всю структуру базы?

Нет. Поиск по схеме передаёт только релевантные таблицы и метрики — это дешевле и снижает число ошибок.

Можно ли выполнять сгенерированный SQL сразу?

Не рекомендуется. Нужны четыре проверки: синтаксис, белый список, права и стоимость, а выполнение — только на реплике для чтения.

Какой точности можно достичь?

Зависит от качества схемы, сложности вопросов и методики оценки. Сначала постройте базовый уровень на реальных вопросах, затем улучшайте по неделям; не судите по демонстрационным примерам.

С чего начать небольшой команде?

Выберите один домен, например продажи или операции, опишите 10–20 таблиц и словарь метрик, соберите набор из 50 вопросов и решите, стоит ли расширяться.

Что дальше

Успех анализа данных на 80% зависит от схемы, трактовки метрик и прав, а не от параметров модели. Начните с POC в одном домене, пройдите цикл «вопрос — проверка — выполнение — график — объяснение», затем расширяйтесь. Если нужен единый вход к моделям и управление расходом, можно зарегистрироваться в ZSQH AI Gateway; модели и цены смотрите в разделе тарифов.