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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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. Игнорирование проверок. Мы заметили снижение точности модели при наличии орфографических ошибок, даже если указано игнорировать их. Модель пытается исправить орфографию, пропуская реальные ошибки. Также точность снижается, если одно и то же слово нарушает несколько правил. Поэтому для тестирования мы использовали предложения с единственным нарушением.

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

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

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

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

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

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

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

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

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

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

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

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

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

На основе наших автотестов мы также составили бенчмарк точности моделей. Мы начинали с настройки проверок на 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.

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

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

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

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

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

Выводы

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

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

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

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

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

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