File size: 7,933 Bytes
942050b | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 | # 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),
а тремя слоями поверх:
1. **Измеримая точность.** Eval-harness на публичных бенчмарках
(BIRD-bench и/или Spider) с метрикой Execution Accuracy и сравнением
против опубликованных результатов моделей. Без этого числа проект — игрушка.
2. **Self-correction loop.** Если SQL падает или возвращает 0 строк или вырожденный
результат — граф автоматически переформулирует запрос с error-context
(паттерн из RAG_Support_Assistant: classify → retrieve → generate → verify → retry).
3. **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.
|