ИССЛЕДОВАНИЕ ЭФФЕКТИВНОСТИ ПРИМЕНЕНИЯ ЛОКАЛЬНЫХ ЯЗЫКОВЫХ МОДЕЛЕЙ ДЛЯ ГЕНЕРАЦИИ И СОПРОВОЖДЕНИЯ ДОКУМЕНТАЦИИ ПРОГРАММНОГО КОДА

АННОТАЦИЯ

В статье рассматривается применение локальных языковых моделей для автоматической генерации и сопровождения документации программного кода. Проведён сравнительный анализ моделей Qwen3-1.7B и DeepSeek-Coder-1.3B на задаче формирования комментариев к функциям на языке Swift. Практическая значимость работы заключается в демонстрации эффективности локальных языковых моделей для генерации актуальной и содержательной документации без использования облачных сервисов.

Ключевые слова: генерация документации, нейронные сети, трансформеры, автоматизация программирования, генерация кода.

1. Введение:

Документация играет важную роль в процессе разработки и сопровождения программного кода, обеспечивая передачу знаний и облегчая поддержку программных систем. Однако её создание и актуализация требуют значительных трудозатрат, что часто приводит к устареванию или неполному описанию функций.

Современные языковые модели (LLM), обученные на больших корпусах программного кода и текстов, способны автоматически генерировать осмысленные комментарии, интерпретируя поведение и назначение кода. Использование таких моделей локально, без обращения к облачным сервисам, позволяет повысить безопасность и сохранить приватность данных.

В данной работе проводится экспериментальное исследование эффективности применения локальных языковых моделей для автоматизированной генерации и сопровождения документации кода. Анализируются возможности моделей Qwen3-1.7B и DeepSeek-Coder-1.3B с учётом необходимости их дообучения для достижения практического качества генерации.

2. Процесс документирования программного кода и роль локальных языковых моделей:

Документация к исходному коду играет ключевую роль в успешной разработке и сопровождении программных систем. Она служит основным средством передачи знаний в команде и существенно облегчает поддержку проекта на протяжении всего жизненного цикла [1].

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

Языковые модели способны существенно облегчить первый и третий этапы документирования – создание описаний и их актуализацию, фактически исключая их. Благодаря обучению на огромных корпусах кода и текстов, LLM могут автоматически сгенерировать осмысленные комментарии к функциям, классам или модулям, описывая их поведение и предназначение [2]. Благодаря тому, что модели могут генерировать описание динамически и быстро, фактически отпадает необходимость написания и поддержки документации в коде, так как можно просто выполнить запрос к модели и получить нужное описание. Тем не менее, использование облачных моделей (ChatGPT, Grok, DeepSeek) сопряжено с рядом ограничений, таких как проблема конфиденциальности данных, а также отсутствие возможности работать без доступа в интернет.

Таким образом, интеграция LLM в процесс документирования кода может снизить трудозатраты на написание и поддержку комментариев.

3. Выбор моделей и критериев оценки:

Для экспериментов были отобраны две большие языковые модели среднего размера: Qwen3-1.7B и DeepSeek-Coder-1.3B-base. Выбор обусловлен несколькими соображениями. Во-первых, обе модели являются открытыми и доступны для локального развёртывания без лицензионных ограничений. Во-вторых, их объем достаточно велик, чтобы обеспечивать разумное качество генерации текста, но при этом достаточно мал чтобы использовать модель локально и дообучать ее. В-третьих, модели различаются по специализации, что позволяет провести сравнительный анализ. Qwen3-1.7B представляет собой универсальную трансформерную LLM третьего поколения из серии Qwen. Эта модель ориентирована на многоязычные задачи и обладает режимами работы, повышающими эффективность на логических и кодовых задачах. Напротив, DeepSeek-Coder-1.3B – это специализированная модель для программного кода, обученная «с нуля» на массивном датасете объемом порядка 2 триллионов токенов, из которых ~87% составляют исходные коды на различных языках. Такая тренировка на преимущественно кодовом корпусе позволила DeepSeek-Coder накопить знания шаблонов программирования и структур документации, полезные для генерации комментариев. Оба выбранных LLM относительно компактны по современным меркам, что снижает барьер по вычислительным ресурсам для их адаптации и внедрения в промышленный процесс разработки.

Для оценки качества работы моделей оценивалось с помощью автоматизированных метрик сравнения с эталонной документацией. Использованы метрики BLEU (Bilingual Evaluation Understudy) и ROUGE-L (Recall-Oriented Understudy for Gisting Evaluation, вариант по наибольшей общей подпоследовательности). Метрика BLEU изначально применялась для оценки машинного перевода, она измеряет точность совпадения n-граммов с эталоном и отражает степень лексического сходства генерированного описания с образцовым. В контексте документирования кода высокий BLEU указывает, что модель воспроизвела многие ключевые фразы и терминологию, присутствующие в референсном комментарии. Метрика ROUGE-L широко используется в задачах резюмирования текста, она фокусируется на доле совпадающей длинной последовательности токенов и, по сути, измеряет полноту передачи содержания относительно эталона. Высокое значение ROUGE-L означает, что модель сумела охватить основные факты и идеи, представленные в человеческом описании. Такой набор критериев позволяет объективно сравнить модели до и после дообучения, а также между разными методами обучения.

4. Методика анализа эффективности языковых моделей:

Для оценки эффективности применения локальных языковых моделей была проведена серия контролируемых экспериментов. Сначала определены базовые показатели: модели Qwen3-1.7B и DeepSeek-Coder-1.3B были протестированы без дополнительного обучения на специально подготовленном тестовом наборе функций. Каждому входному фрагменту кода подавался соответствующий промпт, стимулирующий генерацию документации – например, модель получала описание задачи: «Сгенерируй комментарий, поясняющий работу следующей функции» и затем исходный код функции. Выходные тексты сравнивались с референсными комментариями, и вычислялись значения BLEU и ROUGE-L для фиксации исходного качества моделей.

Датасеты для экспериментов сформированы на языке Swift. Выбор языка обусловлен наличием стилизованного формата документационных комментариев (Swift DocComment) и доступностью открытых репозиториев на Swift. Тестовое множество включило более 100 независимых функций различной тематики и сложности.

Для того чтобы раскрыть полный потенциал моделей была проведена дополнительная серия экспериментов. Выбранные модели были предварительно обучены методом параметро-эффективного дообучения QLoRA. QLoRA (Quantized LoRA) – параметро-эффективный метод, сочетающий низкоразрядное квантование модели и обучение компактных добавочных слоёв на основе Low-Rank Adaptation [3]. В рамках QLoRA исходные веса модели фиксируются, представляются в сжатом виде, а небольшое число дополнительных параметров обучается для корректировки выходов модели. После дообучения модель была заново протестирована на тестовом наборе функций.

5. Анализ результатов экспериментов:

Тестирование исходных  версий моделей подтвердило ожидаемую разницу в их возможностях [4, 5]. Модель Qwen3-1.7B сразу продемонстрировала более высокое качество генерации документации, чем DeepSeek-Coder-1.3B: BLEU составил ~0.41 против ~0.30 у DeepSeek, а показатель ROUGE-L – около 0.50 против ~0.40 соответственно. Это означает, что без дополнительной настройки Qwen лучше подстраивается под содержимое функций и стиль комментариев. Кроме того, сгенерированные Qwen описания оказались ближе по объему к образцам, длина вывода примерно в 1.65 раза больше референса, тогда как DeepSeek-Coder склонна к «многословию», так как генерировала комментарии более чем в 2.2 раза длиннее эталонных. Тем не менее, в абсолютном выражении исходное качество обеих моделей было недостаточным для практического применения: значения BLEU < 0.5 указывают на большое количество расхождений с эталоном, а низкий ROUGE-L свидетельствует об упущении существенной части информации. Например, DeepSeek-Coder зачастую воспроизводила лишь фрагменты описания и добавляла лишние общие фразы, не отражающие специфики функции.

Параметро-эффективное дообучение через QLoRA принесло сильные улучшения. Для модели Qwen BLEU вырос с 0.414 до ~0.784, то есть на 89% относительно исходного уровня. Аналогично, ROUGE-L для Qwen (QLoRA) приблизился к 0.95. Интересно, что для модели DeepSeek-Coder метод QLoRA оказался весьма эффективен: BLEU повысился до ~0.786. Метрики полноты у DeepSeek-Coder также значительно улучшились. Происходит редкий случай, когда обучение небольшого числа дополнительных параметров даёт столь высокий результат — вероятно, за счёт сохранения обобщающих свойств предобученных представлений. В итоге, обе модели при QLoRA-донастройке достигли высоких абсолютных показателей качества: BLEU ~0.78–0.79 и ROUGE-L ~0.85–0.95, что указывает на почти человеческий уровень соответствия между генерируемой и реальной документацией. Кроме того, структурно комментарии стали аккуратнее: модели избегают избыточных пояснений и ближе придерживаются фактов, упомянутых в коде, обеспечивая точное соответствие длины и содержания референсам. Важно отметить, что для дообучения понадобилось примерно ~4 ГБ VRAM, что указывает на, то, что модели можно дообучать локально на домашних видеокартах.

Важно, также отметить, что среднее время ответа модели 20 секунд при применении видеокарты Nvidia GTX 1660 TI.

Результаты проведённых экспериментов ясно показывают, что исходный выбор модели существенно влияет на начальное качество генерации документации. Более крупная и универсальная модель (Qwen3-1.7B) демонстрирует значительно лучшие показатели на этапе без дополнительного обучения по сравнению с более специализированной, но меньшей моделью DeepSeek-Coder-1.3B. Это подтверждает, что архитектурные различия, объём предобученных данных и стратегии обучения играют ключевую роль в способности модели обобщать информацию и адаптироваться к стилистическим требованиям документации.

Однако в исходной форме ни одна из протестированных моделей не обеспечивает достаточного качества для практического использования в задаче генерации сопровождающей документации к коду. Низкие значения BLEU и ROUGE-L указывают на существенные расхождения между генерируемыми и эталонными комментариями, а также на неспособность моделей полноценно учитывать специфику и смысловую структуру кода без дополнительной настройки.

Дополнительное дообучение с использованием кардинально меняет ситуацию. После дообучения обе модели демонстрируют качественный скачок по всем метрикам, достигая уровня, близкого к человеческому. Структура и содержание сгенерированных комментариев становятся более релевантными и сдержанными, что делает модели практически пригодными для автоматизированного сопровождения программного кода.

Таким образом, можно сделать следующие практические выводы:

1. Выбор базовой модели важен — более крупные и универсальные модели изначально обладают лучшим потенциалом генерации.
2. Базовые модели, которые можно запускать локально (до 2B параметров) не подходят для прямого применения в задаче генерации документации без дообучения.
3. Дообучение позволяет добиться высокого качества генерации при умеренных вычислительных затратах, что делает возможным локальное обучение и использование моделей на обычных пользовательских видеокартах.

В результате, для эффективного локального применения языковых моделей в задаче генерации и сопровождения документации к коду необходимо предусматривать этап специализированного дообучения под целевой язык программирования и стиль документации.

6. Заключение:

Проведённое исследование показало, что локальные языковые модели имеют высокий потенциал для автоматизированной генерации и сопровождения документации программного кода. Однако без специализированного дообучения их качество недостаточно для практического использования. Применение параметро-эффективного метода QLoRA позволяет значительно повысить точность и полноту генерации, приближая результат к уровню ручной документации.

Выбор базовой модели существенно влияет на исходные результаты: универсальная Qwen3-1.7B демонстрирует лучшие показатели по сравнению с DeepSeek-Coder-1.3B. После дообучения обе модели достигают высокого качества генерации (BLEU ~0.78–0.79, ROUGE-L ~0.85–0.95), при этом остаются пригодными для локального применения на пользовательских видеокартах (~4 ГБ VRAM, время генерации около 20 секунд).

Таким образом, эффективное использование локальных языковых моделей для генерации документации требует обязательного этапа дообучения под целевой язык и стандарты оформления. Перспективными направлениями являются оптимизация методов обучения, а также расширение применения на разные языки программирования и промышленные сценарии.

Список литературы:

1. RepoAgent: An LLM-Powered Open-Source Framework for Repository-level Code Documentation Generation. [Электронный ресурс] // Arxiv. URL: https://arxiv.org/html/2402.16667v1#bib.bib26 (дата обращения: 12.05.2025).
2. Katzy J., Huang Y., Panchu G.-R., Ziemlewski M., Loizides P., Vermeulen S., Deursen A. van, Izadi M. A Qualitative Investigation into LLM-Generated Multilingual Code Comments and Automatic Evaluation Metrics / arXiv:2505.15469 [cs]. — arXiv, 2025 (дата обращения: 03.06.2025).
3. Dettmers T., Pagnoni A., Holtzman A., Zettlemoyer L. QLoRA: Efficient Finetuning of Quantized LLMs. [Электронный ресурс] // Arxiv. URL: https://arxiv.org/abs/2305.14314v1 (дата обращения: 16.05.2025).
4. DeepseekCoder-1.3b-base Метрики [Электронный ресурс] // GitHub. URL: https://github.com/nschpy/shinkai/tree/main/metrics/deepseek-ai (дата обращения: 02.06.2025).
5. Qwen3-1.7B Метрики [Электронный ресурс] // GitHub. URL: https://github.com/nschpy/shinkai/tree/main/metrics/Qwen (дата обращения: 01.06.2025).