Bedrock через LiteLLM

Используйте эту страницу, если ваша организация направляет запросы Codex к Amazon Bedrock через LiteLLM. Если шлюз LiteLLM уже существует, сначала подключите Codex. Развёртывайте LiteLLM, только если вашей организации нужен новый шлюз.

Для других шлюзов действуют те же требования к шлюзу и порядок подключения Codex.

Подключение к существующему шлюзу

Получите у администратора шлюза следующие значения:

• Базовый URL HTTPS, например https://gateway.example.com/v1.
• Псевдоним модели, который LiteLLM направляет к утверждённой модели Bedrock.
• Идентификатор провайдера для конфигурации Codex.
• Учётные данные шлюза с ограниченными правами или вспомогательную программу аутентификации, которая их возвращает.
• Каталог моделей, если он распространяется с конфигурацией вашей организации.

Затем выполните подключение в следующем порядке:

1. Попросите команду шлюза подтвердить, что шлюз обслуживает POST /v1/responses, передаёт ответы потоком, сохраняет последующие ходы и вызовы инструментов, а также маршрутизирует утверждённый псевдоним. См. Совместимость шлюза.
2. Следуйте инструкциям Подключение к шлюзу, чтобы настроить провайдера, модель и учётные данные.
3. Проверьте активного провайдера и псевдоним, отправьте короткий запрос gateway-ok из руководства по подключению и убедитесь, что запись LiteLLM показывает ожидаемых пользователя и псевдоним.
4. Для распространения в масштабе организации перейдите к разделу Развёртывание Codex через шлюз.

Ваши учётные данные шлюза служат для аутентификации в LiteLLM. Шлюз самостоятельно управляет своими учётными данными Bedrock; копировать их на рабочую станцию не нужно.

Подготовка шлюза

Используйте этот раздел, только если перед подключением Codex вам нужно создать шлюз LiteLLM.

Перед развёртыванием

Убедитесь, что у вас есть:

• Разрешение на развёртывание утверждённой архитектуры LiteLLM в вашей среде AWS.
• Доступ в Bedrock к моделям или профилям инференса, к которым вы будете направлять запросы.
• Проверенные образ LiteLLM и схема развёртывания.
• Доверенное имя хоста HTTPS и сертификат.
• Ограниченный диапазон клиентских сетей.

Для приведённого ниже примера Runtime учётной записи AWS шлюза требуется bedrock:InvokeModel для выбранного профиля инференса и проекта по умолчанию в этой учётной записи. Необходимые разрешения см. в инструкциях AWS по настройке GPT-6 Sol.

Архитектура

В этом развёртывании LiteLLM находится между Codex и Bedrock, а на границе с клиентом используется HTTPS. Балансировщик нагрузки и LiteLLM находятся внутри границы шлюза вашей организации; учётные данные провайдера остаются на шлюзе.

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

Запросы пользователя, фрагменты исходного кода и результаты инструментов проходят через шлюз и могут попадать в его журналы. Определите правила хранения, доступа и скрытия чувствительных данных до включения журналирования запросов. MCP servers и плагины имеют отдельные подключения и аутентификацию; эта конфигурация шлюза их не настраивает.

Этапы развёртывания

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

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

Выбор маршрута Bedrock

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

Для новых конфигураций используйте Bedrock Runtime. В примере ниже используется его конечная точка Responses, совместимая с OpenAI.

Об альтернативном маршруте см. Интеграция LiteLLM с Bedrock Mantle.

В качестве примера развёртывания в AWS используйте закреплённую версию эталонной реализации LiteLLM в ECS. Эта реализация использует Bedrock Runtime и обновляет данные аутентификации из роли задачи ECS. Выполняйте её инструкции по развёртыванию и аутентификации вместе и сверяйте её требования к рабочей среде со своими политиками сетевого доступа, TLS, журналирования и сохранения ресурсов.

Какой бы маршрут вы ни выбрали, проверьте развёрнутую комбинацию версии шлюза, конечной точки вышестоящего провайдера и модели на соответствие разделу Совместимость шлюза. Наличие модели вышестоящего провайдера в списке моделей шлюза не подтверждает, что её потоковая передача, продолжение диалога и работа с инструментами совместимы с Codex.

Настройка маршрута модели Runtime

Сопоставьте стабильный псевдоним для Codex с утверждённой моделью вышестоящего провайдера. Перед использованием этого примера Runtime подтвердите доступ в вашей учётной записи и регионе AWS.

model_list:
  - model_name: company-coding-model
    litellm_params:
      model: openai/global.openai.gpt-6-sol
      api_key: os.environ/AWS_BEARER_TOKEN_BEDROCK
      api_base: https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1

Предоставьте действующий Bedrock API key в качестве AWS_BEARER_TOKEN_BEDROCK через свою систему управления секретами. Для краткосрочного ключа выпустите замену до истечения срока действия, обновите окружение процесса шлюза и перезапустите или повторно разверните использующие его рабочие процессы. Эталонная реализация ECS вместо этого обновляет учётные данные внутри процесса из роли своей задачи; используйте её конфигурацию и точку входа вместе.

Префикс openai/ выбирает адаптер LiteLLM, совместимый с OpenAI; настроенный api_base отправляет запросы в Bedrock Runtime. Профиль инференса Global может направлять запросы за пределы исходного региона. Выберите профиль и регион, соответствующие вашим разрешениям AWS и требованиям к размещению данных, и при необходимости замените оба значения.

Клиент отправляет company-coding-model; LiteLLM использует настроенный маршрут к вышестоящему провайдеру. Для этого пользовательского псевдонима требуется соответствующий клиентский каталог, описанный далее. Обычный шлюз не наследует корректировки метаданных встроенного провайдера Bedrock.

Подготовка клиентского каталога

Для этого примера GPT-6 Sol/Runtime с Codex 0.158.0 возьмите за основу полную запись gpt-6-sol из каталога моделей этой версии. Внесите в эту запись все следующие изменения:

Сохраните остальные поля, включая инструкции модели и ограничения контекста. Оставьте изменённую запись в массиве верхнего уровня models каталога. Эти изменения соответствуют выпущенным корректировкам метаданных Bedrock и ограничению поиска Runtime. При смене версии клиента или модели вышестоящего провайдера повторно сверяйте их с соответствующим исходным кодом.

Распространите полный файл JSON и настройте model_catalog_json согласно разделу Развёртывание Codex через шлюз. Сохраните web_search = "disabled" в конфигурации клиента Runtime. Проверьте изменённый каталог через шлюз, прежде чем распространять его среди других пользователей.

Проверка поддержки Responses

Предоставьте POST /v1/responses на доступной клиентам конечной точке HTTPS. Настройте балансировщик нагрузки и все обратные прокси на передачу потоковых событий без буферизации. Сохраняйте последующие ходы и результаты вызовов функций. Одной работающей конечной точки Chat Completions для такого подключения недостаточно.

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

Выдача тестовых учётных данных

Создайте виртуальный ключ LiteLLM с ограниченными правами для одного тестового пользователя. Ограничьте его доступ утверждённым псевдонимом и настройте срок действия, ограничения частоты запросов и бюджет. Доступные средства контроля описаны в документации LiteLLM по виртуальным ключам.

Распространяйте ключ в рамках своего процесса управления секретами или через вспомогательную программу аутентификации. Не выдавайте пользователям административный ключ LiteLLM и не встраивайте учётные данные шлюза в config.toml.

Проверка подключения пользователя

Выполните эти проверки перед расширением доступа:

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

Сохраните версию развёрнутого образа, конфигурацию маршрута и результаты тестов вместе с записью о внедрении. Для распространения в команде и дальнейшей эксплуатации перейдите к разделу Развёртывание Codex через шлюз.

Устранение проблем с подключением

Сузьте поиск проблемы, определив уровень, на котором возникает сбой:

После исправления повторно протестируйте тот же пользовательский путь. Успешная проверка работоспособности шлюза не подтверждает ни выполнение аутентифицированного запроса инференса, ни завершение полного хода Codex.