Создание ИИ-агента для технических писателей: от прототипа к промышленному коду
Команда документирования СберТеха столкнулась с колоссальным объемом несоответствий в терминологии: в коде на каждую десятую строчку приходилась ошибка. Ручной контроль тысяч терминов из глоссария был невозможен. В ответ была развита собственная система на Python, использующая векторный поиск и модельный контекстный протокол (MCP), для автоматической проверки и исправления текста прямо в редакторе.
# Как мы создали ИИ-агента для технических писателей и почему это оказалось сложнее, чем кажется
Разработка технической документации для масштабных платформ — это не только творческий процесс, но и работа с жесткими стандартами. В СберТехе мы создали глоссарий, содержащий более 750 терминов, с участием специалистов по кибербезопасности и разработчиков документации. Однако главной проблемой стало не создание правил, а их соблюдение.
Представьте ситуацию: в коде ошибки встречаются настолько часто, что вручную исправить их всё равно что подниматься пешком на 150-этажный небоскреб. Команды не могут постоянно проверять каждую строчку. Мы поняли, что рутину нужно автоматизировать, а проверку необходимо производить в момент написания текста, прямо внутри редактора кода.
От идеи до прототипа за один вечер
Идея создания агента возникла естественным образом: требуется система, которая проверит текст сразу после ввода. Мы руководствовались принципом скорости и использовали доступные инструменты.
Архитектура первого прототипа базировалась на комбинации двух компонентов:
* Клиентский агент: Работает внутри среды разработки (IDE). Мы использовали плагин Continue, который интегрируется с IDE и инициирует взаимодействие с внешними системами. * Серверный агент: Выполняет основную логику обработки. В качестве конструктора логики выбрали Langflow (визуальный low-code фреймворк).
Связь между агентами строилась по протоколу MCP (Model Context Protocol). Система работала следующим образом: разработчик вводит текст в редактор, клиентский агент передает его серверу, тот сверяет содержание с глоссарием и возвращает исправления. Разработчик принимает или отклоняет изменения одной кнопкой.
Для работы использовалась внутренняя модель Qwen3-32b, которая подключена к нашему серверу. Весь процесс настройки занял несколько часов, что позволило быстро увидеть результат.
Когда «просто» перестает работать
Эксперимент прошел успешно на малых объемах, однако при попытке обработки серьезного массива текста проявились системные ограничения:
1. Ограничения контекстного окна: Модель не могла удерживать в памяти огромный глоссарий и одновременно отслеживать внесенные ранее правки в текущем абзаце. Информация «испарялась». 2. Ресурсоемкость: Процесс работал медленно и требовал избыточных вычислительных мощностей (GPU). 3. Надежность: Решение, собранное на визуальных блоках, не соответствовало требованиям промышленной эксплуатации, где важна стабильность и предсказуемость.
Стало очевидно, что для массового внедрения необходимо изменить подход к обработке данных. Вместо передачи всего текста целиком, его нужно разбивать на логические блоки и формировать для каждого отдельный, релевантный фрагмент глоссария.
Векторный поиск и собственное решение на Python
Ключевой задачей стало определить, какие именно термины из общего глоссария (более 700 записей) требуются для конкретного абзаца текста. Вручную это делать неэффективно.
Мы выбрали векторный поиск. Вместо сложной инфраструктуры Kubernetes решение реализовалось локально в памяти (In-Memory).
Как это устроено технически
Мы использовали векторное хранилище Qdrant с Python-библиотекой qdrant-client и моделью эмбеддингов bge-m3. Последняя преобразует слова и фразы в числовые векторы, сохраняя их смысловую близость.
В базе данных мы хранили не просто список терминов, а рассчитанные для них числовые векторы. Структура словарной статьи включала:
* Сам термин (например, hotfix). * Допустимые аналоги. * Термин на английском языке (origin). * Нерекомендуемые синонимы. * Описание термина.
При проверке текста алгоритм выполнял следующие шаги: 1. Разбивал текст на слова с помощью регулярных выражений. 2. Фильтровал короткие слова (предлоги, союзы). 3. Для каждого значимого слова рассчитывал вектор и искал похожие в базе данных. 4. Использовал порог схожести (match score) в диапазоне 0,85–0,90 для исключения случайных совпадений. 5. Генерировал мини-глоссарий, содержащий только термины, актуальные для текущего контекста.
Этот подход позволил ИИ-агенту работать быстро и точно, так как модель анализировала лишь релевантный набор данных, а не весь словарный запас сразу.
Переход к написанию собственного кода на Python занял несколько дней вместо недели адаптации визуального конструктора. Мы использовали библиотеки FastMCP и стандартные инструменты для управления задачами. Это дало полный контроль над процессом: от парсинга исходного глоссария до логики векторного поиска. Дополнительно был пересмотрен формат данных: глоссарий был переведен из Markdown в YAML для более удобного парсинга машинным чтением, а промпты были адаптированы под английский язык для повышения качества ответов модели.
Планы на будущее
На данный момент ИИ-агент эффективно справляется с проверкой терминологии. Однако модель еще не учитывает требования внутреннего руководства по стилю (редполитики) и иногда добавляет лишнюю информацию или искажает форматирование.
Следующая цель — разработка полноценного MCP-сервера с API, где логика будет разбита на отдельные навыки (skills) для максимальной гибкости. Мы планируем создать решение, которое можно будет запускать как локальный скрипт, сервер или вызывать удаленно. Полное описание архитектуры этих навыков будет представлено в следующих материалах.
ИИ пока не способен полностью заменить редактора из-за рисков искажения смысла, но он стал мощным инструментом для стандартизации и ускорения работы над документацией.