Рефакторинг и улучшение компонентов

Основные изменения в коде: 1. Токенизатор (bpe.py): - Добавлен прогресс-бар через tqdm в метод fit() - Улучшено логирование процесса обучения - Добавлена обработка edge-cases для vocab_size 2. Генерация текста (generate_text.py): - Полный рефакторинг скрипта - Добавлены проверки модели перед загрузкой - Поддержка уменьшенных моделей (seq_len=32) - Подробное логирование процесса генерации 3. Обучение GPT (train_gpt_model.py): - Автоподбор параметров под размер данных - Уменьшенные параметры модели по умолчанию - Контроль памяти и устройств (CPU/MPS) 4. Токенизация корпуса (tokenize_corpus.py): - Добавлены проверки входных данных - Подробное логирование процесса - Обработка ошибок загрузки файлов Исправления: - Синхронизация размеров слоёв в GPT - Корректная работа с малыми наборами данных - Исправление загрузки моделей на MPS Обновление README.md - Добавлены обязательные зависимости: dill и tqdm - Добавлен раздел 'Цель проекта' с описанием задач - Добавлен раздел 'Участие в разработке' для контрибьюторов - Добавлен раздел 'Лицензия' с условиями MIT Рефакторинг основных скриптов и обновление данных Основные изменения: 1. Скрипты в bin/: - Оптимизация generate_text.py (генерация текста) - Улучшение tokenize_corpus.py (обработка корпуса) - Рефакторинг train_gpt_model.py (обучение модели) - Обновление train_tokenizer.py (алгоритм BPE) 2. Данные: - Удалены устаревшие артефакты: * simple_llm_gpt.pth (модель) * bpe_tokenizer.json (токенизатор) * corpus_tokens.pkl (токены) - Подготовка к генерации новых данных
2026-01-23 21:14:17 +00:00 · 2025-07-24 12:58:59 +03:00
parent 6ce048d4ad
commit cc4138aba8
19 changed files with 515 additions and 338 deletions
--- a/README.md
+++ b/README.md
@@ -1,202 +1,169 @@
-# Simple-LLM Framework
+# Simple-LLM: Персональная языковая модель

-[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)]()
-[![PyTorch Version](https://img.shields.io/badge/pytorch-1.10%2B-orange)]()
+## 🎯 Цель проекта

-> **Актуально для Simple-LLM v1.0 (июль 2025)**
+Simple-LLM - это минималистичная реализация языковой модели (LLM) с полным циклом:
+- Обучение BPE-токенизатора на ваших данных
+- Подготовка датасета для обучения модели
+- Тренировка компактной GPT-архитектуры
+- Генерация текста в заданном стиле

---
+Проект создан для:
+1. Образовательных целей - понимания работы современных LLM
+2. Экспериментов с генерацией текста на небольших датасетах
+3. Создания персонализированных языковых моделей

-## Установка
+Полный цикл от обучения токенизатора до генерации текста

-Рекомендуется использовать виртуальное окружение (venv) для изоляции зависимостей и корректной работы импортов.
+## 🛠 Установка

 ```bash
-python3 -m venv venv
-source venv/bin/activate
-pip install .
+# 1. Клонируйте репозиторий
+git clone https://github.com/ваш-репозиторий/simple-llm.git
+cd simple-llm
+
+# 2. Создайте виртуальное окружение (рекомендуется)
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# или venv\Scripts\activate  # Windows
+
+# 3. Установите зависимости
+pip install torch==2.0.1
+pip install dill tqdm  # Основные зависимости для работы
 ```

-Также вы можете вручную установить необходимые зависимости:
+## 📂 Подготовка данных

+Поместите текстовые файлы (.txt) в папку:
+```
+data/
+└── corpus/
+    └── sample/
+        ├── text1.txt
+        ├── text2.txt
+        └── ...
+```
+
+## 🔄 Полный рабочий цикл
+
+### 1. Обучение BPE-токенизатора
 ```bash
-pip install torch numpy dill
+python bin/train_tokenizer.py \
+  --corpus data/corpus/sample \
+  --output data/tokenizer/bpe_model.json \
+  --vocab-size 500
 ```

-Если появится файл `requirements.txt`, используйте:
-
+### 2. Токенизация данных
 ```bash
-pip install -r requirements.txt
+python bin/tokenize_corpus.py \
+  --corpus data/corpus/sample \
+  --tokenizer data/tokenizer/bpe_model.json \
+  --output data/tokens/tokenized_corpus.pkl
 ```

-Если вы хотите использовать последнюю версию из PyPI:
-
+### 3. Обучение GPT модели
 ```bash
-pip install simple-llm
+python bin/train_gpt_model.py \
+  --tokens data/tokens/tokenized_corpus.pkl \
+  --tokenizer data/tokenizer/bpe_model.json \
+  --output data/model/gpt_model.pth \
+  --seq-len 32 \
+  --batch-size 3 \
+  --epochs 3 \
+  --emb-size 64 \
+  --num-heads 2 \
+  --num-layers 2
 ```

-Если возникают ошибки с импортами, убедитесь, что пакет установлен через pip и вы находитесь в активированном виртуальном окружении.
-
-### Основные зависимости
- torch
- numpy
- dill
-
-**Краткая инструкция по обучению на своих данных:**
-1. Обучите BPE-токенизатор на тексте (см. `simple_llm.tokenizer.bpe.BPE`).
-2. Токенизируйте корпус и создайте датасет через `GetData`.
-3. Инициализируйте модель `GPT` с нужными параметрами.
-4. Обучите модель одной строкой: `model.fit(train_loader, num_epoch=10)`.
-5. Для подробной инструкции и примеров см. [документацию](doc/train_on_custom_data_ru.md).
-
---
-
-**Структура README:**
- Обзор
- Быстрый старт
- Основные компоненты
- Документация
- Тестирование
- Как внести вклад
- Лицензия
- [FAQ](#faq)
-
---
-
-Простая и понятная реализация языковой модели GPT-стиля с нуля на PyTorch
-
-## 🔍 Обзор
-
-Simple-LLM предоставляет:
- Полную реализацию архитектуры GPT
- Эффективный токенизатор BPE
- Модули трансформера (внимание, FFN, эмбеддинги)
- Гибкую систему генерации текста
- Примеры использования и документацию
-
-## 🚀 Быстрый старт
-
-1. Установите зависимости:
+### 4. Генерация текста
 ```bash
-pip install torch numpy tqdm
+python bin/generate_text.py \
+  --model data/model/gpt_model.pth \
+  --tokenizer data/tokenizer/bpe_model.json \
+  --seq-len 32 \
+  --emb-size 64 \
+  --num-heads 2 \
+  --num-layers 2 \
+  --prompt "Ваш текст для продолжения" \
+  --length 100 \
+  --temperature 0.7
 ```

-2. Запустите примеры:
+## 🚀 Быстрый старт (минимальная конфигурация)
 ```bash
-# Пример генерации текста
-python example/example_gpt.py
-
-# Пример обучения модели
-python example/train_gpt_example.py
+# Последовательно выполните:
+./bin/train_tokenizer.py --corpus data/corpus/sample --output data/tokenizer/bpe.json
+./bin/tokenize_corpus.py --corpus data/corpus/sample --tokenizer data/tokenizer/bpe.json
+./bin/train_gpt_model.py --tokens data/tokens/corpus_tokens.pkl --tokenizer data/tokenizer/bpe.json
+./bin/generate_text.py --model data/model/gpt_model.pth --tokenizer data/tokenizer/bpe.json --prompt "Привет"
 ```

-## 🧠 Основные компоненты
+## 🧠 Рекомендации по параметрам

-### Обработка данных
-```python
-from simple_llm.data.get_data import GetData
+| Параметр         | CPU (рекомендации) | GPU (рекомендации) |
+|------------------|--------------------|--------------------|
+| vocab-size       | 2000-5000          | 5000-10000         |
+| seq-len          | 64-128             | 128-256            |
+| batch-size       | 4-8                | 16-32              |
+| emb-size         | 64-128             | 256-512            |
+| num-layers       | 2-4                | 6-12               |

-dataset = GetData(
-    data=[1, 2, 3, 4, 5],  # Входная последовательность
-    seq_len=3,             # Длина окна
-    device="cuda"          # Устройство (опционально)
-)
-```
+## ⚠️ Устранение проблем
+1. **Ошибка памяти**:
+   - Уменьшите `batch-size` и `seq-len`
+   ```bash
+   python bin/train_gpt_model.py --batch-size 2 --seq-len 64
+   ```

-### Модель GPT
-```python
-from simple_llm.transformer.gpt import GPT
+2. **Плохая генерация**:
+   - Увеличьте размер корпуса (>1MB текста)
+   - Добавьте больше эпох обучения (`--epochs 15`)

-model = GPT(
-    vocab_size=10000,
-    max_seq_len=512,
-    emb_size=768,
-    num_heads=12,
-    num_layers=6
-)
-```
+3. **Медленная работа**:
+   ```bash
+   # Для GPU добавьте перед запуском:
+   export CUDA_VISIBLE_DEVICES=0
+   ```

-### Генерация текста
-```python
-output = model.generate(
-    input_ids,
-    max_new_tokens=100,
-    temperature=0.9,
-    top_k=50,
-    top_p=0.9
-)
-```
+## 👥 Участие в разработке

-### Обучение модели
-```python
-from torch.utils.data import DataLoader
+Мы приветствуем вклад в проект! Вот как вы можете помочь:

-# Данные должны быть в формате (input_ids, targets)
-# targets - это input_ids, сдвинутые на 1 токен вперед
-train_loader = DataLoader(...) 
-
-model.fit(
-    train_loader=train_loader,  # Обучающие данные (обязательно)
-    valid_loader=None,          # Валидационные данные (опционально)
-    num_epoch=10,               # Количество эпох
-    learning_rate=0.001         # Скорость обучения
-)
-
-# Сохранение модели
-model.save("model.pt")
-
-# Загрузка модели
-loaded_model = GPT.load("model.pt", device="cuda")
-```
-
-**Требования к данным:**
- Формат: `(input_ids, targets)` где `targets = roll(input_ids, -1)`
- `input_ids`: тензор формы `[batch_size, seq_len]`
- Поддерживаются как синтетические, так и реальные текстовые данные
-
-## 📚 Документация
-
-Полная документация доступна в [doc/](./doc/):
- [Архитектура GPT](./doc/gpt_documentation_ru.md)
- [Алгоритм BPE](./doc/bpe_algorithm.md)
- [Обработка последовательностей](./doc/get_data_documentation_ru.md)
- [Примеры использования](./example/)
-
-## 🛠 Тестирование
-```bash
-pytest tests/
-```
-
-## 🤝 Как внести вклад
+### 🛠 Как внести свой вклад:
 1. Форкните репозиторий
-2. Создайте ветку (`git checkout -b feature/AmazingFeature`)
-3. Сделайте коммит (`git commit -m 'Add some AmazingFeature'`)
-4. Запушьте ветку (`git push origin feature/AmazingFeature`)
-5. Откройте Pull Request
+2. Создайте ветку для вашего изменения (`git checkout -b feature/your-feature`)
+3. Сделайте коммит ваших изменений (`git commit -am 'Add some feature'`)
+4. Запушьте в ветку (`git push origin feature/your-feature`)
+5. Создайте Pull Request

---
+### 📌 Правила:
+- Следуйте существующему стилю кода
+- Пишите понятные сообщения коммитов
+- Добавляйте тесты для новых функций
+- Обновляйте документацию при изменении API

-## ❓ FAQ
-
-**Q: Как установить Simple-LLM, чтобы работали все импорты?**
-A: Рекомендуется установить через pip (локально: `pip install .` или с PyPI: `pip install simple-llm`). Тогда все примеры и импорты будут работать из любой директории.
-
-**Q: Как запустить Simple-LLM на CPU?**
-A: Передайте параметр `device="cpu"` при инициализации модели или обработке данных.
-
-**Q: Как использовать свой датасет?**
-A: Используйте класс `GetData` из `simple_llm.data.get_data` для подготовки своих последовательностей. Следуйте формату `(input_ids, targets)`.
-
-**Q: Где посмотреть примеры?**
-A: В папке [`example/`](./example/) есть скрипты генерации и обучения.
-
-**Q: Ошибка CUDA out of memory!**
-A: Уменьшите размер batch_size или размерность модели, либо используйте CPU.
-
-**Q: Как добавить новый модуль или улучшение?**
-A: Ознакомьтесь с документацией, следуйте рекомендациям по вкладу и открывайте Pull Request.
-
---
+### 🐛 Сообщение об ошибках:
+Открывайте Issue с описанием:
+1. Шаги для воспроизведения
+2. Ожидаемое поведение
+3. Фактическое поведение
+4. Версии ПО (Python, PyTorch и т.д.)

 ## 📜 Лицензия
-Распространяется под лицензией MIT. См. [LICENSE](./LICENSE)
+
+Проект распространяется под лицензией MIT. Полный текст лицензии доступен в файле [LICENSE](LICENSE).
+
+Основные положения:
+- Разрешается свободное использование, модификация и распространение кода
+- Обязательно указание авторства
+- Лицензия предоставляется "как есть" без гарантий
+- Авторы не несут ответственности за последствия использования
+
+## 📌 Важно
+- Все скрипты имеют встроенную помощь:
+```bash
+python bin/train_tokenizer.py --help
+```
+- Модель автоматически использует GPU если доступен
+- Для выхода из виртуального окружения: `deactivate`