Spaces:

Tyycha
/

Ru2SQL

Running

App Files Files Community

Ru2SQL / plan_VKR_text2sql_ru.md

Tyycha

initial commit

8871df9 about 1 month ago

preview code

raw

history blame contribute delete

16.5 kB

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