Использование LLM для автоматического формирования документации для базы данных

Качественная документация базы данных – это неотъемлемая часть успешного проекта. Она обеспечивает ряд преимуществ:

• Упрощает и ускоряет внедрение новых разработчиков;
• Упрощает и ускоряет разработку, снижает риск ошибок;
• Минимизирует риски, связанные с изменением состава команды;
• Повышает прозрачность для бизнеса;

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

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

• Простота развёртывания: внедрение инструмента в проект должно производиться с минимальными затратами.
• Интуитивность использования: работа с инструментом должна быть доступна для пользователей любого уровня подготовки.
• Удобство работы с документацией: структура документации должна быть интуитивно понятна и читаема.
• Возможность работы с различными СУБД.

В основе нашего решения лежат большие языковые модели (LLM), которые благодаря своей эффективности позволяют значительно ускорить процесс создания документации. Выбор пал на локальные open-source LLM. Такое решение оправдано поддержанием конфиденциальности данных, вся информация остаётся в архитектуре проекта.

Преимущество LLM перед существующими системами генерации документации в гибкости и полноте.

Существующие системы работают на основе жестких шаблонов и правил, которые требуют ручной доработки при отклонении от заданной структуры. Их результат сводится к шаблонным формулировкам, лишенных содержательных объяснений логики. LLM предоставляют описание с пояснениями и примерами, что повышает ценность документации. К тому же изменение формата документации не требует серьезных доработок. В отличие от устаревших подходов, LLM позволяют сочетать скорость автоматизации с качеством ручной проверки, делая процесс документирования быстрым и более полезным для пользователей.

В процессе разработки мы протестировали несколько LLM различных архитектур и размеров. Выбор моделей производился по следующим критериям:

▶︎ Точность описания: соответствие описания реальной структуре базы данных;
▶︎ Согласованность: соблюдение единого стиля и формата документации;
▶︎ Минимизация галлюцинаций: отсутствие ошибочных или вымышленных данных.

Наилучшее качество показали 2 модели – Qwen2.5 и Mistral:

Для генерации документации мы используем SQL-скрипты создания основных объектов базы данных. Скрипт для таблицы дополняется случайной выборкой из 10 строк данных. Однако в этих данных недостаточно информации для понимания моделью требуемой задачи. Поэтому в скрипт добавляется контекст для модели. Он помогает добиться получения от LLM желаемых результатов и определяет:

• Формат входных данных;
• Вид объекта во входных данных;
• Задачу модели и конкретизацию требований;
• Ожидаемую структуру и пример результата;
• Язык и стиль результата.

Благодаря контексту модель не отклоняется в общие рассуждения о синтаксисе SQL, фокусируется на ключевых блоках скриптов и формирует структурированный ответ.
Сформированный текст можно легко представить в любой другой удобный формат: json, HTML, Markdown, PDF.

На рисунке ниже представлена схема работы формирования документации:

Разработанный инструмент доказал свою эффективность в нескольких проектах. Ключевым преимуществом стала легкость внедрения: развертывание инструмента не превышает 4-х часов. Помимо этого, он демонстрирует высокую производительность: его использование позволяет сократить время на создание документации в 20 и более раз по сравнению с ручным подходом. База данных, содержащая 1000 объектов, была документирована за 4 часа, при этом уровень ошибок составил менее 5%.

Инструмент наиболее эффективен на больших объемах данных – на базах, содержащих сотни и тысячи объектов. Ручная обработка потребовала бы нескольких недель, тогда как LLM справляются за часы. Время работы увеличивается равномерно с ростом структуры базы данных, без неожиданных скачков. Инструмент приобретает особую ценность в условиях частых изменений объектов в базе, поскольку автоматически актуализирует документацию.