Автор: Александр Казанцев, руководитель отдела документации и контента
Представьте, что вы поддерживаете крупный проект с документацией на нескольких языках. Каждый раз, когда в английской версии появляется новое руководство или исправляется ошибка, нужно вручную обновлять все переводы в других языковых версиях. Это дорого, медленно и чревато рассинхронизацией. Даже два дополнительных языка начинают создавать проблему, а если их больше?
Именно такую проблему решает специализированный агент для автоматического перевода технической документации, о котором пойдёт речь. Сразу скажем, что на английском языке мы делаем перевод с русского (или пишем изначально) вручную, а далее всю работу за нас делает наше создание.
Что это за агент и зачем он нужен
Агент — это не просто скрипт, который отправляет текст в нейросеть и записывает ответ. Это продуманная система, которая понимает специфику технической документации: сохраняет код и команды без изменений, не переводит названия кнопок и элементов интерфейса, следит за форматированием Markdown и даже автоматически генерирует оглавление в нужном стиле.
В основе лежит идея оркестрации нескольких специализированных компонентов. Есть переводчик, который получает исходный текст и выдаёт черновой перевод. Есть валидатор — отдельная модель, которая проверяет результат по чётким правилам: все ли разделы на месте, не переведены ли случайно команды терминала, соблюдена ли терминология. Если валидатор находит ошибки, запускается корректор, который вносит точечные правки. Этот цикл может повторяться несколько раз, пока качество не достигнет приемлемого уровня, оцениваемого по шкале от 0% до 100%.
Почему не взять готовое решение
Возникает закономерный вопрос: зачем писать свой агент, если есть OpenClaw, различные обёртки над LLM или даже готовые сервисы машинного перевода? Ответ кроется в трёх ключевых требованиях, которые редко выполняются в универсальных инструментах.
Техническая документация — это не художественный текст. Здесь критически важно сохранить работоспособность примеров кода, точность терминов и структуру разметки. Универсальные переводчики часто «ломают» код, переводят переменные или меняют форматирование, что делает результат непригодным для публикации.
Процесс перевода документации — это не разовая операция, а непрерывный поток изменений. Нужна интеграция с системой контроля версий, возможность обрабатывать только изменённые файлы, синхронизировать удаления и учитывать правила исключения отдельных разделов. Готовые инструменты редко предоставляют такую гибкость «из коробки».
Качество перевода должно контролироваться автоматически. В агенте валидация встроена в конвейер: каждая правка проверяется, ошибки фиксируются, а при необходимости запускается повторная генерация. В универсальных решениях эту логику пришлось бы надстраивать вручную, что сводит на нет преимущество их использования.
Плюсы специализированного подхода
Главное преимущество агента — предсказуемость результата. Благодаря чётким правилам в промптах валидатора система знает, что строки в кавычках вроде "Code successfully verified" — это сообщения интерфейса, которые должны остаться на английском. Что команды в блоках кода трогать нельзя. Что оглавление генерируется отдельным скриптом, поэтому модель не должна создавать своё.
Другой плюс — модульность. Компоненты агента слабо связаны: можно заменить модель перевода, не переписывая валидатор; можно отключить генерацию оглавления для определённых языков; можно добавить новый язык (сейчас у нас есть французский и турецкий, но в планах перевод еще на испанский, голландский и, самое сложное, китайский), просто прописав новые параметры в файле конфигурации. Это делает систему устойчивой к изменениям и простой в поддержке.
Третий важный аспект — прозрачность. Все этапы работы логируются, ошибки валидации сохраняются в отдельный файл, а при включённом отладочном режиме можно увидеть полные запросы и ответы моделей. Это критически важно для отладки и дообучения промптов.
Минусы и ограничения
У подхода есть и обратная сторона. Во-первых, сложность настройки. Чтобы агент заработал, нужно подготовить конфигурационный файл, прописать пути к репозиторию, настроить исключения, подобрать параметры контекста для моделей. Для разового перевода это избыточно.
Во-вторых, зависимость от качества промптов. Если правила валидатора сформулированы неточно, агент может пропустить ошибку или, наоборот, начать бесконечно исправлять стилистические нюансы. Требуются итерации и ручная проверка результатов на старте. В нашем случае для перевода использовались те же промпты и модели, что и в ручном варианте, поэтому результат был достаточно предсказуем. Но также потребовал вносить изменения как в промпты переводчика, так и валидатора при настройке агента.
В-третьих, ресурсоёмкость. Цикл валидации с несколькими попытками исправления означает, что на один файл может уйти в разы больше токенов, чем при простом переводе. Это увеличивает стоимость и время обработки, особенно для крупных документов. В нашем случае у нас у отдела документации есть свой GPU сервер, не самый мощный на связке из четырех Nvidia V100 по 16 Гб. И у него пиковая скорость примерно 50-60 токенов в секунду. То есть в среднем перевод с валидацией одной статьи может занимать от 3 до 20 минут, в зависимости от размера и числа повторов каждого этапа.
Наконец, агент заточен под конкретный формат документации — Markdown с определённой структурой (у нас это Material for MkDocs с нашими доработками). Если нам (вдруг) потребуется работать с reStructuredText, AsciiDoc или другим форматом, значительную часть логики придётся переписывать.
Архитектура: модульность и разделение ответственности
Агент построен по принципу слабосвязанных модулей, написанных на Python, каждый из которых решает одну задачу. В центре находится конфигурация — класс AgentConfig, который загружает настройки из YAML-файла и предоставляет единый интерфейс доступа к параметрам. Это позволяет менять поведение системы, не переписывая код: добавить новый язык, скорректировать лимиты токенов или изменить правила исключения файлов.
Далее идут специализированные компоненты. OpenWebUIClient отвечает за низкоуровневое общение с API нейросети: формирование запросов, обработку ответов, повторные попытки при сбоях. TranslationValidator управляет циклом валидации и исправления, но не знает, как именно отправляются запросы. ImageSync занимается только копированием изображений, а RepoWatcher отслеживает изменения в репозитории через Git. Такая изоляция упрощает тестирование: можно заменить клиент API, не затрагивая логику валидации.
Вся постобработка вынесена в утилиты: генерация оглавления, очистка ссылок, оценка токенов. Это не случайно. Когда логика размазана по коду, любое изменение требует правок в десятке мест. Когда она собрана в одном месте — достаточно обновить одну функцию.
Конвейер обработки: от изменения в репозитории до готового файла
Пайплайн агента можно представить как последовательность этапов, через которые проходит каждый файл.
Запускается конвейер простой командой вида
python3 ./main.py --lang tr --file /billing/billing_cycle.md --since "24 hours ago"которая говорит агенту (в данном случае для турецкого языка) отследить все изменения турецкой языковой ветки в файле billing_cycle.md, который находится в директории billing, за последние 24 часа и если они есть, сделать перевод. Таким же образом можно работать как с целыми директориями (параметр --dir), так и даже со всей веткой.
Первый этап — обнаружение изменений. Агент может работать в нескольких режимах: обработать один файл по запросу, просканировать всю директорию или отследить изменения через Git с момента последнего запуска. Фильтрация по исключениям применяется сразу: если файл попадает в exclude_dirs или соответствует паттерну в exclude_files, он игнорируется.
Второй этап — подготовка контекста. Исходный Markdown читается, из него удаляется старое внутреннее оглавление (чтобы модель не пыталась его переписать или продублировать), оценивается размер в токенах. Это важно: если текст не влезает в контекстное окно, его нужно разбить или запросить у модели больше памяти.
Третий этап — перевод. Очищенный текст отправляется в модель-переводчик с минимальной температурой (обычно 0.1), чтобы снизить вариативность и получить максимально детерминированный результат.
Четвёртый этап — валидация. Здесь в игру вступает вторая модель, настроенная на критический анализ. Она сравнивает исходник и перевод, проверяет полноту, сохранность кода, терминологию и формат. Если найдены ошибки, запускается цикл исправления: корректор получает список замечаний и вносит точечные правки. Цикл повторяется до достижения порога качества или исчерпания лимита попыток.
Пятый этап — постобработка. Ссылки очищаются от якорей, генерируется новое оглавление в формате MkDocs, результат сохраняется в целевую директорию. Параллельно копируются отсутствующие изображения.
Шестой этап — логирование. Если валидация не пройдена, детальный отчёт с примерами ошибок сохраняется в JSONL-файл для последующего анализа.
Технически все крутится на связке Ollama + OpenWebUI, а за нейросети отдувается модель Qwen 3.6:27b.
Работа с LLM: не просто отправить запрос
Самая интересная часть здесь, это как агент общается с нейросетями.
Динамическое управление контекстом. Модели имеют ограничение на длину входного окна. Агент не использует фиксированное значение, а рассчитывает его на лету: оценивает размер входного текста в токенах, добавляет запас на ответ и убедится, что сумма не превышает максимум, разрешённый конфигурацией (у нас это 100 000 токенов, больше связка из двух V100 с суммарными 32 гигабайтами не вытягивает).
# Упрощённый пример расчёта контекста
estimated = len(text) / 4 # грубая оценка: 4 символа ≈ 1 токен
max_input = context_max - response_reserve
actual_input = min(estimated * 1.05, max_input)
num_ctx = actual_input + response_reserveЭто позволяет обрабатывать как короткие заметки, так и многостраничные руководства, не теряя в качестве.
Разделение промптов для разных ролей. Модель-переводчик получает минимальные инструкции именно в агенте, так как полный системный промт уже настроен в ее кастомной реализации внутри OpenWebUI.
Валидатор же получает подробный системный промпт с правилами: что проверять, что игнорировать, в каком формате возвращать ответ.
Пример фрагмента промпта валидатора:
✅ CHECK:
1. COMPLETENESS: All sections from source are present.
2. CODE/COMMANDS: $VAR, /paths, curl — DO NOT translate.
3. TERMINOLOGY: Use standard translations or keep original.
4. FORMAT: Markdown syntax is preserved.
❌ IGNORE:
- TOC blocks, link anchors, admonition syntax.
⚡ CRITICAL: ALL UI STRINGS IN QUOTES MUST REMAIN IN ENGLISH.Такая специализация повышает качество: переводчик не отвлекается на проверку, а валидатор не пытается переписать текст.
Обработка неидеальных ответов. Нейросети не всегда возвращают валидный JSON, особенно когда просят структурированный вывод. Агент включает механизм «ремонта» ответа: удаляет markdown-обёртки, вырезает объект от первой { до последней }, исправляет висячие запятые, экранирует кавычки внутри строк.
# Упрощённая логика ремонта JSON
response = re.sub(r'^```json\s*', '', response)
start = response.find('{')
end = response.rfind('}') + 1
response = response[start:end]
response = re.sub(r',\s*}', '}', response) # убираем ,}Если даже после этого парсинг не удаётся, агент пытается восстановить данные по частям или записывает ошибку для ручного разбора.
Повторные попытки и экспоненциальная задержка. Сетевые сбои, таймауты, перегрузка сервера — обычное дело. Агент не сдаётся после первой ошибки. Он повторяет запрос до пяти раз, увеличивая паузу между попытками по экспоненте: 2 секунды, потом 4, потом 8, но не больше 30. Это баланс между настойчивостью и уважением к ресурсам сервера.
Цикл валидации: как несколько вызовов LLM работают вместе
Одно из ключевых отличий агента — многошаговая валидация. Это не просто «перевели и забыли», а итеративный процесс улучшения качества.
На первом шаге валидатор получает исходник и черновой перевод, возвращает список замечаний в структурированном виде и оценивает качество перевода (от 0 до 1). Если ошибок нет или нас устраивает оценка (сейчас это 0.85), то файл считается готовым. Если есть — корректор получает те же тексты плюс список проблем и инструкцию исправить только их, не переписывая остальное.
После исправления валидатор проверяет результат снова. Цикл повторяется до трёх-пяти раз. Такой подход позволяет ловить ошибки, которые модель-переводчик пропустила с первого раза: пропущенный абзац, неправильно переведённый термин, сломанная разметка.
Важный нюанс: валидатор настроен на строгость, но с разумными исключениями. Он не ругается за отсутствие оглавления (его генерирует скрипт), не обращает внимания на пробелы, не требует идеального стиля. Это предотвращает бесконечные циклы исправлений из-за субъективных замечаний. С учетом того, что мы допускаем до 15% несущественных ошибок, цикл перевода и валидации часто идет непрерывно и без повторов.
Почему оркестрация важнее одной мощной модели
Можно было бы попробовать решить задачу одной моделью: «переведи и проверь себя сама». Но на практике это работает хуже. Одна модель, получающая противоречивые инструкции («будь креативным» и «будь строгим»), начинает путаться. Она может пропустить ошибку, потому что «и так сойдёт», или, наоборот, начать переписывать рабочий код в погоне за стилем.
Разделение на переводчика и валидатора имитирует рабочий процесс человеческой команды: один делает черновик, другой вычитывает. Каждая модель фокусируется на своей задаче, промпты остаются простыми и понятными, а результат — предсказуемым.
Кроме того, оркестрация даёт гибкость. Можно использовать более дешёвую модель для перевода и более точную — для валидации. Можно отключить валидацию для черновых сборок и включить для релиза. Можно собрать статистику: какие типы ошибок встречаются чаще, и дообучить промпты.
Когда такой агент оправдан
Специализированный агент — это не панацея и замена сотрудников отдела (хотя они, скажу честно, уже косо смотрят на него). Он не нужен, если вы переводите пару статей раз в полгода. Но он становится незаменимым, когда:
документация обновляется ежедневно;
требуется поддерживать более трёх языков;
важны точность терминов и сохранение примеров кода;
есть требования к единообразию оформления;
процесс должен быть воспроизводимым и контролируемым.
В таких условиях затраты на разработку и настройку агента окупаются за счёт сокращения ручного труда, уменьшения количества ошибок и ускорения выпуска обновлений.
Вместо заключения
Автоматизация перевода технической документации — это не про замену людей, а про освобождение их от рутины. Агент берёт на себя черновую работу: первичный перевод, проверку формата, синхронизацию файлов. А человек сосредотачивается на том, что действительно требует экспертизы: выверке сложных формулировок, адаптации примеров под локальные особенности, финальном ревью.
Специализированный агент, в отличие от универсального инструмента, заточен под конкретную задачу. Он знает контекст, соблюдает правила и работает предсказуемо. Да, его сложнее настроить. Но когда поток изменений становится постоянным, именно такая предсказуемость превращает хаос в управляемый процесс.