Слой абстракции

Слой абстракции — это принадлежащий вам код между приложением и внешней зависимостью, выставляющий интерфейс, описанный в ваших терминах. Приложение вызывает ваш интерфейс, а слой переводит вызов в то, что ожидает текущий провайдер. Никакой магии здесь нет: слой просто собирает знание о провайдере в одном месте вместо того, чтобы размазывать его по кодовой базе. Чаще всего называют выгоду переносимости — она настоящая, но её обычно преувеличивают. Слой превращает смену провайдера в проект с границами, а не в бесконечный, потому что код, знающий о поставщике, перечислим. Бесплатной замену он не делает: различия в поведении, качестве и семантике ошибок всё равно придётся обработать, а это не то, что способен поглотить интерфейс. Реже всего называют как раз те выгоды, которые окупают слой в первый же месяц. Единственное место, где добавляются повторы, таймауты, обработка лимитов и размыкатель цепи. Единственное место, где однообразно пишутся логи запросов и стоимость. Единственное место, куда подставляется тестовый двойник, — а это разница между быстрым набором тестов и тем, который ходит в платный API. И единый словарь вашей предметной области вместо вендорского, чтобы остальной код читался как ваш продукт, а не как чей-то SDK. Проектная ошибка, которой стоит избегать, — абстрагировать не на том уровне. Слой, повторяющий API провайдера один в один, не даёт ничего: ваш интерфейс меняется всякий раз, когда меняется их. Слой, моделирующий ваш сценарий — «сократи этот документ», «классифицируй это обращение», «ответь на вопрос вот по этим источникам», — оставляет вам свободу менять способ исполнения. Правильный шов — это возможность вашего продукта, а не форма чужой конечной точки. Для ИИ-зависимостей слою стоит владеть всей конфигурацией, а не только вызовом. Промпт, версия модели, параметры сэмплирования, описания инструментов, настройки поиска и схема вывода принадлежат друг другу, потому что поведение — произведение их всех. Именно эта группировка позволяет версионировать поведение как один артефакт, прогонять по нему оценку и откатывать без правки кода. Стоимость стоит назвать честно. Любая абстракция — это код, который надо сопровождать, место, где функции задерживаются, потому что сперва должен вырасти интерфейс, и соблазн построить фреймворк, которого никто не просил. Соразмерная версия — тонкая, написанная под те две-три операции, которые вы действительно выполняете, и расширяемая только при появлении второго настоящего применения, а не спроектированная заранее под всё, что провайдер когда-нибудь может предложить.