Искусственный интеллект в документации: как внедрить бота-документоведа
На продуктовых сайтах AI-боты обитают часто: оказывают техподдержку, помогают выбрать продукт, собирают лиды и многое другое, но на сайтах с документацией они встречаются реже. Правда, сейчас картина меняется: роботы помогают людям найти нужные материалы. В некоторых компаниях они уже пришли на смену поисковым плагинам.
Меня зовут Александр Панов, я занимаюсь разработкой документации в Test IT и хочу поделиться опытом имплементации такого бота. Расскажу, зачем он нам нужен, что он должен уметь, как мы его подключили и как он помогает улучшить документацию (а то и продукт). Еще обсудим цены и попробуем разобраться, обязательно ли редактировать промт.
Зачем документации искусственный интеллект
Идея запустить на сайт робота-документоведа возникла так: наша система управления тестированием развивалась, ее функциональность расширялась, а следом разрослась и документация — обычного поиска по заголовкам уже не хватало. Конечно, заголовок в техдоке должен быть информативным, но весь контент он охватить не может, да и пользователи не всегда точно знают, что нужно искать.
Мы изучили около десятка сервисов, предлагающих умных ботов для документации. К делу подошли практически: настраивали и тестировали бесплатные версии, брали пробные периоды, ходили на демо и задавали вопросы. Заодно поняли, что пока не готовы разрабатывать бота сами и что нам подходят далеко не все продукты.
Когда внедрили ИИ-помощника, функцию поиска отключать не стали и не планируем в дальнейшем — пусть поисковый плагин и бот дополняют друг друга. Наш робот пока учится. Как это происходит, расскажем в конце.
Интерфейс AI-бота
Как подружить ИИ с сайтом
Самое очевидное решение — чат-бот с искусственным интеллектом. Это удобно: запрос может быть в свободной форме, можно писать с ошибками или на другом языке — нынешние роботы к этому приучены.
Интегрировать бота с сайтом можно по-разному. Одни компании предлагают встроить его через сторонние сервисы наподобие Jivo — в этом случае вам придется заплатить еще и за сервис, выступающий посредником. Другие готовы интегрировать бота с чем угодно, но для этого нужна дополнительная разработка, а значит снова дополнительные расходы. Такие продукты нам не подошли. Наконец, есть сервисы, которые позволяют встроить чат-бот в большинство сайтов напрямую. Копируешь скрипт с ID бота и вставляешь в проект — как правило на каждую страницу сайта.
Правда, дефолтный скрипт, подготовленный разработчиками, может не сработать на вашем сайте, в нашем случае так и оказалось. На помощь пришла фронтенд-команда. Ребята допилили и усовершенствовали скрипт, чтобы не нужно было вставлять его на каждую страницу. В экстренном случае бота можно отключить, убрав всего одну строку из конфигурационного файла.
Наша имплементация включала следующие этапы:
Загрузка базы знаний (пока в бесплатной версии, с ограниченным объемом данных)
Доработка скрипта для встраивания в сайт
Развертывание и тестирование бесплатной версии бота на dev-окружении
Оплата выбранного тарифа для полноценного использования
Загрузка полной базы знаний
Развертывание и тестирование платной версии бота на dev-окружении
Развертывание платной версии бота на проде
Развернули на прод в октябре 2024 года. Сейчас наш бот находится в тестовом режиме, мы решили понаблюдать за ним три месяца и посмотреть, что из этого выйдет.
Что должны уметь роботы
Нам пока не нужны ветвистые сценарии со сбором лидов, выбором продукта, записью на демо или формой связи с техподдержкой. Хотя идея сценариев для бота-документоведа интересна, их можно разработать для разных процессов, категорий пользователей и версий продукта. Но сейчас от робота требуется только дать пользователю ответ по работе с системой, найти ссылки на нужные статьи и при этом не заблудиться в паре сотен страниц.Каким критериям он должен отвечать, чтобы выполнять эти задачи?
Какие требования к ИИ-боту мы рассматривали:
Интеграция с сайтом. Каким бы разумным ни был робот, если его нельзя встроить в сайт, он бесполезен. Поэтому сначала убедитесь, что бота можно подружить с вашим сайтом. Если дефолтные скрипты не подходят, можно попробовать их доработать.
Загрузки базы знаний. Ответ робота должен содержать ссылки на нужные статьи. Значит, лучше скормить базу знаний через URL, список ссылок или карту сайта. Сайтмап можно загрузить за пару кликов, а если он обновляется автоматически, достаточно сделать это один раз.
Всего же способов передачи базы множество: текстовый документ, CSV-файл, страница Confluence или GitBook, встроенная страница вопросов и ответов вплоть до преобразования YouTube-видео в текст. Правда, некоторые сервисы позволяют загружать только файлы Word или PDF. Возможно, кого-то устроит такой вариант.
Обновление базы знаний. Если ваш сайт обновляется регулярно, нужно обновлять источники в боте. Если вы «скормили» базу знаний в виде документов, их придется обновить вручную, то есть перезалить новые версии. Для таких источников как URL или страницы Confluence можно настроить автоматическое обновление. Здесь все зависит от поставщика и тарифа: заплатите больше и все источники будут обновляться автоматически каждый день. Заплатите меньше и придется делать это руками.
Объем базы знаний. Сервисы предлагают различные тарифы, позволяющие загрузить разный объем данных. Например, вы подпишетесь на самый демократичный план, а после обнаружите, что объем вашей базы превышает его лимит. А за более продвинутый план придется выложить в несколько раз больше. Главное: Объем загружаемых данных должен соответствовать вашей базе знаний.
Количество доступных запросов. Возможны варианты от оплаты по одному запросу до месячного лимита (от 50 до ∞). Понять потенциальное количество запросов поможет аналитика сайта. При ежедневной аудитории в 1000 уникальных пользователей 1000 запросов в месяц может быть недостаточно. Также нужно понимать, что если пользователь напишет в чат «Добрый день!», это тоже будет запрос.
Формат ответов. Бот нужен для технической документации. Значит, его ответы должны быть наглядными и удобными для быстрого просмотрового чтения (scannable). Важно, чтобы робот мог показать клиенту скриншоты, таблицы, понимал различие между описанием процесса и глоссарием, а еще поддерживал нужную разметку (мы используем Markdown). Пока это могут не все сервисы.
Выбор ИИ-модели. Модели постоянно совершенствуются. Некоторые сервисы в качестве базового предложат вам условный GPT-4o Mini, а за более продвинутые модели возьмут дополнительную плату. Другие не дают выбора и используют одну модель. Есть и те, которые разрабатывают движки сами.
Выбор движка для AI-бота
Нужна ли для документации более продвинутая модель — вопрос индивидуальный для каждого кейса. Хуже от нее точно не будет.
Аналитика. Важно знать, что спрашивают пользователи и какие получают ответы. Для этого нужен дашборд с аналитикой, он позволит улучшить документацию и настроить бота так, чтобы он давал точную информацию. Доступность и объем аналитики также зависят от тарифов. Есть сервисы, которые при оплате самого недорогого тарифа показывают только четыре последних запроса.
Дашборд сервиса AI-бота
Дизайн. Это возможность изменять внешний вид чата: загружать его аватар, менять цвета, шрифты и т. д. Наш робот должен соответствовать стилю продукта, стать его частью. Как минимум, это означает возможность покрасить его «шкурку» в брендовые цвета. Можно также добавить описание или логотип продукта.
Дизайн AI-бота
Цена. Бот-документовед не приносит прямую прибыль и не участвует в продажах. Точно подсчитать, сколько он сэкономит тоже непросто. Значит, цена не должна быть высокой. На момент написания статьи цена на ИИ-помощников варьировалась от 1,5 тысяч рублей в месяц до 1,5 миллионов за полную разработку с ежемесячной платой в 80–100 тысяч и выше. Притом что задачи выполняются те же и с примерно одинаковым качеством.
Как правило, российские продукты дороже. Если не хотите разбираться сами, за дополнительную плату вам могут настроить бота под ключ. Сервисы по умеренной цене в России тоже есть, но пока подключить их можно только через платформу-посредника (например, Jivo). Поэтому сегодня готовых ботов с прямой интеграцией в сайт мы смогли найти только у иностранных провайдеров (может, плохо искали).
Выбирайте тариф для своих возможностей. Часто поставщики предлагают несколько тарифных планов с разной функциональностью. Различаются объем базы знаний, используемая модель, количество ботов и запросов, аналитика и многое другое. Хотя бывает, цену не оглашают и оффер готовят индивидуально под ваши нужды. В нашем случае такие офферы всегда существенно превышали бюджет. Кстати, некоторые компании предложат бота бесплатно и бессрочно, но его функциональность будет минимальна. Например, несколько тысяч символов базы знаний и 50 запросов в месяц — для коммерческого продукта этого мало.
Это были наши основные требования, а есть и другие: «температура» ответов (насколько точно или наоборот, креативно отвечает бот), время между запросами, возможность удалять диалог и не только.
Нужно ли редактировать промт
Здесь у создателей ИИ-сервисов нет единого мнения. Одни позволяют свободно изменять промт и добавлять дополнительный контекст. Другие говорят: «Редактирование промта — это продвинутая фича! Хотите редактировать промт — подписывайтесь на продвинутый тариф. Или пользуйтесь дефолтным промтом, он универсален и подходит для большинства задач». Третьи вовсе не дают такой возможности. Объясняют, что их промт выверенный и точный, а владелец сайта, не знакомый с тонкостями промт-инжиниринга, только испортит всё дело.
Настройка промта
Сейчас мы работаем с дефолтным промтом: робот находит ответы и ссылки в документации, не болтает на посторонние темы и ничего не выдумывает. Хотя поэкспериментировать с разными сервисами и запросами было занятно, а порой и весело. А попытки настроить промт под свой уникальный продукт или сайт могут дать интересные результаты.
AI-бот: каков запрос, таков ответ
Обратная связь: проблемы и решения
Итак, тариф выбран, база знаний загружена, бот встроен на сайт и развернут на прод-окружении. Клиенты спрашивают, и чаще всего робот отвечает толково. Но все же изредка пользователи уходят недовольные и оставляют дизлайки: на простые вопросы ИИ-консультант извиняется и просит переформулировать, а то и вовсе отвечает невпопад. Если это происходит систематически, дело может быть в боте, тогда от него придется отказаться. Или все-таки нет?
Часто проблемы в ответах могут указывать на недоработки документации:
Материал недостаточно структурирован.
Терминология используется непоследовательно, один и тот же объект называется по-разному. Например, бот легко поймет, что Kubernetes и K8s — одно и то же, но в менее распространенных терминах (таких как «мигратор» или «импортер») может запутаться.
Отсутствуют нужные инструкции.
Заголовки неинформативны или вводят в заблуждение.
Язык документации не соответствует языку, на котором говорят пользователи.
Бот помогает нам найти эти недостатки и показать, какие трудности испытывают пользователи с документацией. Например, в нашей системе ручные тесты, чек-листы и общие шаги были объединены в условную группу «Рабочие элементы». Пользователь, который хочет создать тест-кейс, не будет искать по фразе «Рабочий элемент» — он с этой терминологией не знаком. Поэтому поиск спотыкался на самых первых, простых задачах. В результате мы попытались сделать нашу терминологию более стандартной и интуитивной.
Для человека, особенно разработчика или технического писателя, «живущего» в продукте или на своем сайте, эти проблемы часто не очевидны. К собственному стилю привыкаешь и перестаешь замечать недочеты. Конечно, не стоит бездумно перекраивать документацию, основываясь на ответах бота и реакциях пользователей. Сперва проанализируем эти данные и найдем реальные проблемы, а затем можно править и дополнять документацию или даже менять продуктовые тексты. Например, если они не соответствуют стандартам или бизнес-практике.
Также вопросы пользователей помогают понять, что их интересует: что можно потенциально улучшить на сайте и что в продукте вызывает наибольшие трудности.
Не на каждый вопрос нужна отдельная статья. Для таких случаев мы создали и поддерживаем страницу «Часто задаваемые вопросы». Кстати, такие вопросы можно настроить и в самом боте, или выбрать самые актуальные и поместить в начало диалога. В нашем случае сервис создает эти вопросы автоматически, но можно сделать это вручную.
Часто задаваемые вопросы
Дефолтный промт мы не меняем, наш робот обучается на документации и дополнительных материалах. Например, можно подготовить и загрузить документ со списком необходимых ссылок и их описанием. Выглядеть он может произвольно — главное, чтобы ИИ понимал, о чем идет речь. Так бот сможет вернее направлять пользователей на нужные статьи.
Что дальше
Робот-документовед поселился у нас недавно, но уже сейчас мы видим в нем потенциал. Он подсказывает пользователям и разгружает техподдержку — то есть выполняет свои основные задачи. Иногда ошибается, но учится на своих ошибках. И это не все: он указывает нам на проблемы, помогая улучшить документацию и продукт. Мы считаем, он может усовершенствовать подходы к документации и разработке, стать хорошим помощником не только для клиентов, но и для технических писателей, PO и аналитиков. Сбудется ли это? Увидим…
