Совместимость OpenAI SDK после замены base_url в проде

Почему проблемы всплывают не сразу

После замены base_url совместимость почти всегда выглядит лучше, чем есть на самом деле. Команда меняет адрес, отправляет один chat-запрос, получает ответ и закрывает задачу. Но один удачный ответ ничего не гарантирует.

Первая причина простая: SDK прячет часть поведения. Таймауты, ретраи, чтение stream-ответа и реакция на обрыв соединения часто настраиваются не там, где разработчик смотрит в первую очередь. Пока запрос короткий, модель отвечает быстро, а сеть спокойная, эти детали не видны. Как только ответ идет дольше обычного, клиент вдруг повторяет запрос, ждет меньше, чем вы рассчитывали, или обрывает поток раньше, чем шлюз успевает его закончить.

Есть и второй слой. OpenAI-совместимый API не значит одинаковое поведение во всех деталях. Шлюз, провайдер и сама модель могут по-разному делить ответ на чанки, завершать stream, считать таймаут простоя и возвращать служебные поля. Снаружи схема одна и та же. На практике мелкие расхождения быстро ломают код, который раньше работал без шума.

Хороший пример обычно выглядит слишком скучно, поэтому его пропускают. Команда меняет base_url на api.rullm.com, гоняет пару запросов с ноутбука и видит, что все в порядке. Через неделю в проде появляются длинные ответы, параллельные запросы, embeddings для батчей и вызовы инструментов. И тут всплывает то, чего локально не было: один запрос висит дольше, другой приходит кусками с паузой, третий упирается в скрытый лимит клиента.

Локальный тест почти всегда слишком чистый. В нем нет очереди, нет десятков одновременных пользователей, нет длинных сессий и редких сетевых сбоев. Под нагрузкой мелкие различия перестают быть мелкими. Они накапливаются и проявляются не в первом запросе, а в пятом, пятидесятом или во время вечернего пика.

Где искать расхождения

Проблема редко живет в одном месте. После замены base_url первый запрос часто проходит нормально, и команда решает, что проверила совместимость. Обычно это ложное спокойствие. Смотреть нужно не на SDK "в целом", а на те методы и форматы, которые продукт реально вызывает каждый день.

Сначала зафиксируйте версию SDK. Иначе вы будете сравнивать сразу две переменные: новый шлюз и новое поведение клиента. Это частая ошибка. Один и тот же код на соседних версиях SDK может по-разному обрабатывать streaming, retries, сериализацию tool calls и поля ответа.

Дальше разложите проверку на несколько поверхностей. Отдельно проверьте chat или responses, если они уже живут в проде. Отдельно проверьте embeddings, если на векторах держатся поиск, RAG или дедупликация. Если у вас есть вызовы функций, тестируйте tool calls сами по себе, а не вместе с обычным текстовым ответом. И отдельно зафиксируйте, в каком виде приходит результат: SSE, JSON целиком или обычный HTTP-ответ без потока.

Особенно важно выписать, где клиент ждет SSE, а где обычный JSON. На словах "OpenAI-совместимый API" звучит просто, но в реальном коде один участок читает события по кускам, другой ждет готовый объект, а третий смотрит только на status code и тело ошибки. Если эти ожидания нигде не описаны, баги могут прятаться очень долго.

Хороший рабочий документ содержит не только endpoint и модель. В нем стоит зафиксировать, что именно вызывает клиент, какие поля он читает, какой finish_reason считает нормальным и как ведет себя код при 4xx и 5xx.

На ошибках различия видны быстрее всего. Один клиент ждет JSON с code и message, другой парсит вложенный error, третий решает, делать ли ретрай, по типу исключения внутри SDK. То же самое с finish_reason: если оркестратор понимает только stop, а получает другой маркер завершения, цепочка ломается не в модели, а в бизнес-логике.

Если команда переводит трафик на api.rullm.com без смены SDK и кода, такой список экономит много часов. Он сразу показывает, что нужно проверить руками, а что легко закрыть контрактным тестом.

Как проверить интеграцию по шагам

Самая частая ошибка после замены base_url - смотреть только на итоговый текст ответа. Так легко пропустить вещи, которые ломают прод позже: другой формат stream-событий, пустые поля в tool calls, лишние задержки на длинных запросах или неожиданный размер вектора в embeddings.

Если вы переводите трафик, например, со старого провайдера на OpenAI-совместимый шлюз вроде api.rullm.com, не меняйте сразу весь контур. Возьмите один и тот же набор запросов и прогоните его параллельно через старый и новый base_url. Параметры должны совпадать: модель, temperature, сообщения, tools, размер батча и режим ответа.

Для первого прохода хватает пяти сценариев:

1. Короткий chat-запрос без stream.
2. Длинный запрос с большим контекстом.
3. Тот же сценарий в stream-режиме.
4. Набор embeddings на реальных текстах, а не на тестовой строке из двух слов.
5. Запрос с tool calls, где модель точно должна вызвать функцию.

Для каждого прогона сохраняйте сырые ответы целиком. Нужны не только текст и request id, но и HTTP-код, заголовки, время до первого байта, полное время ответа и порядок чанков в stream. Если оркестратор падает редко, именно эти данные обычно и показывают причину.

С embeddings многие проверяют только то, что запрос не упал. Этого мало. Сравните размерность векторов, тип чисел, порядок элементов в массиве и поведение на пустых или почти одинаковых строках. Иначе проблема всплывет позже, когда поиск начнет давать странную выдачу.

С tool calls важна структура. Проверьте имя функции, аргументы в JSON, признак завершения ответа и то, как SDK отдает вызовы в обычном и stream-режиме. Если текст ответа выглядит похожим, а нужное поле лежит в другом месте, ваш код может сломаться молча.

Хороший тест заканчивается не фразой "вроде работает", а папкой с двумя наборами сырых артефактов и понятной разницей между ними.

Таймауты без путаницы

После смены base_url многие думают, что таймаут один. На деле их как минимум три. Connect timeout отвечает за установление соединения. Read timeout - за ожидание следующего байта ответа. Отдельно нужен общий deadline, после которого запрос уже не имеет смысла держать.

Эти значения рвут запрос в разных местах. Слишком короткий connect timeout убивает вызов еще до модели. Слишком короткий read timeout чаще бьет по streaming и длинной генерации, когда токены идут неравномерно. А без общего deadline сервис может ждать дольше, чем позволяет логика продукта.

Если вы перевели код на api.rullm.com и сохранили тот же OpenAI SDK, проверьте всю цепочку, а не один параметр timeout. Ошибка часто сидит в одном из четырех узлов: в SDK, в HTTP-клиенте под ним, в прокси или ingress, либо у провайдера, который реально исполняет запрос.

Значения по умолчанию лучше менять только после замера. У одного клиента они переживут обычный chat completion, но сломают stream на сороковой секунде. У другого все пройдет в тесте, а в проде повторные попытки просто удвоят время ожидания, потому что каждый retry стартует с тем же лимитом.

Измеряйте не средний запрос, а несколько отдельных сценариев: короткий ответ, длинную генерацию, stream и запрос с retry. Это дает нормальную картину. Например, длинный нестриминговый ответ может укладываться в 70 секунд, а stream спокойно жить 3 минуты без ошибки, если read timeout считает только паузу между чанками, а не все время с начала запроса.

Практика здесь простая: задайте явный общий deadline на уровне сервиса, отдельно выставьте connect timeout, а read timeout подберите под самый длинный ожидаемый ответ. Потом проверьте, что прокси и балансировщик не режут соединение раньше. Если ingress закрывает запрос через 60 секунд, настройка SDK это не исправит.

Streaming без ложных ожиданий

Самая неприятная ошибка в streaming появляется тихо: первый токен приходит, и кажется, что совместимость есть. Но сбои часто сидят в деталях SSE-потока. После замены base_url проверяйте не только сам факт стриминга, а форму событий до самого конца.

Сначала смотрят на порядок чанков. Клиент нередко ожидает, что в начале придет role, потом пойдут куски content, а в финале появится событие с finish_reason. На практике шлюз, провайдер или модель могут отдавать это чуть иначе. Если код жестко привязан к одному порядку, он начнет терять текст, дважды закрывать поток или зависать в ожидании финального маркера.

Проверка простая: сохраните сырой SSE-поток целиком, сравните delta, role, content и finish_reason по чанкам, а потом убедитесь, что финальное событие вообще приходит и что UI с бэкендом одинаково трактуют конец ответа.

Отдельная ловушка - обрыв SSE. Соединение может порваться после 80 процентов ответа, и SDK не всегда ведет себя так, как вы ожидаете. Один клиент вернет частичный текст, другой выбросит исключение, третий попробует читать дальше и зависнет. Это лучше решить заранее: показываете ли вы пользователю уже полученный фрагмент, перезапускаете ли запрос или помечаете ответ как невалидный.

Еще один частый сбой связан не с текстом, а с tool calls. Модель может начать стримить не content, а структуру вызова инструмента. Если оркестратор ждет обычный текст, он решит, что модель "молчит", хотя та уже отдает аргументы функции по кускам.

В проде это всплывает быстро. Команда меняет base_url на api.rullm.com, первый чат работает, а агент с инструментами ломается только на длинных диалогах. Причина обычно не в самом streaming, а в том, что клиент слишком уверенно предположил форму потока.

Embeddings и размерность векторов

С embeddings чаще ломается не запрос, а индекс. Код получает вектор, запись проходит, а потом поиск дает странные результаты, потому что другая модель вернула другую длину.

После замены base_url нельзя считать, что размерность останется прежней. Даже если API выглядит знакомо, конкретная модель у другого провайдера может вернуть вектор другой длины. Иногда меняется и формат ответа: вместо массива float приходит base64, а иногда сервер прямо отвечает ошибкой, если такой формат не поддерживается.

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

Смотрите не только на HTTP 200. Проверьте тип поля embedding, длину вектора, число объектов в data и стабильность размерности между повторами. Если сегодня вы получили 1536, а завтра 3072, векторный индекс этого не переживет.

Особенно часто проблема всплывает в проде, когда старые векторы уже лежат в базе. Индекс не должен смешивать векторы разной длины в одной коллекции. Если вы меняете модель, создайте новый индекс или новую таблицу и переиндексируйте данные отдельно.

На OpenAI-совместимом шлюзе вроде RU LLM это тоже стоит проверить заранее, особенно если вы тестируете несколько моделей и провайдеров через один endpoint. Один и тот же SDK-код может отработать без ошибок, а семантический поиск просядет уже на реальных запросах.

Простой тест экономит много времени: отправьте один и тот же текст пять раз, сохраните длину вектора и первые несколько чисел, затем повторите тест для батча и длинного ввода. Если хоть один из результатов гуляет без понятной причины, индексировать документы рано.

Tool calls, которые ломают оркестратор

Проблемы после замены base_url часто начинаются именно на tool calls. Текстовая генерация еще работает, а оркестратор падает на первом же вызове функции. Обычно причина простая: код ждет один формат ответа, а модель или шлюз отдают другой.

Чаще всего ломаются arguments. Одни модели возвращают их строкой с JSON внутри, другие - уже разобранным объектом. Если оркестратор всегда делает json.loads, он упадет на объекте. Если он всегда ждет объект, то пропустит строку и передаст в функцию мусор. Выглядит как мелочь, но в проде это быстро превращается в цепочку повторных запросов и шумных логов.

Есть еще несколько мест, где несовпадения видны сразу. tool_choice может вести себя по-разному при auto, принудительном выборе инструмента и полном запрете вызовов. Несколько вызовов подряд не все обработчики умеют собирать в правильном порядке. Пустой список tools одни клиенты считают нормой, а другие - некорректным запросом. finish_reason для вызова инструмента тоже может прийти не там, где код его ждет.

Со streaming это особенно неприятно. В одном потоке имя функции приходит раньше arguments, в другом arguments копятся кусками, а finish_reason появляется только в самом конце. Если оркестратор запускает инструмент слишком рано, он получает неполные аргументы. Если ждет слишком долго, вы теряете время на каждом ходе диалога.

Имена функций тоже не всегда переживают миграцию без проверки. Где-то допустимы точки в имени, где-то нет. Где-то схема терпит лишнее поле, а где-то модель начинает придумывать аргумент, которого нет в JSON Schema. У одной команды банка после смены base_url не упала модель, но сломался роутинг: оркестратор искал get_balance, а модель стабильно вызывала getCustomerBalance.

Защита здесь скучная, но рабочая: приводите arguments к одному виду, валидируйте схему до запуска инструмента, храните сырые чанки streaming-ответа и отдельно тестируйте три сценария - один вызов, два вызова подряд и ответ без инструментов. Обычно именно на них и становится ясно, совместим ли стек на деле.

Один реальный сценарий миграции

Команда банка перевела внутреннего ассистента на новый шлюз и поменяла только base_url. SDK, промпты и вызовы оставили прежними. На бумаге все выглядело совместимым, и первые тесты это будто подтверждали.

Короткие ответы в обычном chat проходили без сбоев. Миграцию уже собирались выпускать в релиз. Проблемы появились позже, когда команда прогнала эталонный набор запросов на длинных диалогах, поиске по базе и сценариях с вызовом инструментов.

Сначала сломался stream. На коротких репликах все шло нормально, а на длинных ответах клиент иногда обрывал поток раньше конца. Пользователь видел недописанный ответ, хотя сервер еще отправлял чанки. Причина оказалась не в модели, а в сочетании таймаутов SDK, прокси и ожиданий самого сервиса.

Потом всплыл поиск. Сами embeddings строились без ошибки, но новая модель вернула другую размерность векторов. Индекс в базе ждал старый размер, и качество поиска сразу поехало. Проблема долго выглядела как "модель отвечает хуже", хотя на самом деле сломался векторный слой.

Третьим оказался агент с инструментами. В обычном режиме он работал, а в stream-режиме начинал функцию слишком рано, потому что ждал готовые arguments, а получал их частями. В логах это выглядело как случайные падения оркестратора.

После этого команда сделала то, что стоило сделать в начале: зафиксировала версию SDK, собрала короткий набор живых сценариев и начала сравнивать сырые ответы, а не только итоговый текст. После этого расхождения стали видны за один прогон, а не после релиза.

Что чаще всего упускают

Почти всегда команда проверяет только "счастливый путь": один короткий промпт, быстрый ответ, без stream. Такой тест мало что доказывает. Он не ловит обрывы длинного ответа, разницу в формате чанков, задержку первого токена и странности с tool calls.

Из-за этого совместимость выглядит нормальной ровно до первого живого трафика. В проде приходят длинные диалоги, повторные запросы, ретраи, большие embeddings и ответы через балансировщик со своим таймаутом.

Частая ошибка еще проще: команда смотрит только на HTTP 200. Но 200 не значит, что все прошло чисто. Если не сохранять тело ошибки, куски stream и служебные поля ответа, потом почти невозможно понять, где именно сломалась цепочка: в SDK, в шлюзе, в балансировщике или у провайдера модели.

Еще хуже, когда в одном релизе меняют и SDK, и base_url. После этого никто не знает, что именно дало сбой. Намного спокойнее разнести изменения: сначала оставить прежний SDK и сменить только маршрут, например на api.rullm.com, а уже потом обновлять библиотеку.

Отдельная ловушка - смешивать модели с разным поведением в одном сценарии. Одна модель возвращает tool call как ожидаемый JSON, другая добавляет лишний текст, третья дает другую размерность векторов для embeddings. Если тест гоняет все сразу, диагноз получается мутным.

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

Короткий чек перед релизом

Не выпускайте код после одного удачного запроса. Большая часть сбоев прячется в мелочах: другая версия SDK, другая модель по умолчанию, другой формат ошибки или иное поведение stream на длинном ответе.

Перед релизом зафиксируйте две вещи: точную версию SDK и конкретную модель для каждого сценария. Иначе вы не поймете, что сломалось - шлюз, провайдер или обновление клиента. Если команда переводит трафик на api.rullm.com, это особенно полезно: код может остаться тем же, а поведение на краях все равно изменится.

Потом прогоните один и тот же набор запросов в обычном режиме и через stream. Нужны не только короткие фразы, но и длинные ответы, на которых видны таймауты, обрывы соединения и странности с ретраями. Смотрите на фактическое время до первого токена и до полного ответа, а не только на статус 200.

Перед выкладкой обычно хватает такого минимума:

• Сравнить ответ без stream и со stream на одинаковых промптах.
• Проверить размерность embeddings и убедиться, что индекс принимает именно такой вектор.
• Сверить формат tool calls: имя инструмента, аргументы, JSON и порядок полей.
• Прогнать длинные запросы с боевыми таймаутами и ретраями.
• Сохранить сырые ошибки и сырые ответы в тестовом контуре.

Последний пункт часто недооценивают. Текст ошибки из логгера почти всегда слишком короткий. Для разбора после релиза нужны исходный код ответа, тело ошибки, request id, модель, режим вызова и признак retry. Без этого команда часами спорит, где проблема: в SDK, в маршрутизации, в модели или в своем оркестраторе.

Хороший релиз выглядит скучно: версии записаны, тесты одинаковые для sync и stream, embeddings проверены на реальном индексе, tool calls разобраны парсером, ошибки сохранены целиком. Именно такая скука и экономит ночной откат.

Что делать дальше

Случайные ручные проверки почти всегда дают ложное спокойствие. Здесь полезнее собрать маленький compatibility suite из живых запросов команды и гонять его регулярно.

Хватает 10-15 сценариев, если они взяты из продовой практики, а не придуманы на ходу. Добавьте в набор длинный ответ с риском таймаута, streaming, один запрос на embeddings, один tool call и пару запросов с нестандартными параметрами, которые уже встречались в коде.

Подход простой: зафиксируйте входные payload, ожидаемую форму ответа и метрики, которые для вас важны. Проверяйте не только текст, но и длительность, порядок событий в streaming, длину вектора и JSON у tool calls. Запускайте этот набор перед сменой модели, провайдера и base_url, а отличия между прогонами сохраняйте отдельно, чтобы команда сразу видела, что именно изменилось.

Такой набор лучше держать рядом с интеграционными тестами и запускать перед релизом, а не после инцидента. Если оркестратор ломается один раз из десяти, обычный smoke test это пропустит, а повторяемый прогон поймает.

Если вам нужен OpenAI-совместимый endpoint внутри РФ, тот же набор можно прогнать через RU LLM на api.rullm.com. Это удобно, когда нужно сравнить поведение разных моделей и провайдеров через один и тот же интерфейс, не переписывая SDK, код и промпты.

Если у вас есть требования по 152-ФЗ, не ограничивайтесь ответом модели. Отдельно проверьте, что происходит в логах, как работает маскирование PII и какие аудит-трейлы остаются после ваших реальных сценариев. Для таких тестов лучше использовать синтетические ФИО, телефоны и номера договоров, чтобы проверить маршрут данных без риска для продовых записей.

Если этот suite запускается по расписанию и перед каждым изменением маршрута запросов, большая часть сюрпризов перестает быть сюрпризами.