Блог
Публикации о процессе разработки, решённых задачах и изученных технологиях
Как я обновил архитектуру голосового агента за один вечер
Работаю над проектом `ai-agents-voice-agent` — это голосовой ассистент, построенный на Claude API с поддержкой десктопной автоматизации. Недавно добавили новый модуль CUA (Computer Use Agent) на базе UI-TARS VLM, и документация отстала от реальности на несколько итераций. Проблема классическая: разработчики добавляют функции, коммитят в main, но документация остаётся в статусе «to-do». Я открыл `docs/architecture/` и понял — там старая структура, нет упоминания о CUA, а в `CAPABILITY_ARCHITECTURE.md` описана трёхуровневая архитектура, хотя фактически их уже четыре. Решил обновить все критические файлы параллельно: **Переделал `overview.md`** — добавил CUA в проекцию модулей, обновил граф зависимостей, расширил tech stack упоминанием UI-TARS. Теперь новый разработчик сразу видит, что есть desktop automation. **Переписал `CAPABILITY_ARCHITECTURE.md`** — это был ключевой файл. Сменил 3-уровневую иерархию на 4-уровневую: веб-инструменты → десктоп-инструменты → встроенные модули → локальные пакеты. К четвёртому уровню добавил примеры (`requests`, `pillow`) и decision tree для выбора между слоями. **Обновил документацию TMA** (`tma/00-ARCHITECTURE.md`) — убрал все пометки "(NEW)" (они потеряли смысл), переименовал секцию "Новые файлы" в "Файлы модуля" для фактичности. **Актуализировал `06-NEW-INTERFACES.md`** — это было больно. Там была информация о Tesseract OCR, которая вообще не использовалась. Заменил на CUA с описанием UI-TARS, добавил три забытых десктоп-инструмента (`desktop_drag`, `desktop_scroll`, `desktop_wait`). Фаза 3 теперь содержит 21 инструмент вместо старых 12. **Закрыл все задачи Фазы 3** в `02-TASK-LIST.md` — просто поставил галочки рядом с пунктами 3.1–3.9. Формально это не мой долг, но документация о незавершённых делах раздражает. Вся работа заняла около часа благодаря параллельному обновлению файлов. Главное — не оставлять документацию как груз, который весит на совести. Она либо актуальна, либо токсична. --- *Кстати, есть такая шутка в мире DevOps: Apache — единственная технология, где «это работает» считается полноценной документацией.* 😄
Как мы превратили экспертную проверку в систему
# Как мы собрали пакет экспертной оценки и что из этого вышло В **borisovai-site** встала типичная задача, которая только звучит простой: нужно было подготовить полноценный пакет для проверки системы feedback опытными разработчиками. Звучит как обычная административная работа, но это была отличная возможность создать инструмент, который сделает экспертизу структурированной и воспроизводимой. **Первым делом я понял объём.** Нужно не просто раскидать ссылки на код, а создать комплекс документов: брифинг для экспертов с конкретными техническими вопросами, чек-лист для быстрой ориентации, инструкции для организатора проекта и шаблоны для сбора обратной связи. Это не пять строк README, это полноценный пакет, который должен работать как система. **Начал с архитектуры пакета.** Разбил его по ролям: на пять экспертных направлений — безопасность, backend-архитектура, frontend-код, UX/дизайн и production-готовность. Каждому направлению нужны были свои вопросы, достаточно специфичные, чтобы эксперт не занимался ерундой, но при этом охватывающие реальные проблемы. Неожиданно выяснилось, что правильные вопросы — это половина успеха. Вопрос вроде «Насколько хорошо задокументирован код?» даст размытый ответ, а вот «Может ли новый разработчик за час разобраться с API feedback-системы?» уже даёт конкретное понимание. **EXPERT_REVIEW_REQUEST.md** стал главным документом — это детальный брифинг на 15 килобайт, где я описал контекст системы, текущие проблемы, которые волнуют команду, и пять специфических технических вопросов на каждое направление. **EXPERT_REVIEW_CHECKLIST.md** — это его компактный напарник для быстрой ориентации. А **HOW_TO_REQUEST_EXPERT_REVIEW.md** — пошаговая инструкция для организатора: как выбрать экспертов, как подготовить пакет, как отправить приглашения (даже шаблон email приготовил), как отслеживать ответы и компилировать feedback. **Интересный момент:** сам процесс создания этого пакета выявил слабые места в нашей документации. Когда пишешь вопросы для экспертов, понимаешь, что даже тебе не совсем понятно, почему архитектура именно такая. Это классический случай, когда подготовка к экспертизе становится самой полезной экспертизой. **Финальный результат** — структурированная система, которая масштабируется. Если в следующий раз понадобится ещё одна экспертная оценка, пакет легко адаптируется под новые вопросы. И главное — у нас есть объективный критерий: целевой рейтинг 4.0+ из 5.0 звёзд. Это не «хорошо» по наитию, а конкретное число, которое можно отслеживать и улучшать. Теперь осталось только найти экспертов и отправить им пакеты. Сама система feedback оценивает себя через других — очень meta, но работает. --- Разработчик: «Я подготовил пакет для экспертной оценки». Эксперт: «А есть ли у вас сам ответ?». Разработчик: «Да, но я хочу услышать ваше мнение». 😄
Эксперименты, которые показали, что нейросеть не готова расти сама
# Когда эксперименты показывают, что вы идёте в тупик — это тоже результат Проект **llm-analisis** стоял на пороге важного этапа. Нужно было разобраться, может ли нейросеть с динамической архитектурой (то есть такая, которая меняет себя прямо во время обучения) работать эффективнее статичной модели. Звучит амбициозно: система, которая сама растёт, адаптируется, эволюционирует. Но амбиции и реальность — вещи разные. ## Столкновение с жёсткой реальностью Phase 7b был нацелен на проверку трёх гипотез. Первая: можно ли помочь модели через синтетические метки (*synthetic labels*)? Вторая: поможет ли вспомогательная функция потерь на основе энтропии (*auxiliary entropy loss*)? Третья: может быть, прямой подход с энтропией — самый эффективный? Я запустил три параллельных эксперимента с соответствующими реализациями: `train_exp7b1.py`, `train_exp7b2.py` и `train_exp7b3_direct.py`. Каждый файл — это 250–310 строк кода, где каждая деталь архитектуры была тщательно продумана. Добавил специализированный `control_head.py` для управления вспомогательными функциями потерь и `expert_manager.py` для работы с модулем экспертов. Результаты оказались шокирующими, но очень информативными. ## Что сломалось и почему это ценно Первая неожиданность: когда я попытался обучать вспомогательные потери одновременно с основной функцией потерь, точность упала на **11,5–27%**. Это не баг — это конфликт целей. Модель получала противоречивые сигналы, пытаясь одновременно минимизировать несколько функций потерь. Классический случай, когда многозадачное обучение работает против вас, если не структурировать его правильно. Вторая проблема: я использовал отдельное валидационное множество для отслеживания прогресса. Знаете что? Это вызвало распределительный сдвиг (*distribution shift*), который сам по себе подорвал производительность на **13%**. Урок: не всегда валидационное множество — друг вашей модели. Третье открытие касалось архитектуры. Когда система пыталась изменяться динамически (добавлять новых экспертов прямо во время тренинга), её точность была **60,61%**. Когда я зафиксировал архитектуру (12 экспертов, неизменные), результат поднялся до **69,80%**. Разница в девять процентов — это не погрешность измерений, это фундаментальный выбор. ## Как мы переосмыслили стратегию Вместо того чтобы биться в стену дальше, я потратил время на документирование всего, что выучил. Создал 14 файлов документации, включая `PHASE_7B_FINAL_ANALYSIS.md` и детальные планы для каждого из трёх подходов. Это не выглядит как успех, но это именно тот момент, когда осознание становится дороже экспериментов. На основе этого анализа родилась совершенно новая стратегия для Phase 7c: вместо самоизменяющейся архитектуры система теперь будет использовать **фиксированную топологию с обучаемыми параметрами**. Маски, гейтинг, распределение внимания между экспертами — всё это может меняться. Но сама структура остаётся стабильной. Добавим обучение на двух задачах одновременно (CIFAR-100 и SST-2) с использованием **Elastic Weight Consolidation** для защиты от катастрофического забывания. ## Что даёт этот опыт Получилось то, что я называю "честным провалом": все подходы Phase 7b не сработали, но мы *знаем почему*. Это стоит больше, чем слепое везение. Проект остался в фазе "NO-GO" для Phase 7b, но Phase 7c уже полностью спланирована и готова к старту. Вместо двух недель блуждания в темноте мы потратили 16 часов на выявление тупиков. **Главный урок:** иногда самый ценный результат — это понимание того, что не работает. И документирование этого пути для будущих итераций. 😄 *Совет дня: если ваша модель падает на 27% при добавлении вспомогательной функции потерь, проблема не в коде — проблема в архитектуре целей.*
Когда самоадаптивная сеть начинает саботировать сама себя
# Когда всё падает: Как я 16 часов охотился на призрак в нейросети Проект **llm-analysis** вошёл в фазу 7b, и я был уверен — вот она, момент прорыва. Идея казалась блестящей: добавить вспомогательные потери энтропии, заставить модель самостоятельно управлять архитектурой во время обучения. Синтетические метки, динамическая модификация слоёв, умные функции потерь — казалось, всё сходится в одну точку. Но вместо взлёта получилась полоса падения. На фазе 7a я достиг 69.80% точности на фиксированной архитектуре. Теория была простой: если зафиксированная сеть хороша, то самоадаптирующаяся должна быть лучше. Опубликовано же, оптимизируют ведь. Запустил эксперименты. **Эксперимент 7b.1** с синтетическими метками упал до 58.30% — деградация на 11.5%. Попробовал добавить entropy-based вспомогательную потерю с joint training — тут вообще беда: 42.76% точности. Модель явно конфликтовала сама с собой, оптимизируя одновременно классификацию и архитектурные модификации. **Эксперимент 7b.3** с прямой энтропией показал 57.57% — чуть лучше, но всё равно худше исходной фазы 7a. Три недели назад я бы назвал это просто плохими гиперпараметрами. Но я писал логи детально, сравнивал шаг за шагом. И вот оно — откровение, которое укусило во время отладки: *валидационный split меняет распределение данных*. Только эта смена дала деградацию в 13% от исходного результата. Архитектура здесь была вторична. Ключевой инсайт пришёл неожиданно: **самомодифицирующиеся архитектуры во время обучения фундаментально нестабильны**. Модель не может одновременно оптимизировать классификацию, менять структуру слоёв и остаться в здравом уме. Это не issue в коде, это issue в физике обучения. Похоже на попытку водителя одновременно управлять авто и переделывать двигатель — машина просто развалится. Я потратил 16 часов на пять тренировочных скриптов (1500 строк), семь детальных документов анализа (1700 строк документации) и в итоге понял, что идти туда не надо. В нормальной биологии архитектура наследуется и фиксируется, а адаптация идёт через параметры. Фаза 7c будет про фиксированную архитектуру с многозадачным обучением. Фаза 8 — про meta-learning гиперпараметров, но не про модификацию самой сети. Неприятно? Да. Потрачено впустую? Нет — я выявил dead end до того, как зайти туда с полным размахом. Быстрое *отрицательное* открытие иногда дороже золота. Дальше — фаза 7c, предполагаю 8–12 часов работы, и на этот раз архитектура будет стоять как скала. 😄 Оказывается, мудрость эволюции в том, чтобы *не* переделывать себя во время прохождения теста.
Микротюнинг алгоритма: как сэкономить гигабайты памяти
# Когда микротюнинг алгоритма экономит гигабайты памяти Работаю над проектом speech-to-text, и вот типичная история: всё кажется работающим, но стоишь перед выбором — либо система пожирает память и отзывается медленно, либо производит мусор вместо текста. На этот раз пришлось разбираться с двумя главными вредителями: слишком агрессивной фильтрацией T5 и совершенно бесполезным адаптивным fallback'ом. Начну с того, что случилось. Тестировали систему на аудиокниге, и T5 (модель для коррекции текста) вела себя как чрезмерно ревностный редактор — просто удаляла слова направо и налево. Результат? Потеря 30% текста при попытке поднять качество. Это был провал: WER (Word Error Rate) показывал 28,4%, а сохранялось всего 70% исходного текста. Представьте, вы слушаете аудиокнигу, а система вам отдаёт её в сокращённом виде. Первым делом залез в `text_corrector_t5.py` и посмотрел на пороги схожести слов. Там стояли скромные значения: 0,6 для одиночных слов и 0,7 для фраз. Я поднял их до 0,80 и 0,85 соответственно. Звучит как небольшое изменение? На самом деле это означало: «T5, удаляй слово только если ты ОЧЕНЬ уверена, а не если просто подозреваешь». И вот что получилось — WER упал до 3,9%, а сохранение текста прыгнуло на 96,8%. Это был уже другой уровень. Но это был только первый фронт войны. Вторым врагом оказался **adaptive_model_fallback** — механизм, который должен был срабатывать, когда основная модель барахлит, и переключаться на резервную. Звучит логично, но на практике? Тестировали на синтетических деградированных аудио — отлично, WER 0,0%. На реальных данных (TTS аудиокниги в чистом виде) — хуже базовой линии: 34,6% вместо 31,9%. На шумных записях — 43,6%, никакого улучшения. Получилось, что адаптивный fallback был как дорогой зонтик, который вообще не спасает от дождя, но при этом весит килограмм и занимает место в рюкзаке. Я отключил его по умолчанию в `config.py`, выставив `adaptive_model_fallback: bool = False`. Код оставил — вдруг когда-нибудь появятся реальные микрофонные записи, где это сработает, но пока это просто груз. **Интересный факт**: задача выбора порога схожести в NLP похожа на тюнинг гитары — сдвигаешь колок на миллиметр, и звук либо поёт, либо звенит. Только вместо уха здесь работаешь с метриками и надеешься, что улучшение на тестовом наборе не рухнет на боевых данных. В итоге система стала на 86% точнее на аудиокнигах, освободилась от 460 МБ ненужной памяти и ускорилась на 0,3 секунды. Всё это из-за двух небольших изменений пороговых значений и одного отключённого флага. Результаты зафиксировал в `BENCHMARK_RESULTS.md` — полная таблица тестов, чтобы потом никто не начинал возвращать fallback обратно. Урок такой: иногда микротюнинг работает лучше, чем архитектурные перестройки. Иногда лучшее решение — просто выключить то, что не работает, вместо того чтобы его развивать. 😄 Что общего у T5 и подросткового возраста? Оба требуют очень точных параметров, иначе начинают удалять всё подряд.
SSH спасает: ищем потерянный QR-код в файловой системе
# Как SSH-команда спасла от чёрного экрана в Authelia Проект **borisovai-admin** требовал добавить двухфакторную аутентификацию. Задача была простой на первый взгляд — установить Authelia, настроить TOTP-регистрацию и запустить. Но когда тестировщик нажал кнопку «Register device», экран остался чёрным. QR-код не появился. Никаких ошибок в консоли, никаких намёков на проблему — просто ничего. Первые полчаса я искал в классических местах: консоль браузера, логи Authelia, конфигурация сервера. Сертификаты в порядке, порты открыты, контейнеры Docker работают нормально. Но QR-код так и не возникал. Казалось, система делает что-то, но что именно — никому не известно. И вот возникла мысль, которая могла решить всё: **а что если Authelia вообще не отправляет уведомление браузеру?** Я ещё раз посмотрел на конфигурацию и увидел деталь, которую раньше воспринимал как обычный параметр: `notifier: filesystem`. Это не email, не SMS, не какой-то облачный сервис. Это самый примитивный вариант — Authelia пишет уведомления прямо в файл на сервере. Вот тут я понял, что нужно залезть в систему по SSH и посмотреть, что там реально происходит. Подключился на сервер и выполнил команду: ``` cat /var/lib/authelia/notifications.txt ``` И там она была! Ссылка вида `https://auth.borisovai.tech/...token...` — та самая ссылка, которая должна была привести к QR-коду. Authelia делала всё правильно. Просто в конфигурации для разработки уведомления не отправляются пользователю по стандартным каналам, а записываются в лог-файл на диск. **Тут я узнал интересный момент**: `notifier: filesystem` в Authelia — это не какой-то костыль или режим отладки. Это фактически идеальная настройка для локальной разработки. Вместо того чтобы настраивать SMTP-сервер, интеграцию с SendGrid или другой внешний сервис, Authelia просто пишет ссылку в файл. Быстро, просто, полезно для разработки. Но в продакшене это превращается в ловушку: система работает, но пользователи ничего не видят. Когда я открыл эту ссылку в браузере, QR-код тут же появился. Отсканировал его в приложении Google Authenticator — всё сработало. Задача решена за несколько минут, но урок остался на всю жизнь: иногда самое очевидное решение скрыто в одной строке документации, и оно работает ровно так, как задумано инженерами. Теперь в конфигурации проекта есть комментарий про `filesystem` notifier и ссылка на команду для проверки. Следующему разработчику, который будет настраивать двухфакторку, не придётся ловить QR-код в файловой системе 😄
QR-код в файле: как я нашел потерянное уведомление Authelia
# Когда QR-код спрятался в файл: история отладки Authelia Проект **borisovai-admin** требовал добавить двухфакторную аутентификацию. Казалось бы, что может быть проще — установили Authelia, настроили по документации, и хотели включить TOTP для повышения безопасности. Но когда тестировщик нажал кнопку «Register device», экран остался чёрным. QR-код просто не появился. Первые полчаса ушли на классическую отладку: проверка консоли браузера, логов Authelia, конфига. Всё выглядело нормально. Сертификаты в порядке, порты открыты, контейнеры запущены. Но QR так и не появлялся. В какой-то момент возникла идея: а что если Authelia вообще не отправляет уведомление? Вот тут и вспомнилась одна важная деталь из конфигурации — `notifier: filesystem`. Это не email, не Telegram, а самый простой вариант для разработки: Authelia записывает ссылку на регистрацию прямо в файл на сервере. Никаких стандартных каналов связи, никакой магии с SMTP. Пришлось подключиться по SSH к серверу и выполнить простую команду: ```bash cat /var/lib/authelia/notifications.txt ``` И вот оно! В файле лежала ссылка вида `https://auth.borisovai.tech/...token...` — та самая ссылка, которая должна была привести к QR-коду. Оказалось, Authelia всё делала правильно. Просто в конфигурации для разработки уведомления отправляются не пользователю, а в лог-файл на диск. **Интересный момент**: многие разработчики не замечают, что в конфигурации `notifier: filesystem` — кажется, что это какой-то непонятный режим, а на самом деле это *идеальная* настройка для локальной разработки. Вместо того чтобы настраивать SMTP-сервер или интеграцию с внешними сервисами, Authelia просто пишет ссылку в файл. Быстро, просто, полезно. Когда я открыл эту ссылку в браузере, QR-код тут же появился. Сканировали его в TOTP-приложении, всё сработало. Задача решена за несколько минут, но урок остался: иногда самое очевидное решение скрыто в документации, и оно работает лучше, чем нами предполагалось. Теперь в конфигурации проекта есть комментарий про `filesystem` notifier и ссылка на команду для проверки. Следующему разработчику, который будет настраивать двухфакторку, не придётся искать её полчаса. --- *Authelia: когда QR-код путешествует по файловой системе вместо того, чтобы сразу показаться в браузере 😄*