Как мы создали ИИ-агент для дизайн-системы

Всем привет! Меня зовут Юля Федорова, я UX-редактор команды дизайн-системы FinAI в Сбере. Наша дизайн-система (далее по тексту ДС) — это набор компонентов и паттернов, из которых разные продуктовые команды собирают сервисы финансовой платформы в едином визуальном стиле.

За несколько лет у ДС выросла масштабная документация. И чем больше она становилась, тем очевиднее была проблема: знанием стало тяжело пользоваться. В этой статье я пошагово расскажу, как мы с командой сделали ИИ-агент, который помогает дизайнерам и продуктовым командам соблюдать требования ДС, что уже получилось и над чем ещё нужно поработать. Кода в статье не будет, речь пойдёт именно про процесс создания агента.  

Всё началось с редполитики

Идея ИИ-помощника появилась, когда мы дописали редакционную политику. Сервисы платформы делают разные команды, поэтому единое руководство по текстам было необходимо, чтобы весь продукт говорил в одном Tone of Voice. Получилась объёмная документация из восьми разделов с подразделами, которая живёт в Confluence.

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

Мы прикинули, сколько времени уходит на чтение и поиск по документации, и поняли: даже помощник, который просто суммаризирует раздел и отвечает на точечный вопрос, заметно сэкономит время на ежедневных «а как правильно?» и дизайнерам, и редактору. Так идея превратилась в задачу.

Универсальный помощник ДС

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

Перед началом работы мы задались вопросами: 

• Кто из коллег уже делал что-то похожее — можно ли переиспользовать?

• Что из инфраструктуры и ресурсов нам понадобится?

• Где агент будет жить?

• Как быстро собрать всю документацию в пригодный для обучения вид?

• Как вообще «обучить» агент требованиям ДС?

Чтобы ответить на них, провели исследование: изучили существующие агенты в банке, поговорили с соседними командами и другими дизайн-системами, сходили за консультацией в профильные сообщества.

Готовое решение мы искали в первую очередь. Разработка ИИ-агентов — не основная деятельность команды дизайн-системы, и наши базовые задачи никуда не делись. Поэтому идеальным вариантом было бы взять чей-то готовый инструмент и адаптировать под наши потребности. Но ничего подходящего «из коробки» не нашлось: близкие по духу решения были заточены под другие задачи и данные. Так мы поняли, что весь путь создания агента нам придётся пройти самим — и это оказалось чуть сложнее, чем мы думали.

Подготовка документации — базы знаний ИИ-агента

Ещё на этапе исследования стало ясно: главная работа — не в коде агента, а в подготовке базы знаний. И по одному только количеству документации ДС было понятно, что на этом этапе мы надолго.

Чем предстояло наполнить базу знаний агента:

• больше 50 файлов по атомарным компонентам (кнопки, поля ввода и так далее);

• 25 файлов по таблице — это отдельный шаблонный компонент на Canvas-основе, который любой продукт платформы может использовать у себя;

• больше 20 файлов по другим шаблонным компонентам (левая панель, виджет, модальное окно и др.);

• больше 20 дизайнерских руководств по этим компонентам;

• 8 разделов редполитики. 

С каждым документом нужно было пройти такой путь: выгрузка → проверка актуальности в дизайне и коде → перевод в формат MD → повторная проверка → передача агенту. Также необходимо было сразу продумать, как мы будем обновлять базу знаний агента по мере развития ДС, — иначе агент устареет через месяц.

Отдельная сложность была в том, что документация живёт в двух разных местах и форматах:

• Редполитику легко выгрузить из Confluence в формате docx.

• Документация по компонентам — это целая файловая система в Pixso (аналог Figma), вытащить из неё документы оказалось сложнее. 

Сначала мы выгружали файлы из Pixso только в PDF — казалось, этого достаточно. Но довольно быстро стали вылезать ошибки: часть чисел считывалась неверно, например, размеры. Чтобы это компенсировать, мы начали дополнительно выгружать sketch — в нём как раз лежала недостающая информация. В итоге PDF-файл обеспечивал структуру документации — заголовки, подписи к картинкам, таблицы состояний и прочее, — а sketch помогал полностью сохранить наполнение файла без необходимости перепечатывать что-то вручную. 

Переводом документации в MD дизайнеры нашей команды занимались вдвоём. Но у них был помощник — GigaCode, который сейчас является одним из основных ИИ-ассистентов разработчика в Сбере. После выгрузки из Pixso каждый файл мы отдавали GigaCode, чтобы он перевёл его в MD. Это ускорило работу над документацией в 3-4 раза по сравнению с ручным переводом.

Каждый файл в MD проходил через нашу проверку: мы вычитывали документ целиком и сверяли его с дизайном и кодом. Обнаружили, что часть документации расходилась с тем, что уже было реализовано, и это мы дорабатывали отдельно: выписывали списком в три пункта: что в дизайне, что в коде, что предлагаем. Далее с помощью скрипта собирали из MD docx-файл, дизайнер проверял в привычном редакторе Word, а другой скрипт вытягивал комментарии вместе с текстом, к которому они привязаны, и правки применялись к MD. Конечно, можно было попросить дизайнеров проверять пул-реквесты, но это было бы красивее на словах и медленнее на практике.

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

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

И раз уж мы всё равно проходили руками по каждому документу, то собрали единую шапку с метаданными и подготовили FAQ-раздел, который очень помог при обучении ИИ-агента: типовые вопросы с эталонными ответами дают ему опору и заметно повышают качество на частых запросах. Вот ещё несколько приёмов, которые помогли нам сделать ответы агента более качественными уже в первой версии:

• У любого компонента два парных документа — для дизайнеров и разработчиков, с одинаковой шапкой. Тело документа для разработчиков мы не переписывали вообще. 

• FAQ всегда разделён на «для дизайнеров» и «для разработчиков», и код-имена свойств не попадают в дизайнерский раздел — иначе агент начинает отвечать дизайнеру свойствами. 

• Мы заранее прописали, что агент должен делать, когда в документации нет ответа на вопрос. Вместо тупиковых «не подтверждено» или «в коде отсутствует» ИИ-агент направляет пользователя к живому источнику — в Storybook, руководства в Pixso или чат поддержки ДС. Это важно ещё и потому, что информацию могли обновить в исходниках, а агент её пока не подтянул. 

Где живёт агент и что у него под капотом

В Сбере агенты размещают в ИИ-хабах — это единая ИТ-инфраструктура для разработки и внедрения GenAI- и ML-решений. «Заселить» агент в хаб нам помогала отдельная профильная команда. У них выстроен процесс по подключению и взаимодействию с командами-создателями. Наши разработчики изучили документацию, получили доступы к репозиториям и приступили к разработке.

Что под капотом у агента ДС:

• Python 3.12

• FastAPI 0.115.5

• LLM: GigaChat-2-PRO

• RAG OpenSearch

Для максимально качественных ответов агента мы поделили документацию на мелкие чанки, всего их получилось около 1000. По мере дополнения документации мы пропорционально увеличим их количество. 

Промпт агента специализированный, его написали так, чтобы ответы ограничивались информацией дизайн-системы, и донастроили для деления ответов по тематическим разделам: разработка, дизайн, редполитика. 

Как агент отвечает на вопрос:

1. принимает вопрос пользователя;

2. ищет в базе знаний ДС релевантные фрагменты (retrieval из OpenSearch);

3. по топ-7 найденных фрагментов дозапрашивает полную информацию по разделам, к которому относятся фрагменты

4. передаёт вопрос и найденный контекст в GigaChat;

5. возвращает развёрнутый ответ со ссылкой на раздел документации, откуда он взят.

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

Интерфейс ИИ-агента выглядит как чат, но мы предусмотрели в нём чипы «Дизайн», «Разработка» и «Редполитика». Пользователь выбирает, по какой теме у него вопрос, и агент с помощью донастроенного промпта ищет нужную информацию по конкретной теме.

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

Что у нас получилось: знакомьтесь — DAIS

Агент ДС запущен, дизайнеры и разработчики вовсю тестируют его.

 Пока DAIS отрабатывает не идеально: выдать правильный ответ по описанию пользователя у него получается через раз, с общими вопросами («Какой текст у кнопки при редактировании?», «Нужны ли точки в конце заголовка?») он справляется хорошо.

С 17 июня по 8 сентября, то есть с момента запуска агента и до завершения подготовки этой статьи, пользователи отправили DAIS 663 запроса, из которых:

• 410 — по разработке;

• 93 — по дизайну (пока доступны только ответы по атомарным компонентам);

• 160 — по редполитике.

Мы также проанализировали качество ответов агента и сделали несколько выводов:

• Почти на 60% запросов агент дал конкретный ответ из документации.

• Самая результативная категория ответов — редполитика. В большинстве случаев пользователь получает ответ и ссылку на документ-источник.

• Основной источник запросов — компонент таблицы. Но успешных ответов в этой категории около 44%. Это объясняется тем, что вопросы от разработчиков касаются узких мест или продвинутых свойств таблицы, которые не задокументированы в базе знаний агента. Будем работать на этим.

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

Как видите, нам ещё есть куда расти и что улучшать, но и эти результаты мы считаем достойными.

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

Что далось тяжело

Поиск точки входа. В Сбере разработка агентов — приоритетное направление работы, поэтому инструментов настолько много, что появляется проблема выбора. Приличное количество времени у нас ушло не на «как сделать», а на «с чего начать»: в какой хаб идти, где взять доступы, как интегрироваться с внутренними системами. Старт оказался небыстрым, и без исследования и общения с коллегами, которые уже прошли его, мы бы застряли совсем надолго.

Разработка только на Python. Наши разработчики — фронты, и агента им хотелось создавать на «родном» языке программирования. Но был доступен только Python, поэтому пришлось выйти из зоны комфорта.

Подготовка документации. Этот процесс съел у нас больше всего времени даже с использованием ИИ. Выгрузка из Pixso в PDF и Sketch, перевод в MD, двойная перепроверка на соответствие дизайну и коду — это кропотливая работа, хоть и наполовину автоматическая. Если бы мы обрабатывали вручную больше 100 файлов, то было бы гораздо тяжелее. И сэкономить силы на этом этапе не получилось, так как качество базы знаний агента определяет качество его ответов пользователям.

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

Планы

Помимо доработок качества ответов у нас появились идеи по развитию DAIS:

• С помощью МСР научить агент работать с макетами: проверять и генерировать отчёт.

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

• Отладить процесс обновления базы знаний по мере развития ДС, сделать его автоматическим.

Это далеко не все идеи, которые мы хотим реализовать, а лишь то, на чём сосредоточимся в первую очередь.

Благодарности

Агент появился благодаря всей команде, каждый вложил в него много сил:

• Лена Капитанова — наш лид: направляла, поддерживала и заряжала.

• Рамиль Ховалыг, Паша Потапов, Артур Асадуллин — разработчики: протестировали большую часть доступных внутренних инструментов и подобрали рабочее решение.

• Вероника Малышева, Женя Кузнецов, Юля Сабуцкая, Вика Кукульян — дизайнеры, которые обработали всю (!) документацию ДС, чтобы по ней можно было обучать агент.