File size: 16,494 Bytes
8871df9 | 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 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 | # План практической части ВКР: «Утилита Natural Language → SQL для бизнес-аналитики»
**Студент:** Danis, ПИ, 4 курс
**Срок:** 4 недели
**Дата:** 29 апреля 2026
---
## 0. Контур решения
**Финальный продукт:** утилита, которая позволяет аналитику малого и среднего бизнеса задавать вопросы на русском языке и получать готовые данные из корпоративной базы данных — без знания SQL.
Система: вопрос на русском → бизнес-словарь компании → схема БД → SQL → выполнение → результат.
Подход: fine-tuning **Qwen2.5-Coder-3B-Instruct** методом QLoRA на датасете **PAUQ**, обёрнутый в **FastAPI** с дополнительными модулями подключения к произвольной БД, настраиваемым бизнес-словарём и веб-интерфейсом на Streamlit.
Для научного сравнения параллельно прогоняется **GigaChat API** (или OpenAI) и **ruT5-base** baseline.
Инфраструктура:
- Тренировка: **Kaggle Notebooks** (T4 16 GB бесплатно).
- Разработка кода и API: **десктоп** Ryzen 5 3600X + 16 GB RAM.
- Демо на защите: **ноутбук** Ryzen 5 5500U + 16 GB RAM, инференс на CPU.
Артефакты ВКР:
- Рабочая утилита с веб-интерфейсом (Streamlit)
- Модуль подключения к произвольной БД (SQLite / PostgreSQL / MySQL)
- Модуль бизнес-словаря (YAML-конфиг с определениями метрик компании)
- Сравнительная таблица метрик (EM, Execution Accuracy)
- Анализ ошибок на 30+ примерах
---
## 1. Технологический стек
### 1.1 Среда разработки
| Компонент | Выбор |
|---|---|
| Язык | Python 3.10+ |
| Менеджер пакетов | uv (быстрый, современный) |
| Контроль версий | Git + GitHub |
| IDE | VS Code |
### 1.2 ML и обучение
| Компонент | Выбор | Где используется |
|---|---|---|
| PyTorch 2.x | основа | Kaggle |
| transformers | модели и токенизация | Kaggle + десктоп |
| peft | LoRA/QLoRA | Kaggle |
| bitsandbytes | 4-bit квантизация | Kaggle (на CPU не нужен) |
| trl | SFTTrainer | Kaggle |
| datasets | работа с PAUQ | Kaggle + десктоп |
| W&B | логирование экспериментов | Kaggle |
### 1.3 Инференс на десктопе и ноутбуке
Для локального инференса без GPU есть два пути:
| Путь | Скорость | Сложность | Применение |
|---|---|---|---|
| transformers на CPU (int8) | 15–30 с/запрос | проще | разработка, отладка |
| llama.cpp (gguf int4) | 5–15 с/запрос | сложнее | финальное демо |
**Рекомендация:** для разработки — transformers, для защиты — llama.cpp.
### 1.4 API и SQL
| Компонент | Выбор |
|---|---|
| FastAPI + Uvicorn | REST API |
| Pydantic v2 | валидация |
| sqlite3 (stdlib) | работа с БД из PAUQ |
| sqlglot | парсинг и валидация SQL |
| pytest | тесты |
---
## 2. Архитектура
```
┌──────────────────────────────────────────────────────────────┐
│ Streamlit Web Interface │
│ Поле вопроса | Выбор БД | Редактор бизнес-словаря │
│ Таблица результатов | История запросов │
└──────────────────────────┬───────────────────────────────────┘
│ HTTP
┌──────────────────────────▼───────────────────────────────────┐
│ FastAPI REST API │
│ POST /query {question_ru, db_id} → {sql, result, ...} │
└──────┬──────────────┬───────────────┬────────────────────────┘
│ │ │
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌─────────────────┐
│ DbConnector│ │ Business │ │ SchemaRetriever │
│ SQLite / │ │ Vocabulary │ │ (DDL из БД) │
│ Postgres / │ │ (YAML- │ └────────┬────────┘
│ MySQL │ │ конфиг) │ │
└─────┬──────┘ └─────┬──────┘ │
│ │ │
│ ┌────▼─────────────────▼──┐
│ │ PromptBuilder │
│ │ вопрос + схема + │
│ │ определения метрик │
│ └────────────┬────────────┘
│ ▼
│ ┌────────────────────────┐
│ │ InferenceEngine │
│ │ Qwen2.5-Coder-3B │
│ │ + LoRA adapter │
│ └────────────┬───────────┘
│ ▼
│ ┌────────────────────────┐
│ │ SqlPostProcessor │
│ │ (sqlglot validation) │
│ └────────────┬───────────┘
│ │
└──────────────────────┘
│ выполнить SQL
▼
┌─────────────────┐
│ SqlExecutor │
│ результат → │
│ аналитику │
└─────────────────┘
```
Структура проекта (см. файлы в репозитории):
```
ru2sql/
├── README.md
├── pyproject.toml
├── .gitignore
├── notebooks/
│ └── kaggle_train_qwen_qlora.ipynb
├── src/
│ ├── config.py
│ ├── data/ — loader, schema, prompt
│ ├── models/ — inference, postprocess
│ ├── evaluation/ — metrics, evaluate
│ └── api/ — main, schemas, dependencies
├── tests/
└── scripts/
```
---
## 3. Помесячный план
### Неделя 1. Окружение, данные, baseline
**Цель:** работающий pipeline от вопроса до SQL на маленькой модели.
| День | Задача |
|---|---|
| 1 | Установка Python 3.10+, uv, Git. Клонирование репозитория. `uv sync`. Проверка что FastAPI стартует. |
| 2 | Регистрация на Kaggle, HuggingFace, W&B. Скачивание PAUQ (https://github.com/ai-forever/pauq). |
| 3 | Анализ датасета в notebook: распределения, сложности, примеры. Реализация `SchemaRetriever`. |
| 4 | Реализация `PromptBuilder`. Тесты: `pytest tests/test_prompt.py`. |
| 5–6 | Kaggle-notebook: обучение **ruT5-base** на 2 эпохи. Сохранение чекпойнта. |
| 7 | Реализация `metrics.py` (EM + Execution Accuracy). Прогон ruT5 на dev. Запись в W&B. |
Контрольная точка недели: ruT5-base даёт 25–35% EM на PAUQ dev.
### Неделя 2. Главная модель (Qwen2.5-Coder-3B + QLoRA)
**Цель:** обученный LoRA-адаптер для Qwen с метриками выше baseline.
| День | Задача |
|---|---|
| 1 | Kaggle-notebook: загрузка Qwen2.5-Coder-3B в 4-bit, тестовый inference. |
| 2 | Подготовка PAUQ в chat-формате под модель. |
| 3–4 | SFTTrainer + LoRA (r=16, alpha=32). Прогон 2–3 эпохи (~4–6 часов суммарно). |
| 5 | Сохранение LoRA-адаптера на HuggingFace Hub (приватный репозиторий). |
| 6 | Скачивание адаптера на десктоп. Локальный инференс на CPU через transformers. |
| 7 | Прогон на dev split, метрики, error analysis на 30 примерах. |
Контрольная точка недели: Qwen+LoRA даёт 50–60% EM на PAUQ dev и работает на десктопе.
### Неделя 3. Бизнес-утилита: коннектор + словарь + исполнение SQL
**Цель:** превратить API в полноценную бизнес-утилиту — подключение к реальной БД, настройка под компанию, возврат данных.
| День | Задача |
|---|---|
| 1 | FastAPI: `/generate-sql`, `/query`, `/databases`, `/health`. Lifespan для загрузки модели. |
| 2 | Модуль `DbConnector` — подключение к SQLite/PostgreSQL/MySQL по строке подключения. Автоматическое чтение схемы (`INFORMATION_SCHEMA`). |
| 3 | Модуль `BusinessVocabulary` — загрузка YAML-конфига с определениями метрик. Подстановка определений в промпт перед генерацией SQL. Пример конфига: `выручка: "SUM(orders.amount) WHERE status='paid'"`. |
| 4 | Эндпоинт `/query` — принимает вопрос, генерирует SQL, выполняет на подключённой БД, возвращает результат в JSON (таблица строк). |
| 5 | Получение API-ключа GigaChat (или YandexGPT), скрипт прогона на тех же примерах. Сравнительная таблица: ruT5 vs Qwen+LoRA vs GigaChat по EM и EX. |
| 6 | `SqlPostProcessor` через sqlglot. Тесты pytest на все новые модули. |
| 7 | Создание демо-базы данных (SQLite) с реалистичными бизнес-данными: продажи, клиенты, товары. Написание бизнес-словаря под эту базу. |
Контрольная точка недели: аналитик вводит "Какая выручка за январь?" → утилита возвращает число из реальной БД.
### Неделя 4. Streamlit-интерфейс, демо, материалы для ВКР
**Цель:** красивый рабочий продукт для защиты + готовые материалы для текста ВКР.
| День | Задача |
|---|---|
| 1 | Streamlit-интерфейс: поле ввода вопроса, выбор БД, отображение сгенерированного SQL и таблицы результатов. |
| 2 | В интерфейсе: вкладка настройки бизнес-словаря (редактирование YAML прямо в браузере). История запросов. |
| 3 | Error analysis: разбор 30 ошибок Qwen+LoRA, классификация по категориям (неверный JOIN, неверное условие WHERE и т.д.). |
| 4 | Конвертация LoRA + базовой модели в gguf через llama.cpp для быстрого инференса на CPU. |
| 5 | Диаграммы архитектуры (draw.io), скриншоты интерфейса, графики метрик (matplotlib). |
| 6 | Глава «Реализация» и глава «Практическое применение» в тексте ВКР. |
| 7 | Прогон полного сценария на ноутбуке с демо-базой. Резервная копия чекпойнта на HuggingFace. |
---
## 4. Метрики качества
Стандарт для Text-to-SQL:
- **Exact Match (EM)** — нормализуем оба SQL и сравниваем посимвольно.
- **Execution Accuracy (EX)** — выполняем оба SQL на реальной SQLite, сравниваем результаты как множества кортежей.
EX важнее EM, потому что разные SQL могут дать одинаковый результат.
Целевые числа на PAUQ dev (ориентировочно):
- ruT5-base: 25–35% EM, 30–40% EX.
- Qwen2.5-Coder-3B + LoRA: 50–60% EM, 55–70% EX.
- GigaChat / GPT-4 (zero-shot, через API): 55–70% EM, 65–80% EX.
Ваш Qwen после QLoRA должен быть близок к API-моделям. Это и будет защищаемый результат.
---
## 5. Риски и план B
| Риск | План B |
|---|---|
| Kaggle квота закончилась | Переключиться на Google Colab Free или арендовать GPU на vast.ai (~$2 за обучение) |
| Qwen-3B плохо сходится | Понизить learning rate до 1e-4, увеличить эпохи до 5, проверить prompt format |
| llama.cpp не успеваю настроить к защите | Демо через transformers на CPU напрямую — медленнее, но работает |
| GigaChat недоступен | YandexGPT либо OpenAI через VPN — Pydantic-обёртка одна, провайдер меняется одной строчкой |
| Не хватает времени на error analysis | Минимум — 20 ошибок руками, простая классификация в Excel |
---
## 6. Что вынести в «направления дальнейшей работы»
Эти улучшения **не делаем** в рамках месяца, но упоминаем в ВКР:
- Few-shot retrieval (поиск похожих примеров через эмбеддинги).
- Schema linking (автоматический отбор таблиц).
- Self-correction (выполнение SQL, исправление по ошибке).
- Constrained decoding (ограничение токенов до валидной SQL-грамматики).
- Дообучение на синтетических данных от GPT-4.
---
## 7. Итоговый чек-лист на старте
- [ ] Установлены Python 3.10+, uv, Git, VS Code на десктопе
- [ ] Создан репозиторий ru2sql на GitHub
- [ ] Зарегистрированы аккаунты Kaggle, HuggingFace, W&B
- [ ] Получен ключ GigaChat (или OpenAI)
- [ ] Скачан PAUQ
- [ ] `uv sync` проходит без ошибок
- [ ] `uvicorn src.api.main:app --reload` стартует
- [ ] Прочитаны статьи: Spider (2018), QLoRA (2023), краткое описание Qwen2.5-Coder
После чек-листа можно стартовать День 3 первой недели.
|