simple-llm/doc/decoder_ru.md

# Декодер Transformer

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

---

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

---

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

---

## Назначение
Декодер - ключевой компонент архитектуры Transformer, предназначенный для:
- Генерации последовательностей (текст, код и др.)
- Обработки входных данных с учетом контекста
- Постепенного построения выходной последовательности
- Работы с масками внимания (предотвращение "утечки" будущего)

## Алгоритм работы

```mermaid
graph TD
    A[Входной тензор] --> B[Многоголовое внимание]
    B --> C[Residual + LayerNorm]
    C --> D[FeedForward Network]
    D --> E[Residual + LayerNorm]
    E --> F[Выходной тензор]
    
    style A fill:#f9f,stroke:#333
    style F fill:#bbf,stroke:#333
```

1. **Self-Attention**:
   - Вычисление внимания между всеми позициями
   - Учет масок для автопрегрессивного декодирования
   - Multi-head механизм (параллельные вычисления)

2. **Residual Connection + LayerNorm**:
   - Стабилизация градиентов
   - Ускорение обучения
   - Нормализация активаций

3. **FeedForward Network**:
   - Нелинейное преобразование
   - Расширение скрытого пространства
   - Дополнительная емкость модели

## Использование

```python
from simple_llm.transformer.decoder import Decoder

# Инициализация
decoder = Decoder(
    num_heads=8,
    emb_size=512,
    head_size=64,
    max_seq_len=1024
)

# Прямой проход
x = torch.randn(1, 10, 512)  # [batch, seq_len, emb_size]
output = decoder(x)

# С маской
mask = torch.tril(torch.ones(10, 10))
masked_output = decoder(x, mask)
```

## Параметры

| Параметр     | Тип  | Описание |
|--------------|------|----------|
| num_heads    | int  | Количество голов внимания |
| emb_size     | int  | Размерность эмбеддингов |
| head_size    | int  | Размерность каждой головы |
| max_seq_len  | int  | Макс. длина последовательности |
| dropout      | float| Вероятность дропаута (0.1 по умолч.) |

## Применение в архитектурах

- GPT (автопрегрессивные модели)
- Нейронный машинный перевод
- Генерация текста
- Кодогенерация

## Рекомендации
- Используйте корректные маски для автопрегрессивного декодирования
- Следите за размерностью входа и маски
- Для сложных случаев используйте teacher forcing

---

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

### Ошибка: Размерности не совпадают при подаче входа или маски
**Возможные причины:**
- Размерность входного тензора не совпадает с emb_size
- Форма маски не совпадает с [seq_len, seq_len]

**Решение:**
- Проверьте, что размерность входа и маски соответствует требованиям

### Ошибка: Модель не обучается (loss не уменьшается)
**Возможные причины:**
- Ошибка в подключении слоя к модели
- Ошибка в маскировании (утечка будущего)

**Решение:**
- Проверьте корректность маски
- Проверьте, что параметры декодера передаются в оптимизатор

### Ошибка: CUDA out of memory
**Возможные причины:**
- Слишком большой batch_size, seq_len или emb_size

**Решение:**
- Уменьшите batch_size, seq_len или emb_size

---

3. **Оптимизации**:
   - Кэширование ключей/значений
   - Пакетная обработка