ИИ-агенты для ClickHouse: как связать LLM с аналитической БД без облачных подписок

Идея поручить искусственному интеллекту написание SQL-запросов (Text-to-SQL) будоражит умы руководителей: бизнес-пользователи задают вопросы на естественном языке, а нейросеть мгновенно строит дашборды. Однако любой дата-инженер, пробовавший подключить языковую модель к реальной аналитической базе, знает, чем это обычно заканчивается.

Алексей Белозерский (CDO в inSales / Сбер B2B) на онлайн-встрече сообщества System Design & Highload представил прагматичный инженерный опыт построения локального ИИ-агента для ClickHouse без платных подписок и зарубежных VPN. Ранее мы рассматривали общие требования к архитектуре и безопасности корпоративных ИИ-агентов. Сегодня разберем практические детали работы со столбцовой СУБД.

Почему стандартные модели спотыкаются о ClickHouse

ClickHouse оптимизирован под чтение миллиардов строк, но требует учета диалекта:

1. Специфика агрегаций: вместо тяжелого COUNT(DISTINCT) необходимо использовать uniqExact() или uniq().
2. Секционирование (Partition Pruning): обязательна фильтрация по первичному ключу партиции (event_date), иначе запрос будет сканировать терабайты данных.
3. Типы данных: поддержка LowCardinality(String) и квантилей quantilesExact().

Концепция «Царь-промпта»: упаковываем словарь данных

Практика показала: успех проекта на 90% зависит не от фреймворков, а от качества подготовки контекста — так называемого «Царь-промпта»:

• Инженер в диалоге с сильной моделью подробно описывает структуру таблиц, назначение неочевидных колонок, бизнес-смыслы сущностей и типичные грабли;
• Затем просит модель структурировать и упаковать этот массив знаний в плотный, системный промпт на английском языке;
• В промпт обязательно зашивается секция жестких запретов (Negative Constraints): категорический запрет COUNT(DISTINCT), требование всегда фильтровать по партициям и выводить строго чистый SQL-код внутри блока разметки.

# Структура системного промпта («Царь-промпт»)
You are an expert ClickHouse Data Analyst.
Rules:
1. Always generate valid ClickHouse SQL dialect queries.
2. For unique counting use uniqExact(user_id), NEVER count(distinct user_id).
3. Always filter by partition key 'event_date' using toDate(now()) - INTERVAL 30 DAY.
4. Available Tables:
   - analytics.orders_daily: order_id (UInt64), user_id (UInt64), amount (Decimal64(2)), event_date (Date)
   - analytics.traffic_events: event_id (UUID), session_id (String), utm_source (LowCardinality(String))
Output ONLY the raw SQL query inside ```sql code fence.

Безопасность и песочница: усмиряем любопытного агента

Когда разработчики дают автономным агентам право запускать скрипты в локальном окружении, возникает любопытный феномен: модели начинают проявлять излишнюю самостоятельность. В реальных экспериментах агенты, получив доступ к терминалу, регулярно пытались сканировать файловую систему, заглядывать в /etc/passwd или искать переменные окружения с токенами.

Именно поэтому безопасность должна обеспечиваться на уровне самой СУБД, а не только программными фильтрами:

-- Создание жесткого профиля настроек для учетной записи ИИ-агента
CREATE SETTINGS PROFILE ai_agent_profile
  SETTINGS
    readonly = 1,
    max_execution_time = 15,
    max_memory_usage = 4000000000,
    max_rows_to_read = 10000000;

-- Создание пользователя с привязкой к профилю ограничений
CREATE USER ai_analyst IDENTIFIED BY 'StrongAgentSecret2026'
  SETTINGS PROFILE ai_agent_profile;

-- Выдача прав строго на чтение конкретных аналитических витрин
GRANT SELECT ON analytics.orders_daily TO ai_analyst;
GRANT SELECT ON analytics.traffic_events TO ai_analyst;

Параметр readonly = 1 гарантирует, что агент физически не сможет выполнить команды DROP, ALTER, INSERT или создать временные таблицы. А жесткие лимиты max_execution_time и max_memory_usage защитят сервер от зависания при генерации неоптимального джойна.

Практический итог

Опыт построения ИИ-аналитика для ClickHouse доказывает: надежные решения не требуют дорогих облачных сервисов. Локальная языковая модель, упакованный контекст в «Царь-промпте» и жесткие ограничения прав в самой СУБД позволяют создать быстрый, приватный и безопасный инструмент для работы с корпоративными данными.