Трудности перевода: почему LLM не умеют писать нормальные докстринги на русском и как это исправить

Каждый, кто пробовал заставить кодинг-LLM написать вменяемый комментарий к коду на русском, знает, какая это боль. Часто модели либо срываются на английский, либо выдают «кальку», либо игнорируют структуру. А всё потому, что они изначально заточены на английский язык. Огрехи встречаются, в частности, в терминологии: модели путают технические заимствования, например «деплой», «коммит», с их буквальным переводом, что делает текст неестественным для разработчика. В структуре тоже не всегда всё гладко: при генерации на русском модели часто «ломают» установленный для Docstring формат (описание, параметры, return, exceptions), из-за чего IDE перестают подхватывать документацию.

Существующие в природе датасеты для обучения кодинг-моделей вроде CodeSearchNet и The Vault либо не содержат русского языка, либо, как MCoNaLa, заточены на поиск, а не на генерацию документации. Именно эту проблему решают ученые из MWS AI: они самостоятельно собрали датасет StRuCom, как раз ориентированный на обучение ИИ генерировать комментарии к коду.

Под катом — история о том, как он был собран.

По-научному работа по сборке датасета описана здесь. Статья была представлена на конференции ACL 2025 в конце прошлого года. Может и вам пригодиться.

Коротко о StRuCom

StRuCom — специализированный датасет для генерации структурированных комментариев к коду на русском языке. 

Ключевые фичи:

• 153 тысячи пар «код — комментарий» на русском языке, 5 языков программирования.

• Только реальные русскоязычные комментарии из репозиториев с качественными синтетически сгенерированными примерами, без машинного перевода.

• Все комментарии прошли валидацию на соответствие стандартам: GoogleDoc для Python, JSDoc для JS и так далее.

В дополнение исследователи разработали инструмент фильтрации и валидации структурированных комментариев в соответствии с пятью стандартами документации: Python — GoogleDoc, Java — Javadoc, Go — GoDoc, C# — XML, JavaScript — JSDoc.

Как собирали датасет: квест с GitHub и LLM

GitHub API не позволяет просто спросить: «Дай мне репозитории, где коммиты на русском». Ученым пришлось выкручиваться.

1. Майнинг и фильтрация

Авторы скачали репозитории с русскоязычными описаниями и открытыми лицензиями. Дальше в дело вступили парсеры: function parser (для Python, Java, Go) и Code-Text (для JS, C#).

Главная боль — мусор. Пришлось вычищать:

• код библиотек (там почти всегда английский);

• автогенерацию;

• дубликаты.

Для определения языка использовали комбинации FastText и Lingua. Оказалось, что Lingua работает точнее, если скармливать ей очищенный текст без меток кода.

2. Валидация структуры

Мало найти русскоязычный текст комментария — нужно, чтобы он был валидный. Именно поэтому пришлось разработать инструмент, который проверяет наличие ключевых полей: описания аргументов, возвращаемых значений и исключений.

Все комментарии были разделены на три группы:

• полные: есть описание всех аргументов и return;

• частичные: что-то есть, но не всё;

• некорректные: формат сломан.

В итоговый датасет попали только полные и корректные частичные комментарии.

Итоговый набор данных после фильтрации:

3. Расширение с помощью LLM (синтетика)

Реальных данных оказалось недостаточно (особенно для JS и Python, где люди часто ленятся писать полные докстринги). Было решено использовать LLM для дописывания.

Для этого взяли модель MIQU-70B (это сильная открытая модель, отлично понимающая русский).

• Сценарий 1 (Augmentation): брали «неполный» комментарий и просили модель дописать недостающие поля (типы, return) без изменения авторского текста.

• Сценарий 2 (Generation): для кода совсем без комментариев генерировали докстринги с нуля.

Интересный факт: Go оказался самым простым для улучшения (эффективность 84%), потому что его стандарт документации минималистичен. А вот с Python и JS модели мучились больше всего из-за требований к указанию типов.

Оценка

Чтобы проверить пользу датасета, ученые провели на нем тонкую настройку семейства моделей Qwen2.5-Coder ( 0.5B, 1.5B, 3B и 7B параметров). 

Результаты сравнивали с базовыми моделями. Использовали две метрики:

1. BERTScore (семантическая близость);

2. chrF++ (символьное совпадение, важно для точного синтаксиса кода).

Дообучение дало статистически значимый прирост качества для всех размеров моделей. Особенно сильно выиграли «малыши» (0.5B и 1.5B параметров). Они начали генерировать комментарии, которые по качеству приближаются к тому, что пишут большие модели.

Для проверки также использовали метод LLM-as-a-judge, сравнивая генерации с эталонными. В 80% случаев автоматическая оценка совпадала с мнением живых экспертов.

Часть датасета доступна на Hugging Face.

Оригинальная статья с описанием методики его сборки на ACL Anthology