К содержимому
Блог

Переход с GPT на Claude по API: что менять в коде и промптах

Переход с GPT на Claude по API: что менять в коде и промптах

Миграция с OpenAI на Claude через Relay начинается с одной правки: в поле model вместо GPT стоит ID Claude, а SDK, адрес и ключ остаются прежними. Дальше идёт настоящая работа. Нужно проверить параметры, которые Claude не принимает, различия протоколов, счёт токенов и поведение промптов, и только потом переключать нагрузку.

Коротко

  • Минимальный шаг: тот же OpenAI SDK и POST /v1/chat/completions, если карточка выбранной модели подтверждает этот протокол.

  • Первыми ломаются нестандартный temperature, previous_response_id в Responses и код, читающий заголовки x-ratelimit-*.

  • Токены считаются иначе: посчитайте промпт заранее методом count_tokens, не закладывая коэффициент.

  • Запасной вариант между семействами пишется на уровне приложения, а резервный маршрут Relay решает другую задачу.

Что остаётся на месте, а что придётся менять?

Есть два пути. Первый: оставить OpenAI SDK и Chat Completions, поменять только model. Перед этим откройте карточку кандидата в каталоге и проверьте поддержку этого протокола. Второй путь: перейти на Anthropic SDK и POST /v1/messages. Он нужен, когда без возможностей Messages не обойтись, например без явных маркеров кэша cache_control.

Мы бы начинали с первого. Он меняет одну строку, а откат сводится к возврату старого значения в конфигурации. На второй стоит переходить, когда вы упёрлись в то, чего первый не даёт.

Relay не разбирает тело подробно: поля вроде system, tools и thinking в Messages и всё лишнее в Chat Completions уходят модели без изменений. Значит, поддержку каждого параметра определяет сама модель, и проверять надо каждый параметр из вашего кода.

Место в кодеЧто проверить при переходе
temperature, top_p, top_kНа Claude 4.7 и новее нестандартные значения дают 400. Параметр уберите
max_tokensВ Messages поле обязательно по правилам вендора. Relay принимает запрос и без него, но модель может его потребовать: задавайте явно
Системная инструкцияВ Chat Completions остаётся сообщением system. В Messages идёт отдельным полем system, а не ролью в messages
ИнструментыВ Chat Completions формат прежний. В Messages схема лежит в input_schema, вызов приходит блоком tool_use, результат возвращается блоком tool_result
Причина остановкиfinish_reason в Chat Completions, stop_reason в Messages. Там появляется refusal: для него нужна своя ветка
Расход токеновprompt_tokens и completion_tokens в Chat Completions, input_tokens и output_tokens в Messages
Формат ошибокОбёртка error в Chat Completions, объект type: "error" в Messages
Responsesprevious_response_id со значением resp_… и background: true Relay отвергает с ответом 400. Историю передавайте в input
Заголовки лимитовx-ratelimit-* Relay не обещает. Код, который читает их, получит пустое значение
ИдемпотентностьНе поддерживается: повтор запроса остаётся новым платным запросом

С какой модели Claude начать сравнение?

Прямого соответствия по ступеням у семейств нет, поэтому берите кандидатов по задаче. Для первого сравнения используйте claude-sonnet-5, а для более сложного сценария добавьте claude-opus-5 или claude-opus-5-5. Прогоните один и тот же набор запросов и сравните прошедшие результаты с расходом.

Если нужен быстрый кандидат, в живом каталоге есть claude-haiku-4.5, claude-haiku-5.5, claude-fable-5 и claude-fable-5-1. Цена и доступный протокол не следуют из имени. Сверьте карточку, затем проведите такой же прогон, как для Sonnet.

Какие параметры сломаются первыми?

Найдите их до того, как они найдут вас:

bash
grep -rnE "temperature|top_p|top_k|previous_response_id|x-ratelimit" --include="*.py" --include="*.ts" --include="*.go" .

По странице Anthropic на 14 октября 2026 года Claude 4.7 и новее отвечают 400 на temperature, top_p и top_k с нестандартным значением. Relay отдаёт модели остальные поля как есть, поэтому отказ придёт к вам, а не будет молча проигнорирован. Если в GPT-коде стояло temperature: 0.2 ради стабильности, уберите его и добивайтесь стабильности самим промптом.

Со вторым местом сложнее. Relay не хранит ответы Responses между вызовами и отвергает previous_response_id. Если приложение строило диалог на нём, историю придётся собирать у себя и отправлять целиком в input. Это изменение логики, а не конфигурации, закладывайте на него время отдельно.

Третье место тихое. Заголовков x-ratelimit-* в ответах нет, и код адаптивного троттлинга, который на них опирался, получит пустоту. Ориентируйтесь на Retry-After и x-should-retry, они описаны в справочнике ошибок.

Каталог моделей

Как проверить поведение модели после замены?

Первое: посчитать токены. Модели разных семейств режут текст по-своему, и промпт, который у GPT весил одно число, у Claude может весить другое. Коэффициент «символов на токен» не закладывайте, посчитайте реальный промпт. Метод не списывает деньги и не удерживает резерв:

bash
curl -i https://relay-llm.ru/v1/messages/count_tokens \
  -H "x-api-key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5", "messages": [{"role": "user", "content": "Текст вашего реального промпта"}]}'

В ответе одно поле, input_tokens, и оно бывает точным или оценкой. Тело до 32 КиБ шлюз передаёт модели для точного подсчёта. Собственную оценку он даёт, когда тело больше, исчерпан лимит запросов на подсчёт, модель не умеет считать токены или не ответила, и тогда добавляет заголовок x-token-count-estimated: true. Флаг -i в команде выше нужен как раз для того, чтобы увидеть заголовки. Полный разбор метода лежит в документации.

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

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

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

Как переключать нагрузку и держать запасной вариант?

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

Запасной вариант между семействами пишется в приложении. Через Relay обе модели доступны по одному адресу и одному ключу, поэтому код короткий:

python
import os

from openai import APIStatusError, APITimeoutError, OpenAI

client = OpenAI(
    base_url="https://relay-llm.ru/v1",
    api_key=os.environ["RELAY_API_KEY"],
    max_retries=0,
    timeout=30,
)
CHAIN = [os.environ["PRIMARY_MODEL"], os.environ["FALLBACK_MODEL"]]


def ask(messages):
    last_error = None
    for model in CHAIN:
        try:
            reply = client.chat.completions.create(model=model, messages=messages)
            return reply.choices[0].message.content, model
        except APITimeoutError as err:
            last_error = err
        except APIStatusError as err:
            retryable = err.response.headers.get("x-should-retry") == "true"
            if not retryable and err.code != "model_unavailable":
                raise
            last_error = err
    raise last_error

Повторы внутри SDK выключены через max_retries=0: иначе они умножатся на повторы приложения, а каждый повтор Relay считает отдельным запросом. Ошибка 400 уходит наружу сразу: она говорит о дефекте запроса, и тихий уход на другую модель его скрыл бы. Возвращайте имя ответившей модели и пишите его в лог: ответы двух семейств отличаются стилем, и без этого поля в логе не разобрать, что видел пользователь. Запасная модель может стоить дороже основной, поэтому проверьте её карточку и лимит расходов ключа.

Не путайте этот приём с резервным маршрутом Relay. Резервный маршрут работает внутри одной модели: если основной путь к ней недоступен, запрос уходит другим путём к той же модели, и признак виден в заголовке x-route. Claude на GPT он не переключит. Подробности и настройка на ключе описаны в документации резервных маршрутов.

Частые вопросы

Нужно ли менять SDK при переходе с GPT на Claude?

Нет, если выбранная модель поддерживает Chat Completions. Проверьте это в карточке модели перед миграцией. Anthropic SDK нужен для возможностей, которых нет в Chat Completions, например явных маркеров кэша. Выбор протокола разобран в статье о Messages и Responses.

Почему запрос с temperature вернул 400?

Claude 4.7 и новее отклоняют нестандартные temperature, top_p и top_k, это поведение самой модели. Relay передаёт эти поля без изменений. Уберите параметр из запроса и проверьте результат на своём наборе: стабильность придётся добирать формулировкой промпта.

Работает ли previous_response_id в Responses?

Нет. Relay не хранит ответы между запросами, и previous_response_id со значением, которое начинается с resp_, даёт 400. Передавайте всю историю диалога в поле input, а если на связке ответов у вас построена сложная логика, закладывайте на её переписывание отдельное время.

Чем эта статья отличается от переноса приложения с OpenAI SDK на Relay?

Здесь меняется семейство модели, и вместе с ним поведение ответов. Если же вы остаётесь на той же модели и меняете только адрес и ключ, вам нужен чеклист переноса OpenAI SDK, а краткую справку по адресам даёт страница миграции.

Открыть Claude Sonnet 5 в каталоге

Источники

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.