README.md

---
language:
- ru
base_model:
- openai-community/gpt2
datasets:
- timbossm/sales_lab_mgpu_2_course
pipeline_tag: text-generation
tags:
- code
license: apache-2.0
---

# Model Card for timbossm/sales-sql-finetuned-model

<!-- Provide a quick summary of what the model is/does. -->

Эта модель представляет собой дообученную версию GPT-2, специализированную для генерации SQL-запросов и объяснений к ним на основе описания схемы базы данных "Продажи", используемой в лабораторном практикуме МГПУ по языку SQL.

## Model Details

### Model Description

<!-- Provide a longer summary of what this model is. -->

`timbossm/sales-sql-finetuned-model` - это дообученная (fine-tuned) модель GPT-2, предназначенная для выполнения задач Text-to-SQL и SQL-объяснения в контексте конкретной учебной схемы базы данных "Продажи".

Модель была дообучена на небольшом датасете, созданном на основе примеров и заданий из лабораторных работ МГПУ. Она учится генерировать SQL-запросы (преимущественно SELECT) на естественном языке (русском), когда ей предоставляется описание схемы базы данных и запрос пользователя. Также модель может генерировать объяснения к предоставленным SQL-запросам или элементам схемы.

**Важное замечание:** Модель была дообучена на **очень маленьком датасете (16 примеров)**. Из-за этого она, вероятно, имеет крайне ограниченные возможности обобщения и может просто запоминать обучающие примеры, не являясь надежным инструментом для работы с другими запросами или схемами.

- **Developed by:** timbossm
- **Funded by [optional]:** [More Information Needed]
- **Shared by [optional]:** [More Information Needed]
- **Model type:** Causal Language Model (Decoder-only Transformer), дообученная (fine-tuned). Основана на архитектуре GPT-2.
- **Language(s) (NLP):** Русский (Russian) для входных промптов и текстовых ответов/объяснений; SQL для генерируемых запросов.
- **License:** Лицензия базовой модели `gpt2` - MIT License. Лицензия данного дообученного артефакта наследует эту лицензию. Однако, данные для дообучения основаны на учебных материалах, и их использование может регулироваться отдельными условиями (предположительно, образовательными/некоммерческими). Рекомендуется ознакомиться с исходным практикумом. Лицензия модели: MIT.
- **Finetuned from model [optional]:** gpt2

### Model Sources [optional]

<!-- Provide the basic links for the model. -->

- **Repository:** `https://huggingface.co/timbossm/sales-sql-finetuned-model`
- **Paper [optional]:** Данная модель основана на материалах:
    Босенко, Т. М., & Фролов, Ю. В. (2025). *Лабораторный практикум по языку SQL: практикум*. МГПУ.

### Direct Use

*   Генерация SQL-запросов для конкретной схемы базы данных "Продажи", представленной в обучающем датасете.
*   Получение базовых объяснений по этой схеме и простым SQL-запросам.
*   В образовательных целях для демонстрации процесса дообучения LLM для задачи Text-to-SQL на очень простом примере.

### Downstream Use [optional]

Модель может быть использована как отправная точка для дальнейших экспериментов по дообучению на более крупных и разнообразных датасетах Text-to-SQL, хотя, учитывая крайне маленький исходный тренировочный набор, ее полезность в качестве базы сильно ограничена.

### Out-of-Scope Use

*   Генерация SQL-запросов для любых других схем баз данных.
*   Генерация сложных или нестандартных SQL-конструкций, отсутствующих в обучающих примерах.
*   Использование в реальных приложениях, где требуется надежность и точность.
*   Генерация связного текста на общие темы.
*   Использование для любых задач, не связанных напрямую с заданной схемой БД "Продажи" и форматом промпт/ответ из обучающего датасета.

## Bias, Risks, and Limitations

<!-- This section is meant to convey both technical and sociotechnical limitations. -->

*   **Крайне маленький размер обучающего датасета (16 примеров):** Это основное ограничение. Модель, вероятно, просто переобучилась на этих примерах и не сможет успешно обрабатывать запросы, которые значительно отличаются от увиденных во время обучения. Обобщающие способности очень низкие.
*   **Смещение по схеме:** Модель обучена только на одной конкретной схеме БД "Продажи". Она ничего не знает о других схемах или общих принципах построения БД и SQL.
*   **Ограниченное разнообразие запросов:** Обучающие примеры охватывают только определенные типы SELECT-запросов и базовые объяснения. Модель не научится DML-операциям (INSERT, UPDATE, DELETE) или другим DDL-операциям, кроме интерпретации CREATE TABLE.
*   **Риск некорректной генерации:** Несмотря на обучение, модель может генерировать синтаксически неверные SQL-запросы или логически неправильные ответы даже для целевой схемы, особенно при малейших отклонениях во входном промпте.

### Recommendations

Пользователям настоятельно рекомендуется осознавать серьезные ограничения данной модели, связанные с крайне маленьким размером обучающего датасета. Модель непригодна для использования в продакшене или для задач, требующих надежной генерации SQL. Она может служить лишь как учебный пример дообучения LLM. Любые сгенерированные SQL-запросы должны быть тщательно проверены.

## How to Get Started with the Model

Вы можете использовать модель для генерации текста следующим образом (включая DDL схему в промпт, как в обучающих данных):

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

# Укажите путь к сохраненной модели или ID на Hugging Face Hub
# model_name = "./model" # Если модель сохранена локально
model_name = "timbossm/sales-sql-finetuned-model" # Если загружаете с Hub

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name)

# Убедитесь, что токен паддинга установлен, если его нет (важно для генерации)
if tokenizer.pad_token is None:
     tokenizer.pad_token = tokenizer.eos_token
     model.config.pad_token_id = tokenizer.pad_token_id # Убедитесь, что и в конфиге модели он установлен

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model.to(device)
model.eval() # Переключиться в режим инференса

prompt_text = """Используя следующую схему базы данных:

CREATE TABLE clients (
    client_id INTEGER PRIMARY KEY AUTO_INCREMENT,
    last_name VARCHAR(50) NOT NULL,
    first_name VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL,
    phone VARCHAR(14) NOT NULL
);

CREATE TABLE orders (
    order_id INTEGER PRIMARY KEY AUTO_INCREMENT,
    client_id INTEGER NOT NULL,
    order_date DATE NOT NULL,
    cost DECIMAL(10, 2) NOT NULL,
    FOREIGN KEY (client_id) REFERENCES clients(client_id)
);

CREATE TABLE products (
    product_id INTEGER PRIMARY KEY AUTO_INCREMENT,
    description VARCHAR(200) NOT NULL,
    price DECIMAL(10, 2) NOT NULL,
    quantity INTEGER NOT NULL,
    order_id INTEGER,
    FOREIGN KEY (order_id) REFERENCES orders(order_id)
);

Напиши SQL-запрос, чтобы вывести email всех клиентов.
""" # Пример промпта с DDL

# Подготовка ввода с attention_mask
inputs = tokenizer(
    prompt_text + "\n", # Добавляем разделитель как при обучении
    return_tensors="pt",
    max_length=1024, # Использовать ту же максимальную длину
    truncation=True,
    padding="max_length",
    return_attention_mask=True # Важно передавать маску внимания
).to(device)

# Генерация текста
output_sequences = model.generate(
    inputs["input_ids"],
    attention_mask=inputs["attention_mask"], # Передаем маску внимания
    max_new_tokens=100, # Максимальное количество новых токенов в ответе
    num_beams=1, # Жадный поиск
    no_repeat_ngram_size=2,
    eos_token_id=tokenizer.eos_token_id,
    pad_token_id=tokenizer.pad_token_id,
)

generated_text = tokenizer.decode(output_sequences[0], skip_special_tokens=False)

print("--- Сгенерированный ответ (полный текст): ---")
print(generated_text)
print("---------------------------------------------")

# Опционально: извлечь только сгенерированную часть
prompt_end_marker = prompt_text + "\n"
prompt_end_index = generated_text.find(prompt_end_marker)
if prompt_end_index != -1:
    generated_response = generated_text[prompt_end_index + len(prompt_end_marker):].strip()
    if generated_response.endswith(tokenizer.eos_token):
        generated_response = generated_response[:-len(tokenizer.eos_token)].strip()
    print("\n--- Извлеченный ответ: ---")
    print(generated_response)
    print("--------------------------")

```

## Training Details

### Training Data

Модель была дообучена на пользовательском датасете `sales_lab.jsonl`, созданном на основе примеров из "ЛАБОРАТОРНОГО ПРАКТИКУМА ПО ЯЗЫКУ SQL" МГПУ (2025, составители Т. М. Босенко, Ю.В. Фролов).

Датасет содержит 16 пар "промпт" - "ответ", где промпты включают DDL схему базы данных "Продажи" и запрос на естественном языке или SQL код для объяснения, а ответы - соответствующий SQL код или текстовое объяснение. Схема БД включает таблицы `clients`, `orders`, `products`.

**Важное замечание:** Датасет крайне мал (14 примеров для обучения, 2 для валидации).

[More Information Needed] (Ссылка на Dataset Card, если он будет создан и выгружен отдельно).

### Training Procedure

Модель `gpt2` была дообучена с использованием библиотеки Hugging Face `transformers` и класса `Trainer`.

#### Preprocessing [optional]

Каждая пара "промпт" и "ответ" из датасета была объединена в одну строку в формате `[prompt]\n[response][eos_token]`. Полученные строки были токенизированы с использованием `AutoTokenizer` для `gpt2`. Максимальная длина последовательности была установлена в 1024 токена с усечением (`truncation=True`) и паддингом до максимальной длины батча или `max_length` (`padding="max_length"`). Метки для обучения (`labels`) были созданы путем копирования входных токенов (`input_ids`), при этом токены, соответствующие оригинальному промпту (включая разделитель `\n`), были заменены на `-100`, чтобы функция потерь игнорировала их.

#### Training Hyperparameters

- **Training regime:** fp16 mixed precision (если `fp16=True` в TrainingArguments). Иначе fp32 non-mixed precision.
- **num_train_epochs:** 5
- **per_device_train_batch_size:** 8
- **per_device_eval_batch_size:** 8
- **learning_rate:** 5e-5
- **weight_decay:** 0.01
- **eval_strategy:** "epoch"
- **save_strategy:** "epoch"
- **load_best_model_at_end:** True
- **max_length (tokenization):** 1024
- **gradient_accumulation_steps:** 1 (по умолчанию в скрипте)

#### Speeds, Sizes, Times [optional]

- **Hardware Type:** NVIDIA RTX 2000 (использовалась одна GPU, если применялся `CUDA_VISIBLE_DEVICES=0`)
- **Cloud Provider:** Локальное обучение.

### Testing Data, Factors & Metrics

#### Testing Data

Модель оценивалась на небольшом валидационном разбиении исходного датасета, состоящем из 2 примеров.


#### Summary

Результаты валидации на таком маленьком наборе данных (2 примера) **не являются репрезентативными** и не могут служить показателем реального качества модели или ее способности к обобщению. Высока вероятность переобучения на тренировочном наборе.


- **Hardware Type:** NVIDIA RTX 2000
- **Cloud Provider:** Локальное обучение


## Technical Specifications [optional]

### Model Architecture and Objective

Модель использует стандартную архитектуру GPT-2 - это трансформер типа "декодер-онли", обученный на задаче предсказания следующего токена. Дообучение адаптирует эту способность к задаче генерации SQL-запросов и объяснений на основе структурированных промптов, содержащих схему БД.

### Compute Infrastructure

#### Hardware

Обучение проводилось на GPU NVIDIA RTX 2000.

#### Software

*   Python
*   PyTorch
*   Hugging Face `transformers`
*   Hugging Face `datasets`
*   Hugging Face `accelerate`
*   Hugging Face `huggingface-hub`