Поставщик инференса

По умолчанию ваш сервер отправляет вызовы модели в Claude API. На этой странице показано, как отправлять их облачному поставщику или в шлюз моделей, которым управляете вы. Чтобы сменить поставщика:

1. Поместите пример из раздела вашего поставщика на этой странице в файл настроек сервера.
2. Передайте серверу учётные данные поставщика, как показано в том же разделе.
3. Перезапустите сервер, как показано в разделе Где находятся настройки. В Docker Compose, если на шаге 2 изменились .env или docker-compose.yml, вместо этого выполните docker compose up -d, потому что при перезапуске они не перечитываются.
4. Проверьте поставщика.

Параметр inference.provider принимает следующие значения:

При любом значении, кроме anthropic, серверу не нужен ключ API Claude. Он игнорирует ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN и ANTHROPIC_BASE_URL. Единственное исключение — шлюз моделей, ключ которого сервер по вашему указанию считывает из одной из этих переменных.

Агенты называют модели по их идентификаторам в Claude API, например claude-opus-5-5. Сервер преобразует идентификатор, поэтому определение агента работает без изменений с любым поставщиком, который обслуживает эту модель.

Некоторые инструменты и настройки агентов зависят от поставщика. См. раздел Различия, зависящие от вашего поставщика инференса.

Передача серверу облачных учётных данных

То, как учётные данные облачного поставщика попадают на сервер, зависит от вашей установки:

• Docker Compose: передайте каждую переменную и файл серверу.
• Kubernetes: чарт сервера не передаёт переменные AWS, Google Cloud или Azure, поэтому используйте “workload identity” (удостоверение рабочей нагрузки) вашего облака. Создайте сервисный аккаунт с аннотацией удостоверения рабочей нагрузки вашего облака и установите в server.serviceAccountName его имя. Эта аннотация указана в values.yaml чарта. В Azure Kubernetes Service также установите server.azureWorkloadIdentity: true.

Amazon Bedrock

inference:
  provider: bedrock
  region: us-east-1
  #model_id_prefix: global.anthropic.
  #model_id_overrides:
  #  claude-opus-5-5: us.anthropic.claude-opus-5-5

Сервер подписывает свои вызовы любыми учётными данными, которые находит на хосте цепочка учётных данных по умолчанию AWS SDK. Это может быть роль задачи или идентификатор пода. На рабочей станции это может быть AWS_PROFILE или AWS_ACCESS_KEY_ID.

Включите в учётной записи модели, которые вы используете. Удостоверению AWS, которым сервер подписывает вызовы, нужны следующие разрешения:

• bedrock:InvokeModel и bedrock:InvokeModelWithResponseStream для моделей и профилей инференса, которые вы используете.
• bedrock:ListFoundationModels и bedrock:ListInferenceProfiles для ресурса *. Сервер считывает списки моделей Amazon Bedrock, чтобы агенты могли использовать модель, более новую, чем выпуск вашего сервера. Чтобы пропустить это, установите inference.list_models: false.

По умолчанию сервер добавляет us.anthropic. перед каждым идентификатором модели, что указывает на “cross-region inference profile” (межрегиональный профиль инференса). Чтобы использовать другое семейство профилей, раскомментируйте model_id_prefix.

Claude Models on Google Cloud (Google managed)

inference:
  provider: vertex
  region: us-east5
  project_id: my-project
  #model_id_overrides:
  #  claude-haiku-4-5: claude-haiku-4-5@20251001

Параметр region обязателен. Это расположение Google Cloud’s Agent Platform, в котором доступны используемые вами модели, или global. project_id — это проект, в котором выполняются вызовы и на который выставляется за них счёт.

Сервер использует Google Application Default Credentials: файл, указанный в GOOGLE_APPLICATION_CREDENTIALS, или сервисный аккаунт, который прикрепляют Compute Engine, Cloud Run или GKE. Этому удостоверению нужна роль roles/aiplatform.user в проекте. В проекте должны быть включены API aiplatform.googleapis.com и используемые вами модели Claude.

Microsoft Foundry

inference:
  provider: foundry
  foundry:
    resource: my-resource
  #model_id_overrides:
  #  claude-opus-5-5: team-a-opus

resource — это имя вашего ресурса Foundry, первая часть его имени хоста: <resource>.services.ai.azure.com.

Учётные данные берутся из окружения сервера:

• Ключ API Foundry: установите ANTHROPIC_FOUNDRY_API_KEY. В стеке Compose передайте переменную серверу. В Kubernetes поместите её в Secret cma-server-upstream. Если в файле значений сервера указано earlierNames: true, у Secret другое имя. Найдите его в разделе Kubernetes: имена ваших объектов.
• Microsoft Entra ID: оставьте переменную ANTHROPIC_FOUNDRY_API_KEY неустановленной. Тогда сервер получает токен для субъекта-службы, удостоверения рабочей нагрузки в Azure Kubernetes Service или управляемого удостоверения. Удостоверению нужна роль Azure в ресурсе Foundry, разрешающая вызовы его развёртываний моделей. Для субъекта-службы установите AZURE_TENANT_ID, AZURE_CLIENT_ID и AZURE_CLIENT_SECRET.

Запрос к Foundry указывает развёртывание, и сервер отправляет идентификатор модели в качестве имени развёртывания. Если у развёртывания другое имя, сопоставьте его с помощью model_id_overrides.

Сопоставление отличающегося идентификатора модели

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

Шлюз моделей

Сначала проверьте, какие запросы принимает ваш “model gateway” (шлюз моделей):

• Те же запросы, что и Claude API, с одними долгоживущими учётными данными: оставьте поставщика по умолчанию. Установите в ANTHROPIC_BASE_URL адрес шлюза, а в ANTHROPIC_API_KEY или ANTHROPIC_AUTH_TOKEN — учётные данные, которые ожидает шлюз.
• Те же запросы, что и Claude API, но с краткосрочными токенами, учётными данными в другом заголовке или собственными идентификаторами моделей: установите inference.provider: gateway с format: anthropic-messages.
• Формат InvokeModel Amazon Bedrock: установите inference.provider: gateway с format: bedrock-invoke.
• Формат rawPredict Claude Models on Google Cloud (Google managed): установите inference.provider: gateway с format: vertex-raw-predict.

Этот пример устанавливает inference.provider: gateway с format: bedrock-invoke для шлюза, который принимает один долгоживущий ключ. Поместите ключ в переменную окружения и укажите имя переменной, но никогда не само значение:

inference:
  provider: gateway
  gateway:
    url: "https://llm-gateway.example.com/v1/model/{model}/invoke"
    format: bedrock-invoke
    # Quote every model_map value.
    model_map:
      claude-opus-5-5: "us.anthropic.claude-opus-5-5"
      claude-sonnet-5: "us.anthropic.claude-sonnet-5"
  credentials:
    supplier: env
    env: { var: LLM_GATEWAY_KEY }
    send_as: { header: x-api-key }

• url — маршрут модели в шлюзе. {model} отмечает место, куда подставляется идентификатор модели. URL должен начинаться с https:// и оканчиваться на /invoke.
• model_map сопоставляет каждый идентификатор модели, который может указать агент, с идентификатором, который ожидает шлюз. Сервер отклоняет модель, для которой нет записи.
• send_as задаёт заголовок, в котором передаётся ключ. Без него сервер отправляет Authorization: Bearer <key>.
• В стеке Compose передайте переменную серверу.
• В Kubernetes чарт сервера не может передать вашу собственную переменную. Но он передаёт ANTHROPIC_AUTH_TOKEN, которую считывает из Secret cma-server-upstream, поэтому используйте это имя:
  1. Установите env: { var: ANTHROPIC_AUTH_TOKEN }.
  2. Поместите ключ шлюза в Secret cma-server-upstream под именем ANTHROPIC_AUTH_TOKEN. Если в файле значений сервера указано earlierNames: true, у Secret другое имя. Найдите его в разделе Kubernetes: имена ваших объектов.

Для format: anthropic-messages замените блок gateway следующим:

inference:
  gateway:
    url: "https://llm-gateway.example.com/v1/messages"
    format: anthropic-messages
    # Quote every model_map value.
    model_map:
      claude-opus-5-5: "corp-claude-opus"
      claude-sonnet-5: "corp-claude-sonnet"

Здесь url — полный URL маршрута Messages шлюза, без {model}.

Для format: vertex-raw-predict замените блок gateway следующим:

inference:
  gateway:
    url: "https://llm-gateway.example.com/v1/projects/my-project/locations/global/publishers/anthropic/models/{model}:rawPredict"
    format: vertex-raw-predict
    # Quote every model_map value.
    model_map:
      claude-opus-5-5: "claude-opus-5-5"
      claude-sonnet-5: "claude-sonnet-5"

Здесь url — маршрут rawPredict шлюза, и он должен оканчиваться на /{model}:rawPredict. Значение в model_map не может содержать двоеточие. Блок credentials остаётся без изменений. Сервер отправляет собственные учётные данные вашего шлюза и не получает учётных данных Google.

В справочнике по конфигурации перечислены другие настройки шлюза, такие как streaming и параметр inference.headers.

Краткосрочные токены

Если ваш шлюз принимает краткосрочные токены, замените блок credentials следующим:

inference:
  credentials:
    supplier: oauth_exchange
    assertion:
      url: "https://app.example.com/assertion"
      auth: { type: mtls, cert_file: /etc/callback/client.pem, key_file: /etc/callback/client.key }
    exchange:
      token_url: "https://login.example.com/oauth2/token"
      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer"

Тогда сервер получает каждый токен в два этапа. Сначала он обращается к HTTP-“callback” (обратному вызову), который создаёте вы. Обратный вызов возвращает “assertion” (утверждение) — подписанное заявление, обычно являющееся JSON Web Token (JWT). Затем сервер обменивает утверждение на вашем эндпоинте токенов OAuth на токен доступа, который он отправляет шлюзу.

• auth определяет, как сервер проходит аутентификацию в обратном вызове. В примере используется клиентский сертификат. Чтобы использовать bearer-токен, который сервер считывает из файла, установите auth: { type: bearer_file, token_file: /etc/callback/token }.
• exchange указывает ваш эндпоинт токенов OAuth. Сервер отправляет на этот эндпоинт только grant_type и утверждение, без идентификатора клиента и секрета.
• Если вашему эндпоинту токенов нужно больше, не указывайте exchange. Пусть ваш обратный вызов сам получает токен доступа и возвращает его в поле assertion, которое сервер затем отправляет шлюзу.
• В Kubernetes поместите файлы сертификатов в Secret, укажите его имя в server.extensionFiles.secretName чарта и направьте cert_file и key_file на /run/cma-server/extension-files/.

Сервер отправляет обратному вызову запрос POST со следующим телом:

{
  "version": 1,
  "purpose": "inference",
  "session": {
    "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
    "agent_id": "agent_011CYm1BLqPXpQRk5khsSXrs",
    "environment_id": "env_01595EKxaaTTGwwY3kyXdtbs"
  },
  "principal": {
    "issuer": "https://login.example.com/oauth2/default",
    "subject": "00u1a2b3c4d5e6f7g8h9"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

principal — это вызывающая сторона, создавшая сессию. Для вызывающей стороны с единым входом issuer — это issuer_url этой вызывающей стороны, а subject — её субъект. Для ключа API сервера principal — это {"issuer": "cma", "subject": "server"}. Пусть обратный вызов игнорирует поля, которые ему неизвестны.

Обратный вызов отвечает кодом состояния 200 и следующим телом:

{ "assertion": "<signed JWT>", "reuse": "session" }

reuse указывает, какие сессии могут использовать токен. При значении session, используемом по умолчанию, его может использовать только сессия из запроса, что подходит для токена, указывающего одного пользователя. При значении deployment сессии используют токен совместно, поэтому возвращайте deployment только для токена, который указывает вашу организацию и ни одного человека.

Если обратный вызов или эндпоинт токенов завершается ошибкой, ход заканчивается событием session.error с типом model_request_failed_error, а сессия остаётся пригодной к использованию. Причина указана в журнале сервера, в строке, содержащей credential supplier failed.

Если в ответе эндпоинта токенов нет expires_in, а в токене нет заявки exp, сервер отправляет токен, но не сохраняет его. Тогда он запрашивает новый токен при каждом вызове модели.

Описание других настроек, таких как renew_before и ca_file, см. в таблицах справочника по конфигурации: настройки шлюза моделей и настройки краткосрочных токенов.

Токены Microsoft Entra ID

Если ваш шлюз проверяет токены Microsoft Entra ID по собственной регистрации приложения, замените блок credentials следующим:

inference:
  credentials:
    supplier: azure
    azure: { scope: "api://11111111-2222-3333-4444-555555555555/.default" }

scope — это URI идентификатора приложения или идентификатор приложения из регистрации приложения шлюза, за которым следует /.default. Указывайте только собственную регистрацию шлюза. Токен для другого ресурса позволил бы тому, кто управляет шлюзом, действовать там от имени сервера.

Токен выдаётся собственному удостоверению Azure сервера, настроенному так же, как для Microsoft Entra ID в разделе Microsoft Foundry. Если регистрация требует роли приложения, назначьте эту роль удостоверению до запуска сервера. Более позднее назначение вступает в силу только тогда, когда сервер получает новый токен.

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

Проверка поставщика

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

level=INFO msg="upstream credential resolved" provider=bedrock

Эта строка не доказывает, что в вашей учётной записи включена модель. Отсутствующая модель проявляется как session.error на первом ходе, в котором она используется.

Шлюз, который вы указываете в ANTHROPIC_BASE_URL, может отклонять поле или заголовок резервного переключения на стороне сервера. Если по этой причине каждый ход завершается ошибкой, установите inference.model_fallback: false в файле настроек.