simple-llm/doc/gpt_documentation_ru.md

# Документация по GPT модели

## 1. Общее описание
GPT (Generative Pre-trained Transformer) - это авторегрессивная модель генерации текста на основе архитектуры трансформера.

**Ключевые особенности реализации:**
- Поддержка различных режимов генерации (жадный поиск, сэмплирование)
- Многослойный декодер с механизмом самовнимания
- Оптимизированная работа на CPU/GPU
- Гибкая настройка параметров генерации
- Поддержка комбинированных стратегий (top-k + top-p)

## 2. Архитектура и алгоритм

### 2.1 Полная блок-схема
```mermaid
graph TD
    A[Входные токены] --> B[Токенные эмбеддинги]
    A --> C[Позиционные эмбеддинги]
    B --> D[Сумма эмбеддингов + Dropout]
    C --> D
    D --> E[Стек декодеров]
    E --> F[Многоголовое самовнимание]
    F --> G[Add & Norm]
    G --> H[FeedForward]
    H --> I[Add & Norm]
    I --> J[Выходные логиты]
    J --> K[Выбор следующего токена]
    K --> L[Добавление к последовательности]
```

### 2.2 Режимы генерации
1. **Жадный поиск** (do_sample=False):
   - Всегда выбирает токен с максимальной вероятностью
   - Детерминированный результат

2. **Вероятностное сэмплирование** (do_sample=True):
   - С температурой (temperature=0.5-1.5)
   - Top-k (top_k=10-100)
   - Nucleus sampling (top_p=0.7-0.95)
   - Комбинированный режим (top_k + top_p)

## 3. Практическое использование

### 3.1 Инициализация модели
```python
from simple_llm.transformer.gpt import GPT

model = GPT(
    vocab_size=10000,    # Размер словаря
    max_seq_len=512,     # Макс. длина контекста
    emb_size=768,        # Размерность эмбеддингов
    num_heads=12,        # Число голов внимания
    head_size=64,        # Размерность головы
    num_layers=6,        # Количество слоев декодера
    dropout=0.1,         # Вероятность dropout
    device='cuda'        # 'cpu' или 'cuda'
)
```

### 3.2 Генерация текста
```python
output = model.generate(
    input_ids,           # Входные токены [batch_size, seq_len]
    max_new_tokens=50,    # Макс. число новых токенов
    do_sample=True,      # Режим сэмплирования
    temperature=0.9,     # Контроль случайности (0.1-2.0)
    top_k=50,            # Ограничение по топ-k токенам
    top_p=0.9,           # Параметр nucleus sampling
    repetition_penalty=1.2, # Штраф за повторения
    stop_tokens=None     # Токены для остановки генерации
)
```

### 3.3 Примеры использования

**Базовый пример:**
```python
text = "Анализ данных - это"
input_ids = tokenizer.encode(text)
output_ids = model.generate(input_ids, max_new_tokens=100)
generated_text = tokenizer.decode(output_ids[0])
```

**Креативная генерация:**
```python
output = model.generate(
    input_ids,
    max_new_tokens=100,
    do_sample=True,
    temperature=1.3,
    top_k=60,
    top_p=0.85
)
```

## 4. Оптимизация и настройка

### 4.1 Рекомендуемые параметры

| Тип задачи       | Параметры                     |
|------------------|-------------------------------|
| Точные ответы    | temp=0.7, top_k=40, top_p=0.8 |
| Креативная письмо| temp=1.2, top_k=60, top_p=0.9 |
| Кодогенерация    | temp=0.8, top_k=50, top_p=0.85|

### 4.2 Производительность

**Для CPU:**
```python
model = GPT(
    emb_size=256,
    num_layers=4,
    num_heads=8,
    device='cpu'
)
```

**Для GPU:**
```python
model = GPT(
    emb_size=1024,
    num_layers=12,
    device='cuda'
)
```

## 5. Ограничения и решения

| Ограничение               | Решение                      |
|---------------------------|------------------------------|
| Длинные последовательности| Чанкование входных данных    |
| Высокая загрузка памяти   | Уменьшение batch_size        |
| Повторы в генерации       | Настройка repetition_penalty |
| Медленная генерация       | Кэширование ключей/значений  |

## 6. Дополнительные материалы
- [Примеры использования](../example/example_gpt.py)
- [Тесты](../tests/test_gpt.py)
- [Оптимизация производительности](performance_guide.md)