One API или New API: выбор по задачам, лицензии и рискам миграции
Сопоставьте официальные описания с требованиями своей установки, зафиксируйте версии и проверьте каналы, права, учёт расходов и перенос данных. Матрица приёмки поможет определить условия перехода и отката.
Выбирая между One API и New API, сначала определите, какую задачу должен выполнять ваш клиент. Затем проверьте интерфейсы, права доступа, учёт расходов и обслуживание конкретной версии. Если действующий шлюз удовлетворяет требованиям, более длинный список функций другого проекта сам по себе не повод менять образ.
Материал рассчитан на отдельных разработчиков и небольшие команды, которые сами обслуживают API-шлюз. Источники проверены 21 октября 2026 года; ссылки ведут на фиксированные коммиты официальных репозиториев. Заявления документации отделены от результатов приёмочных проверок. Мы не сравнивали производительность двух шлюзов и не предлагаем универсальную команду переноса рабочей базы данных.
1. Сформулируйте требования как проверяемые задачи
«Поддерживает много моделей» — недостаточно точный критерий. Один клиент может использовать обычные ответы, потоковую передачу, вызовы инструментов, файлы и асинхронные задания. Одна успешная реплика не проверяет весь рабочий процесс.
Заполните таблицу для обязательных функций. Для ненужных сейчас возможностей укажите «не применяется»: гипотетические будущие задачи не должны вытеснять сегодняшние требования к надёжности.
| Пункт | Что записать | Пример условия приёмки |
|---|---|---|
| Клиент | Название, версия, фактический путь запроса и протокол | Исходный клиент выполняет задачу без потери обязательных полей |
| Upstream и модель | Разрешённый источник доступа, точный ID модели, допустимые псевдонимы | Запрос попадает в нужный канал без неожиданной замены модели |
| Формат ответа | Обычный или потоковый ответ, инструменты и вложения | Результат полный, завершение и ошибка различимы |
| Права | Администратор, обычный пользователь, ключ приложения, группа | Отключённые ключи и запрещённые модели отклоняются |
| Учёт расходов | Единицы, источник цен, связь использования и списаний | Попытки и списания одной логической задачи можно объяснить |
| Эксплуатация | База, резервные копии, окно работ, ответственный | При сбое можно остановить переход и восстановить проверенное сочетание компонентов |
Это условия проверок, которые предстоит выполнить вам, а не результаты тестирования в статье. Название открытого проекта не подтверждает разрешение канала на работу с upstream и доступность конкретной модели.
2. Что подтверждают материалы двух проектов
Сравнение ниже относится только к README и лицензиям в коммитах, указанных в конце статьи.[1]—[4] Описание текущих исходников может опережать релиз или отличаться от старой версии. Перед выбором повторите проверку для версии, которую собираетесь установить.
| Критерий | Официальное описание One API | Официальное описание New API | Как использовать при выборе |
|---|---|---|---|
| Базовое управление | Перечислены балансировка каналов, управление токенами доступа, группы пользователей и каналов, сопоставление моделей, повторные попытки | Перечислены маршрутизация, приоритеты и веса, контроль доступа, квоты, учёт использования и расходов | Проверить настройку обязательных правил, а не считать пункты меню |
| Интерфейсы | Разные upstream подключаются через единый совместимый формат; есть предупреждение, что сопоставление моделей может перестраивать тело запроса и мешать передаче ещё не поддержанных полей | Перечислены несколько текстовых протоколов и преобразования; возможности зависят от канала, upstream-модели и пути преобразования, а поля могут не иметь точного соответствия | Проверять реальные запросы клиента; совместимость не означает эквивалентность всех функций |
| Конфигурация и запуск | Есть описание развёртывания, баз данных, переменных окружения и работы на нескольких машинах | Есть описание развёртывания, баз данных, переменных и нескольких узлов; рекомендуется фиксировать версию образа и оценивать совместимость миграции | Проверять выбранную версию; не переносить значения по умолчанию одного проекта на другой |
| Лицензия | Файл LICENSE содержит MIT | LICENSE содержит AGPLv3; README также описывает дополнительные условия об указании авторства и ссылке на исходный проект | До модификации, распространения или предоставления сервиса изучить полные условия выбранной версии |
Таблица не утверждает, что у One API отсутствуют все неупомянутые функции. Поддержка интерфейса в документации New API также не означает, что её обеспечивает ваш upstream. Если надёжного описания возможности не найдено, пометьте её как «нужно уточнить», а не как «не поддерживается».
README New API называет One API исходной основой проекта.[2] Это объясняет некоторые общие понятия, но не доказывает двустороннюю совместимость баз любых версий, возможность сохранить ключи или способность старого приложения читать преобразованные данные. Общее происхождение не делает MIT и AGPLv3 взаимозаменяемыми. Изучайте лицензию и заявления конкретной версии, а не только значок в репозитории.
3. Зафиксируйте версии кандидатов и оцените смысл перехода
Для каждого кандидата запишите адрес репозитория, тег релиза, digest образа, соответствующую документацию и дату выпуска. Изменяемый тег latest не является воспроизводимым номером версии. Возможность, недавно добавленная в README ветки main, не обязательно есть в старом образе.
Затем изучите относящиеся к вам примечания к выпуску и известные проблемы: затрагивают ли они вашу СУБД, протокол клиента, потоковые ответы, сопоставление моделей или правила доступа; вошло ли нужное исправление в выбранный релиз. Закрытая задача, исправленный исходный код и образ с этим исправлением — разные состояния. Частота коммитов и число звёзд не заменяют такую проверку.
Решение удобно принимать по трём сценариям:
- Действующий One API проходит обязательные задачи, явного пробела нет: сохраните обслуживаемую версию и запишите условия, при которых вернётесь к вопросу миграции.
- Текущая версия не обеспечивает обязательный процесс, а документация выбранной версии New API описывает нужную возможность: проведите изолированную приёмку с фактическим каналом и настройками, затем решайте о переходе.
- Оба проекта выполняют задачи: сравните доступные вам процедуры обслуживания, диагностику, лицензионные требования и окна обновления. Не назначайте оценки производительности или стабильности без данных.
Для нового шлюза нужны те же проверки, только без переноса прежних учётных записей. Доступность исходного кода бесплатно не означает отсутствия расходов на сервер, базу, обслуживание и upstream-вызовы.
4. Разделите пять видов настроек и не подключайте кандидата к рабочей базе
Если миграцию стоит оценить, составьте соответствие «исходная настройка → целевая настройка → результат проверки». Методы резервного копирования рассмотрены в руководстве по резервным копиям и восстановлению шлюза. Здесь важны различия смысла настроек между проектами, а не повторение команд резервного копирования.
- Каналы и сопоставление моделей. Запишите тип канала, адрес назначения, группу, приоритет, вес, повторные попытки и резервные маршруты. Одинаковые названия не доказывают совпадение внутренних значений и поведения. При необходимости создайте конфигурацию заново по документации целевой версии.
- Пользователи и ключи приложений. Проверьте роли, отключённые записи, квоты, набор моделей, сроки действия и другие используемые ограничения. Различайте клиентский ключ шлюза и учётные данные для upstream. Сохранение прежних токенов требует подтверждения для конкретной пары версий, а не предположения.
- Цены и средства на счетах. Сопоставьте исходные единицы учёта, коэффициенты, цены, остатки и незавершённые операции. Одинаковое число в интерфейсе не гарантирует одинаковые единицы и округление. Не исправляйте баланс вручную, чтобы скрыть расхождение.
- Зависимости среды. Проверьте основную базу, базу журналов, кеш, монтирования, переменные окружения и зависимости от ключей шифрования или сессий. Одинаковое имя переменной не гарантирует одинаковые значения по умолчанию, назначение и область действия. Одного переименования контейнера для изоляции недостаточно.
- Внешние интеграции. Если используются callback входа, платёжные уведомления, почта, расписания или административный API, включите их вызывающие системы в приёмку. Две копии шлюза не должны одновременно обрабатывать одно производственное событие.
Сначала восстановите данные в отдельную базу и отдельные каталоги. Сохраните исходную восстановленную копию, которую новая программа ещё не изменяла. До запуска стенда запретите соединения с рабочей базой, платными upstream, платежами и почтой, отключите фоновые задания, затем подключите контролируемый локальный имитатор. Пока исходная база обслуживает рабочую систему, не подключайте к ней новую программу «просто проверить запуск».
Обсуждать повторное использование данных можно только после обнаружения официального пути миграции для исходной версии, целевой версии и СУБД и проверки этого пути на копии. Если таких подтверждений нет, способ миграции остаётся неподтверждённым. Рассмотрите новый экземпляр с контролируемым восстановлением настроек; не пытайтесь постоянно запускать два проекта поверх одной базы.
5. Отделите заявленную поддержку от работоспособности матрицей приёмки
Сначала проведите локальные проверки с имитатором, затем ответственный администратор может проверить необходимые реальные upstream-функции в рамках заранее заданного бюджета. Имитация позволяет проверить авторизацию, маршрутизацию и обработку ошибок шлюза, но не качество модели, реальное число токенов или списания поставщика. В статье предлагается методика: реальная миграция шлюзов и платные API-вызовы не выполнялись.
| Сценарий | Что проверить в изолированной среде | Что смотреть при ошибке |
|---|---|---|
| Границы доступа | Ограниченным тестовым токеном обычного пользователя проверить разрешённую модель, запрещённую модель и отключённый токен | Роль, ограничения токена, группу и сопоставление моделей |
| Обычный и потоковый ответ | Имитировать нормальное завершение, обрыв потока и ошибку; проверить, не помечен ли сбой как успех | Адаптер, буферизацию прокси, тайм-ауты, события завершения |
| Маршрутизация и повторы | Задать имитатору запланированные отказы и записать канал, модель и идентификатор каждой попытки | Веса, приоритеты, повторы и резервные маршруты |
| Инструменты и асинхронные задания | Если они нужны, проверить полный цикл с тестовым инструментом или заданием без внешних побочных эффектов | Поля протокола, ID задания, запрос статуса, риск повторного выполнения |
| Использование и списания | На фиксированном имитируемом расходе проверить локальные правила учёта; реальные счета сверять отдельно | Единицы, коэффициенты, округление, ошибки и несколько попыток |
| Управление и аудит | Убедиться, что обычный пользователь не читает административные данные, а обезличенные записи связывают задачу с её попытками | Проверки прав, поля журналов и способ связывания |
Фиксированное имитируемое использование проверяет только локальный расчёт. Оно не доказывает, что upstream выставит счёт за то же количество. Оплачиваются ли ошибочные запросы, нужно проверять по условиям канала и фактическому счёту, а не выводить из HTTP-статуса.
Например, команде нужны только потоковый текст и ограниченные ключи: инструменты и асинхронные задания можно пометить «не применяется». Если же клиент обязан вызвать инструмент и прочитать его результат, необходим полный цикл. Не расширяйте тестирование ради списка функций, но и не компенсируйте провал обязательной возможности успешной обычной репликой.
Если обычный вызов работает, а важный параметр теряется, используйте разбор потери параметров в шлюзе. Если после ошибки выбирается другая модель, проверьте управление резервной моделью: разные результаты нельзя автоматически считать успешным выполнением исходной задачи.
6. Откройте реальный трафик только после выполнения условий перехода
До переключения запишите три условия: все обязательные задачи прошли; расхождения данных и прав объяснены; определены ответственные и шаги остановки перехода и восстановления старой среды. Необъяснимый баланс, обход прав или неожиданная замена модели — основания приостановить переход.
Назначьте момент переключения, прекратите приём новых задач через старый вход и дождитесь завершения текущих запросов и учёта операций. На этапе проверки направляйте в целевой экземпляр только явно выбранные приложения с низким риском. Один пользователь или одна операция не должны случайно попадать в две независимо учитывающие расходы базы. Не дублируйте платёжные callback на обе системы: источник истины для расчётов должен быть один.
Если структура базы мигрировала, откат должен учитывать и программу, и состояние данных. Возврат старого образа не гарантирует чтения новой структуры. Изменения учётных записей, списания и результаты задач, появившиеся после открытия записи в новую систему, не сохранятся автоматически при восстановлении старого снимка. Восстановление и обработку новых записей нужно отрепетировать до переключения, а не собирать данные вручную во время аварии.
Сохраните краткое решение: проект и фиксированная версия, результаты обязательных задач, карта настроек, непроверенные области, момент переключения и условия отката. Если есть только фраза в документации, статус — «кандидат». Вывод «подходит для этой установки» появляется после проверки соответствующей версии и реального рабочего процесса.
7. Первичные источники и границы версий
- [1] One API README, коммит 8df4a26: управление, предупреждение о сопоставлении моделей, развёртывание и настройки.
- [2] New API README, коммит 206e0fa: возможности и ограничения преобразований, фиксация версии, происхождение проекта и описание дополнительных условий.
- [3] One API LICENSE, тот же коммит: текст MIT.
- [4] New API LICENSE, тот же коммит: текст AGPLv3.
Это снимки исходного кода, изученные 21 октября 2026 года, а не заявление о последних стабильных релизах. Статья не сравнивает цены, рейтинги, пропускную способность или доступность конкретных моделей. Перед запуском проверьте выбранный релиз и разрешённый доступ к upstream.