Искусственный интеллект в документации: как внедрить бота-документоведа

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

Меня зовут Александр Панов, я занимаюсь разработкой документации в Test IT и хочу поделиться опытом имплементации такого бота. Расскажу, зачем он нам нужен, что он должен уметь, как мы его подключили и как он помогает улучшить документацию (а то и продукт). Еще обсудим цены и попробуем разобраться, обязательно ли редактировать промт.

• Зачем документации искусственный интеллект

• Как подружить ИИ-бота с сайтом

• Что должны уметь роботы

• Нужно ли редактировать промт

• Обратная связь: проблемы и решения

• Что дальше?

Зачем документации искусственный интеллект

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

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

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

Как подружить ИИ с сайтом

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

Интегрировать бота с сайтом можно по-разному. Одни компании предлагают встроить его через сторонние сервисы наподобие Jivo — в этом случае вам придется заплатить еще и за сервис, выступающий посредником. Другие готовы интегрировать бота с чем угодно, но для этого нужна дополнительная разработка, а значит снова дополнительные расходы. Такие продукты нам не подошли. Наконец, есть сервисы, которые позволяют встроить чат-бот в большинство сайтов напрямую. Копируешь скрипт с ID бота и вставляешь в проект — как правило на каждую страницу сайта.

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

Наша имплементация включала следующие этапы:

1. Загрузка базы знаний (пока в бесплатной версии, с ограниченным объемом данных)

2. Доработка скрипта для встраивания в сайт

3. Развертывание и тестирование бесплатной версии бота на dev-окружении

4. Оплата выбранного тарифа для полноценного использования

5. Загрузка полной базы знаний

6. Развертывание и тестирование платной версии бота на dev-окружении

7. Развертывание платной версии бота на проде

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

Что должны уметь роботы

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

Какие требования к ИИ-боту мы рассматривали:   

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

• Загрузки базы знаний. Ответ робота должен содержать ссылки на нужные статьи. Значит, лучше скормить базу знаний через URL, список ссылок или карту сайта. Сайтмап можно загрузить за пару кликов, а если он обновляется автоматически, достаточно сделать это один раз. 

Всего же способов передачи базы множество: текстовый документ, CSV-файл, страница Confluence или GitBook, встроенная страница вопросов и ответов вплоть до преобразования YouTube-видео в текст. Правда, некоторые сервисы позволяют загружать только файлы Word или PDF. Возможно, кого-то устроит такой вариант.

• Обновление базы знаний. Если ваш сайт обновляется регулярно, нужно обновлять источники в боте. Если вы «скормили» базу знаний в виде документов, их придется обновить вручную, то есть перезалить новые версии. Для таких источников как URL или страницы Confluence можно настроить автоматическое обновление. Здесь все зависит от поставщика и тарифа: заплатите больше и все источники будут обновляться автоматически каждый день. Заплатите меньше и придется делать это руками.

• Объем базы знаний. Сервисы предлагают различные тарифы, позволяющие загрузить разный объем данных. Например, вы подпишетесь на самый демократичный план, а после обнаружите, что объем вашей базы превышает его лимит. А за более продвинутый план придется выложить в несколько раз больше. Главное: Объем загружаемых данных должен соответствовать вашей базе знаний.

• Количество доступных запросов. Возможны варианты от оплаты по одному запросу до месячного лимита (от 50 до ∞). Понять потенциальное количество запросов поможет аналитика сайта. При ежедневной аудитории в 1000 уникальных пользователей 1000 запросов в месяц может быть недостаточно. Также нужно понимать, что если пользователь напишет в чат «Добрый день!»,  это тоже будет запрос.

• Формат ответов. Бот нужен для технической документации. Значит, его ответы должны быть наглядными и удобными для быстрого просмотрового чтения (scannable). Важно, чтобы робот мог показать клиенту скриншоты, таблицы, понимал различие между описанием процесса и глоссарием, а еще поддерживал нужную разметку (мы используем Markdown). Пока это могут не все сервисы.

• Выбор ИИ-модели. Модели постоянно совершенствуются. Некоторые сервисы в качестве базового предложат вам условный GPT-4o Mini, а за более продвинутые модели возьмут дополнительную плату. Другие не дают выбора и используют одну модель. Есть и те, которые разрабатывают движки сами.

•  Нужна ли для документации более продвинутая модель – вопрос индивидуальный для каждого кейса. Хуже от нее точно не будет.

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

• Дизайн. Это возможность изменять внешний вид чата: загружать его аватар, менять цвета, шрифты и т. д. Наш робот должен соответствовать стилю продукта, стать его частью. Как минимум, это означает возможность покрасить его «шкурку» в брендовые цвета. Можно также добавить описание или логотип продукта. 

 

• Цена. Бот-документовед не приносит прямую прибыль и не участвует в продажах. Точно подсчитать, сколько он сэкономит тоже непросто. Значит, цена не должна быть высокой. На момент написания статьи цена на ИИ-помощников варьировалась от 1,5 тысяч рублей в месяц до 1,5 миллионов за полную разработку с ежемесячной платой в 80–100 тысяч и выше. Притом что задачи выполняются те же и с примерно одинаковым качеством. 

Как правило, российские продукты дороже. Если не хотите разбираться сами, за дополнительную плату вам могут настроить бота под ключ. Сервисы по умеренной цене в России тоже есть, но пока подключить их можно только через платформу-посредника (например, Jivo). Поэтому сегодня готовых ботов с прямой интеграцией в сайт мы смогли найти только у иностранных провайдеров (может, плохо искали).

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

Это были наши основные требования, а есть и другие: «температура» ответов (насколько точно или наоборот, креативно отвечает бот), время между запросами, возможность удалять диалог и не только.  

Нужно ли редактировать промт

Здесь у создателей ИИ-сервисов нет единого мнения. Одни позволяют свободно изменять промт и добавлять дополнительный контекст. Другие говорят: «Редактирование промта — это продвинутая фича! Хотите редактировать промт — подписывайтесь на продвинутый тариф. Или пользуйтесь дефолтным промтом, он универсален и подходит для большинства задач». Третьи вовсе не дают такой возможности. Объясняют, что их промт выверенный и точный, а владелец сайта, не знакомый с тонкостями промт-инжиниринга, только испортит всё дело.

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

Обратная связь: проблемы и решения

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

Часто проблемы в ответах могут указывать на недоработки документации:

• Материал недостаточно структурирован.

• Терминология используется непоследовательно, один и тот же объект называется по-разному. Например, бот легко поймет, что Kubernetes и K8s — одно и то же, но в менее распространенных терминах (таких как «мигратор» или «импортер») может запутаться.   

• Отсутствуют нужные инструкции.

• Заголовки неинформативны или вводят в заблуждение.

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

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

Для человека, особенно разработчика или технического писателя, «живущего» в продукте или на своем сайте, эти проблемы часто не очевидны. К собственному стилю привыкаешь и перестаешь замечать недочеты. Конечно, не стоит бездумно перекраивать документацию, основываясь на ответах бота и реакциях пользователей. Сперва проанализируем эти данные и найдем реальные проблемы, а затем можно править и дополнять документацию или даже менять продуктовые тексты. Например, если они не соответствуют стандартам или бизнес-практике.

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

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

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

Что дальше

Робот-документовед поселился у нас недавно, но уже сейчас мы видим в нем потенциал. Он подсказывает пользователям и разгружает техподдержку — то есть выполняет свои основные задачи. Иногда ошибается, но учится на своих ошибках. И это не все: он указывает нам на проблемы, помогая улучшить документацию и продукт. Мы считаем, он может усовершенствовать подходы к документации и разработке, стать хорошим помощником не только для клиентов, но и для технических писателей, PO и аналитиков. Сбудется ли это? Увидим…