Microsoft Foundry

Провайдер azure-foundry в VibeOS поддерживает Microsoft Foundry (ранее Azure AI Foundry) и Azure OpenAI. Один ресурс Foundry может размещать модели с двумя разными сетевыми форматами:

• В стиле OpenAI — POST /v1/chat/completions на эндпоинтах вида https://<resource>.openai.azure.com/openai/v1. Используется для GPT-4.x, GPT-5.x, Llama, Mistral и большинства моделей с открытыми весами.
• В стиле Anthropic — POST /v1/messages на эндпоинтах вида https://<resource>.services.ai.azure.com/anthropic. Используется, когда Microsoft Foundry обслуживает модели Claude через формат Anthropic Messages API.

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

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

• Ресурс Microsoft Foundry или Azure OpenAI хотя бы с одним развёртыванием
• URL-адрес эндпоинта развёртывания
• Либо ключ API (из портала Azure, раздел «Ключи и эндпоинт»), либо роль RBAC Azure AI User на ресурсе Foundry, если вы планируете использовать Microsoft Entra ID (рекомендуемый Microsoft путь без ключей). В некоторых арендаторах роль может отображаться как Foundry User в процессе переименования Microsoft.

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

vibeos model
# → Выберите «Azure Foundry»
# → Введите URL вашего эндпоинта
# → Выберите аутентификацию:
#     1. Ключ API
#     2. Microsoft Entra ID  (управляемое удостоверение / workload identity / az login)
# → (Entra) VibeOS проверяет DefaultAzureCredential; при успехе ключ больше не запрашивается
# → (Ключ API) Введите ваш ключ API
# VibeOS проверяет эндпоинт и автоматически определяет транспорт + модели
# → Выберите модель из списка (или введите имя развёртывания вручную)

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

1. Анализ пути URL — URL, оканчивающиеся на /anthropic, распознаются как маршруты Microsoft Foundry Claude.
2. Проверка GET <base>/models — если эндпоинт возвращает список моделей в формате OpenAI, VibeOS переключается на chat_completions и заполняет список выбора идентификаторами развёртываний.
3. Проверка формата Anthropic Messages — запасной вариант для эндпоинтов, которые не предоставляют /models, но принимают формат Anthropic Messages.
4. Ручной ввод как запасной вариант — частные/закрытые эндпоинты, отклоняющие все проверки, всё равно работают; вы выбираете режим API и вводите имя развёртывания вручную.

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

Microsoft Entra ID (без ключей, RBAC) — рекомендуется

Microsoft рекомендует аутентификацию без ключей с Microsoft Entra ID для рабочих нагрузок Foundry в production. VibeOS поддерживает Entra ID для обоих API-интерфейсов:

• В стиле OpenAI (api_mode: chat_completions / codex_responses) — GPT-4/5, Llama, Mistral, DeepSeek и др.
• В стиле Anthropic (api_mode: anthropic_messages) — модели Claude на Microsoft Foundry.

RBAC Foundry действует на уровне ресурса (Azure AI User предоставляет доступ к обоим интерфейсам; в некоторых арендаторах может отображаться Foundry User), и Microsoft документирует одну и ту же область действия вывода (https://ai.azure.com/.default) для обоих. Под капотом:

• Стиль OpenAI использует собственный вызываемый контракт api_key= Python SDK OpenAI — SDK автоматически создаёт новый JWT для каждого запроса.
• Стиль Anthropic использует httpx.Client с установленным хуком события запроса от agent.azure_identity_adapter.build_bearer_http_client, поскольку Anthropic SDK изначально не принимает вызываемый auth_token. Хук перезаписывает Authorization: Bearer <fresh-jwt> для каждого исходящего запроса. Тот же RBAC Microsoft, та же область Foundry — разница только в контракте SDK.

Зачем использовать Entra ID?

• Нет долгоживущих ключей API, которые нужно ротировать или отзывать.
• Доступ на основе RBAC — предоставьте или удалите Azure AI User на ресурсе Foundry, не требуется перенастройка конфигурации.
• Журналы доступа и аудита сегментированы по назначенным лицам, а не все вызывающие используют один статический ключ.
• Единый интерфейс аутентификации для виртуальных машин Azure, подов AKS, App Service, Functions, Container Apps и Foundry Agent Service через управляемое удостоверение.
• Потоки workload identity и субъекта-службы для конвейеров CI/CD.

Одноразовая настройка (сторона Azure)

1. На портале Azure откройте ваш ресурс Foundry → Управление доступом (IAM) → Добавить → Добавить назначение ролей.
2. Выберите роль Azure AI User (или Foundry User, если в вашем арендаторе используется переименованная роль).
3. Назначьте её:
   • Вашей учётной записи для локальной разработки с az login.
   • Управляемому удостоверению или workload identity для вычислительных ресурсов Azure (рекомендуется для production).
   • Удостоверению агента размещённого агента Foundry Agent Service, когда VibeOS работает внутри размещённого агента.
   • Субъекту-службе для конвейеров CI/CD, когда workload identity недоступен.
4. Подождите ~5 минут для распространения роли.

Эквивалент в Azure CLI:

az role assignment create \
  --assignee <principal-or-agent-identity-client-id> \
  --role "Azure AI User" \
  --scope <foundry-resource-id>

Одноразовая настройка (сторона VibeOS)

vibeos model
# → Выберите «Azure Foundry»
# → Введите URL вашего эндпоинта
# → Аутентификация: 2 (Microsoft Entra ID)
# → (необязательно) идентификатор клиента управляемого удостоверения, назначенного пользователем
# → (необязательно) идентификатор арендатора Azure
# → VibeOS проверяет DefaultAzureCredential() и сообщает, какое внутреннее
#    удостоверение сработало (например, AzureCliCredential, ManagedIdentityCredential)

Мастер выполняет ограниченную предварительную проверку (тайм-аут 10 с). В случае неудачи он предлагает «сохранить в любом случае, проверить позже» — полезно при настройке на машине, у которой ещё нет учётных данных, но они появятся во время выполнения (например, подготовка конфигурации для развёртывания с управляемым удостоверением).

azure-identity устанавливается автоматически при первом использовании через механизм ленивой установки VibeOS. Для предварительной установки:

pip install azure-identity

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

model:
  provider: azure-foundry
  base_url: https://my-resource.openai.azure.com/openai/v1
  api_mode: chat_completions
  auth_mode: entra_id
  default: gpt-4o
  context_length: 128000
  entra:
    scope: https://ai.azure.com/.default        # только при переопределении значения по умолчанию

VibeOS управляет только одним специфическим для Entra параметром в config.yaml:

• scope — область действия ресурса OAuth. По умолчанию используется документированная Microsoft область действия вывода (https://ai.azure.com/.default). Переопределяйте только в том случае, если ваш ресурс был подготовлен для нестандартной аудитории.

Всё остальное (арендатор, секрет субъекта-службы, файл федеративного токена, центр суверенного облака, настройки брокера) считывается azure-identity напрямую из стандартных переменных окружения AZURE_* — см. порядок разрешения учётных данных ниже. Установите их в ~/.vibeos/.env или в вашей среде развёртывания, в точности как описано в справочнике Microsoft SDK.

Никакие секреты не попадают в ~/.vibeos/.env для режима Entra — azure-identity кэширует токены в процессе (и, где возможно, в вашей связке ключей ОС / ~/.IdentityService).

Порядок разрешения учётных данных

DefaultAzureCredential из azure-identity проходит по этой цепочке при каждом запросе токена, останавливаясь на первом удостоверении, которое возвращает токен:

1. Удостоверение среды — AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_SECRET (или AZURE_CLIENT_CERTIFICATE_PATH / AZURE_FEDERATED_TOKEN_FILE).
2. Workload Identity — AZURE_FEDERATED_TOKEN_FILE (федеративные токены AKS / OIDC).
3. Управляемое удостоверение — конечная точка IMDS (169.254.169.254) для виртуальных машин; IDENTITY_ENDPOINT для App Service / Functions / Container Apps. Размещённые агенты Foundry Agent Service используют удостоверение агента размещённого агента.
4. Visual Studio Code — расширение учётной записи Azure.
5. Azure CLI — сессия az login.
6. Azure Developer CLI — azd auth login.
7. Azure PowerShell — Connect-AzAccount.
8. Брокер (только Windows / WSL) — Web Account Manager.

Интерактивное удостоверение браузера исключено по умолчанию для автоматических запусков VibeOS; вместо него используйте Azure CLI, Azure Developer CLI, управляемое удостоверение, workload identity или учётные данные субъекта-службы.

Шаблоны развёртывания

Локальная разработка:

az login
vibeos model   # выберите Azure Foundry → Entra ID
vibeos         # использует ваш токен az login

Виртуальная машина Azure / Functions / App Service / Container Apps (системное управляемое удостоверение):

1. Включите системное удостоверение на вычислительном ресурсе.
2. Предоставьте удостоверению роль Azure AI User (или Foundry User) на ресурсе Foundry.
3. Установите model.auth_mode: entra_id в config.yaml — переменные окружения не требуются.

Виртуальная машина Azure / Functions / App Service / Container Apps (управляемое удостоверение, назначенное пользователем):

• Установите AZURE_CLIENT_ID в идентификатор клиента удостоверения, назначенного пользователем, чтобы DefaultAzureCredential выбрал правильное.

Размещённый агент Foundry Agent Service:

• Создайте размещённого агента и предоставьте удостоверению этого агента роль Azure AI User (или Foundry User) на ресурсе Foundry. VibeOS использует ManagedIdentityCredential изнутри размещённого агента; назначение роли должно быть на удостоверение агента, а не только на родительский проект или вашего пользователя.

AKS Workload Identity (заменяет AAD Pod Identity):

• Аннотируйте учётную запись службы пода идентификатором клиента workload identity.
• Файл федеративного токена пода автоматически обнаруживается через AZURE_FEDERATED_TOKEN_FILE.
• model.auth_mode: entra_id работает без дополнительных изменений конфигурации.

Субъект-служба в CI:

• Установите AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET в окружении раннера.

Суверенные облака (Government, China)

Экспортируйте AZURE_AUTHORITY_HOST (например, https://login.microsoftonline.us для Azure Government, https://login.partner.microsoftonline.cn для Azure China). azure-identity считывает его напрямую.

Проверки работоспособности

vibeos doctor выполняет 10-секундную проверку DefaultAzureCredential, когда model.auth_mode: entra_id, сообщая, какое внутреннее удостоверение сработало (присутствуют переменные окружения, доступна конечная точка управляемого удостоверения и т.д.).

vibeos auth показывает структурированный блок состояния:

azure-foundry (Microsoft Entra ID):
  Endpoint: https://my-resource.openai.azure.com/openai/v1
  Scope: https://ai.azure.com/.default
  Status: configured; live token probe is skipped here

Ограничения

• Эндпоинты в стиле Anthropic используют хук события httpx. Anthropic Python SDK (≤ 0.86.0) изначально не принимает вызываемый auth_token. VibeOS устанавливает хук события запроса на пользовательский httpx.Client, который создаёт новый JWT для каждого исходящего запроса и перезаписывает Authorization: Bearer <jwt>. Функционально это эквивалентно собственному контракту Callable[[], str] SDK OpenAI, но добавляет один уровень косвенности. Если Anthropic SDK добавит первоклассную поддержку вызываемой аутентификации в будущем релизе, VibeOS прозрачно переключится на неё.
• Пакетные задания и multiprocessing.Pool. Провайдер токенов Entra — это замыкание, которое не может быть сериализовано через границы процессов. batch_runner.py автоматически удаляет вызываемый объект из конфигурации рабочего процесса и позволяет каждому рабочему процессу перестроить свой собственный провайдер из config.yaml — никаких действий от пользователя не требуется, но каждый рабочий процесс выполняет один проход по цепочке при запуске.
• Нет сохранения JWT-токена в auth.json. VibeOS не дублирует внутренний кэш токенов azure-identity; холодные запуски проходят по цепочке учётных данных при первом выводе.

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

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

model:
  provider: azure-foundry
  base_url: https://my-resource.openai.azure.com/openai/v1
  api_mode: chat_completions         # или "anthropic_messages"
  default: gpt-5.4-mini              # имя вашего развёртывания / модели
  context_length: 400000             # автоматически определено

И в ~/.vibeos/.env:

AZURE_FOUNDRY_API_KEY=<your-azure-key>

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

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

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

Важное поведение:

• GPT-5.x, codex и o-серия автоматически перенаправляются на Responses API. Microsoft Foundry развёртывает модели GPT-5 / codex / o1 / o3 / o4 только через Responses API — вызов /chat/completions для них возвращает 400 "The requested operation is unsupported.". VibeOS определяет эти семейства моделей по имени и прозрачно повышает api_mode до codex_responses, даже если в config.yaml всё ещё указано api_mode: chat_completions. GPT-4, GPT-4o, Llama, Mistral и другие развёртывания остаются на /chat/completions.
• max_completion_tokens используется автоматически. Azure OpenAI (как и прямой OpenAI) требует max_completion_tokens для моделей gpt-4o, o-серии и gpt-5.x. VibeOS отправляет правильный параметр на основе эндпоинта.
• Эндпоинты до v1, требующие api-version. Если у вас устаревший базовый URL вида https://<resource>.openai.azure.com/openai?api-version=2025-04-01-preview, VibeOS извлекает строку запроса и передаёт её через default_query в каждом запросе (в противном случае SDK OpenAI отбрасывает её при объединении путей).

Эндпоинты в стиле Anthropic (Claude через Microsoft 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

Важное поведение:

• /v1 удаляется из базового URL. Anthropic SDK добавляет /v1/messages к каждому URL запроса — VibeOS удаляет любой завершающий /v1 перед передачей URL в SDK, чтобы избежать двойных путей /v1.
• api-version передаётся через default_query, а не добавляется к URL. Azure Anthropic требует строку запроса api-version. Встраивание её в базовый URL приводит к некорректным путям вида /anthropic?api-version=.../v1/messages и возвращает 404. VibeOS передаёт api-version=2025-04-15 через default_query SDK Anthropic.
• Используется Bearer-аутентификация вместо x-api-key. Совместимый с Anthropic маршрут Azure требует Authorization: Bearer <key>, а не собственный заголовок x-api-key Anthropic. VibeOS обнаруживает azure.com в базовом URL и направляет ключ API через поле auth_token SDK, чтобы правильный заголовок достиг вышестоящего сервера.
• Заголовок бета-версии контекстного окна 1M сохраняется. Azure по-прежнему ограничивает контекст Claude в 1M токенов (Opus 4.6/4.7, Sonnet 4.6) заголовком anthropic-beta: context-1m-2025-08-07. VibeOS сохраняет этот бета-заголовок на путях Azure (он удаляется из собственных запросов OAuth Anthropic, потому что некоторые подписки его отклоняют, но Azure требует его).
• Обновление токена OAuth отключено. Развёртывания Azure используют статические ключи API. Цикл обновления токена OAuth ~/.claude/.credentials.json, который применяется к Anthropic Console, явно пропускается для эндпоинтов Azure, чтобы предотвратить перезапись вашего ключа Azure токеном OAuth Claude Code в середине сессии.

Альтернатива: provider: anthropic + базовый URL Azure

Если у вас уже настроен provider: anthropic и вы просто хотите направить его на Microsoft 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, установленным в ~/.vibeos/.env. VibeOS обнаруживает azure.com в базовом 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, а не ключом API вывода.

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

• Эндпоинты Azure OpenAI v1 (<resource>.openai.azure.com/openai/v1) предоставляют GET /models с каталогом доступных моделей ресурса. VibeOS использует этот список для предварительного заполнения выбора модели.
• Маршруты Microsoft Foundry /anthropic: обнаруживаются по пути URL, имя модели вводится вручную.
• Частные / защищённые брандмауэром эндпоинты: ручной ввод с дружественным сообщением «не удалось проверить».

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

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

Переменная	Назначение
AZURE_FOUNDRY_API_KEY	Основной ключ API для Microsoft Foundry / Azure OpenAI (режим api_key)
AZURE_FOUNDRY_BASE_URL	URL эндпоинта (устанавливается через vibeos model; переменная окружения используется как запасной вариант)
AZURE_ANTHROPIC_KEY	Используется provider: anthropic + базовый URL Azure (альтернатива ANTHROPIC_API_KEY)
AZURE_TENANT_ID	Арендатор Entra ID для потоков субъекта-службы
AZURE_CLIENT_ID	Идентификатор клиента Entra ID (субъект-служба, workload identity или управляемое удостоверение, назначенное пользователем)
AZURE_CLIENT_SECRET	Секрет субъекта-службы
AZURE_CLIENT_CERTIFICATE_PATH	Сертификат субъекта-службы (альтернатива секрету)
AZURE_FEDERATED_TOKEN_FILE	Путь к федеративному токену Workload Identity (AKS)
AZURE_AUTHORITY_HOST	Переопределение центра суверенного облака
IDENTITY_ENDPOINT / MSI_ENDPOINT	Конечная точка управляемого удостоверения для App Service, Functions и Container Apps; виртуальные машины обычно используют IMDS

Azure SDK считывает переменные окружения AZURE_* напрямую. VibeOS никогда не проверяет их, кроме как для сообщения о том, какие источники присутствуют в выводе vibeos doctor.

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

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

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

Мастер сообщает «Auto-detection incomplete.» Эндпоинт отклонил как проверку /models, так и проверку Anthropic Messages. Это нормально для частных эндпоинтов за брандмауэром или с белым списком IP. Вернитесь к ручному выбору режима API и введите имя развёртывания — всё равно будет работать, VibeOS просто не может предварительно заполнить список выбора.

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

model:
  provider: azure-foundry
  api_mode: anthropic_messages   # или chat_completions

Entra ID: «credential chain exhausted» или 401 Unauthorized после переключения на auth_mode: entra_id.

• Запустите az login, чтобы обновить сессию разработчика (кэшированный токен мог истечь).
• Убедитесь, что назначение роли Azure AI User (или Foundry User) вступило в силу: az role assignment list --assignee <user-or-identity-id> должно показывать её на вашем ресурсе Foundry. Распространение роли может занять до 5 минут.
• Для управляемых удостоверений, назначенных пользователем, перепроверьте, что AZURE_CLIENT_ID соответствует удостоверению, прикреплённому к вычислительному ресурсу.
• Запустите vibeos doctor — проверка Azure Entra сообщает, успешно ли получен токен, и включает подсказку по исправлению.

Entra ID: предварительная проверка мастера зависает или истекает по тайм-ауту. 10-секундная предварительная проверка является мягкой. Выберите «Сохранить в любом случае и проверить позже» и запустите vibeos doctor после развёртывания в целевой среде. Распространённые причины включают недоступную службу токенов или устаревшее состояние локального входа — предпочитайте workload identity в CI, установите AZURE_TENANT_ID+AZURE_CLIENT_ID+AZURE_CLIENT_SECRET при использовании субъекта-службы или запустите az login для локальной разработки.

401 на эндпоинте в стиле Anthropic с Entra ID. Убедитесь, что та же роль Azure AI User (или Foundry User) назначена на ресурсе Foundry (она охватывает оба пути /openai/v1 и /anthropic). Если проверка в стиле OpenAI работает во время мастера, но запросы claude-* завершаются ошибкой во время выполнения, наиболее распространённая причина — устаревший model.entra.scope, оставшийся от предыдущего запуска мастера — удалите строку entra.scope из config.yaml, чтобы среда выполнения вернулась к области по умолчанию https://ai.azure.com/.default.

Связанные темы

• Переменные окружения
• Конфигурация
• AWS Bedrock — интеграция с другим крупным облачным провайдером
• Microsoft: Настройка Entra ID для Foundry — документация Microsoft по пути без ключей