Почему смена model ID - полноценная миграция
Две модели могут принимать похожий массив сообщений, но по-разному следовать инструкциям, вызывать инструменты, считать токены, возвращать JSON, обрабатывать изображения и отказываться от ответа. Даже новая версия того же семейства способна изменить длину, стиль и частоту tool calls.
Поэтому изменение model рассматривают как production-релиз со спецификацией, тестами, ограниченным rollout и rollback. Главная метрика - не победа в публичном benchmark, а качество конкретного workflow.
Причины миграции и разные критерии успеха
| Причина | Главный критерий | Скрытый риск |
|---|---|---|
| Deprecation | Завершить до shutdown | Сжатое окно проверки |
| Снижение стоимости | Cost per success | Больше повторов и ручной работы |
| Новая capability | Надёжность функции | Preview lifecycle |
| Снижение latency | P95 end-to-end | Регрессия сложных кейсов |
| Смена провайдера | Функциональная и policy-совместимость | Data residency и API semantics |
Запишите причину и deadline до выбора кандидата. Иначе команда будет оптимизировать разные показатели и не сможет принять решение.
Шаг 1. Инвентаризация всех зависимостей от модели
Модель редко изолирована. Её поведение зависит от prompt bundle, SDK, response schema, tool definitions, retrieval, параметров генерации и логики повторов.
- Все model IDs, aliases, regions и endpoints.
- System/developer prompts и few-shot examples.
- Input/output schemas и validators.
- Tools, права, side effects и approvals.
- RAG pipeline, embeddings и context limits.
- Temperature, output limit и reasoning controls.
- Streaming, batch, cache и file APIs.
- Rate limits, quotas, retries и timeouts.
- Data retention, residency и договорные ограничения.
- Evals, dashboards, alerts и владельцы.
Шаг 2. Зафиксируйте воспроизводимый baseline
Перед тестом кандидата сохраните текущую production-версию: точный model ID, SDK, prompt version, schemas, параметры и retrieval index. Соберите качество, критические ошибки, стоимость успешной задачи и latency на репрезентативном периоде.
Workflow: [название] Current model ID: [точная версия] Prompt / schema / retrieval versions: [ID] Traffic period and cohorts: [границы] Success definition: [критерий] Quality metrics: [список] Critical errors: [список] P50/P95 latency: [данные] Cost per successful task: [данные] Retry, fallback, handoff rates: [данные] Known limitations and incidents: [ссылки]
Alias вроде latest не является воспроизводимым baseline, если его цель может измениться без вашего релиза. Для production полезна закреплённая версия и управляемый alias внутри системы.
Шаг 3. Постройте compatibility matrix
Матрица превращает фразу «API совместим» в список проверяемых требований. Статус должен быть не только yes/no, но и native, adapter, unsupported или unknown.
| Область | Проверить | Доказательство |
|---|---|---|
| Messages | Роли, порядок, system semantics | Contract tests |
| Structured output | Подмножество JSON Schema | Schema suite |
| Tools | Arguments, parallel calls, IDs | Tool eval |
| Multimodal | Типы, размеры, порядок parts | Media cases |
| Long context | Фактическое качество retrieval | Needle и domain eval |
| Operations | Streaming, cancel, batch, cache | Integration tests |
| Policy | Region, retention, training terms | Approved documentation |
Модельные версии: stable, preview и floating aliases
Провайдеры используют разные стадии lifecycle. Google документирует stable, preview, latest и experimental identifiers: production-приложениям обычно подходит конкретная stable-версия, тогда как latest может переключаться. У других API правила именования и сроки иные.
- Не делайте preview единственным production route без плана замены.
- Подпишитесь на release notes и deprecation notices.
- Храните owner и replacement deadline для каждой модели.
- Проверяйте дату shutdown на официальной странице, а не в старой статье.
- Разделяйте технический deadline и более ранний внутренний deadline.
Модельные сроки и рекомендованные замены меняются, поэтому в статье нет статической таблицы будущих shutdown-дат.
Шаг 4. Соберите репрезентативный eval-набор
Публичные benchmarks помогают сформировать shortlist, но не проверяют вашу схему, язык, документы и ошибки. Набор должен отражать распределение production-трафика и отдельно усиливать критические края.
Golden
Проверенные типовые случаи.
Regression
Прошлые production-сбои.
Critical
Риски, права и действия.
Храните provenance, разрешение на использование, вход, критерии, ожидаемые обязательные свойства и severity ошибки. Не копируйте клиентские данные без основания.
Шаг 5. Сравнивайте парно на одних и тех же входах
Каждый test case отправляется текущей и кандидатной конфигурации с фиксированными версиями. Результаты сравнивают автоматические validators, domain rules и при необходимости слепые экспертные оценки.
Составь paired evaluation для миграции [current] → [candidate]. Зафиксируй одинаковые входы и версии prompt/schema/retrieval. Для каждого кейса оцени: - обязательные факты и формат; - critical errors; - grounding и citations; - tool choice и arguments; - допустимый отказ; - latency и все попытки; - стоимость успешного результата. Раздели результаты по cohorts и сложности. Не объединяй критическую ошибку со средним баллом.
Нестабильность ответа: один прогон может быть недостаточен
Генеративная система может давать разные ответы. Для критичных или пограничных кейсов проведите несколько запусков по заранее заданному протоколу. Сравнивайте не красивый лучший пример, а вероятность прохождения критериев и тяжесть отказов.
- Фиксируйте параметры генерации и доступный seed, если он поддерживается, но не считайте seed гарантией идентичности.
- Отдельно измеряйте schema validity и бизнес-корректность.
- Не ретрайте ответ до тех пор, пока он случайно не станет хорошим.
- Учитывайте все попытки в стоимости и latency.
- Анализируйте разницу по сегментам, а не только общий average.
Prompt portability: сначала сохраняйте контракт, не формулировки
Промпт, оптимизированный под одну модель, может быть избыточен или неоднозначен для другой. Сначала зафиксируйте неизменяемый контракт задачи: входы, обязательные свойства результата, источники, запреты и допустимый отказ. Затем создайте кандидатную реализацию prompt.
| Слой | Сохранять | Можно адаптировать |
|---|---|---|
| Business contract | Критерий успеха и риски | Нет |
| Output schema | Поля downstream | Только версионированно |
| Prompt wording | Смысл ограничений | Формулировка и порядок |
| Examples | Покрываемые случаи | Формат представления |
| Provider options | Целевое поведение | Названия и значения |
Tool calling: самая опасная зона несовместимости
Модели отличаются выбором инструмента, форматом arguments, параллельностью и продолжением после tool result. Для каждого tool проверяйте выбор, обязательные параметры, лишние вызовы, повтор side effect и реакцию на ошибку.
- Tool schema поддерживается candidate API.
- Arguments проходят строгую validation.
- Неизвестные поля отклоняются или безопасно игнорируются.
- Side effects имеют idempotency key.
- Рискованные tools требуют approval.
- Цикл ограничен шагами, временем и бюджетом.
- Ошибки tool не вызывают бесконечный retry.
- Parallel calls не нарушают порядок операций.
Structured output: совместимый JSON ещё не означает верные данные
Кандидат может лучше проходить JSON Schema, но чаще заполнять поля недоказанными значениями. Разделите уровни проверки: синтаксис, schema, cross-field invariants, grounding и бизнес-правила.
Schema
Типы и обязательные поля.
Invariant
Связи полей и диапазоны.
Grounding
Значение подтверждено источником.
Embeddings и RAG мигрируют отдельно
Замена embedding-модели меняет геометрию векторов. Старые и новые embeddings нельзя считать взаимозаменяемыми в одном индексе без доказательства. Обычно нужен новый versioned index, повторная индексация и сравнение retrieval.
- Создайте параллельный индекс с новым namespace.
- Сравните recall@k и downstream answer quality.
- Проверьте chunking, dimensionality и distance metric.
- Сохраните связь chunk с исходной версией документа.
- Переключайте retrieval alias через canary.
- Удаляйте старый индекс после rollback window.
Shadow traffic: реальная нагрузка без реальных действий
В shadow-режиме production-вход копируется candidate pipeline, но ответ не показывается пользователю и не управляет бизнес-процессом. Любые tool side effects должны быть отключены, заменены sandbox-реализациями или записаны как намерение.
- Есть правовое основание передавать данные candidate provider.
- Секреты и лишние поля редактируются.
- Side effects физически заблокированы.
- Shadow не конкурирует за критическую quota.
- Трафик семплируется по репрезентативным cohorts.
- Ответы связаны парным trace ID.
- Дополнительная стоимость ограничена бюджетом.
- Retention и удаление результатов задокументированы.
Canary rollout: стабильный cohort и заранее заданные ворота
После offline и shadow-проверки кандидат получает небольшую долю реальных запросов. Cohort должен быть стабильным: один пользователь или workflow не должен хаотично переключаться между версиями внутри связанного сценария.
| Ворота | Продолжить | Остановить |
|---|---|---|
| Critical errors | Не хуже допуска | Любое нарушение hard limit |
| Success rate | Выше quality floor | Статистически и practically хуже |
| P95 latency | В пределах SLO | Нарушает user journey |
| Cost/success | В пределах бюджета | Экономия запроса ухудшила результат |
| Fallback/retry | Без аномалии | Системный рост |
Наблюдаемость: версия модели должна быть на каждом trace
Для сравнения логируйте alias, фактический model ID, provider, region, prompt/schema/retrieval versions, route reason, tokens, latency, retries, fallback и итог validators. Срезы нужны по cohort и классу сложности.
Migration dashboard: - traffic by current/candidate; - success and critical errors by cohort; - schema/tool/grounding failures; - abstain and human handoff rate; - input/cached/output tokens; - cost per successful task; - P50/P95 latency; - retries, fallback and timeout; - incident links and release markers. Не выводи только среднее: показывай объём и доверительный интервал.
Rollback должен работать без нового deploy
Rollback - переключение versioned alias или feature flag на проверенную конфигурацию. Он возвращает не только model ID, но и совместимые prompt, schema, tools, retrieval и параметры.
- Предыдущий bundle immutable и доступен.
- Alias переключается за целевое время.
- Кэш ключуется версией и не смешивается.
- In-flight requests имеют определённое поведение.
- Новая schema не повредила необратимо stored data.
- Старые credentials ещё действуют в rollback window.
- On-call знает stop conditions и команду отката.
- После отката подтверждаются метрики восстановления.
Миграция из-за deprecation: календарь обратного планирования
Официальное уведомление о deprecation означает, что endpoint будет выведен из эксплуатации по правилам провайдера. Не планируйте завершение на дату shutdown. От неё отнимите production observation, canary, shadow, offline eval, исправления, procurement и security review.
Deadline
Внутренний раньше внешнего shutdown.
Evidence
Evals и canary требуют времени.
Exit
Старый route удаляется после окна отката.
Что делать после полного переключения
100% трафика не завершает миграцию. Наблюдайте полный бизнес-цикл: отложенная оценка, жалобы и ручные исправления могут появиться позже. Затем закройте временную инфраструктуру.
- Продолжайте усиленный monitoring в заданное окно.
- Проведите повторный анализ по редким cohorts.
- Добавьте найденные сбои в regression suite.
- Обновите runbooks, ADR, каталог моделей и владельцев.
- Отзовите ненужные provider keys и доступы.
- Удалите shadow data по retention policy.
- Архивируйте baseline и decision report.
- Назначьте дату следующей проверки lifecycle.
Итоговый чек-лист безопасной миграции
- Причина, owner и внутренний deadline определены.
- Все зависимости и data flows инвентаризированы.
- Текущий baseline воспроизводим.
- Compatibility matrix заполнена доказательствами.
- Eval-набор версионирован и репрезентативен.
- Critical errors отделены от среднего score.
- Tools, schemas, multimodal и RAG проверены отдельно.
- Shadow блокирует side effects и соблюдает data policy.
- Canary использует стабильный cohort.
- Quality floor и stop conditions утверждены заранее.
- Cost per success и P95 входят в решение.
- Rollback возвращает весь совместимый bundle.
- Откат отрепетирован до rollout.
- После 100% предусмотрено окно наблюдения.
- Старые доступы удаляются только после закрытия окна.
Безопасная миграция не обещает идентичность моделей. Она делает различия видимыми, измеряет их на ваших задачах и ограничивает последствия ошибки.