Claude в Microsoft Foundry

Это руководство показывает, как настроить и выполнять вызовы API к Claude в Microsoft Foundry с помощью одного из клиентских SDK Anthropic или прямых HTTP-запросов. При доступе к Claude в Microsoft Foundry плата за использование Claude начисляется через Azure Marketplace. Вы можете использовать новейшие модели Claude, включая Claude Opus 5, Claude Opus 4.8 и Claude Sonnet 5, а также такие функции, как контекстное окно на 1 млн токенов, управляя расходами через вашу подписку Azure.

Claude доступен в типах развёртывания Global Standard и US Data Zone Standard в ресурсах Foundry, а оплата производится в единицах потребления Claude (Claude Consumption Units) через Azure Marketplace. Подробности см. на странице Цены на Claude в Microsoft Foundry.



Варианты размещения

Модели Claude в Microsoft Foundry доступны в двух вариантах размещения. Вы выбираете вариант размещения при настройке развёртывания.



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

Прежде чем начать, убедитесь, что у вас есть:

• Активная подписка Azure
• Доступ к порталу Foundry
• Установленный Azure CLI (требуется для примера cURL с Entra ID, в остальных случаях необязателен)
• Роль Azure RBAC, позволяющая использовать ресурс, например Foundry User (ранее Azure AI User) или Cognitive Services User



Установка SDK

Клиентские SDK Anthropic поддерживают Foundry через специфичный для платформы пакет или класс клиента. Примеры на этой странице также показывают запросы с использованием cURL и ant CLI. Чтобы настроить CLI, см. Быстрый старт CLI.

pip install -U "anthropic"

# Для аутентификации через Entra ID также установите библиотеку Azure Identity
pip install azure-identity



Подготовка ресурсов

Foundry использует двухуровневую иерархию: ресурсы содержат конфигурацию безопасности и биллинга, а развёртывания — это экземпляры моделей, которые вы вызываете через API. Сначала вы создадите ресурс Foundry, а затем одно или несколько развёртываний Claude внутри него.



Подготовка ресурсов Foundry

Создайте ресурс Foundry, который необходим для использования сервисов в Azure и управления ими. Вы можете следовать этим инструкциям, чтобы создать ресурс Foundry. В качестве альтернативы вы можете начать с создания проекта Foundry, что включает создание ресурса Foundry.

Чтобы подготовить ресурс:

1. Перейдите на портал Foundry.
2. Создайте новый ресурс Foundry или выберите существующий.
3. Настройте управление доступом с помощью ключей API, выданных Azure, или Entra ID (ранее Azure Active Directory) для управления доступом на основе ролей.
4. При необходимости настройте ресурс как часть частной сети (Azure Virtual Network), чтобы ограничить сетевой доступ к вашему ресурсу.
5. Запишите имя вашего ресурса. Вы будете использовать его как {resource} в конечных точках API (например, https://{resource}.services.ai.azure.com/anthropic/v1/*).



Создание развёртываний Foundry

После создания ресурса разверните модель Claude, чтобы сделать её доступной для вызовов API. Эти шаги описывают новый портал Foundry (переключатель New Foundry включён):

1. Войдите на портал Foundry. На главной странице портала выберите Discover в правом верхнем меню навигации, затем Models в левой панели, чтобы открыть каталог моделей.
2. Найдите и выберите модель Claude (например, claude-opus-5). Каждая модель отображается в каталоге один раз независимо от того, сколько вариантов размещения она поддерживает.
3. На карточке модели выберите Deploy, затем Custom settings, чтобы открыть панель настроек развёртывания. Если вместо этого вы выберете Default settings, развёртывание будет автоматически настроено как размещённое в Azure для моделей, доступных в обоих вариантах размещения.
4. При первом развёртывании Claude ознакомьтесь с условиями Azure Marketplace, выберите отрасль и нажмите Agree and Proceed, чтобы принять условия и подписаться на предложение Azure Marketplace.
5. Настройте развёртывание:
   • Deployment name: по умолчанию соответствует идентификатору модели, но вы можете изменить его (например, my-claude-deployment). Имя развёртывания нельзя изменить после создания.
   • Region scope: выберите Global или, для моделей, размещённых в Azure, Data Zone. Выбор Data Zone создаёт развёртывание US Data Zone Standard, которое удерживает инференс в пределах США и эквивалентно установке inference_geo: "us" в Claude API.
   • Model version: разверните Model version settings и выберите версию из раскрывающегося меню Model version. Каждый вариант размещения указан как отдельная версия модели с пометкой варианта размещения (например, версия 1 для размещения в Anthropic, версия 2 для размещения в Azure).
6. Выберите Deploy и дождитесь завершения подготовки.
7. После развёртывания выберите Build в правом верхнем меню навигации, затем Models в левой панели и откройте ваше развёртывание. На вкладке Details отображаются Target URI (URL вашей конечной точки) и Key (ваш ключ API).

Если переключатель New Foundry выключен, вы находитесь в классическом интерфейсе портала. В нём откройте Model catalog в левой панели, чтобы найти и развернуть модель, и откройте Models + endpoints (в разделе My assets), чтобы просмотреть ваши развёртывания и сведения об их конечных точках.



Аутентификация

Claude в Microsoft Foundry поддерживает два метода аутентификации: ключи API и токены Entra ID. Оба метода используют конечные точки, размещённые в Azure, в формате https://{resource}.services.ai.azure.com/anthropic/v1/*.



Аутентификация по ключу API

После подготовки ресурса Foundry для Claude вы можете получить ключ API на портале Foundry:

1. На портале Foundry выберите Build в правом верхнем меню навигации, затем Models в левой панели.
2. Откройте ваше развёртывание Claude и выберите вкладку Details.
3. Скопируйте значение Key (и запишите Target URI для вашей конечной точки).
4. Используйте заголовок api-key или x-api-key в ваших запросах либо передайте ключ в SDK.

SDK для Foundry требуют ключ API и либо имя ресурса, либо базовый URL. SDK для C#, Java, PHP, Python и TypeScript автоматически считывают их из следующих переменных окружения, если они определены:

• ANTHROPIC_FOUNDRY_API_KEY — ваш ключ API
• ANTHROPIC_FOUNDRY_RESOURCE — имя вашего ресурса (например, example-resource)
• ANTHROPIC_FOUNDRY_BASE_URL — альтернатива имени ресурса: полный базовый URL (например, https://example-resource.services.ai.azure.com/anthropic/). SDK для C# не считывает эту переменную: он всегда формирует базовый URL из имени ресурса.

Пример с использованием ключа API:

import os
from anthropic import AnthropicFoundry

client = AnthropicFoundry(
    api_key=os.environ.get("ANTHROPIC_FOUNDRY_API_KEY"),
    resource="example-resource",  # your resource name
)

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)



Аутентификация Microsoft Entra

Аутентификация Entra ID позволяет управлять доступом с помощью Azure RBAC, интегрироваться с системой управления идентификацией вашей организации и избежать ручной работы с ключами API. Чтобы использовать токены Entra ID:

1. Включите аутентификацию Microsoft Entra ID для вашего ресурса Foundry.
2. Получите токен доступа от Entra ID.
3. Используйте токен в заголовке Authorization: Bearer {TOKEN}.

Пример с использованием Entra ID:

from anthropic import AnthropicFoundry
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# Получите токен Microsoft Entra ID с помощью паттерна поставщика токенов
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

# Создайте клиент с аутентификацией через Entra ID
client = AnthropicFoundry(
    resource="example-resource",  # your resource name
    azure_ad_token_provider=token_provider,  # Use token provider for Entra ID auth
)

# Выполните запрос
message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)



Идентификаторы запросов для корреляции

Foundry включает идентификаторы запросов в заголовки HTTP-ответов для отладки и трассировки. При обращении в службу поддержки укажите значения request-id и apim-request-id (Azure API Management), чтобы помочь командам быстро найти и исследовать ваш запрос в системах Anthropic и Azure.



Поддержка функций

Claude в Microsoft Foundry поддерживает большинство функций Claude. Все поддерживаемые в настоящее время функции можно найти в разделе Обзор функций.



Контекстное окно

Claude Fable 5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 и Claude Sonnet 4.6 имеют контекстное окно на 1 млн токенов в Microsoft Foundry. Другие модели Claude, включая Claude Sonnet 4.5, имеют контекстное окно на 200 тыс. токенов.



Функции Claude, не поддерживаемые для Claude в Microsoft Foundry

• Admin API
• Инструмент Advisor
• Claude Managed Agents
• Compliance API
• Models API
• Message Batches API
• Резервное переключение на стороне сервера (параметр fallbacks; вместо него используйте шаблон резервного переключения на стороне клиента)



Дополнительные функции, не поддерживаемые при размещении в Azure

Следующие функции доступны для развёртываний, размещённых в Anthropic, но не поддерживаются для развёртываний, размещённых в Azure:

• Структурированные выходные данные
• Серверные инструменты (веб-поиск, веб-загрузка, выполнение кода и поиск инструментов)
• Коннектор MCP
• Agent Skills
• Программный вызов инструментов
• Files API

Запросы, использующие эти функции к развёртыванию, размещённому в Azure, возвращают ошибку 400 Bad Request — это предусмотренное поведение. Claude Code определяет развёртывания, размещённые в Azure, и автоматически адаптирует свой набор функций.



Ответы API

Ответы API от Claude в Microsoft Foundry следуют стандартному формату ответов Claude API. Это включает объект usage в телах ответов, который предоставляет подробную информацию о потреблении токенов для ваших запросов. Объект usage единообразен на всех платформах (Claude API, Amazon Bedrock, Claude Platform на AWS, Foundry и Google Cloud).

Подробности о заголовках ответов, специфичных для Foundry, см. в разделе Идентификаторы запросов для корреляции.



Идентификаторы моделей API и развёртывания

Термины жизненного цикла (Deprecated — устаревшая, Retired — выведенная из эксплуатации) определены в разделе Устаревание моделей. Microsoft Foundry следует графику жизненного цикла Claude API.

Через Foundry доступны следующие модели Claude:

По умолчанию имена развёртываний совпадают с идентификаторами моделей, указанными в таблице выше. Однако вы можете создавать пользовательские развёртывания с другими именами на портале Foundry, чтобы управлять различными конфигурациями, версиями или ограничениями скорости. Используйте имя развёртывания (не обязательно идентификатор модели) в ваших запросах к API.



Биллинг

Оплата за Claude в Microsoft Foundry производится через Azure Marketplace. Использование измеряется в единицах потребления Claude (Claude Consumption Units, CCU), учитывается ежечасно и выставляется в счёте ежемесячно по факту использования в вашем счёте Azure. CCU не являются предоплаченными кредитами. Баланса CCU или обязательств по ним не существует.

Цену CCU, механику конвертации и тарифы на токены для каждой модели см. в разделе Цены на Claude в Microsoft Foundry.



Миграция между вариантами размещения

Чтобы перенести существующее развёртывание с одного варианта размещения на другой:

1. Создайте новое развёртывание другой версии размещения модели (размещение в Azure или размещение в Anthropic). Это можно сделать в том же ресурсе Foundry или в новом.
2. Обновите ваше приложение, чтобы оно передавало новое имя развёртывания в параметре model.
3. Удалите старое развёртывание после переноса трафика.

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



Мониторинг и логирование

Azure предоставляет мониторинг и логирование использования Claude через стандартные механизмы Azure:

• Azure Monitor: отслеживание использования API, задержек и частоты ошибок
• Azure Log Analytics: запросы и анализ логов запросов/ответов
• Cost Management: мониторинг и прогнозирование расходов, связанных с использованием Claude

Anthropic рекомендует вести логирование вашей активности как минимум за скользящий 30-дневный период, чтобы понимать закономерности использования и расследовать возможные проблемы.



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



Ошибки аутентификации

Ошибка: 401 Unauthorized или Invalid API key

• Решение: проверьте правильность вашего ключа API. Вы можете найти его на портале Foundry на вкладке Details вашего развёртывания (в разделе Build > Models).
• Решение: если используется Microsoft Entra ID, убедитесь, что ваш токен доступа действителен и не истёк. Токены обычно истекают через 1 час.

Ошибка: 403 Forbidden

• Решение: у вашей учётной записи Azure может не быть необходимых разрешений. Убедитесь, что вам назначена соответствующая роль Azure RBAC (например, Foundry User (ранее Azure AI User) или Cognitive Services User).



Ограничение скорости

Ошибка: 429 Too Many Requests

• Решение: вы превысили ограничение скорости. Реализуйте в вашем приложении логику экспоненциальной задержки и повторных попыток.
• Решение: рассмотрите возможность запросить увеличение ограничений скорости через портал Azure или службу поддержки Azure.



Заголовки ограничения скорости

Foundry не включает в ответы стандартные заголовки ограничения скорости Anthropic (anthropic-ratelimit-tokens-limit, anthropic-ratelimit-tokens-remaining, anthropic-ratelimit-tokens-reset, anthropic-ratelimit-input-tokens-limit, anthropic-ratelimit-input-tokens-remaining, anthropic-ratelimit-input-tokens-reset, anthropic-ratelimit-output-tokens-limit, anthropic-ratelimit-output-tokens-remaining и anthropic-ratelimit-output-tokens-reset). Вместо этого управляйте ограничением скорости с помощью инструментов мониторинга Azure.



Ошибки моделей и развёртываний

Ошибка: Model not found или Deployment not found

• Решение: убедитесь, что вы используете правильное имя развёртывания. Если вы не создавали пользовательское развёртывание, используйте идентификатор модели по умолчанию (например, claude-opus-5).
• Решение: убедитесь, что модель/развёртывание доступны в вашем регионе Azure.

Ошибка: Invalid model parameter

• Решение: параметр model должен содержать имя вашего развёртывания, которое можно настроить на портале Foundry. Убедитесь, что развёртывание существует и правильно настроено.



Дальнейшие шаги



Дополнительные ресурсы