Как мы адаптировали LLM для русского языка

История про токенизацию, научные статьи и production reality

Как мы потратили 2 месяца на адаптацию Qwen3-0.6B для русского языка. Написали систему с нуля на основе 8 научных статей из arXiv. Исправили 6 критических багов (от NaN в fp16 до архитектурных проблем). Получили +35% training speed и +60% inference speed. В этой статье — честный рассказ о том, что не работает из коробки, какие грабли ждут в production, и как мы их обошли.

Мы — это я и мой друг =)

Как всё началось

Август 2025. Мы работаем над MAWO — системой fine-tuning для русскоязычных LLM. У нас есть модель Qwen3-0.6B. Почему именно 0.6B, а не 8B или 70B?

RTX 4080 Super (16GB VRAM) — это всё, что у нас есть =)

• Qwen3-8B в fp16: ~16GB только для модели + градиенты + optimizer → OOM (Out of Memory)

• Qwen3-0.6B: влезает даже с batch_size=8 и остаётся место для экспериментов

Мы выбрали прагматизм. Лучше маленькая работающая модель, чем большая сломанная. Плюс всё, что мы делаем, масштабируется на большие модели (если купим больше видеокарт =)).

Но с моделью была одна проблема:

tokenizer.encode(«Привет, как дела?») # Output: 10 токенов ❌

Для сравнения, английская фраза такой же длины:

tokenizer.encode(«Hello, how are you?») # Output: 4 токена ✅

Что это значит:

• Обучение в 2.5 раза медленнее (больше токенов = больше forward/backward passes)

• Inference дороже (API берут деньги за токены)

• Модель хуже понимает морфологию («программирование» разбивается на 5 кусочков)

Западные модели (Qwen, Llama, Mistral) обучены преимущественно на английском корпусе (80-90%). Их tokenizer’ы оптимизированы для английского языка. А русский с его:

• 6 падежами (программирование, программированием, программированию…)

• Богатой морфологией (приставки, суффиксы, окончания)

• Длинными словами (в среднем на 20% длиннее английских)

превращается в последовательность маленьких кусочков. В этом плане идеальны модели Яндекса и Сбера, но они очень большие и просто так не взять =)

Решение

Мы решили адаптировать модель для русского языка. Не обучать с нуля (это 3-6-12 месяцев и миллионы долларов, а у нас только 1 видеокарта =)), а взять существующую и «научить» её лучше работать с русским.

План был простой:

1. Прочитать научные статьи про адаптацию токенизаторов

2. Реализовать алгоритмы из arXiv

3. Запустить и получить результат

На деле оказалось не все так просто.

Мы потратили 2 месяца, исправили 6 критических багов (от NaN в fp16 до архитектурных проблем), переписали 3 компонента и чуть не сдались раз пять.

Но в итоге получили работающую систему.

Что мы хотели получить

Согласно научным статьям (arXiv:2312.02598, 2406.11477), адаптация токенизатора даёт:

Шикарно! Но чтобы это получить, нужно было пройти через 5 компонентов:

┌─────────────────────────────────────────┐ │ Пайплайн адаптации │ ├─────────────────────────────────────────┤ │ │ │ 1 VocabularyCalculator │ │ Решаем: expansion или replacement? │ │ │ │ 2 TokAlign + MorphUnigram │ │ Обучаем новый токенизатор │ │ │ │ 3 VocabularyExpander │ │ Добавляем 1K русских токенов │ │ │ │ 4 LEP Initialization │ │ Инициализируем embeddings умно │ │ │ │ 5 CPT (опционально) │ │ Дообучаем модель (3-5 дней) │ │ │ └─────────────────────────────────────────┘

Две стратегии адаптации: быстро vs качественно

Прежде чем рассказать про баги, важно понять: существует две принципиально разные стратегии адаптации токенизатора для нового языка. От выбора стратегии зависит ВСЁ: время, качество, архитектура решения.

EXPANSION (Расширение словаря)

Идея: Экономим время, добавляя токены сверху

Представьте, что у вас есть англо-русский словарь на 150,000 слов. Вместо того чтобы переписывать его с нуля, вы просто добавляете 1,000 самых употребительных русских слов в конец.

Что делаем:

• Сохраняем весь оригинальный vocabulary (151,669 токенов Qwen3)

• Добавляем сверху 500-1,000 самых частых русских токенов

• Итого: 152,669 токенов (151K старых + 1K новых)

Плюсы:

• ✅ Быстро: 6-8 часов (нет CPT!)

• ✅ Не теряем multilingual способности (английский, китайский остаются)

• ✅ Работает сразу после LEP (Learned Embedding Propagation)

• ✅ Для отладки: запустил, проверил, работает

Минусы:

• ⚠️ Большой vocabulary (152K токенов вместо 25K)

• ⚠️ Медленнее inference (больше токенов = больше softmax)

• ⚠️ Качество ниже: 92-94% от оригинальной модели (arXiv:2406.11477)

Когда использовать:

• Мало данных (<3GB корпуса)

• Нужно сохранить multilingual

• Ограничено время (нет 3-5 дней на CPT)

• Для экономии времени: мы используем expansion для отладки pipeline

Пример:

# Было «Программирование» → [151643, 45892, 101234, …] # 5 токенов # Стало (expansion добавил русские токены 151669+) «Программирование» → [151670, 151901] # 2 токена (новые ID!)

REPLACEMENT (Замена словаря)

Идея: Максимальное качество через полную переделку

Вместо добавления слов, мы выбрасываем весь англо-русский словарь и пишем новый — чисто русский. Меньше, компактнее, оптимизированнее.

Что делаем:

• Удаляем весь оригинальный vocabulary (151,669 токенов)

• Обучаем новый vocabulary на русском корпусе

• Размер: 25,000-40,000 токенов (AUTO-CALCULATED по размеру корпуса)

Плюсы:

• ✅ Максимальное качество: 96-98% (после CPT!)

• ✅ Маленький vocabulary (30K vs 152K) → экономия памяти

• ✅ Быстрый inference (+60% скорость, меньше токенов!)

• ✅ Лучшая морфология (+35% training speed)

• ✅ Токены заточены под русский: «программирование» = 1 токен

Минусы:

• ❌ ОБЯЗАТЕЛЕН CPT (Continual Pre-training, 3-5 дней!)

• ❌ Без CPT модель генерирует мусор (проверено на практике!)

• ❌ Теряем multilingual способности (только русский)

• ❌ Долго: 2-3 часа (TokAlign) + 3-5 дней (CPT)

Когда использовать:

• Большой корпус (≥3GB)

• Есть 3-5 дней на CPT

• Не нужен multilingual (только русский)

• Нужно максимальное качество для production

Пример:

# Было «Программирование» → [151643, 45892, 101234, …] # 5 токенов # Стало (replacement создал новые ID с нуля) «Программирование» → [3421] # 1 токен! Совершенно другой ID!

Автоматический выбор

Мы создали VocabularyCalculator — автоматический калькулятор стратегии на основе научных исследований. Он анализирует:

1. Размер корпуса (главный фактор!) — сколько у нас данных для обучения токенизатора

2. Доступное время — сколько часов мы можем потратить

3. Multilingual требования — нужно ли сохранить другие языки

И выдаёт рекомендацию:

# Наш случай: 5.5GB корпуса, 10 часов времени recommendation = auto_select_strategy( corpus_path=»data/russian_corpus.txt», # 5.5GB available_time_hours=10.0 ) # Output: # Strategy: REPLACEMENT # Target vocab: 30,000 tokens (auto-calculated) # Expected quality: 96-98% (after CPT) # Requires CPT: YES ⚠️ # # ⚠️ КРИТИЧЕСКОЕ: Replacement требует 72ч+ CPT! # БЕЗ CPT модель генерирует мусор!

Приоритет ДАННЫХ > времени:

Даже если у вас только 10 часов, но 5.5GB корпуса — калькулятор всё равно выберет Replacement! Почему? Потому что большой корпус позволяет обучить качественный токенизатор (25K-40K токенов), а expansion на таком корпусе неоптимален.

Как вычисляется vocab size?

Не фиксированный (не всегда 40K как в Vikhr (мы же ходим адаптивность)!), а по формуле из arXiv:2312.02598:

# 33GB corpus → 23K tokens (статья) # 5.5GB corpus → ? if corpus_size >= 30: vocab_size = 40000 # Very large corpus elif corpus_size >= 10: vocab_size = 30000 # Large corpus else: vocab_size = 25000 # Medium corpus

📊 Сравнение стратегий

Что мы выбрали?

Replacement + CPT (5.5GB корпуса, 3-5 дней CPT). Для отладки использовали expansion (6-8 часов).

Теперь, когда вы понимаете стратегии, давайте посмотрим на проблемы, с которыми мы столкнулись…

Когда fp16 убивает обучение за одну секунду

Запускаю обучение LEP (Learned Embedding Propagation) в стопятисотый раз — нейросеть из 3 слоёв, которая улучшает инициализацию embeddings.

Смотрю на логи:

Шаг 0: loss=0.2341 ✅ Шаг 1: loss=nan ❌

Обучение умерло на первом шаге. Наверное, слишком большой learning_rate. Пробуем уменьшить 1e-4 → 1e-5 → 1e-6. Не помогает.

Добавляем логирование градиентов:

Шаг 0: layer.0.weight: 12.34 ✅ layer.3.weight: 45.67 ✅ Шаг 1: layer.0.weight: 1203.45 ⚠️ layer.3.weight: inf ❌

На второй итерации Градиенты улетали в бесконечность.
Модель была в fp16. Почему это проблема?

Fp16 может хранить числа только ±65,504. Это много, но:

1. У нас 3 слоя (Linear + LayerNorm + ReLU)

2. Градиенты накапливаются при backward pass

3. LayerNorm может усиливать градиенты (делит на std)

4. Если gradient > 65,504 → overflow → NaN

Решение:

# 1. Принудительно fp32 (было: .half()) model = LEPPropagationNetwork(…).float() # 2. Gradient clipping (на всякий случай) torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=0.3)

Результат:

Шаг 0: loss=0.2341 ✅ Шаг 100: loss=0.1876 ✅ Шаг 5000: loss=0.0121 ✅

Fp16 — отличная штука для экономии памяти, но не для обучения маленьких сетей с LayerNorm.

Вывод: Всегда используйте fp32 для обучения embedding initialization networks. Fp16 оставьте для inference.

При в е т

Тестируем адаптированный токенизатор после 6 часов обучения:

tokenizer = AutoTokenizer.from_pretrained(«adapted-model») text = «Привет, как дела?» decoded = tokenizer.decode(tokenizer.encode(text)) print(decoded)

Output:

При в е т , к а к д е л а ?

Проверяем конфигурацию:

cat tokenizer.json | jq ‘.decoder’ null # ← Вот проблема!

Когда мы обучали Unigram tokenizer, мы забыли установить decoder. В результате токены склеивались с пробелами:

# Токены после encode: [«▁Прив», «ет», «,», «▁как», «▁дела», «?»] # БЕЗ decoder: » «.join(tokens) = «▁Прив ет , ▁как ▁дела ?» # Пробелы везде! # С decoder: «».join(tokens).replace(«▁», » «) = «Привет, как дела?» # ✅

Решение — одна строка кода:

from tokenizers import decoders tokenizer.decoder = decoders.ByteLevel( add_prefix_space=False, trim_offsets=False )

Вывод: Всегда тестируйте полный цикл encode → decode и проверяйте, что получили исходный текст!

Токены добавлены, но не используются

Мы реализовали expansion strategy: добавили 1,000 самых частых русских токенов к оригинальным 151,669.

Проверяем через 19 минут обучения co-occurrence matrix:

text = «Программирование на Python» tokens = tokenizer.tokenize(text) new_token_usage = count_new_tokens(tokens) print(f»Новых токенов использовано: {new_token_usage}%») # Output: 0% ❌

Мы добавили 1,000 токенов, модель их видит, но не использует!

Проверяем vocabulary:

cat vocab.json | jq ‘. | length’ 152669 # 151669 + 1000 = правильно ✅ cat tokenizer.json | jq ‘.model.vocab | length’ 151669 # только старые токены! ❌

Оказалось, vocab.json содержит 152K токенов, но tokenizer.json — только 151K.

cat tokenizer.json | jq ‘.model.type’ «BPE» # должен быть «Unigram»! ❌

Мы делали expansion так:

1. TokAlign обучает Unigram tokenizer (40K tokens) ✅ 2. VocabularyExpander: — Находит 1K новых токенов ✅ — Объединяет с BPE vocab (151K + 1K = 152K) ✅ — Сохраняет… СТАРЫЙ BPE tokenizer! ❌ 3. Результат: — vocab.json: 152K (mixed BPE + Unigram) ✅ — tokenizer.json: BPE 151K ❌

Fast tokenizers в HuggingFace используют tokenizer.json. Они игнорируют vocab.json!

Нужно передавать обученный Unigram tokenizer через весь pipeline:
После исправления:

«Программирование» → [151670, 151901] # Использует новые токены! ✅

Вывод: Fast tokenizers — это два файла (vocab.json + tokenizer.json). Обновляйте ОБА!

Дооооолгое ожидание

Запускаем CW2V (Convex hull Within Word Vectors) — инициализацию embeddings для 1,000 новых токенов:

python adapt.py —strategy expansion [INFO] Initializing 1,000 new embeddings… [INFO] Building co-occurrence matrix…

Ждем. Ждем. Ждем. Ждем час.

Статья arXiv:2407.05841 описывает CW2V просто:

Для каждого нового токена: 1. Найти k ближайших токенов (по co-occurrence) 2. Взять их embeddings 3. Сделать convex combination

Мы реализовали буквально как написано:

# Наивная реализация for new_token in new_tokens: # 1000 итераций # Читаем корпус для КАЖДОГО токена! neighbors = find_neighbors(new_token, corpus_path)

1,000 токенов × 10,000 строк корпуса = 10,000,000 операций чтения!

Сделали так — читаем корпус ОДИН РАЗ, строим co-occurrence для ВСЕХ токенов одновременно.

Ещё одно улучшение — frequency-based weights вместо uniform:

# arXiv: uniform weights weights = [1/k, 1/k, …, 1/k] # Все соседи одинаково важны ❌ # Наш: frequency-based neighbor_freqs = [1000, 800, 600, …, 5] # Co-occurrence counts weights = softmax(neighbor_freqs) # Частые соседи важнее! ✅

Для токена «нейросеть»:

• Сосед «обучение» (1000 co-occurrences) → вес 0.35 ✅

• Сосед «стол» (5 co-occurrences, шум!) → вес 0.001 ✅

92GB не влезают в 16GB GPU

Запускаем TokAlign с vocabulary = 30,000:

RuntimeError: CUDA out of memory. Tried to allocate 18.2 GB # Co-occurrence matrix 30,000 × 30,000 × 4 bytes (fp32) = 3.6 GB # Alignment matrix (source × target vocab) 151,669 × 30,000 × 4 bytes = 18.2 GB # Total matrices: 21.8 GB # Model + gradients: ~5 GB # TOTAL: 27 GB ❌ # Наша GPU: 16 GB ❌

Проверяем sparsity (сколько элементов = 0):

# Возможных пар: 30,000 × 30,000 = 900,000,000 # Реально встретились вместе: non_zero_pairs = 500,000 # Sparsity: 1 — (500,000 / 900,000,000) = 99.94% sparse!

99.94% элементов — это нули! Слова «программирование» и «банан» вряд ли встретятся в одном окне из 5 токенов.

Решение: Используем PyTorch sparse tensors (COO format):

Потребление памяти:

Теперь влезает в 16GB GPU! 🎉

NLP матрицы почти всегда sparse (99%+). Используйте sparse tensors по умолчанию!

Auto-detection выбрал неправильную стратегию

После адаптации, тестируем модель:

prompt = «Напиши функцию сортировки на Python» output = model.generate(…) print(tokenizer.decode(output))

Output:

влакпщук вмилло пвакщуе фывапролд жэбячсмить…

Мусор. Проверяем метаданные:

strategy: replacement # Не expansion! vocab_size: 25000 # Не 152K! requires_cpt: true cpt_completed: false # ← ПРОБЛЕМА!

Auto-detection выбрал replacement вместо expansion. И мы запустили БЕЗ CPT!

Auto-detection логика была неправильной:

# БЫЛО: if available_time < 24h: strategy = «expansion» # ← Решение только по времени! # НО внутри: if corpus_size >= 3GB: strategy = «replacement» # ← Переопределение БЕЗ предупреждения!

Результат:

1. Пользователь: time = 10h → думает expansion

2. Скрипт видит: corpus = 5.5GB → replacement (без предупреждения!)

3. Replacement без CPT → модель сломана

Решение: Приоритет ДАННЫХ > времени:

Мы реализовали систему на основе 8 научных статей (2024-2025). Почему ни один алгоритм не заработал «из коробки»?

1. Scaling Law не применим для адаптации

arXiv:2407.13623 даёт формулу:

optimal_vocab = 5.4e-4 × model_params^0.83

Для Qwen3-0.6B это даёт 50K tokens.

НО это для training from scratch! Для адаптации:

• Expansion: сохраняем multilingual → 152K tokens

• Replacement: язык-specific → 25K-40K tokens

Scaling Law оптимизирует compute для новой модели, не для адаптации существующей.

2. Sparse tensors не упоминаются

arXiv:2506.03523 тестировался на vocabulary 10K-20K:

20K × 20K × 4 = 1.6 GB # OK для GPU

Production:

151K × 30K × 4 = 18.2 GB # OOM на 16GB GPU!

NLP co-occurrence matrices 99.9% sparse. Sparse tensors обязательны для больших vocabulary!

3. Precision (fp16 vs fp32) не обсуждается

arXiv:2412.21140 не упоминает precision. Вероятно, использовали fp32 по умолчанию (A100 с 80GB).

Мы попробовали fp16 (для экономии памяти на 16GB GPU) → NaN на первой итерации.

4. N-pass алгоритмы для малых датасетов

Статьи тестируются на малых корпусах (для скорости экспериментов).

Production: 5.5GB corpus, 1000 tokens → N-pass = 45 минут!

5. Corpus size thresholds работают (но качество другое!)

Эмпирически подтвердили пороги из arXiv:2312.02598, arXiv:2406.11477:

Важно: Качество — это % от оригинальной модели (NOT absolute accuracy!)

Почему expansion даёт 92-94%, а не 100%?

1. Добавляем только 1,000 токенов к оригинальным 151,669

   • Новые токены: 1K / 152K = 0.65% от vocabulary

   • Остальные 99.35% — старые (неоптимальные для русского)

2. Нет CPT — модель не «переобучилась» на новые токены

3. LEP инициализация даёт 95-97%, оставшиеся 3-5% теряются

Почему replacement даёт 96-98%, а не 100%?

1. CPT не может полностью восстановить знания на других языках

2. Vocabulary оптимизирован для русского, хуже для code/специальных терминов

3. Empirical results (arXiv:2312.02598): «comparable quality» = 96-98%

Что мы получили в итоге

Timeline

HYPEROFA (arXiv:2504.21018) — опциональный компонент для улучшения embeddings (+2-3% качества). Мы пробовали с ним и без него, на маленькой модели разницы не заметили.

Что дальше?

Адаптация — это только STAGE 1 нашего pipeline. Дальше идёт:

STAGE 2: PEFT Fine-tuning

• три метода обучения

• бенчмарки

• нервы

• квантизация

Расскажу в следующей статье =)

Выводы

Что мы поняли за 2 месяца:

1. ✅ Research papers ≠ production code

   • arXiv опускает детали (precision, memory, sparsity)

   • Тестируют на малых датасетах

   • Не учитывают ограничения consumer GPU

2. ✅ Debugging в ML — 80% времени

   • 6 багов, 25+ часов debugging

   • Каждый баг учит чему-то новому

   • Git history бесценна

3. ✅ Production требует optimization

   • Single-pass вместо N-pass

   • Sparse tensors для NLP

   • Frequency weights вместо uniform

4. ✅ Data > Time для ML decisions

   • Большой corpus → replacement optimal

   • Маленький corpus → expansion optimal

   • Threshold 3GB работает эмпирически

5. ✅ Explicit warnings критичны

   • Replacement без CPT = мусор

   • Пользователь должен понимать последствия

   • Manual override обязателен

Самый важный урок: Не бойтесь делать с нуля. Готовые библиотеки удобны, но не всегда решают вашу задачу. Мы получили:

• Полный контроль над процессом

• Глубокое понимание алгоритмов

• Оптимизации под наши нужды

• Систему, которая работает в production

• +35% training speed и +60% inference speed (зависит от исходной модели и качества адаптации)

Ресурсы

Научные статьи (использованы в проекте):

1. arXiv:2508.08424 — MorphUnigram tokenization

2. arXiv:2312.02598 — Russian tokenization (+35% training)

3. arXiv:2412.21140 — LEP: Learned Embedding Propagation

4. arXiv:2407.05841 — CW2V: Convex hull initialization

5. arXiv:2506.03523 — TokAlign

6. arXiv:2406.11477 — Vocabulary expansion

7. arXiv:2407.13623 — Scaling Laws with Vocabulary

8. arXiv:2504.21018 — HYPEROFA

Все баги, решения и метрики из этой статьи — production reality. Репозиторий откроем когда исправим ошибки в STAGE 2 =).

Источник: habr.com