🕷️ Spider SQL Generator

Система генерации SQL-запросов по естественному языку с использованием дообученной модели LoRA и LLM для оптимизации.

📋 Описание

Проект представляет собой микросервисную архитектуру для генерации SQL-запросов из текстовых описаний на русском/английском языках. Система обучена на датасете Spider и использует:

• LoRA Fine-tuned модель - Qwen2.5-Coder-3B-Instruct, дообученная для генерации SQL
• OpenRouter LLM - Claude/DeepSeek для анализа, оптимизации и чата
• Spider Dataset - более 200 SQLite баз данных для тестирования

🏗️ Архитектура

┌─────────────────────────────────────────────────────────────────────┐
│                         Streamlit UI (:8501)                        │
│                    Веб-интерфейс пользователя                       │
└─────────────────┬───────────────┬────────────────┬─────────────────┘
                  │               │                │
                  ▼               ▼                ▼
┌─────────────────────┐  ┌─────────────────┐  ┌─────────────────────┐
│   Model API (:8001) │  │ Spider API      │  │   LLM API (:8002)   │
│   LoRA Inference    │  │ (:8000)         │  │   OpenRouter        │
│                     │  │ Database Ops    │  │                     │
│ • Генерация SQL     │  │ • Выполнение    │  │ • Text-to-SQL       │
│ • Qwen2.5-Coder-3B  │  │   запросов      │  │ • Оптимизация SQL   │
│                     │  │ • EXPLAIN       │  │ • Чат               │
│                     │  │ • Evaluate      │  │ • DeepSeek/Claude   │
└─────────────────────┘  └─────────────────┘  └─────────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────────┐  ┌─────────────────────┐
│    LoRA Adapter     │  │    Spider Data      │
│  ./lora_adapter/    │  │   ./spider_data/    │
│  Qwen2.5-Coder-3B   │  │   200+ databases    │
└─────────────────────┘  └─────────────────────┘

📁 Структура проекта

project/
├── api/
│   ├── model_api/           # API для LoRA модели
│   │   ├── api_model.py     # FastAPI сервер
│   │   ├── inference.py     # Инференс модели
│   │   └── Dockerfile
│   ├── spider_api/          # API для работы с БД Spider
│   │   ├── main.py          # FastAPI сервер
│   │   ├── evaluator.py     # Оценка качества SQL
│   │   └── Dockerfile
│   ├── llm_api/             # API для OpenRouter LLM
│   │   ├── main.py          # FastAPI сервер
│   │   ├── llm.py           # LLM клиент
│   │   └── Dockerfile
│   └── streamlit_app/       # Веб-интерфейс
│       ├── app.py           # Streamlit приложение
│       └── Dockerfile
├── models/                  # Базовая модель
│   └── Qwen2.5-Coder-3B-Instruct/
├── lora_adapter/            # Обученный LoRA адаптер
├── spider_data/             # Spider датасет
│   ├── database/            # 200+ SQLite баз данных
│   ├── dev.json             # Валидационные примеры
│   ├── train_spider.json    # Тренировочные примеры
│   └── tables.json          # Схемы таблиц
├── train_src/               # Скрипты обучения
│   ├── train.py             # Основной скрипт обучения
│   └── data_preparation.py  # Подготовка данных
├── docker-compose.yml       # Конфигурация сервисов
├── restart.sh               # Скрипт перезапуска
└── check_status.sh          # Скрипт проверки статуса

🚀 Быстрый старт

Предварительные требования

1. Docker и Docker Compose
2. NVIDIA GPU с поддержкой CUDA (рекомендуется 8+ GB VRAM)
3. NVIDIA Container Toolkit для работы GPU в Docker
4. OpenRouter API Key для LLM функций

1. Клонирование и настройка

# Клонируйте репозиторий
git clone <repository-url>
cd project

# Создайте .env файл с API ключом OpenRouter
echo "OPENROUTER_API_KEY=your_api_key_here" > .env

2. Скачивание модели и данных

Убедитесь, что в папке models/ находится базовая модель:

models/Qwen2.5-Coder-3B-Instruct/

LoRA адаптер должен быть в папке lora_adapter/.

Spider датасет должен быть в папке spider_data/.

3. Запуск сервисов

# Дать права на выполнение скриптов
chmod +x restart.sh check_status.sh

# Запуск всех сервисов
./restart.sh

# Или вручную через docker-compose
docker-compose up -d --build

4. Проверка статуса

# Проверить статус всех сервисов
./check_status.sh

5. Доступ к интерфейсам

Сервис	URL	Описание
Streamlit UI	http://localhost:8501	Веб-интерфейс
Model API Docs	http://localhost:8001/docs	Swagger для LoRA API
Spider API Docs	http://localhost:8000/docs	Swagger для Spider API
LLM API Docs	http://localhost:8002/docs	Swagger для LLM API

📡 API Endpoints

Model API (LoRA) - порт 8001

Метод	Endpoint	Описание
GET	/health	Проверка статуса и загрузки модели
POST	/generate	Генерация SQL по тексту

Пример запроса /generate:

{
  "question": "Show all singers with age greater than 30",
  "db_id": "concert_singer",
  "schema": "CREATE TABLE singer (singer_id INT, name TEXT, age INT)"
}

Spider API (Database) - порт 8000

Метод	Endpoint	Описание
GET	/health	Проверка статуса
GET	/databases	Список доступных баз данных
GET	/schema/{db_id}	Схема указанной БД
POST	/query	Выполнение SQL запроса
POST	/explain	Получение EXPLAIN плана запроса
POST	/evaluate	Оценка SQL запроса

Пример запроса /query:

{
  "db_id": "concert_singer",
  "sql": "SELECT * FROM singer WHERE age > 30"
}

Пример запроса /explain:

{
  "db_id": "concert_singer",
  "sql": "SELECT * FROM singer WHERE age > 30"
}

LLM API (OpenRouter) - порт 8002

Метод	Endpoint	Описание
GET	/health	Проверка статуса
GET	/models	Список доступных LLM моделей
POST	/text-to-sql	Генерация SQL через LLM
POST	/optimize-sql	Оптимизация SQL с анализом
POST	/chat	Общий чат с LLM

Пример запроса /optimize-sql:

{
  "sql": "SELECT * FROM singer WHERE age > 30",
  "schema": "CREATE TABLE singer (...)",
  "explain_plan": "SCAN singer",
  "model": "deepseek/deepseek-chat-v3-0324"
}

Ответ с structured output:

{
  "original_sql": "SELECT * FROM singer WHERE age > 30",
  "optimized_sql": "SELECT singer_id, name, age FROM singer WHERE age > 30",
  "analysis": "Заменён SELECT * на явный список колонок",
  "recommendations": ["Создать индекс на колонке age"]
}

🎓 Обучение модели

Подготовка данных

cd train_src

# Скачивание базовой модели (если нужно)
python download_model.py

# Подготовка данных для обучения
python data_preparation.py

Запуск обучения

# Обучение с конфигурацией по умолчанию
python train.py

# Обучение с кастомной конфигурацией
python train.py --config configs/custom_config.yaml

Параметры LoRA

Модель использует следующие параметры LoRA:

• r: 16 (ранг)
• lora_alpha: 32
• lora_dropout: 0.05
• target_modules: q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj

🛠️ Конфигурация

Переменные окружения

# .env файл
OPENROUTER_API_KEY=sk-or-...  # API ключ OpenRouter (обязательно)

Docker Compose сервисы

Сервис	Порт	GPU	Описание
lora_model_inference	8001	Да	LoRA модель
spider_fastapi	8000	Нет	База данных Spider
llm_fastapi	8002	Нет	OpenRouter LLM
streamlit_ui	8501	Нет	Веб-интерфейс

📊 Использование через Streamlit

1. Откройте http://localhost:8501
2. Выберите базу данных из списка (например, concert_singer)
3. Введите вопрос на естественном языке
4. Выберите модель:
   • LoRA (Qwen2.5-Coder-3B) - локальная дообученная модель
   • DeepSeek Chat V3 - через OpenRouter
   • Claude 3.5 Sonnet - через OpenRouter
5. Нажмите "Сгенерировать SQL"
6. Просмотрите результаты:
   • Сгенерированный SQL
   • Результат выполнения
   • EXPLAIN план
   • Рекомендации по оптимизации (если применимо)

🔧 Устранение неполадок

Модель не загружается

# Проверьте логи
docker-compose logs -f lora_model_inference

# Убедитесь, что модель и адаптер на месте
ls -la models/Qwen2.5-Coder-3B-Instruct/
ls -la lora_adapter/

GPU не используется

# Проверьте NVIDIA Docker runtime
docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

OpenRouter не работает

# Проверьте API ключ
echo $OPENROUTER_API_KEY

# Проверьте логи LLM API
docker-compose logs -f llm_fastapi

Перезапуск с пересборкой

# Полный перезапуск с очисткой
docker-compose down
docker-compose build --no-cache
docker-compose up -d

📝 Логи

# Все логи
docker-compose logs -f

# Логи конкретного сервиса
docker-compose logs -f lora_model_inference
docker-compose logs -f spider_fastapi
docker-compose logs -f llm_fastapi
docker-compose logs -f streamlit_ui