Что означает OpenAI-совместимость для API?

Краткий ответ

Когда провайдер говорит, что его API openai-compatible, это означает, что он принимает те же HTTP-запросы, которые отправляют клиентские библиотеки OpenAI, и возвращает ответы в той же структуре. Вы сохраняете свой код, меняете базовый URL и ключ, и вызов отправляется на другой сервер.

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

Что на самом деле покрывает эта метка

На практике совместимость с OpenAI — это короткий список конкретных вещей. Если провайдер поддерживает все из них, большая часть клиентского кода работает без изменений.

• Пути. Запросы на чат отправляются на POST /v1/chat/completions, а список моделей загружается с GET /v1/models.
• Аутентификация. Ключ передается в заголовке Authorization: Bearer.
• Тело запроса. Строка model, массив объектов messages с полями role и content, а также необязательные поля сэмплирования, такие как temperature, top_p, stop и seed.
• Тело ответа. Массив choices с сообщением ассистента, поле finish_reason и объект usage с подсчетом токенов.
• Потоковая передача. При stream: true сервер отправляет события Server-Sent Events, каждое из которых содержит небольшую JSON-дельту, заканчиваясь финальным маркером.
• Необязательные функции. Вызов функций, JSON-режим и аналогичные поля, где провайдер решает их поддерживать.

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

Почему один формат стал общей целью

Формат chat completions распространился, потому что он был простым и появился рано. Автор инструмента, поддерживающий его один раз, может охватить много бэкендов, а автор бэкенда, поддерживающий его один раз, может охватить много инструментов. Это выгодная сделка для обеих сторон, поэтому формат закрепился, даже среди сервисов, не имеющих отношения к компании, которая его разработала.

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

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

Что эта метка вам не говорит

Здесь людей часто удивляют вещи. Метка опускает все, что определяет, полезно ли API для вашей работы.

Модель, стоящая за ним

Совместимый эндпоинт может обслуживать любую модель. Некоторые обслуживают модели с открытыми весами, некоторые маршрутизируют запросы к нескольким поставщикам, некоторые оборачивают проприетарную модель. Совместимость не означает, что сервис запущен компанией OpenAI, и не означает, что модель ведет себя как их модель. Имя модели, которое вы передаете в model, — это просто строка, определенная провайдером.

Поведение при отказе

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

Глубина функций

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

Лимиты, цены и ошибки

Лимиты запросов, длина контекста, максимальный размер тела и цена за токен — все это выбор провайдера. Тела ошибок также различаются в деталях, даже когда коды состояния HTTP совпадают, поэтому логика повторных попыток должна опираться на коды состояния и заголовки, а не на текст сообщения.

Быстрый тест совместимости

Вы можете проверить провайдера за несколько минут с помощью трех запросов. Замените ключ на свой. Этот пример использует базовый URL этого сайта.

Copycurl https://api.kimicode.top/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

Первый вызов подтверждает ключ и перечисляет идентификаторы моделей. Второй проверяет структуру чата. Затем протестируйте части, от которых зависит ваше приложение: добавьте "stream": true и наблюдайте за инкрементальными фрагментами, передайте массив tools, если используете вызов функций, и установите response_format в {"type":"json_object"}, если вам нужен разборчивый вывод.

Также намеренно вызовите ошибку, например, с неверным ключом. Вы хотите видеть чистый код HTTP и тело ошибки в формате JSON, которое ваш клиент может обработать.

Тот же вызов на Node

JavaScript SDK принимает те же два значения. Вот вызов потоковой передачи, который является формой, используемой большинством интерфейсов чата.

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.kimicode.top/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Name three uses of SSE." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

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

Как выглядит переключение в коде

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

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.kimicode.top/v1",
    api_key="YOUR_API_KEY",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarize SSE in one sentence."}],
)
print(resp.choices[0].message.content)

Node SDK — та же идея с параметрами baseURL и apiKey. Многие инструменты считывают OPENAI_BASE_URL и OPENAI_API_KEY из окружения, поэтому иногда можно переключиться, вообще не касаясь кода.

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

Где вписывается API этого сайта

Этот сервис — хостинговый текстовый API, следующий формату OpenAI. Он запускает одну модель с открытыми весами, управляемую независимым провайдером и настроенную на ответы без отказов по контенту для законного использования взрослыми. Это не официальное API какого-либо вендора моделей, и оно не маршрутизирует запросы между вендорами. Идентификатор модели — uncensored.

Он поддерживает потоковую передачу через SSE с отчетом об использовании в конце, вызов функций, JSON-режим, а также передает параметры temperature, top_p, stop, seed и штрафы. Контекстное окно составляет 100 000 токенов для промпта и завершения вместе. Он не генерирует изображения или аудио, и не предлагает эмбеддинги или дообучение. Одно правило фиксировано: запрещён сексуальный контент с участием несовершеннолетних.

Биллинг — предоплаченный и измеряемый: $0,15 за 1M входных токенов и $0,50 за 1M выходных токенов, без подписки. Вы можете увидеть цифры на странице цен, а документация подробно описывает первый запрос. Если вы хотите попробовать его без оплаты, новые аккаунты могут получить пробный баланс $0,50 одним кликом на странице API-ключа.

Распространённые проблемы совместимости

1. Неверный базовый URL. URL должен заканчиваться на /v1. Клиенты самостоятельно добавляют к нему /chat/completions, поэтому добавление этого пути к базовому URL приводит к ошибке 404.
2. Неподдерживаемые параметры. Если библиотека отправляет поле, которое сервер не распознаёт, проверьте, отклоняется ли оно или игнорируется, а затем удалите его.
3. Потоковая передача и параллелизм. Запрос в режиме потоковой передачи удерживает слот параллелизма до завершения потока. Если ваше приложение открывает множество потоков, вы можете получить ошибку 429 с кодом concurrency, даже если ваш счетчик запросов в минуту низкий.
4. Повторная отправка запроса при 429. Воспринимайте 429 как сигнал к ожиданию. Если присутствует заголовок Retry-After, следуйте его указаниям.
5. Подсчёт токенов. Не предполагайте, что токенизатор другого провайдера совпадает с нашим. Читайте объект usage в ответе, чтобы узнать количество токенов, за которые вам начисляется оплата.

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

Дополнительные руководства

• OpenCode с OpenAI совместимым API: Настройка
• Альтернатива Kimicode: Размещённый API LLM без цензуры
• API LLM без цензуры: Интеграция и цены по стандарту OpenAI