> ## Documentation Index
> Fetch the complete documentation index at: https://gproxy.leenhawk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Основные понятия

> Что происходит с запросом внутри GPROXY, какие объекты вы настраиваете и как имя модели и URL запроса выбирают вышестоящий сервис.

В этой главе описан путь запроса через GPROXY и определены объекты, которые вы настраиваете по пути. Прочитайте её до руководств по администрированию: они используют эти термины без повторных объяснений.

## Путь запроса

Клиент обращается к GPROXY, указывая URL шлюза, API-ключ шлюза и имя модели. GPROXY сам не запускает модели. Каждый запрос в итоге попадает на вышестоящий сервис, который выполняет инференс, а GPROXY решает, на какой именно, с какой учётной записью и в каком формате.

1. Клиент отправляет запрос по одному из протоколов, которые понимает GPROXY: OpenAI Chat Completions, OpenAI Responses, Claude Messages или Gemini GenerateContent, с потоковой передачей или без неё. Для эмбеддингов, ранжирования, изображений, аудио, видео, файлов и Realtime есть отдельные эндпоинты; их список приведён в разделе [Маршрутизация и эндпоинты](https://gproxy.leenhawk.com/ru/reference/routing-table.md).
2. GPROXY проверяет ключ. Ключ берётся из заголовка `Authorization: Bearer`, `x-api-key` или `x-goog-api-key`. Это либо API-ключ шлюза, либо токен доступа OAuth, выданный GPROXY. Ключ определяет пользователя и, если задана привязка, организацию или команду.
3. Запрос проходит допуск. Правила разрешений определяют, к каким провайдерам вызывающий может обращаться для этой модели и операции. Владелец учётных данных и привязка ключа определяют, какие учётные данные можно использовать. Затем собираются применимые бюджеты, а лимиты запросов учитываются последними, чтобы запрос, отклонённый по другой причине, не расходовал ничей лимит. Каждая проверка описана в разделе [Разрешения, лимиты запросов и бюджеты](https://gproxy.leenhawk.com/ru/guides/permissions.md).
4. Разрешается имя модели. Имя маршрута раскрывается в его участников, имя вида `provider/model` указывает на одного провайдера. Список кандидатов сужается до провайдеров и учётных данных, допущенных на шаге 3, и упорядочивается по уровню, состоянию и весу. См. [Модели и маршруты](https://gproxy.leenhawk.com/ru/guides/models.md).
5. Выбираются провайдер и учётные данные. Бюджеты проверяются один раз, до обращения к каким-либо учётным данным. Затем GPROXY берёт учётные данные первого кандидата и выполняет попытку. Если попытка завершилась ошибкой, после которой допустим повтор, пробуются следующие подходящие учётные данные или следующий участник маршрута.
6. Запрос преобразуется и отправляется. Если протокол клиента отличается от протокола вышестоящего сервиса, запрос переводится прямо в формат вышестоящего сервиса. К переведённому запросу применяются правила перезаписи, и канал отправляет его с аутентификацией из учётных данных. Ответ проходит те же шаги в обратном порядке: сначала правила перезаписи, затем преобразование обратно в протокол клиента.
7. Учитываются использование и стоимость. Каждый физический вызов вышестоящего сервиса создаёт одну запись об использовании с количеством токенов и других величин. Стоимость вычисляется по настроенным правилам цен и списывается с применимых бюджетов после завершения вызова. См. [Использование, журналы и аудит](https://gproxy.leenhawk.com/ru/guides/observability.md).

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

## Термины

### Канал

Канал — это адаптер для одного семейства вышестоящих сервисов. Он определяет способ аутентификации, форматы запросов, которые принимает вышестоящий сервис, и поддерживаемые операции. Примеры: `openai`, `codex` и `custom`; `custom` предназначен для OpenAI-совместимых сервисов, которым нужны собственный базовый URL и список протоколов. Все каналы перечислены в [каталоге каналов](https://gproxy.leenhawk.com/ru/reference/channel-catalog.md).

### Провайдер

Провайдер — это сохранённое подключение к вышестоящему сервису: имя, канал, базовый URL, настройки канала и пул учётных данных. Один канал могут использовать несколько провайдеров, например два OpenAI-совместимых сервиса с разными адресами. Имя провайдера также используется в URL запросов и в именах моделей, как описано ниже.

### Учётные данные

Учётные данные — это то, с помощью чего провайдер входит в вышестоящий сервис: API-ключ, токен OAuth или Cookie. У одного провайдера может быть несколько наборов учётных данных. GPROXY выбирает среди них для каждого запроса и переключается на другие, если какие-то упёрлись в лимит или возвращают ошибки. Учётные данные могут принадлежать пользователю, организации или команде, и это ограничивает круг тех, кто может ими пользоваться.

Если настроен мастер-ключ, секреты хранятся в зашифрованном виде. Без него CLI хранит их незашифрованными и выводит предупреждение. См. [Конфигурация](https://gproxy.leenhawk.com/ru/reference/configuration.md).

### Маршрут модели

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

### API-ключ шлюза

API-ключ шлюза выдаётся GPROXY пользователю. Клиенты отправляют его при вызове моделей. На ключ действуют разрешения, лимиты запросов и бюджеты пользователя, а также собственные ограничения ключа. Он не связан с API-ключами вышестоящих сервисов, хранящимися в провайдерах; клиенты их никогда не видят. См. [Пользователи и API-ключи](https://gproxy.leenhawk.com/ru/guides/users-and-keys.md).

### Правило перезаписи

Правило перезаписи изменяет запрос или ответ при прохождении через провайдера: может добавить системный текст, вставить точки кэширования, задать или удалить поля JSON, заменить текст или задать заголовки. Правила объединяются в наборы правил, которые привязываются к провайдерам. См. [Правила перезаписи](https://gproxy.leenhawk.com/ru/guides/rules.md).

### Пользователи, организации и команды

Пользователь — это учётная запись с ролью `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"`.

Полный порядок разрешения имён и ограничения на имена, не позволяющие именам маршрутов и провайдеров пересекаться, приведены в разделе [Модели и маршруты](https://gproxy.leenhawk.com/ru/guides/models.md).

## Где работает GPROXY

Один и тот же шлюз поставляется в трёх вариантах:

* Приложение: настольное или мобильное приложение со встроенным мастером настройки и консолью.
* CLI и контейнер: серверный процесс с HTTP API и консолью в браузере.
* Cloudflare Workers: развёртывание на периферии с удалённым хранилищем и поддержкой WebSocket / Realtime.

Пакеты и ограничения по платформам перечислены в разделе [Загрузка и установка](https://gproxy.leenhawk.com/ru/download.md). Если вы обновляетесь с v3, сначала прочитайте [руководство по миграции](https://gproxy.leenhawk.com/ru/deployment/v3-to-v4.md). Чтобы перейти к настройке, следуйте разделу [Быстрый старт](https://gproxy.leenhawk.com/ru/getting-started/quick-start.md).


## Related topics

- [GPROXY](https://gproxy.leenhawk.com/ru/index.md)
- [Архитектура](https://gproxy.leenhawk.com/ru/development/architecture.md)
- [Консоль](https://gproxy.leenhawk.com/ru/guides/console.md)
- [Конфигурация](https://gproxy.leenhawk.com/ru/reference/configuration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.