Добавлены TokenEmbeddings: реализация, документация и примеры

doc/token_embeddings_ru.md

@@ -0,0 +1,69 @@
+# TokenEmbeddings - Векторные представления токенов
+
+## Назначение
+Модуль `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 | Размерность векторных представлений |
+
+## Особенности
+- **Автоматическое обучение**: Векторы адаптируются в процессе тренировки модели
+- **Эффективность**: Быстрое преобразование индексов в векторы
+- **Гибкость**: Может использоваться как самостоятельный слой или часть более сложной архитектуры
+
+## Типичные сценарии использования
+1. Первый слой в нейросетевых моделях NLP
+2. Представление категориальных признаков
+3. Создание плотных представлений для sparse данных
+
+## Рекомендации
+- Для больших словарей используйте размерность 256-1024
+- При использовании предобученных эмбеддингов можно заморозить слой (embedding_layer.requires_grad_(False))
+- Для обработки неизвестных токенов (OOV) резервируйте нулевой индекс

example/example_token_embeddings.py

@@ -0,0 +1,94 @@
+"""
+Пример использования TokenEmbeddings для работы с векторными представлениями токенов
+
+Содержит:
+1. Базовый пример создания и использования эмбеддингов
+2. Пример обучения эмбеддингов
+3. Визуализацию похожих токенов
+"""
+
+import torch
+import matplotlib.pyplot as plt
+from sklearn.decomposition import PCA
+from simple_llm.embedding.token_embedings import TokenEmbeddings
+
+def basic_example():
+    """Базовый пример использования TokenEmbeddings"""
+    print("\n=== Базовый пример ===")
+    
+    # Создаем слой эмбеддингов для словаря из 10 токенов с размерностью 3
+    embedding_layer = TokenEmbeddings(vocab_size=10, emb_size=3)
+    
+    # Создаем тензор с индексами токенов (2 примера по 3 токена)
+    tokens = torch.tensor([
+        [1, 2, 3],  # Первая последовательность
+        [4, 5, 6]   # Вторая последовательность
+    ])
+    
+    # Получаем векторные представления
+    embeddings = embedding_layer(tokens)
+    
+    print("Исходные индексы токенов:")
+    print(tokens)
+    print("\nВекторные представления (формат: [batch, sequence, embedding]):")
+    print(embeddings)
+    print(f"\nФорма выходного тензора: {embeddings.shape}")
+
+def training_example():
+    """Пример обучения эмбеддингов"""
+    print("\n=== Пример обучения ===")
+    
+    # Инициализация
+    embed = TokenEmbeddings(vocab_size=5, emb_size=2)
+    optimizer = torch.optim.SGD(embed.parameters(), lr=0.1)
+    
+    # Токены для обучения (предположим, что 0 и 1 должны быть похожи)
+    similar_tokens = torch.tensor([0, 1])
+    
+    print("Векторы ДО обучения:")
+    print(embed(torch.arange(5)))  # Все векторы
+    
+    # Простейший "тренировочный" цикл
+    for _ in range(50):
+        optimizer.zero_grad()
+        embeddings = embed(similar_tokens)
+        loss = torch.dist(embeddings[0], embeddings[1])  # Минимизируем расстояние
+        loss.backward()
+        optimizer.step()
+    
+    print("\nВекторы ПОСЛЕ обучения:")
+    print(embed(torch.arange(5)))
+    print(f"\nРасстояние между токенами 0 и 1: {torch.dist(embed(torch.tensor([0])), embed(torch.tensor([1]))):.4f}")
+
+def visualization_example():
+    """Визуализация эмбеддингов в 2D пространстве"""
+    print("\n=== Визуализация ===")
+    
+    # Создаем эмбеддинги для 100 токенов
+    embed = TokenEmbeddings(vocab_size=100, emb_size=16)
+    
+    # Получаем все векторы
+    all_embeddings = embed(torch.arange(100)).detach().numpy()
+    
+    # Уменьшаем размерность до 2D для визуализации
+    pca = PCA(n_components=2)
+    embeddings_2d = pca.fit_transform(all_embeddings)
+    
+    # Визуализация
+    plt.figure(figsize=(10, 8))
+    plt.scatter(embeddings_2d[:, 0], embeddings_2d[:, 1], alpha=0.7)
+    plt.title("Визуализация эмбеддингов токенов (PCA)")
+    plt.xlabel("Компонента 1")
+    plt.ylabel("Компонента 2")
+    
+    # Подпишем некоторые точки
+    for i in [0, 1, 2, 50, 51, 52, 98, 99]:
+        plt.annotate(str(i), (embeddings_2d[i, 0], embeddings_2d[i, 1]))
+    
+    plt.grid()
+    plt.show()
+
+if __name__ == "__main__":
+    basic_example()
+    training_example()
+    visualization_example()