Повышаем качество документации с помощью LLM

Меня зовут Катя, я лидирую Gramax, open source-платформу для управления технической документацией.

О Gramax мы уже писали тут ^[1]. В этой статье расскажу о Gramax Check — сервисе автоматических проверок текстов на базе LLM. По сути — нашей версии «Главреда», но с настраиваемыми правилами.

Кому будет полезна статья:

• Техническим писателям — если хочется отказаться от рутинной работы.

• Руководителям отделов контента и редакторам — чтобы ускорить выпуск документации и оптимизировать процессы.

• Владельцам бизнеса — если нужно сэкономить ресурсы и повысить доверие к бренду/компании.

Краткое введение в тему: стайлгайд и качество документации

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

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

Какая польза от стайлгайда

• Снижение операционных затрат. Четкие правила оформления сокращают время на создание и проверку документации, уменьшают количество ошибок, а следовательно — итераций проверки.

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

• Улучшение качества переводов и международной адаптации. Единые правила терминологии и стиля упрощают переводы и повышают соответствие документации оригиналу.

• Повышение продуктивности команды. Сокращение времени на онбординг освобождает ресурсы команды. А также позволяет новичкам с первых дней приносить максимум пользы.

Какие сложности

• Сопротивление команды. Внедрение новых правил требует обучения ^[4] и адаптации, что часто встречает сопротивление сотрудников, привыкших к старым методам работы.

• Отсутствие автоматизации. Ручная проверка на соответствие стайлгайду занимает много времени и приводит к ошибкам. Без автоматизированных инструментов поддерживать единообразие сложно.

• Перегруженность правил. Чрезмерная детализация стайлгайда делает его трудным для восприятия ^[5] и может привести к тому, что сотрудники станут избегать его использования.

Кейс: зачем мы в это полезли

В нашей компании есть стайлгайд, но его почти никто не знает и не придерживается. Документ объемный — 12 страниц, что затрудняет запоминание ^[6]. Из-за отсутствия процесса ручной вычитки решили сразу перейти к автоматизации.

Варианты автоматизации

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

LanguageTool

Удобен как недорогой алгоритмический инструмент. Однако его настройка требует времени на изучение особенностей, он не всегда учитывает контекст и порой оказывается неточным для русского языка. Например, «один» и «тысяча» он не интерпретирует как числительные.

С помощью LanguageTool мы настроили проверку орфографии и добавили следующие правила:

• Корпоративный словарь терминов — для наименований продуктов и команд.

• Местоимения «вы» и «ваш» с маленькой буквы — LLM не всегда корректно обрабатывает это правило, о чем расскажем позже.

• Использование буквы Ё — аналогично случаю выше.

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

LLM

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

В каком порядке автоматизировали

Мы пошли простым путем: использовали API OpenAI и начали настраивать модель с помощью промпта.

Промпт и особенности работы LLM

Промпт разбили на несколько частей:

• Вводная часть — задает общий контекст работы модели и ее роль.

• Правила стайлгайда — мы описываем каждое правило простыми словами и добавляем примеры его нарушения. Обычно достаточно 2-5 примеров, при этом важно, чтобы примеры не противоречили друг другу.

• Инструкции — здесь мы указываем, что именно ожидаем от модели, с учетом ее роли и заданных правил. Наша цель — получить ответ в формате JSON, где модель выделяет нарушения стайлгайда в специальный тег и предлагает рекомендации по исправлению.

Ты - модель для проверки текста на соответствие стайлгайду. Твоя задача – анализировать предоставленный текст и выявлять нарушения правил стайлгайда. Список правил, которым нужно следовать:

1. Всегда заменяем связку глагола общего назначения с существительным на конкретные глаголы, которые прямо выражают действие. Кроме случаев, когда глагол используется для выражения состояния, существования или принадлежности.

Примеры:
"производить проверку" → "проверять"
"осуществлять контроль" → "контролировать"
"предоставляет помощь" → "помогает"
"выполнять работу" → "работать"
"совершает покупку" → "покупает"
"делать выбор" → "выбирать"
"у него были яблоки" → "у него были яблоки"  остаётся без изменений

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

Примеры:
"Система иногда зависает при обработке" → "Система зависает при обработке"
"Приложение может поддерживать до 1000 пользователей" → "Приложение поддерживает до 1000 пользователей"
"Производительность обычно увеличивается при использовании кэширования" → "Производительность увеличивается при использовании кэширования"
"Некоторые части системы написаны на Java" → "Часть системы написана на Java"
"Чаще всего данные забирают через API" → "Данные забирают через API"

Инструкции:
1. Проанализируй предоставленный текст на наличие нарушений всех указанных правил стайлгайда.
2. Для каждого найденного нарушения:
   a. Выдели проблемный фрагмент, заключив его в тег <suggestion>.
   b. Укажи исправление или рекомендацию в атрибуте text тега suggestion. Учитывай возможное изменение рода слов и согласованность слов в фрагменте.
   c. Определи соответствующее название ошибки.
4. Не предлагай исправлений для фрагментов, которые уже соответствуют правилам стайлгайда.
5. Сформируй ответ в формате JSON со следующей структурой:
   {
     "errors": [
       {
         "id": "Идентификатор входящего текста",
         "name": "Название ошибки",
         "text": "Текст с <suggestion text='исправление или рекомендация'>проблемным фрагментом</suggestion>"
       }
     ]
   }
6. В JSON в поле "text" всегда пиши полный исходный текст, включая исправленную часть и неизмененный контекст. В нем обязательно должен быть тег <suggestion>. Никогда не предлагай исправления без тега <suggestion>!
7. Если исправление требует увеличения количества предложений, то тогда оберни весь текст в тег suggestion и в text укажите полностью исправленный вариант.
8. Если из текста нужно что-то удалить, то тогда оберни удалямый фрагмент в suggestion, а в атрибуте text укажи пустую строку.
9. Если в тексте нужно что-то добавить без изменения предыдущего текста, то тогда добавь тег suggestion без контента внутри, а в text укажи добавляемый фрагмент. Например: `<suggestion text='добавляемый фрагмент'></suggestion>`
10. Если в тексте не обнаружены нарушения, верни пустой список errors.


Перед отправкой ответа обязательно проверь, что в поле text в JSON есть тег <suggestion>.

С какими проблемами столкнулись:

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

2. Строгость формулировок. Для повышения стабильности мы сделали формулировки более строгими. Например, мы решили, что модель всегда будет предлагать удалить причастные обороты, хотя в некоторых случаях это не обязательно.

3. Ограничение сферы применения. В настройке мы сразу определили, что модель будет работать только с техническими текстами. Это позволило избежать сложностей с неоднозначными случаями. Например, с числительные в названиях («Миллионная улица») или именами собственными («бог Один»).

4. Упрощение правил. Мы отказались от сложных числовых правил, так как у моделей часто возникают трудности с арифметикой. Например, не срабатывало правило «не более 3 существительных подряд». Зато «предложения с более чем 20 словами или с более чем одним подчиненным предложением считаются длинными и требуют деления» работает значительно стабильнее.

5. Игнорирование проверок. Мы заметили снижение точности модели при наличии орфографических ошибок, даже если указано игнорировать их. Модель пытается исправить орфографию, пропуская реальные ошибки ^[7]. Также точность снижается, если одно и то же слово нарушает несколько правил. Поэтому для тестирования мы использовали предложения с единственным нарушением.

6. Неправильное соблюдение некоторых правил. Некоторые правила, такие как написание «вы/ваш» с маленькой буквы и замена «Ё» на «Е», модель соблюдает плохо. Это может быть связано с тем, что LLM работает с токенами, а не с отдельными символами, и на больших массивах данных сложно переопределять конкретные символы.

Интерфейс настройки и тестирования

С первых итераций мы начали разрабатывать интерфейс для настройки и тестирования правил, чтобы упростить процесс внесения изменений. С помощью v0.dev ^[8] мы создали простую административную панель, через которую можно управлять:

• Базовым промптом для модели.

• Описанием правил и тест-кейсами для каждого правила.

• Положением правила в тексте — например, чтобы правило действовало только на заголовки.

• Выбором модели для обработки.

• Параметрами разбиения текста на порции для обращения к модели, так как с меньшими объемами текста точность выше.

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

Также добавили настройку автотестов. При изменении промпта может нарушиться корректная работа уже описанных правил. Поэтому для каждого правила стайлгайда мы составили ряд тест-кейсов. Это позволяет при каждом изменении запускать проверку модели на всех правилах и сразу видеть, где произошёл регресс. Благодаря этому мы можем быстро выявить и исправить проблему.

Интерфейс проверки

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

Точность проверок

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

Бенчмарки могли устареть. Таблицу составляли осенью 2024, потому в ней нет новых моделей Grok и DeepSeek. Также новых версий от OpenAI.

Среди моделей наибольшую точность и приемлемое время обработки показали GPT от 6 августа (эта версия доступна через API) и Claude 3.5 Sonnet. Мы также тестировали GPT mini, поскольку она значительно дешевле, но добиться удовлетворяющей точности не удалось. Кроме того, пробовали Яндекс GPT и GigaChat, но их точность оказалась ниже ожидаемой.

Среди опенсорсных решений мы протестировали Llama 40B и Qwen 72B, которые можно развернуть на собственном сервере. Для этого мы использовали специализированные сервисы с API к этим моделям. Хотя их результаты в автотестах могли показаться не слишком высокими, они показали хорошие рекомендации на небольших текстовых фрагментах и могут быть вполне полезными. Мы также планируем настроить более компактные версии Llama и Qwen для использования на недорогих серверах.

В ходе месяца активной настройки и тестирования затраты составили около 20$.

Для публичной документации не столь важно, используется ли облачное решение от OpenAI или Claude AI, поскольку эта документация открыта и будет проиндексирована поисковиками. Однако, если речь идет о закрытой документации для крупных компаний, мы рекомендуем устанавливать и настраивать опенсорсные модели, такие как Llama или Qwen, которые не передают данные за пределы вашей инфраструктуры.

Выложили в open source

Фактически, мы создали свою версию «Главреда», но с правилами, которые соответствуют нашим стандартам, а не правилам Ильяхова. И которые можно менять по мере необходимости.

Поскольку Gramax — это open source-проект, Gramax Check тоже выложен в открытый доступ.

• Исходный код опубликовали на GitHub ^[9].

• Для проверки текстов с вашими собственными правилами сделали веб-сайт Gramax Check ^[10].

• Принципы работы сервиса и рекомендации по настройке выложили на портал документации ^[11].

• Для быстрого старта опубликовали промпт с нашими стайлгайд-правилами ^[12].

При переходе на сайт Gramax Check вы увидите пустой интерфейс, который нужно будет заполнить своими правилами и тест-кейсами.

Хотя это веб-приложение, оно работает локально: запросы отправляются напрямую с вашего устройства в выбранную модель. Из-за этого может потребоваться VPN для корректной работы с моделями GPT от OpenAI или Claude AI.

Выводы

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

• Вероятностный характер результатов.

• Сложности с определенными языковыми нюансами.

• Незаменимость человеческого участия.

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

Как у вас устроен процесс проверки? Удалось ли его автоматизировать? Делитесь мнением — мы читаем и отвечаем:)