openrouter без переписывания интеграции: матрица выбора модели и клиента до замены API

Дальше не отчёт о прогоне, а формат проверки: CSV-матрица «сценарий×клиент×модель» с версией клиента, датой прогона, ссылкой на лог и ссылкой на документацию в каждой строке. По такой строке, а не по названию API, и принимают решение: менять модель без переписывания клиента или нет.

Тезис, который стоит оспорить: единый API сам по себе гарантирует переносимость. Документация OpenRouter прямо говорит обратное: описанные интерфейсы не доказывают, что каждый клиент, модель, парсер стрима и путь ошибки ведут себя одинаково в одном конкретном развёртывании (OpenRouter, доступ 2026-07-18). Отсюда рабочее правило: если хотя бы один критичный слой не подтверждён датированным прогоном, замену модели без переписывания клиента нельзя считать доказанной.

Каталог отвечает на вопрос «доступна ли модель». Клиент отвечает на другой: совпадает ли контракт запроса и ответа в тех сценариях, которые у тебя в проде. Это разные утверждения, и второе не выводится из первого.

OpenRouter описывает схему запроса и ответа как очень похожую на OpenAI Chat API, с некоторыми отличиями, и говорит, что нормализует схемы между моделями и провайдерами (OpenRouter, доступ 2026-07-18). «Похожую» и «с отличиями» не значит «идентичную». Нормализация снижает разброс, но именно отличия режут интеграцию: клиент писался под одну конкретную форму ответа, а не под «в целом похожую».

Это верно и для агрегаторов вроде provod.ai, которые открывают доступ к каталогу моделей через один API: широкий каталог сам по себе не подтверждает, что твой клиент прочитает ответ конкретной модели так, как этот клиент ожидает.

Когда ищут open router ai или просто openrouter, за формулировкой обычно стоит один и тот же вопрос техлида: можно ли переключить модель, не трогая существующий клиент. Отвечает на него не запись в каталоге, а прогон конкретного сочетания: его и собирает матрица.

Здесь работает разделение уверенности. Установленным фактом можно считать только то, что подтверждено первичной документацией и датированным прогоном. Вероятным остаётся то, что совместимый клиент потребует меньшей адаптации в уже подтверждённых сочетаниях. Неизвестным до прогона остаётся поведение конкретной версии клиента, модели и канала. Эту границу нельзя стирать: она отделяет план проверки от рекламы бесшовной миграции.

Первый слой: параметры. Проверяешь, доходят ли до модели поля запроса, на которые опирается клиент, и как передаётся фолбэк. Массив models в документации объявляет резервные модели в порядке приоритета; задокументированные триггеры переключения: ошибки длины контекста, флаги модерации, лимиты и недоступность (OpenRouter, доступ 2026-07-18). Важная деталь контракта: с OpenAI SDK массив models передают через extra_body, а в Anthropic Messages API это отдельный параметр fallbacks, который нельзя комбинировать с models (OpenRouter, доступ 2026-07-18). Один и тот же замысел фолбэка выражается двумя разными способами в зависимости от клиента, и это именно то место, где переносимость ломается на уровне параметров.

Второй слой: обычный ответ. Проверяешь, что клиент читает нестримовый ответ в ожидаемой форме: поля, порядок, наличие usage. Сюда же относится структурированный вывод: он использует переданную JSON Schema и работает только с совместимыми моделями, а несовместимая модель или невалидная схема дают ошибку (OpenRouter, доступ 2026-07-18). Строка «структура» в матрице может быть подтверждена для одной модели и провалена для соседней при том же клиенте.

Третий слой: стрим. Стриминг работает через Server-Sent Events; документация предупреждает, что keep-alive комментарии не являются JSON-нагрузкой, а финальный чанк может содержать данные usage (OpenRouter, доступ 2026-07-18). Наивный парсер, который пытается распарсить каждую строку как JSON, споткнётся о keep-alive; тот, кто не дочитывает поток до конца, потеряет usage из последнего чанка. Оба дефекта не видны в каталоге и всплывают только на прогоне.

Четвёртый слой: ошибка, и здесь самый неочевидный факт контракта. До старта стрима сбой сохраняет HTTP-статус ошибки, и фолбэк-роутинг может повторить запрос на другой эндпоинт. Но как только начался частичный вывод, ответ HTTP 200 уже зафиксирован, и сбой обязан прийти внутри потока (OpenRouter, доступ 2026-07-18). Обработчик ошибок должен уметь читать сбой из тела стрима, а не только из статус-кода. Отдельно стоят канонические категории ошибок: ответы с HTTP 429 или 503 могут включать стандартный заголовок Retry-After (OpenRouter, доступ 2026-07-18).

Эти четыре слоя и есть предмет проверки. Каталог не трогает ни один из них.

Матрица: CSV-таблица «сценарий×клиент×модель», где каждая строка несёт версию клиента, дату прогона, ссылку на лог и ссылку на раздел документации. Без этих четырёх реквизитов строка не считается доказательством: статус нельзя воспроизвести и нельзя привязать ко времени.

Минимальный формат такой:

Три статуса, и только три. «Подтверждено»: есть датированный прогон и лог, поведение совпало с ожидаемым по документации. «Не подтверждено»: прогон был, но результат разошёлся с контрактом клиента. «Не проверено»: прогона не было, и строка не даёт права на решение. Смешивать «не проверено» с «подтверждено по аналогии» нельзя: каталог как раз и провоцирует такую подмену.

Смена клиента показывает, зачем нужна колонка клиент. Тот же замысел фолбэка на OpenAI SDK кодируется через extra_body с массивом models, а в Anthropic Messages API это отдельный параметр fallbacks, несовместимый с models (OpenRouter, доступ 2026-07-18). Значит строка «параметры» для одного клиента ничего не говорит про другого, и обе строки нужны в матрице отдельно.

Механически смена каталога сводится к смене ключа и base_url, и это тот шаг, который единый API делает дешёвым. OpenRouter документирует настройку OpenAI SDK как смену базового URL на ` и подстановку своего ключа (OpenRouter, доступ 2026-07-18). Тот же приём работает для любого OpenAI-совместимого каталога:

Смена двух строк подключает каталог, но не закрывает ни одной строки матрицы: extra_body с массивом models доедет только если целевой клиент и канал реально принимают этот механизм фолбэка, а это отдельная строка слоя «параметры».

Для команды, которая тестирует такой стенд из России, у прямого использования OpenRouter есть трение: обычно нужны иностранная карта и VPN. provod.ai (российский OpenRouter), рыночная аналогия по функции агрегатора, а не филиал или партнёр OpenRouter, даёт тот же принцип подключения: смена ключа и base_url на эндпоинт, совместимый с OpenAI и Anthropic SDK. Оплату при этом можно провести в рублях: картой российского банка, через СБП или по счёту, без VPN. Это снимает финансовое трение прогона, но не отменяет ни одной строки матрицы: слои проверяешь ты.

Самый частый провал живёт не в счастливом пути, а в обработке сбоя посреди стрима. Разбери его как отдельную строку матрицы: клиент, написанный под «ошибка = ненулевой HTTP-статус», молча деградирует.

Логика такая. До первого байта потока сбой ведёт себя как обычная HTTP-ошибка: статус сохраняется, и фолбэк-роутинг может повторить запрос на другой эндпоинт (OpenRouter, доступ 2026-07-18). Но как только пошёл частичный вывод, ответ HTTP 200 уже зафиксирован, и сбой обязан прийти внутри тела стрима (OpenRouter, доступ 2026-07-18). Если парсер закрывает соединение по успешному статусу и не смотрит в тело, оборванный ответ примут за валидный.

Рядом стоит политика повторов. Ответы с HTTP 429 или 503 могут нести стандартный заголовок Retry-After (OpenRouter, доступ 2026-07-18). Клиент, который ретраит по фиксированному собственному бэкоффу и игнорирует заголовок, либо долбит канал, либо ждёт дольше нужного. Провайдерский роутинг умеет приоритизировать явный порядок провайдеров и предпочитать эндпоинты по порогам латентности или пропускной способности; эндпоинты вне порогов остаются как фолбэк (OpenRouter, доступ 2026-07-18). Но это поведение канала, а не гарантия того, что клиент правильно прочитает его исход. Строки «ошибка» и «стрим» поэтому проверяют вместе: сбой в потоке относится сразу к обоим слоям.

Решение опирается на статус слоёв в конкретной строке, а не на обещание каталога. Ниже таблица, которая связывает слой, проверяемый факт и критерий «подтверждено».

Правило простое: менять модель без переписывания клиента можно только для строки, где все критичные слои в статусе «подтверждено» на свежую дату. Компромисс здесь спорный: матрица замедляет старт миграции, зато делает объём адаптации наблюдаемым до релиза, а не после инцидента. Альтернативы хуже. Переключить по заявленной совместимости значит принять решение по каталогу, который четыре слоя не проверяет. Переписать клиента заранее значит заплатить за адаптацию, которая, возможно, не нужна для уже подтверждённых сочетаний.

Строку отклоняешь, если у неё нет версии, даты, лога или ссылки, либо если не проверен хотя бы один из четырёх слоёв. Это и есть критерии отбраковки, встроенные в формат.

Каждый шаг про воспроизводимость. Если прогон нельзя повторить или если версии клиента, модели или контракт API изменились, статус аннулируется и строку гонишь заново.

Матрица не переносит статус между версиями. Подтверждённая строка от 2026-07-18 перестаёт быть доказательством, как только сменилась версия клиента, модели или контракт API. Возможности моделей, версии клиентов, доступность провайдеров, поведение роутинга, лимиты и форматы ошибок меняются, и каждый результат живёт со своей датой.

Матрица также не заменяет нагрузочную и security-проверку. Совпадение контракта в пяти функциональных сценариях ничего не говорит о поведении под нагрузкой и о безопасности: это отдельные проверки с отдельными критериями. Из документации OpenRouter нельзя вывести латентность, аптайм, экономию, безопасность или процент успешной миграции: таких чисел в источниках нет, и подставлять их ради красоты нельзя.

Достаточно ли того, что API описан как «совместимый с OpenAI»? Нет. OpenRouter сам описывает свою схему как очень похожую на OpenAI Chat API, с отличиями, и оговаривает, что интерфейсы не доказывают идентичного поведения каждого клиента и модели в одном развёртывании (OpenRouter, доступ 2026-07-18).

Можно ли перенести статус на соседнюю модель? Не полностью: структурированный вывод, например, работает только с совместимыми моделями (OpenRouter, доступ 2026-07-18), поэтому строку «структура» проверяют для каждой модели отдельно.

Почему ошибку выделили в отдельный слой? Потому что до старта стрима сбой приходит статусом, а после начала вывода сбой приходит в теле потока, а не статусом, потому что HTTP 200 уже зафиксирован (OpenRouter, доступ 2026-07-18). Это два разных пути в коде.

Как учитывать Retry-After? Учитывать на 429 и 503, где заголовок может присутствовать (OpenRouter, доступ 2026-07-18), вместо фиксированного собственного бэкоффа.

Собери матрицу на своём стенде. Канал для прогонов можно взять готовый: подключи provod.ai по одному ключу и base_url, оплати с рублёвого баланса и прогони каталог через один эндпоинт, совместимый с OpenAI и Anthropic SDK. А решение о замене модели прими по подтверждённой строке матрицы, а не по названию API.

Храните документы и поиск у себя, а модель выбирайте по задаче: качество ответа можно улучшать без переноса базы знаний и переписывания всей RAG-системы под нового вендора.

В одном каталоге — актуальные модели для текста и медиа: GPT от OpenAI, Claude от Anthropic, Gemini от Google, Grok от xAI, DeepSeek, Qwen, GLM, Kimi и MiniMax; для изображений — Nano Banana 2 Pro и GPT Image; для видео — последние версии Seedance, Kling, Veo и Google Omni. Также доступны модели для reasoning, поиска, документов, эмбеддингов, музыки и аудио.

Эксперименты с моделями не оплачиваются через лишнюю маржу роутера: тариф каждого провайдера передаётся 1:1, без наценки provod.ai.

Подключите модели к своей базе знаний: форма регистрации · цены на модели · защита данных по 152-ФЗ · API и интеграции