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

doc/token_embeddings_ru.md

@@ -1,5 +1,24 @@
 # TokenEmbeddings - Векторные представления токенов
 
+> **Документ актуален для Simple-LLM v1.0 (июль 2025)**
+
+---
+
+**Краткое summary:**
+Документ описывает слой преобразования индексов токенов в плотные векторные представления (эмбеддинги). Включает алгоритм, пример использования, параметры и типовые ошибки.
+
+---
+
+**Структура документа:**
+- Назначение
+- Алгоритм работы
+- Использование
+- Параметры
+- Особенности
+- Типовые ошибки и их решения
+
+---
+
 ## Назначение
 Модуль `TokenEmbeddings` преобразует дискретные индексы токенов в плотные векторные представления (эмбеддинги). Это фундаментальный компонент большинства нейросетевых моделей для обработки естественного языка (NLP).
 
@@ -53,10 +72,38 @@ embeddings = embedding_layer(tokens)  # векторные представле
 | vocab_size | int | Размер словаря (количество уникальных токенов) |
 | emb_size   | int | Размерность векторных представлений |
 
-## Особенности
-- **Автоматическое обучение**: Векторы адаптируются в процессе тренировки модели
-- **Эффективность**: Быстрое преобразование индексов в векторы
-- **Гибкость**: Может использоваться как самостоятельный слой или часть более сложной архитектуры
+## Рекомендации
+- Для больших словарей используйте размерность 256-1024
+- При использовании предобученных эмбеддингов можно заморозить слой (embedding_layer.requires_grad_(False))
+- Для обработки неизвестных токенов (OOV) резервируйте нулевой индекс
+
+---
+
+## Типовые ошибки и их решения
+
+### Ошибка: Индекс токена вне диапазона словаря
+**Возможные причины:**
+- Входные индексы превышают vocab_size
+
+**Решение:**
+- Проверьте, что все индексы < vocab_size
+- Добавьте обработку [UNK] токенов при необходимости
+
+### Ошибка: Размерности не совпадают при сложении эмбеддингов с другими слоями
+**Возможные причины:**
+- emb_size не совпадает с размерностью других эмбеддингов
+
+**Решение:**
+- Приведите размерности к одному значению во всех слоях
+
+### Ошибка: Эмбеддинги не обучаются
+**Возможные причины:**
+- Параметры слоя не добавлены в оптимизатор
+
+**Решение:**
+- Проверьте, что слой TokenEmbeddings включён в модель и его параметры передаются в оптимизатор
+
+---
 
 ## Типичные сценарии использования
 1. Первый слой в нейросетевых моделях NLP