🏠 Главная › Документация › Гайды

Azure AI Foundry

Hermes Agent поддерживает Azure AI Foundry (и Azure OpenAI) как провайдера первого класса. Один Azure-ресурс может размещать модели с двумя различными сетевыми форматами:

Мастер настройки проверяет ваш эндпоинт и автоматически определяет, какой транспорт используется, какие развёртывания доступны и длину контекста каждой модели.

Предварительные требования

Быстрый старт

hermes model
# → Select "Azure Foundry"
# → Enter your endpoint URL
# → Enter your API key
# Hermes probes the endpoint and auto-detects transport + models
# → Pick a model from the list (or type a deployment name manually)

Мастер выполнит следующее:

  1. Анализирует путь URL — URL-адреса, оканчивающиеся на /anthropic, распознаются как маршруты Azure Foundry Claude.

  2. Проверяет GET <base>/models — если эндпоинт возвращает список моделей в формате OpenAI, Hermes переключается на chat_completions и заполняет список выбора ID развёртываний.

  3. Проверяет формат Anthropic Messages — запасной вариант для эндпоинтов, которые не предоставляют /models, но принимают формат Anthropic Messages.

  4. Возвращается к ручному вводу — частные/закрытые эндпоинты, отклоняющие все проверки, всё равно работают; вы выбираете режим API и вводите имя развёртывания вручную.

Длина контекста для выбранной модели определяется через стандартную цепочку метаданных Hermes (models.dev, метаданные провайдера и жёстко заданные запасные варианты для семейств моделей) и сохраняется в config.yaml, чтобы модель могла правильно рассчитать размер своего окна контекста.

Конфигурация (записывается в config.yaml)

После запуска мастера вы увидите примерно следующее:

model:
  provider: azure-foundry
  base_url: https://my-resource.openai.azure.com/openai/v1
  api_mode: chat_completions         # or "anthropic_messages"
  default: gpt-5.4-mini              # your deployment / model name
  context_length: 400000             # auto-detected

И в ~/.hermes/.env:

AZURE_FOUNDRY_API_KEY=<your-azure-key>

Эндпоинты в стиле OpenAI (GPT, Llama и др.)

GA-эндпоинт v1 Azure OpenAI принимает стандартный Python-клиент openai с минимальными изменениями:

model:
  provider: azure-foundry
  base_url: https://my-resource.openai.azure.com/openai/v1
  api_mode: chat_completions
  default: gpt-5.4

Важные особенности:

Эндпоинты в стиле Anthropic (Claude через Azure Foundry)

Для развёртываний Claude используйте маршрут в стиле Anthropic:

model:
  provider: azure-foundry
  base_url: https://my-resource.services.ai.azure.com/anthropic
  api_mode: anthropic_messages
  default: claude-sonnet-4-6

Важные особенности:

Альтернатива: provider: anthropic + Azure base URL

Если у вас уже настроен provider: anthropic и вы просто хотите направить его на Azure AI Foundry для Claude, вы можете полностью пропустить провайдера azure-foundry:

model:
  provider: anthropic
  base_url: https://my-resource.services.ai.azure.com/anthropic
  key_env: AZURE_ANTHROPIC_KEY
  default: claude-sonnet-4-6

С AZURE_ANTHROPIC_KEY, установленным в ~/.hermes/.env. Hermes обнаруживает azure.com в base URL и обходит цепочку OAuth-токена Claude Code, чтобы Azure-ключ использовался напрямую с аутентификацией x-api-key.

key_env — это каноническое имя поля в snake_case; api_key_env (а также camelCase keyEnv / apiKeyEnv) принимаются как псевдонимы. Если установлены и key_env, и AZURE_ANTHROPIC_KEY/ANTHROPIC_API_KEY, побеждает переменная окружения, указанная в key_env.

Обнаружение моделей

Azure не предоставляет эндпоинт, использующий только API-ключ, для просмотра ваших развёрнутых моделей. Перечисление развёртываний требует аутентификации Azure Resource Manager (az cognitiveservices account deployment list) с субъектом Azure AD, а не ключом inference API.

Что может сделать Hermes:

Вы всегда можете ввести имя развёртывания напрямую — Hermes не проверяет его по возвращённому списку.

Переменные окружения

Переменная Назначение
AZURE_FOUNDRY_API_KEY Основной API-ключ для Azure AI Foundry / Azure OpenAI
AZURE_FOUNDRY_BASE_URL URL эндпоинта (задаётся через hermes model; переменная окружения используется как запасной вариант)
AZURE_ANTHROPIC_KEY Используется provider: anthropic + Azure base URL (альтернатива ANTHROPIC_API_KEY)

Устранение неполадок

401 Unauthorized на развёртываниях gpt-5.x. Azure обслуживает gpt-5.x на /chat/completions, а не на /responses. Hermes обрабатывает это автоматически, когда URL содержит openai.azure.com, но если вы видите 401 с телом Invalid API key, проверьте, что api_mode в вашем config.yaml установлен в chat_completions.

404 на /v1/messages?api-version=.../v1/messages. Это ошибка некорректного URL из старых настроек Azure Anthropic. Обновите Hermes — параметр api-version теперь передаётся через default_query, а не встраивается в base URL, поэтому SDK не может его повредить при объединении путей.

Мастер говорит: «Автоматическое обнаружение не завершено.» Эндпоинт отклонил как проверку /models, так и проверку Anthropic Messages. Это нормально для частных эндпоинтов за файрволом или с IP-белым списком. Вернитесь к ручному выбору режима API и введите имя развёртывания — всё будет работать, Hermes просто не может предзаполнить список.

Выбран неправильный транспорт. Запустите hermes model снова, и мастер выполнит повторную проверку. Если проверка по-прежнему выбирает неправильный режим, вы можете отредактировать config.yaml напрямую:

model:
  provider: azure-foundry
  api_mode: anthropic_messages   # or chat_completions