Mott

Mott (с чеченского — «язык») — дообучение мультиязычной Qwen3-4B на чеченских данных, чтобы получить инструктивную модель, которая говорит на чеченском естественно и грамотно.

Чеченский — низкоресурсный язык: готового инструктивного корпуса не существует, датасет приходится конструировать из параллельных текстов и словарей.

---

Статус

Пайплайн работает от скачивания данных до оценки. Обученная модель v0.1 не работает — и это установленный факт, а не предположение.

Что	Результат
Обучение	✅ 1 800 итераций, 27 мин, пик памяти 7,1 ГБ, без ошибок
Перплексия на тесте	✅ 159,88 → 23,18 (в 6,9 раза)
Генерация	❌ повторы-циклы, перевод не выполняется
Примеры из обучения	❌ не воспроизводит ни одного

Корневая причина: базовая модель не знает чеченского. Перплексия на одном и том же содержании (выровненный smol_ce):

Язык	ppl
чеченский	41,5
русский	8,3
английский	11,8

Инструктивная настройка предполагает, что язык в модели уже есть. Здесь его не было, и 1 197 пар с LoRA на 7 млн параметров этого не исправят.

Следующий шаг — стадия языковой адаптации (см. «План»). Подробный разбор — в SPEC.md, §11.

---

Требования

• macOS на Apple Silicon (проект собран на MacBook Pro M5, 24 ГБ)
• uv
• Бюджет памяти под MLX — 17,76 ГБ, а не весь объём RAM (остаток macOS держит под себя). Проверить: python3 -c "import mlx.core as mx; print(mx.device_info()['max_recommended_working_set_size']/1024**3)"

---

Быстрый старт

uv sync                                        # окружение: Python 3.13 + mlx-lm

uv run python scripts/download_data.py         # данные NM-development -> data/raw/
uv run python scripts/check_tokens.py          # замер токенизации + проверка chat-шаблона

uv run python scripts/filter_dictionary.py     # пул предложений -> data/pool_nmd.parquet
uv run python scripts/build_dataset.py         # chat-датасет -> data/{train,valid,test}.jsonl

uv run python scripts/build_dataset.py --dry-run   # посмотреть, ничего не записывая

Обучение:

uv run mlx_lm.lora -c configs/lora.yaml

Оценка:

# перплексия
uv run mlx_lm.lora --model mlx-community/Qwen3-4B-4bit \
  --adapter-path ./adapters/mott-v0.1-best --data ./data --test

# сравнение базы и адаптера на одних промптах -> data/review/eval.md
uv run python scripts/evaluate.py

---

Структура

mott/
├── SPEC.md              # ИСТОЧНИК ИСТИНЫ: решения, обоснования, замеры, риски
├── AGENTS.md            # брифинг для ИИ-агента + список реальных грабель
├── configs/
│   ├── lora.yaml        # конфиг обучения (в т.ч. ранг LoRA — см. ниже)
│   └── tasks.yaml       # шаблоны инструкций (чеченские заполняет носитель)
├── data/
│   ├── raw/             # скачанные датасеты (gitignore)
│   ├── pool_nmd.parquet # отфильтрованный пул предложений
│   ├── train.jsonl      # chat-формат для mlx_lm.lora
│   ├── valid.jsonl
│   └── test.jsonl
├── mott/                # пакет в КОРНЕ репозитория
│   ├── sources.py       # классификация источников, выбор редакции
│   └── text.py          # безопасная нормализация текста
├── scripts/             # исполняемые утилиты (см. выше)
└── adapters/            # артефакты LoRA (gitignore)

---

Источники данных

Все проверены через Hugging Face API (подробности — SPEC.md, §3).

Датасет	Строк	Поля	Что это
NM-development/nmd-ce-ru-171k-v0	171 224	ce,ru,source	преимущественно словарь Мациева
NM-development/wmt24pp-ce	998	lp,domain,source,target	новости en→ce
NM-development/smol_ce	825	che_Cyrl,rus_Cyrl,eng_Latn	выровненный трёхъязычный корпус
NM-development/ce_ru_toponyms	344	ce_text,ru_text	топонимы
NM-development/ce_ru_officials	66	ce_text,ru_text	официальные тексты

google/wmt24pp чеченского НЕ содержит — проверены все 55 конфигов, только en-XX_YY. Чеченский материал лежит в NM-development/wmt24pp-ce.

---

План

Стадия	Данные	Формат	Цель
A. Языковая адаптация	сырой чеченский текст (Коран, Библия, словарь, проза, новости)	{"text": "..."}	ppl ce 41,5 → ~12
B. Инструктивная настройка	train.jsonl	{"messages": [...]}	поведение «переведи/ответь»

На стадии A регистр не важен — важен объём чеченского текста. На стадии B — наоборот, качество и регистр решают.

Текущий блокер — объём данных. Идёт расширение корпуса.

---

Полезно знать

Три вещи, которые стоили времени и легко повторяются:

1. Ранг LoRA задаётся только через YAML. В CLI флага нет, но lora_parameters не является argparse-аргументом, поэтому значение из конфига применяется:

lora_parameters:
  rank: 32
  scale: 64.0

Конфиг	Обучаемых параметров
rank 8, num_layers 16 (по умолчанию)	7,34 млн (0,182 %)
rank 32, num_layers 36	66,06 млн (1,642 %)

2. Батч больше 2 роняет обучение по памяти. mlx_lm паддит весь батч до самого длинного примера в нём, поэтому --max-seq-length не защищает — он лишь потолок. Батч 8 дал пик 17,755 ГБ и OOM. Больший батч к тому же не ускоряет обучение.

3. Формат данных. mlx_lm.lora --train читает data/train.jsonl, по одному JSON-объекту на строку:

{"messages": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}

<think> в content писать не нужно — chat-шаблон Qwen3 подставляет пустой блок сам. Полный чек-лист — AGENTS.md, §4.

---

Документация

• SPEC.md — источник истины: решения, замеры, риски, результаты v0.1
• AGENTS.md — брифинг для ИИ-агента, 11 реальных грабель проекта

---

Лицензия

Код — MIT.

Данные в data/ — производные от публичных датасетов NM-development на Hugging Face. Их условия переиспользования не проверялись и могут отличаться от MIT; перед коммерческим использованием стоит свериться с исходными карточками датасетов.