Behavioural API contract — почему pin модели не защищает от тихих поломок
Саммари
Документированный API — это то, что провайдер обещает в письменном: эндпоинты, параметры, лимиты, changelog. Реальная зависимость приложения — это поведенческий API-контракт, то есть всё наблюдаемое в ответах модели, на что опирается ваш код, ваши промпты и ваши парсеры. Работа показывает, что модельные версии нумеруются по возможностям, а не по семантике совместимости, поэтому минорный апгрейд 5 → 5.1 приходит с ломаными изменениями, и pin версии этого не предотвращает.
Из этого следует: changelog и страница цен не являются контрактом для вашей системы. Контракт — это список ваших наблюдаемых зависимостей, и его надо вести явно, иначе о нём узнаёшь по факту поломки.
На практике для Revit-инструментов: зависимость от поведения модели у нас обычно неявная — промпт рассчитан на конкретный стиль ответа, парсер ждёт конкретный формат. Это ровно класс «поведенческий контракт», который надо описать и проверять статистически.
Важный нюанс: тихая поломка опаснее громкой не из-за масштаба, а из-за стоимости обнаружения. Пять пунктов pass rate дешевле поймать регрессией, чем заметить в проде.
Второй нюанс: правило трёх для детерминированных инвариантов означает, что большую часть контракта можно проверять дёшево и часто. Дорогие статистические проверки нужны лишь для немногих инвариантов — значит, полный набор тестов реалистичен.
Третий нюанс: pin не защищает, но и не бесполезен — он переносит риск с непрерывно плавающего поведения на один дискретный эпизод миграции. Это лучше, чем дрейф, но требует процедуры на этот эпизод.
Четвёртый нюанс: откат разговора на более старую модель тихо отбрасывает блок рассуждения. Это специфический класс поломки, о котором не думают: многоагентные системы с fallback-маршрутизацией должны проверять, что «дешёвая» ветка вообще может прочитать контекст предыдущей.