NL→SQL Assistant — постановка задачи
Дата: 2026-05-10
Автор: Julia Edomskikh
Статус: v1 draft (corrected 2026-05-10 после CX/KM review). См. также: 01_architecture.md (v1 historical), 02_architecture_v2.md (lean baseline), 03_eval_methodology.md (ablation plan).
1. Что делаем
Инструмент, который принимает вопрос на естественном языке (русский или английский), обращается к реляционной БД и возвращает ответ в одной из форм:
- Число / скаляр — для агрегатных вопросов («сколько заказов в марте?»).
- Текстовое предложение — для фактоидов с подстановкой данных («у клиента X 12 заказов на сумму 340k за 2024 год»).
- Таблица — когда нужен список записей.
- График — когда вопрос про динамику, сравнение, распределение (выбор типа графика автоматический: line / bar / pie / hist / scatter).
- SQL-запрос — всегда показывается пользователю как «доказательство»
- объяснение на естественном языке, что именно посчитали.
2. Почему это не «ещё один чат с БД»
Демо-проект для портфолио, поэтому ценность создаётся не самим NL→SQL (он есть у Vanna, DataHerald, WrenAI, defog/sqlcoder, LangChain SQLAgent), а тремя слоями поверх:
- Измеримая точность. Eval-harness на публичных бенчмарках (BIRD-bench и/или Spider) с метрикой Execution Accuracy и сравнением против опубликованных результатов моделей. Без этого числа проект — игрушка.
- Self-correction loop. Если SQL падает или возвращает 0 строк или вырожденный результат — граф автоматически переформулирует запрос с error-context (паттерн из RAG_Support_Assistant: classify → retrieve → generate → verify → retry).
- Schema-RAG, а не «всю схему в промпт». На сложных БД (десятки таблиц, сотни колонок) полная схема не влезает и шумит. Хранилище: таблицы + колонки + описания + примеры значений + few-shot Q→SQL пары индексируются в Chroma и достаются по релевантности к вопросу.
3. Целевые БД
Для демо берём два разных профиля сложности:
| База | Профиль | Зачем |
|---|---|---|
| BIRD Mini-Dev | 500 Q→SQL примеров (специальный efficient-eval split BIRD; полный BIRD = 95 БД / 12 751 пар / 33.4 GB) | Eval-harness, число Execution Accuracy на публичном leaderboard'е |
| StackExchange public dump в Postgres | Реальная сложная схема (Posts, Users, Votes, Comments, Tags, Badges), миллионы строк, JSONB-поля, временные ряды | Демо-вопросы с красивыми графиками («активность по часам», «распределение тегов», «топ-N пользователей по карме») |
Опционально третья — Sakila или Chinook — для онбординг-демо (простая, всем знакомая, быстро отрабатывает первое впечатление).
4. LLM
Только Mistral по API. Две модели в роутинге:
codestral-latest(Codestral v25.08, актуальный код-специалист — codestral-2501 deprecated с ноября 2025) — генерация SQL и self-correction. Mistral La Plateforme free tier.mistral-large-latest— объяснение результата на естественном языке (intent classification и format selection — детерминированно, без LLM, см. v2 архитектуру).
Embeddings — mistral-embed.
Bakeoff providers ($0 hard budget): codestral-latest + gpt-4o-mini через GitHub Models (free) + qwen2.5-coder:7b локально (Ollama, 4.7 GB Q4_K_M).
Provider abstraction обязательна (LiteLLM или собственный adapter): локальное тестирование без API, замена модели для bakeoff (см.
02_architecture_v2.md§6 + §6.6).
5. Базовый сценарий (happy path)
Пользователь: "Покажи топ-10 тегов на StackOverflow по приросту вопросов в 2023 году"
|
v
1. Classify intent → "aggregation + ranking + time-window + visualization"
2. Schema retrieval → достать релевантные таблицы (Posts, Tags, PostTags) + 3 few-shot примера
3. SQL generation → codestral пишет SQL с CTE по годам и приростом
4. Validate → синтаксис ОК, EXPLAIN ОК, SELECT-only гард прошёл
5. Execute → 10 строк × 3 колонки
6. Verify → результат непустой, типы соответствуют ожиданиям
7. Format → по структуре ответа выбран bar chart + краткий текст
8. Render → markdown-ответ + Plotly-график + блок с SQL и объяснением
При фейле любого шага — retry с error-context (макс. 2 попытки), дальше — graceful failure с показом, где именно споткнулись.
6. Что НЕ делаем (scope cuts)
- Никаких write-операций. Read-only коннект к БД, гард на уровне SQL-парсера.
- Никакого мульти-БД join'а в одном запросе.
- Никакого fine-tuning моделей — только prompt-engineering + RAG.
- Никакой собственной аутентификации/мульти-тенанси (это переусложнение для демо, в RAG_SA уже отработано — здесь не повторяем).
- Никаких write-back в БД на основе вопросов пользователя.
7. Критерии готовности (Definition of Done)
- Execution Accuracy на BIRD Mini-Dev: baseline ≥35-40% к неделе 4, stretch ≥50%. Для калибровки: GPT-4 zero-shot на BIRD Mini-Dev = 47.8 / 40.8 / 35.8% EX (SQLite/MySQL/PostgreSQL); 50% — это уровень GPT-4 с table-augmentation, не Codestral zero-shot. Hard checkpoint на неделе 3: если EA <35% → scope down (см. v2 архитектуру).
- На StackExchange — 20 эталонных вопросов проходят end-to-end с корректным ответом.
- Веб-UI: ввод вопроса, четыре формата ответа, переключение БД, история.
- CI: тесты на гард SELECT-only, на парсер схемы, на pipeline-граф.
- README + диаграмма архитектуры + страница eval-результатов.
- Деплой: docker-compose с Postgres + Chroma + FastAPI + UI.