simple-llm/doc/token_embeddings_ru.md

# TokenEmbeddings - Векторные представления токенов

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

---

**Краткое summary:**
Документ описывает слой преобразования индексов токенов в плотные векторные представления (эмбеддинги). Включает алгоритм, пример использования, параметры и типовые ошибки.

---

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

---

## Назначение
Модуль `TokenEmbeddings` преобразует дискретные индексы токенов в плотные векторные представления (эмбеддинги). Это фундаментальный компонент большинства нейросетевых моделей для обработки естественного языка (NLP).

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

```mermaid
flowchart TD
    A[Начало] --> B[Инициализация таблицы эмбеддингов]
    B --> C[Получение индексов токенов]
    C --> D{Все ли индексы\nв пределах словаря?}
    D -->|Да| E[Поиск векторов в таблице]
    D -->|Нет| F[Ошибка: индекс вне словаря]
    E --> G[Возврат тензора эмбеддингов]
    G --> H[Обновление весов при обучении]
    H --> I[Конец]
    F --> I
```

1. **Инициализация**:
   - Создается таблица эмбеддингов размером `vocab_size x emb_size`
   - Каждая строка таблицы соответствует векторному представлению одного токена
   - Инициализация происходит случайным образом (обычно из нормального распределения)

2. **Преобразование токенов**:
   - На вход принимается тензор целых чисел (индексов токенов)
   - Для каждого индекса выполняется "lookup" в таблице эмбеддингов
   - Возвращается тензор векторных представлений

3. **Обучение**:
   - Веса эмбеддингов обновляются в процессе обучения модели
   - Сходные по значению токены получают близкие векторные представления

## Использование
```python
from simple_llm.embedding.token_embedings import TokenEmbeddings

# Инициализация
embedding_layer = TokenEmbeddings(
    vocab_size=10000,  # размер словаря
    emb_size=300       # размерность векторов
)

# Пример использования
tokens = torch.tensor([[1, 2, 3], [4, 5, 6]])  # индексы токенов
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
2. Представление категориальных признаков
3. Создание плотных представлений для sparse данных

## Рекомендации
- Для больших словарей используйте размерность 256-1024
- При использовании предобученных эмбеддингов можно заморозить слой (embedding_layer.requires_grad_(False))
- Для обработки неизвестных токенов (OOV) резервируйте нулевой индекс