plan_VKR_text2sql_ru.md

# План практической части ВКР: «Утилита 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 первой недели.