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

doc/head_attention_ru.md

@@ -1,5 +1,22 @@
 # HeadAttention - Механизм самовнимания одной головы
 
+> **Документ актуален для Simple-LLM v1.0 (июль 2025)**
+
+---
+
+**Краткое summary:**
+Данный файл описывает реализацию механизма внимания одной головы (Single Head Attention) в трансформерах. Охватывает основные этапы вычислений, пример использования и типовые ошибки.
+
+---
+
+**Структура документа:**
+- Назначение
+- Алгоритм работы
+- Пример использования
+- Типовые ошибки и их решения
+
+---
+
 ## Назначение
 Модуль реализует механизм внимания одной головы из архитектуры Transformer. Основные применения:
 - Моделирование зависимостей в последовательностях
@@ -58,6 +75,42 @@ x = torch.randn(2, 10, emb_size)
 output = attn_head(x)  # [2, 10, head_size]
 ```
 
+---
+
+## Типовые ошибки и их решения
+
+### Ошибка: Размерности не совпадают при умножении матриц
+**Возможные причины:**
+- Несовпадение emb_size и head_size при инициализации
+- Некорректная форма входного тензора
+
+**Решение:**
+- Проверьте, что emb_size делится на head_size без остатка
+- Убедитесь, что вход имеет форму [batch_size, seq_len, emb_size]
+
+### Ошибка: CUDA out of memory
+**Возможные причины:**
+- Слишком большой batch_size или seq_len
+
+**Решение:**
+- Уменьшите batch_size или seq_len
+
+### Ошибка: Не работает маскирование
+**Возможные причины:**
+- Неправильная форма или тип маски
+
+**Решение:**
+- Проверьте, что mask совпадает по размерности с attention scores
+
+## Рекомендации по использованию
+- Следите, чтобы emb_size делился на head_size без остатка
+- Для визуализации весов используйте специализированные инструменты
+- Для сложных задач используйте MultiHeadAttention
+- Размер головы (`head_size`) обычно выбирают 64-128
+- Для длинных последовательностей (>512) используйте оптимизации:
+  - Локальное внимание
+  - Разреженные паттерны
+
 ## Особенности реализации
 
 ### Ключевые компоненты
@@ -73,11 +126,6 @@ output = attn_head(x)  # [2, 10, head_size]
 - Поддерживает только causal-режим
 - Фиксированный максимальный размер последовательности
 
-## Рекомендации по использованию
-1. Размер головы (`head_size`) обычно выбирают 64-128
-2. Для длинных последовательностей (>512) используйте оптимизации:
-   - Локальное внимание
-   - Разреженные паттерны
 3. Сочетайте с MultiHeadAttention для лучшего качества
 
 [Дополнительные примеры](/example/attention_examples.py)