Документация и примеры: унификация путей, стабильная работа на CPU, расширенный корпус для токенизатора, end-to-end пайплайн обучения и генерации. Исправлены все ошибки с устройствами и индексами, добавлены проверки и диагностика prompt.

doc/multi_head_attention_ru.md

@@ -1,5 +1,23 @@
 # MultiHeadAttention - Многоголовый механизм внимания
 
+> **Документ актуален для Simple-LLM v1.0 (июль 2025)**
+
+---
+
+**Краткое summary:**
+Документ описывает реализацию многоголового механизма внимания (Multi-Head Attention) в трансформерах. Включает описание алгоритма, пример использования и типовые ошибки.
+
+---
+
+**Структура документа:**
+- Назначение
+- Алгоритм работы
+- Пример использования
+- Параметры
+- Типовые ошибки и их решения
+
+---
+
 ## Назначение
 Модуль реализует ключевой компонент архитектуры Transformer, который:
 - Параллельно вычисляет несколько типов внимания
@@ -58,6 +76,40 @@ output = mha(x)  # [1, 50, 512]
 ## Параметры
 | Параметр      | Тип  | Описание                     |
 |---------------|------|------------------------------|
+
+## Рекомендации
+- Размерность emb_size должна делиться на num_heads * head_size
+- Для визуализации весов используйте специализированные инструменты
+
+---
+
+## Типовые ошибки и их решения
+
+### Ошибка: Размерности не совпадают при разделении на головы
+**Возможные причины:**
+- emb_size не делится на num_heads * head_size
+- Некорректная форма входного тензора
+
+**Решение:**
+- Проверьте, что emb_size = num_heads * head_size
+- Убедитесь, что вход имеет форму [batch_size, seq_len, emb_size]
+
+### Ошибка: CUDA out of memory
+**Возможные причины:**
+- Слишком большой batch_size, seq_len или число голов
+
+**Решение:**
+- Уменьшите batch_size, seq_len или num_heads
+
+### Ошибка: Не работает маскирование
+**Возможные причины:**
+- Неправильная форма или тип маски
+
+**Решение:**
+- Проверьте, что mask совпадает по размерности с attention scores
+
+---
+
 | `num_heads`   | int  | Количество голов внимания    |
 | `emb_size`    | int  | Размерность входных эмбеддингов|
 | `head_size`   | int  | Размерность каждой головы    |