simple-llm/doc/get_data_documentation_ru.md

# Документация по классу GetData

> **Документ актуален для Simple-LLM v1.0 (июль 2025)**

---

**Краткое summary:**
Документ описывает класс GetData для создания датасетов из последовательных данных. Включает алгоритм, параметры, примеры, рекомендации и типовые ошибки.

---

**Структура документа:**
- Назначение
- Основные возможности
- Алгоритм работы
- Пример использования
- Параметры класса
- Методы
- Рекомендации
- Типовые ошибки и их решения
- Применение
- Пример с текстовыми данными

---

## Назначение
Класс `GetData` предназначен для создания датасетов из последовательных данных для обучения языковых моделей и других задач, работающих с последовательностями.

## Основные возможности
- Преобразование последовательности данных в обучающие пары (input, target)
- Поддержка различных типов данных (числа, токены)
- Автоматический сдвиг целевой последовательности
- Поддержка работы на CPU/GPU
- Проверка корректности входных параметров

## Алгоритм работы
1. Принимает на вход последовательность данных и длину окна
2. Скользящим окном проходит по последовательности
3. Для каждой позиции создает пару:
   - Входная последовательность: `data[pos:pos+seq_len]`
   - Целевая последовательность: `data[pos+1:pos+seq_len+1]` (сдвиг на 1 элемент)
4. Преобразует данные в тензоры PyTorch

```mermaid
flowchart TD
    A[Начало] --> B[Проверка параметров]
    B -->|seq_len <= 0| C[Ошибка: отрицательная длина]
    B -->|seq_len >= len(data)| D[Ошибка: слишком длинное окно]
    B -->|Параметры верны| E[Инициализация датасета]
    E --> F[Для каждого индекса i от 0 до len(data)-seq_len-1]
    F --> G[Входной тензор: data[i:i+seq_len]]
    G --> H[Целевой тензор: data[i+1:i+seq_len+1]]
    H --> I[Преобразование в тензоры PyTorch]
    I --> J[Возврат пары тензоров]
    J --> F
    F -->|Все индексы обработаны| K[Конец]
```

## Пример использования
```python
from simple_llm.data.get_data import GetData

data = list(range(10))  # Последовательность 0-9
seq_len = 3
dataset = GetData(data=data, seq_len=seq_len)

# Получение первого примера
x, y = dataset[0] 
print(f"Вход: {x.tolist()} → Цель: {y.tolist()}")
# Вывод: Вход: [0, 1, 2] → Цель: [1, 2, 3]
```

## Параметры класса
- `data` (list): Входная последовательность данных
- `seq_len` (int): Длина окна последовательности
- `device` (str): Устройство для тензоров ('cpu' или 'cuda')

## Методы
- `__len__()`: Возвращает количество обучающих примеров
- `__getitem__(idx)`: Возвращает пару тензоров по индексу

## Рекомендации
- Для текстовых данных предварительно токенизируйте текст
- Для больших датасетов используйте GPU (`device='cuda'`)
- Подбирайте `seq_len` в зависимости от задачи

---

## Типовые ошибки и их решения

### Ошибка: ValueError при создании датасета
**Возможные причины:**
- `seq_len` <= 0
- `seq_len` >= длины данных

**Решение:**
- Задайте `seq_len` > 0 и < длины данных
- Проверьте корректность входных параметров

---

## Применение
1. Обучение языковых моделей
2. Прогнозирование временных рядов
3. Любые задачи, требующие работы с последовательностями

## Пример с текстовыми данными
```python
text_tokens = [10, 20, 30, 40]  # Токенизированный текст
dataset = GetData(text_tokens, seq_len=2)
x, y = dataset[1]
print(f"Вход: {x.tolist()} → Цель: {y.tolist()}")
# Вывод: Вход: [20, 30] → Цель: [30, 40]
```