Сигнал из хука LLMScience: схема структуры репозитория для ИИ-приложений в продакшене, которая покрывает всю инженерную часть вокруг модели — от обработки запросов и интеграции провайдеров до безопасности, наблюдаемости, оценки качества и деплоя. Ниже — разбор по папкам и честный ответ, что из этого нужно небольшому вайб-проекту в первый день. Витрина — vibe-studio.uk.
Соседи: CABRA: где ломаются агенты в коде, уборка AGENTS.md, локальный RAG на EmbeddingGemma 2, pass@k и надёжность агентов.
Зачем вообще думать о структуре
Прототип на одном файле работает, пока им пользуетесь вы. В продакшене у ИИ-приложения появляются сбои, которых нет у обычного сайта. В исходном посте они названы прямо:
- запрос к модели может не уложиться в отведённое время;
- пользователь может запросить данные, к которым у него нет доступа;
- смена модели или промпта может ухудшить ответы, не сломав ни одного модульного теста.
Структура репозитория сама ничего из этого не решает. Она даёт каждой проблеме понятное место в коде — и вам, и агенту, который этот код правит.
Девять зон и что в каждой
- api/ — обработка запросов, типизированные схемы, аутентификация и ограничение частоты запросов.
- application/ — рабочие процессы, бизнес-правила, бюджеты и проверка того, что вернула модель.
- providers/ — интеграции моделей, предельное время ответа, ограниченное число повторов и отмена запросов.
- security/ — идентификация, изоляция клиентов друг от друга, контроль доступа и разрешения на инструменты.
- prompts/ — шаблоны, требования к входным данным, настройки моделей и версии промптов.
- observability/ — трассировка запросов, задержки, ошибки, расход по моделям и стоимость.
- evals/ — версионируемые наборы данных, проверки качества, приёмочные тесты на отложенных данных и выборочная оценка ответов из продакшена.
- tests/ — модульные и интеграционные тесты, проверки безопасности и сценариев сбоев.
- deploy/ — сборки, инфраструктура, проверки работоспособности и безопасная выкатка обновлений.
RAG, агенты, кеширование, вызов инструментов, хранение данных и фоновые обработчики в схеме вынесены в отдельные подключаемые возможности. Продукту с поиском по данным RAG нужен с первого дня, приложению с агентами — инструменты и оркестрация. Остальным — когда появится задача.
Чем эта схема не является
- Не обязательный шаблон. Девять папок в лендинге с одной формой — это лишняя работа. Автор схемы сам заканчивает словами «начинайте с малого».
- Не замена проверкам. Папка evals/ без наборов данных — просто пустая папка.
- Не про конкретный фреймворк. Раскладка одинаково ложится на Python, Node или что угодно ещё.
С чего начать вайб-проекту
Для небольшого продукта на одной модели хватит четырёх зон, остальные появятся сами:
- providers/ — один файл-обёртка над API модели с таймаутом и двумя-тремя повторами. Это первое, что спасает от зависших запросов и позволяет поменять модель в одном месте.
- prompts/ — промпты отдельными файлами, а не строками внутри кода. Когда ответы испортятся, вы увидите, какая правка промпта это сделала.
- observability/ — хотя бы лог: какой промпт, какая модель, сколько токенов, сколько секунд. Без этого счёт за API приходит сюрпризом — сравните с разбором сколько стоят токены.
- evals/ — десять-двадцать реальных вопросов с ожидаемым ответом. Прогоняйте их перед каждой сменой модели или промпта.
security/ становится обязательной в момент, когда у вас появляется второй клиент или агент получает доступ к инструментам. Не раньше, но и не позже.
Почему структура важна для агента, который пишет код
Свежий бенчмарк CABRA от Microsoft показал: кодовые агенты хорошо справляются, когда нужное можно найти поиском, и ломаются, когда похожая логика разбросана по разным местам и написана по-разному. Чёткие зоны ответственности — ровно то, что делает код находимым. Ретраи лежат в providers/, значит агент поправит их в одном месте, а не в каждом вызове модели.
Опишите раскладку в AGENTS.md: одна строка на папку, что в ней лежит. Это дешевле, чем каждый раз заставлять агента читать дерево проекта.
Пример: панель с ИИ-функциями
Возьмём продукт вроде TG Lead Finder, где ИИ генерирует комментарии и ответы. Выбор модели и ключи — в providers/. Шаблоны комментариев и ответов — в prompts/ с версиями. Лимиты на аккаунт и бюджет на запросы — в application/. Расход токенов по задачам — в observability/. Набор эталонных постов, на которых проверяется качество комментариев, — в evals/. Смена модели тогда становится правкой одного файла и прогоном evals, а не неделей поиска.
Коротко
Схема из девяти зон — api, application, providers, security, prompts, observability, evals, tests, deploy — плюс подключаемые RAG, агенты и кеш. Она не решает проблемы сама, а даёт им места в коде. Вайб-проекту для старта хватит providers, prompts, observability и evals; остальное добавляйте, когда этого требует продукт. Бонус — код, удобный для агента: как это работает, видно по CABRA.