Генерация документации нейросетями в продакшене: 5 ИИ-агентов обновляют API при каждом коммите

Решение описал Александр Казанцев, руководитель отдела документации и контента HOSTKEY. Контекст простой: PHP-бэкенд Invapi содержит порядка 60 контроллеров, общее число вызовов приближается к тысяче, клиенту доступны несколько сотен. До автоматизации документацию писали вручную, она моментально устаревала, а новые методы документировались только если кто-то об этом вспоминал. REST API у проекта нет, поэтому стандартные инструменты вроде Swagger подключить невозможно.

Пять агентов вместо одного скрипта: что внутри?

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

• PHPFuncIndexer (с участием LLM, то есть большой языковой модели, программы, которая понимает и генерирует текст). Сканирует все PHP-файлы функций и строит индекс сигнатур. Извлекает не только имена функций, но и имена полей возвращаемых массивов. Результат кэшируется на 24 часа.
• Whitelist Export (LLM плюс регулярные выражения). Отделяет клиентские методы от внутренних, служебных и административных. Задача нетривиальная: в одном файле из 35 методов клиенту доступны всего семь, а параметры извлекаются по-разному в разных контроллерах.
• Doc Generator (LLM). Получает код контроллера вместе с контекстным сниппетом от индексатора и генерирует документацию в формате Markdown.
• Validator (регулярные выражения плюс LLM). Проверяет сгенерированную документацию на соответствие исходному коду.
• Monitor (GitLab API). Автоматически отслеживает коммиты, определяет, затрагивают ли изменения клиентские методы, и запускает только нужные этапы конвейера.

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

Почему нельзя просто «скормить код нейросети»?

Казанцев подробно объясняет ключевую сложность. PHP-контроллеры Invapi устроены как тонкие маршрутизаторы: контроллер вызывает функции из отдельных файлов. Чтобы LLM корректно описала, что возвращает метод, ей нужен код не только контроллера, но и вызываемых функций.

Вторая проблема: параметры в разных файлах извлекаются по-разному. В одном файле все параметры обёрнуты в один контейнер, в другом разбросаны по 18 переменным на верхнем уровне, причём не все используются во всех методах. Для надёжности система применяет комбинированный подход: регулярные выражения извлекают обращения к входным параметрам, а LLM разбирается в логике.

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

Как попробовать?

1. Установите Ollama (ollama.com), локальный движок для запуска LLM на своём компьютере. Код не уходит на внешние серверы, это принципиально для компаний с закрытой кодовой базой.
2. Подготовьте Python-окружение. Система Invapi построена на Python-скриптах, которые анализируют PHP-файлы из Git-репозитория.
3. Настройте промпты для каждого из пяти этапов конвейера под структуру вашего проекта. Ключевое: индексатор должен видеть не только контроллеры, но и файлы вспомогательных функций.
4. Подключите мониторинг к GitLab API вашего репозитория, чтобы система сама определяла, какие коммиты требуют обновления документации.

Сравнение с доступными в РФ инструментами

Из доступных в России аналогов для работы с кодом стоит упомянуть GigaChat от Сбера и YandexGPT. Оба сервиса умеют анализировать код и генерировать текст, но есть принципиальная разница.

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

Частые вопросы

Нужен ли мощный сервер для запуска?

Ollama работает на обычном компьютере с видеокартой среднего уровня. Для анализа PHP-файлов и генерации Markdown-документации не требуются модели с сотнями миллиардов параметров (параметры, это числа, которые модель выучила при обучении; чем их больше, тем модель «умнее», но и требовательнее к железу). Конкретные требования к оборудованию автор не называет, но Ollama поддерживает модели, запускающиеся на потребительских GPU.

Работает ли это только с PHP?

Принцип конвейера универсален: индексация функций, белый список, генерация, валидация, мониторинг Git. Но конкретные регулярные выражения и логика извлечения параметров написаны под PHP-код Invapi. Для другого языка придётся адаптировать парсеры.

Можно ли доверять документации, которую написала нейросеть?

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

Подход HOSTKEY показывает, что генерация документации нейросетями уже работает в продакшене российских компаний, и барьер входа ниже, чем кажется: бесплатная Ollama, Python-скрипты, доступ к Git-репозиторию. Главное условие не размер бюджета, а готовность разбить задачу на пять узких шагов вместо попытки решить всё одним промптом.