Путь запроса
Клиент обращается к GPROXY, указывая URL шлюза, API-ключ шлюза и имя модели. GPROXY сам не запускает модели. Каждый запрос в итоге попадает на вышестоящий сервис, который выполняет инференс, а GPROXY решает, на какой именно, с какой учётной записью и в каком формате.- Клиент отправляет запрос по одному из протоколов, которые понимает GPROXY: OpenAI Chat Completions, OpenAI Responses, Claude Messages или Gemini GenerateContent, с потоковой передачей или без неё. Для эмбеддингов, ранжирования, изображений, аудио, видео, файлов и Realtime есть отдельные эндпоинты; их список приведён в разделе Маршрутизация и эндпоинты.
- GPROXY проверяет ключ. Ключ берётся из заголовка
Authorization: Bearer,x-api-keyилиx-goog-api-key. Это либо API-ключ шлюза, либо токен доступа OAuth, выданный GPROXY. Ключ определяет пользователя и, если задана привязка, организацию или команду. - Запрос проходит допуск. Правила разрешений определяют, к каким провайдерам вызывающий может обращаться для этой модели и операции. Владелец учётных данных и привязка ключа определяют, какие учётные данные можно использовать. Затем собираются применимые бюджеты, а лимиты запросов учитываются последними, чтобы запрос, отклонённый по другой причине, не расходовал ничей лимит. Каждая проверка описана в разделе Разрешения, лимиты запросов и бюджеты.
- Разрешается имя модели. Имя маршрута раскрывается в его участников, имя вида
provider/modelуказывает на одного провайдера. Список кандидатов сужается до провайдеров и учётных данных, допущенных на шаге 3, и упорядочивается по уровню, состоянию и весу. См. Модели и маршруты. - Выбираются провайдер и учётные данные. Бюджеты проверяются один раз, до обращения к каким-либо учётным данным. Затем GPROXY берёт учётные данные первого кандидата и выполняет попытку. Если попытка завершилась ошибкой, после которой допустим повтор, пробуются следующие подходящие учётные данные или следующий участник маршрута.
- Запрос преобразуется и отправляется. Если протокол клиента отличается от протокола вышестоящего сервиса, запрос переводится прямо в формат вышестоящего сервиса. К переведённому запросу применяются правила перезаписи, и канал отправляет его с аутентификацией из учётных данных. Ответ проходит те же шаги в обратном порядке: сначала правила перезаписи, затем преобразование обратно в протокол клиента.
- Учитываются использование и стоимость. Каждый физический вызов вышестоящего сервиса создаёт одну запись об использовании с количеством токенов и других величин. Стоимость вычисляется по настроенным правилам цен и списывается с применимых бюджетов после завершения вызова. См. Использование, журналы и аудит.
Термины
Канал
Канал — это адаптер для одного семейства вышестоящих сервисов. Он определяет способ аутентификации, форматы запросов, которые принимает вышестоящий сервис, и поддерживаемые операции. Примеры:openai, codex и custom; custom предназначен для OpenAI-совместимых сервисов, которым нужны собственный базовый URL и список протоколов. Все каналы перечислены в каталоге каналов.
Провайдер
Провайдер — это сохранённое подключение к вышестоящему сервису: имя, канал, базовый URL, настройки канала и пул учётных данных. Один канал могут использовать несколько провайдеров, например два OpenAI-совместимых сервиса с разными адресами. Имя провайдера также используется в URL запросов и в именах моделей, как описано ниже.Учётные данные
Учётные данные — это то, с помощью чего провайдер входит в вышестоящий сервис: API-ключ, токен OAuth или Cookie. У одного провайдера может быть несколько наборов учётных данных. GPROXY выбирает среди них для каждого запроса и переключается на другие, если какие-то упёрлись в лимит или возвращают ошибки. Учётные данные могут принадлежать пользователю, организации или команде, и это ограничивает круг тех, кто может ими пользоваться. Если настроен мастер-ключ, секреты хранятся в зашифрованном виде. Без него CLI хранит их незашифрованными и выводит предупреждение. См. Конфигурация.Маршрут модели
Маршрут модели — это имя модели, которое используют клиенты, сопоставленное одному или нескольким участникам. Каждый участник — это провайдер и идентификатор модели у вышестоящего сервиса, с весом и уровнем резервирования. Клиенты продолжают отправлять то же имя, а вы меняете, добавляете или переупорядочиваете участников за ним.API-ключ шлюза
API-ключ шлюза выдаётся GPROXY пользователю. Клиенты отправляют его при вызове моделей. На ключ действуют разрешения, лимиты запросов и бюджеты пользователя, а также собственные ограничения ключа. Он не связан с API-ключами вышестоящих сервисов, хранящимися в провайдерах; клиенты их никогда не видят. См. Пользователи и API-ключи.Правило перезаписи
Правило перезаписи изменяет запрос или ответ при прохождении через провайдера: может добавить системный текст, вставить точки кэширования, задать или удалить поля JSON, заменить текст или задать заголовки. Правила объединяются в наборы правил, которые привязываются к провайдерам. См. Правила перезаписи.Пользователи, организации и команды
Пользователь — это учётная запись с рольюadmin или user. Пользователи с паролем могут входить в консоль; API-ключи может иметь любой пользователь. Администратор экземпляра (роль admin) управляет всем экземпляром.
Организации и команды объединяют пользователей в группы. Команда принадлежит организации. Членство даёт пользователю роль внутри группы, поэтому администратор организации или команды управляет ресурсами своей группы, не будучи администратором экземпляра. Ключ можно привязать к организации или команде; привязка определяет, какие общие учётные данные доступны ключу и с бюджетов каких групп списывается его стоимость.
Имена моделей и URL запросов
Имя модели в теле запроса определяет цель. Если есть маршрут с именемfast, отправьте model: "fast" на /v1/chat/completions.
Чтобы обратиться к провайдеру без маршрута, укажите имя провайдера в URL и передайте идентификатор модели у вышестоящего сервиса: /openai-main/v1/chat/completions. К тому же провайдеру можно обратиться через /v1/chat/completions с именем модели вида openai-main/<upstream model ID>.
Имена маршрутов могут содержать пространство имён. Маршрут с именем acme/fast можно вызвать как model: "acme/fast" на /v1/chat/completions или через /acme/v1/chat/completions с model: "fast".
Полный порядок разрешения имён и ограничения на имена, не позволяющие именам маршрутов и провайдеров пересекаться, приведены в разделе Модели и маршруты.
Где работает GPROXY
Один и тот же шлюз поставляется в трёх вариантах:- Приложение: настольное или мобильное приложение со встроенным мастером настройки и консолью.
- CLI и контейнер: серверный процесс с HTTP API и консолью в браузере.
- Cloudflare Workers: развёртывание на периферии с удалённым хранилищем и поддержкой WebSocket / Realtime.