«OpenAI-совместимый» стало почти универсальным обещанием в сфере больших моделей: поменяйте Base URL, и прежний OpenAI SDK заработает с моделью другого поставщика. Звучит как изменение одной строки конфигурации, но на практике миграция часто приносит 404, ошибки параметров, обрывы потокового вывода и несовпадения формата вызова инструментов. Причина проста: совместимость обычно покрывает самые распространённые интерфейсы, а не все возможности.

Разберём границы совместимости, правильную запись Base URL, настройку SDK, различия параметров и шаги миграции — чтобы можно было сменить модель или поставщика без переписывания бизнес-кода.

Примечание: OpenAI — товарный знак соответствующего правообладателя; статья не связана с вендорами отношениями подчинения. Объём совместимости каждого поставщика определяется его документацией, модели и цены — разделом тарифов.

1. Какой именно уровень совместим

OpenAI-совместимый API обычно означает те же HTTP-пути, поля тела запроса и структуру ответа. Степень совместимости распространённых интерфейсов сильно различается:

Интерфейс Назначение Типичная совместимость
/v1/chat/completions Диалог и генерация текста Самая распространённая, базовые поля обычно поддерживаются
/v1/embeddings Векторизация текста Частая, но проверяйте размерность векторов
/v1/models Список моделей Иногда возвращает только часть моделей или не возвращает ничего
/v1/images/generations Генерация изображений Зависит от поставщика
/v1/audio/transcriptions Транскрипция аудио Зависит от поставщика
/v1/responses Более новый интерфейс Responses Поддержка различается; до миграции уточняйте

Поэтому «совместимый» не равно «полностью эквивалентный». Минимальный критерий подключения сервиса — нормальный ответ /v1/chat/completions. Если бизнес зависит от вызова инструментов, структурированного вывода или мультимодальности, проверяйте каждый пункт отдельно, а не доверяйте рекламной странице.

2. Правильная запись Base URL

SDK автоматически добавляет к Base URL пути вроде /chat/completions. Поэтому Base URL обычно указывают до /v1, а не до конкретного интерфейса. Типичные варианты:

Запись Насколько распространена Пояснение
https://api.example.com/v1 Самая частая SDK сам добавит /chat/completions
https://api.example.com/openai/v1 Некоторые шлюзы Префикс пути задаёт поставщик
https://api.example.com/v1/chat/completions Ошибка Получится дублирование пути и 404
https://api.example.com Зависит от реализации Некоторые сервисы сами добавляют /v1; не полагайтесь на это

Три детали:

  1. Не добавляйте в конец несколько слэшей вручную, иначе появится //chat/completions.
  2. Различайте «адрес консоли» и «адрес API»: первый обычно нельзя использовать как Base URL.
  3. Если пример поставщика работает сразу, копируйте его, а не переписывайте путь самостоятельно.

3. Подключение SDK: три эквивалентных варианта

Официальный Python SDK:

from openai import OpenAI

client = OpenAI(
    api_key="sk-ваш-ключ",
    base_url="https://api.example.com/v1",
)

resp = client.chat.completions.create(
    model="название-модели",
    messages=[{"role": "user", "content": "Ответь только OK"}],
)
print(resp.choices[0].message.content)

Node SDK:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://api.example.com/v1",
});

const resp = await client.chat.completions.create({
  model: "название-модели",
  messages: [{ role: "user", content: "Ответь только OK" }],
});
console.log(resp.choices[0].message.content);

Можно использовать переменные окружения, чтобы не записывать адрес и ключ в код:

export OPENAI_API_KEY="sk-ваш-ключ"
export OPENAI_BASE_URL="https://api.example.com/v1"

Официальный SDK обычно читает OPENAI_BASE_URL, но в разных языках и версиях имя переменной может отличаться; ориентируйтесь на документацию используемого SDK. В производственной среде Base URL лучше хранить в конфигурационном центре, а ключ — в менеджере секретов.

4. Совместимость параметров: где чаще всего возникают проблемы

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

Параметр Типичное различие
model Нужно имя, опубликованное поставщиком, а не официальное название модели
max_tokens Часть новых моделей использует max_completion_tokens; старое поле могут отклонить или проигнорировать
temperature / top_p Reasoning-модели могут фиксировать или игнорировать параметр
stream Поддерживается часто, но структура потоковых событий может отличаться
tools / tool_choice Поддержка различается сильно; parallel_tool_calls доступен не всегда
response_format json_object встречается чаще, поддержка json_schema неоднородна
seed / logprobs / n Многие совместимые сервисы не поддерживают; передача может сразу вызвать ошибку
reasoning_effort Поддерживается только частью reasoning-моделей, значения могут трактоваться иначе

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

5. Шаги миграции с официального API

Выполняйте по порядку — так риск остаётся в узких границах:

  1. Инвентаризация вызовов: перечислите все сервисы, скрипты и задания по расписанию, использующие OpenAI SDK.
  2. Фиксация зависимостей: отметьте, где применяются диалог, потоковый вывод, вызов инструментов, структурированный вывод, Embedding и мультимодальность.
  3. Новый ключ и бюджет: создайте отдельный ключ для миграции, задайте лимит и оповещения.
  4. Смена Base URL: используйте переменные окружения или конфигурацию, не меняйте бизнес-код.
  5. Дымовой тест: отправьте по одному запросу через curl и SDK, проверьте адрес, ключ и имя модели.
  6. Регрессионная выборка: подготовьте 30–100 реальных запросов, сравните качество, задержку, коды ошибок и расход токенов.
  7. Поэтапное переключение: сначала переведите один некритичный сервис, наблюдайте неделю, затем расширяйте охват; сохраните возможность быстрого отката.

Миграция — это не «поменять адрес и готово». При смене модели могут измениться стиль вывода, длина контекста и успешность вызова инструментов; набор оценки надёжнее субъективных ощущений.

6. Частые ошибки и диагностика

Ошибка Частая причина Действие
401 Unauthorized Неверный, просроченный или отсутствующий ключ Проверьте заголовки и лишние символы в ключе
403 Forbidden У ключа нет прав на модель или сработал риск-контроль Уточните права на модель и статус аккаунта
404 Not Found Неверный путь Base URL Уберите /chat/completions, проверьте необходимость /v1
400 Bad Request Неподдерживаемый параметр или ошибка формата Исключайте параметры по одному, вернитесь к минимальному телу
429 Too Many Requests Превышены параллельность или квота Снизьте параллельность, используйте экспоненциальную задержку
500 / 502 / 503 Сбой upstream или шлюза Повторите и запишите request ID; при постоянном сбое переключитесь на резерв
Обрыв потокового вывода Буферизация прокси, таймаут или сетевые колебания Отключите буферизацию прокси, задайте разумные таймауты и heartbeat

При диагностике сохраняйте исходный запрос: URL, заголовки (без ключа), тело, код и тело ответа. По одной фразе «вызов не работает» причину найти почти невозможно.

7. Реальные различия потокового вывода, инструментов и мультимодальности

  • Потоковый вывод: совместимые интерфейсы обычно возвращают Server-Sent Events, начинающиеся с data: и заканчивающиеся [DONE]. Но инкрементальные поля вызова инструментов и статистика использования в потоке у разных поставщиков не совпадают. До включения статистики уточните, поддерживает ли её сервис.
  • Вызов инструментов: имена функций и структура JSON параметров в целом совпадают, но параллельные вызовы, строгий режим и поля рассуждений могут отсутствовать. Для сложных агентов сначала прогоните реальную цепочку инструментов.
  • Структурированный вывод: json_object обычно доступен, ограничения JSON Schema поддерживаются не всегда. На downstream всё равно нужен разбор и валидация; нельзя предполагать, что модель вернёт корректный JSON.
  • Мультимодальность: передача изображения по URL или Base64, поддерживаемые форматы и размеры различаются заметно. Перед загрузкой проверяйте размер и формат.
  • Responses API: на совместимых сервисах покрытие слабее, чем у Chat Completions; приложениям, зависящим от этого интерфейса, нужно отдельное подтверждение до миграции.

8. Стоимость и биллинг

У совместимых API правила тарификации тоже могут отличаться:

  1. Уточните, считается вход и выход раздельно или общей суммой.
  2. Уточните, тарифицируются ли попадания в кэш и токены рассуждений отдельно.
  3. Потоковый ответ не всегда возвращает usage; при необходимости оценивайте токены локально.
  4. Разделяйте ключи по проектам или бизнес-линиям, иначе сверка в конце месяца будет невозможна.
  5. Задайте дневной бюджет и оповещения об аномалиях, чтобы цикл повторов не раздувал расход.

Конкретные цены смотрите в разделе тарифов. Не выводите общую стоимость из цены одной модели: модели, длина контекста и правила биллинга меняются.

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

OpenAI-совместимый API и официальный OpenAI API — это одно и то же?

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

Нужно ли указывать /v1 в Base URL?

Смотрите документацию поставщика. Большинство сервисов требуют указывать путь до /v1, а SDK добавляет /chat/completions; у некоторых шлюзов свой префикс. Критерий простой: после добавления /chat/completions должен открываться правильный интерфейс.

Почему curl работает, а SDK возвращает 404?

Частая причина — SDK сам добавляет путь, а Base URL уже содержит /chat/completions; также конфигурацию в коде может перекрывать переменная окружения. Выведите фактический адрес запроса и сравните.

Поддерживают ли совместимые интерфейсы вызов инструментов и структурированный вывод?

Частично, в зависимости от поставщика и модели. Перед миграцией прогоните отдельно реальную цепочку инструментов и JSON Schema, а не только обычный диалог.

Что делать, если после миграции упало качество ответов?

Сначала убедитесь, что имя модели, температура и промпты не изменились, затем сравните на одной и той же выборке. При необходимости скорректируйте промпт, смените модель или сохраните двух поставщиков с разделением трафика; не делайте вывод по одному-двум субъективным впечатлениям.

Что дальше

Ценность OpenAI-совместимого API — в снижении затрат на переключение, но совместим протокол, а не возможности. Начинайте с минимального тела запроса, затем поочерёдно включайте потоковый вывод, вызов инструментов и структурированный вывод. Если нужны единый OpenAI-совместимый вход, управление ключами и статистика расхода, начните с регистрации в ZSQH AI Gateway; модели и цены смотрите в разделе тарифов.

Читайте также: