Microsoft Foundry의 Claude
Microsoft Foundry의 Claude (Claude in Microsoft Foundry)
이 가이드는 Anthropic의 클라이언트 SDK 또는 직접 HTTP 요청으로 Microsoft Foundry에서 Claude에 접근하고 API 호출을 하는 방법을 보여줘요. Microsoft Foundry에서 Claude에 접근하면 Claude 사용량은 Azure Marketplace로 청구돼요. Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5 같은 모델과 1M 토큰 컨텍스트 창 같은 기능을 Azure 구독으로 비용을 관리하면서 사용할 수 있어요.
출처: 문서
본문
이 가이드는 Anthropic의 클라이언트 SDK 또는 직접 HTTP 요청으로 Microsoft Foundry에서 Claude에 접근하고 API 호출을 하는 방법을 보여줘요. Microsoft Foundry에서 Claude에 접근하면 Claude 사용량은 Azure Marketplace로 청구돼요. Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5 같은 모델과 1M 토큰 컨텍스트 창 같은 기능을 사용할 수 있으며, Azure 구독으로 비용을 관리할 수 있어요.
Claude는 Foundry 리소스의 Global Standard와 US Data Zone Standard 배포 유형으로 사용할 수 있고, Azure Marketplace를 통해 Claude 소비 단위(CCU)로 청구돼요. 자세한 내용은 Microsoft Foundry의 Claude 가격을 방문하세요.
호스팅 옵션 (Hosting options)
Microsoft Foundry의 Claude 모델은 두 가지 호스팅 옵션으로 사용할 수 있어요. 배포를 구성할 때 호스팅 옵션을 선택해요.
| Hosted on Azure | Hosted on Anthropic | |
|---|---|---|
| 추론이 실행되는 곳 | Azure 인프라에서 실행되는 Anthropic 운영 서비스 | Anthropic 인프라에서 실행되는 Anthropic 운영 서비스 |
| 모델 가용성 | Opus, Sonnet, Haiku 계열의 최신 모델 | Microsoft Foundry에서 사용 가능한 모든 Claude 모델 |
| 배포 유형 | Global Standard, US Data Zone Standard | Global Standard |
| 추천 대상 | 대부분 워크로드 | 아직 Azure에 호스팅되지 않은 기능 또는 모델 접근 |
참고: Anthropic은 Microsoft의 독립 처리자(independent processor)로 행동해요. Microsoft Foundry로 Claude를 사용하는 고객은 Anthropic의 데이터 사용 약관의 적용을 받아요. Azure에 호스팅된 배포의 경우 프롬프트와 완료는 Azure 내에 유지돼요. 사용 메타데이터와 Anthropic의 안전 시스템이 플래그한 콘텐츠만 Anthropic으로 이탈해요. Anthropic은 자신의 안전과 데이터 약속을 계속 제공해요.
사전 요구 사항 (Prerequisites)
시작하기 전에 다음이 있는지 확인하세요:
- 활성 Azure 구독
- Foundry 포털 접근
- 설치된 Azure CLI(Entra ID cURL 예시에 필요, 그 외에는 선택)
- 리소스 사용을 허용하는 Azure RBAC 역할(Foundry User(이전 Azure AI User) 또는 Cognitive Services User 등)
SDK 설치하기
Anthropic의 클라이언트 SDK는 플랫폼별 패키지나 클라이언트 클래스를 통해 Foundry를 지원해요. 이 페이지의 예시는 cURL과 ant CLI로도 요청을 보여줘요. CLI 설정은 CLI 퀵스타트를 참고하세요.
참고: Foundry는 C#, Java, PHP, Python, TypeScript SDK에서 지원돼요. Foundry는 현재 Go와 Ruby SDK에서는 사용할 수 없어요.
# For Entra ID authentication, also install the Azure Identity library
pip install azure-identity
```
# For Entra ID authentication, also install the Azure Identity library
npm install @azure/identity
```
// For Entra ID authentication, also add the Azure Identity library
implementation("com.azure:azure-identity:1.18.3")
```
</Tab>
<Tab title="Maven">
```xml
<dependency>
<groupId>com.anthropic</groupId>
<artifactId>anthropic-java</artifactId>
<version>2.65.0</version>
</dependency>
<dependency>
<groupId>com.anthropic</groupId>
<artifactId>anthropic-java-foundry</artifactId>
<version>2.65.0</version>
</dependency>
<!-- For Entra ID authentication, also add the Azure Identity library -->
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.18.3</version>
</dependency>
```
</Tab>
</Tabs>
프로비저닝 (Provisioning)
Foundry는 두 수준 계층을 사용해요. 리소스는 당신의 보안과 청구 구성을 포함하고, 배포는 API를 통해 호출하는 모델 인스턴스예요. 먼저 Foundry 리소스를 만든 다음, 그 안에 하나 이상의 Claude 배포를 만들어요.
Foundry 리소스 프로비저닝
Azure에서 서비스를 사용·관리하는 데 필요한 Foundry 리소스를 만드세요. 다음 지침으로 Foundry 리소스를 만들 수 있어요. 대안으로 Foundry 프로젝트를 만들어 시작할 수도 있는데, 이는 Foundry 리소스 생성을 수반해요.
리소스를 프로비저닝하려면:
- Foundry 포털로 이동하세요.
- 새 Foundry 리소스를 만들거나 기존 것을 선택하세요.
- Azure 발급 API 키 또는 역할 기반 접근 제어를 위한 Entra ID(이전 Azure Active Directory)로 접근 관리를 구성하세요.
- 선택적으로 리소스를 사설 네트워크(Azure Virtual Network)의 일부로 구성해 리소스에 대한 네트워크 접근을 제한하세요.
- 리소스 이름을 기록하세요. 이것을 API 엔드포인트의
{resource}로 사용해요(예:https://{resource}.services.ai.azure.com/anthropic/v1/*).
Foundry 배포 생성
리소스를 만든 후 Claude 모델을 배포해 API 호출에 사용할 수 있게 하세요. 이 단계들은 새 Foundry 포털(New Foundry 토글이 켜짐)을 설명해요:
- Foundry 포털에 로그인하세요. 포털 홈페이지에서 오른쪽 상단 탐색의 Discover를 선택하고, 왼쪽 창의 Models를 선택해 모델 카탈로그를 여세요.
- Claude 모델(예: claude-opus-5)을 검색하고 선택하세요. 각 모델은 지원하는 호스팅 옵션 수와 무관하게 카탈로그에 한 번 나타나요.
- 모델 카드에서 Deploy를 선택한 다음 Custom settings를 선택해 배포 설정 창을 여세요. 대신 Default settings를 선택하면, 두 호스팅 옵션에서 모두 사용 가능한 모델의 경우 배포가 자동으로 Hosted on Azure로 구성돼요.
- 첫 Claude 배포에서 Azure Marketplace 약관을 검토하고, 산업을 선택하고, Agree and Proceed를 선택해 약관을 수락하고 Azure Marketplace 제안에 구독하세요.
- 배포를 구성하세요:
- Deployment name: 모델 ID로 기본값이 정해지지만 맞춤 설정할 수 있어요(예:
my-claude-deployment). 배포 이름은 생성 후 변경할 수 없어요. - Region scope: Global을 선택하거나, Azure에 호스팅된 모델은 Data Zone을 선택하세요. Data Zone을 선택하면 US Data Zone Standard 배포가 생성되고, 이는 추론을 미국 내에 유지하며 Claude API에서
inference_geo: "us"를 설정하는 것과 동일해요. - Model version: Model version settings를 펼치고 Model version 드롭다운 메뉴에서 버전을 선택하세요. 각 호스팅 옵션이 별도의 모델 버전으로 나열되고, 호스팅 옵션으로 라벨이 붙어 있어요(예: Hosted on Anthropic는 버전 1, Hosted on Azure는 버전 2).
- Deployment name: 모델 ID로 기본값이 정해지지만 맞춤 설정할 수 있어요(예:
- Deploy를 선택하고 프로비저닝이 완료될 때까지 기다리세요.
- 배포되면 오른쪽 상단 탐색의 Build를 선택하고 왼쪽 창의 Models를 선택한 다음 배포를 여세요. Details 탭이 Target URI(엔드포인트 URL)와 Key(API 키)를 보여줘요.
New Foundry 토글이 꺼져 있으면 클래식 포털 레이아웃이에요. 거기서는 왼쪽 창의 Model catalog를 열어 모델을 찾아 배포하고, (My assets 아래의) Models + endpoints를 열어 배포와 엔드포인트 상세를 봐요.
참고: 선택한 배포 이름이 API 요청의
model매개변수에 전달하는 값이 돼요. 같은 모델의 배포를 다른 이름으로 여러 개 만들어 별도의 구성이나 속도 제한을 관리할 수 있어요.
인증 (Authentication)
Microsoft Foundry의 Claude는 API 키와 Entra ID 토큰의 두 가지 인증 방법을 지원해요. 두 방법 모두 https://{resource}.services.ai.azure.com/anthropic/v1/* 형식의 Azure 호스팅 엔드포인트를 사용해요.
API 키 인증
Foundry Claude 리소스를 프로비저닝한 후 Foundry 포털에서 API 키를 얻을 수 있어요:
- Foundry 포털에서 오른쪽 상단 탐색의 Build를 선택한 다음 왼쪽 창의 Models를 선택하세요.
- Claude 배포를 열고 Details 탭을 선택하세요.
- Key 값을 복사하고(엔드포인트의 Target URI도 기록)하세요.
- 요청에서
api-key또는x-api-key헤더를 사용하거나 SDK에 제공하세요.
Foundry SDK는 API 키와 리소스 이름 또는 base URL을 요구해요. C#, Java, PHP, Python, TypeScript SDK는 다음 환경 변수가 정의되어 있으면 자동으로 읽어요:
ANTHROPIC_FOUNDRY_API_KEY- API 키ANTHROPIC_FOUNDRY_RESOURCE- 리소스 이름(예:example-resource)ANTHROPIC_FOUNDRY_BASE_URL- 리소스 이름의 대안: 전체 base URL(예:https://example-resource.services.ai.azure.com/anthropic/). C# SDK는 이 변수를 읽지 않아요. 항상 리소스 이름으로 base URL을 구성해요.
참고:
resource와base_url매개변수는 상호 배타적이에요. 리소스 이름(URL을https://{resource}.services.ai.azure.com/anthropic/로 구성하는 데 SDK가 사용) 또는 전체 base URL을 직접 제공하세요.
API 키 사용 예시:
# ant reads ANTHROPIC_API_KEY and sends it as x-api-key, which Foundry accepts
export ANTHROPIC_API_KEY="YOUR_AZURE_API_KEY"
ant messages create \
--base-url https://example-resource.services.ai.azure.com/anthropic \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello!"}' \
--transform content
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-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)
import AnthropicFoundry from "@anthropic-ai/foundry-sdk";
const client = new AnthropicFoundry({
apiKey: proces...KEY,
resource: "example-resource" // your resource name
});
const message = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
});
console.log(message.content);
using Anthropic.Foundry;
using Anthropic.Models.Messages;
var client = new AnthropicFoundryClient(
new AnthropicFoundryApiKeyCredentials(
Environment.GetEnvironmentVariable("ANTHROPIC_FOUNDRY_API_KEY")!,
"example-resource"
)
);
var response = await client.Messages.Create(new MessageCreateParams
{
Model = "claude-opus-5-5",
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello!" }],
});
Console.WriteLine(
string.Join("", response.Content
.Select(block => block.Value)
.OfType<TextBlock>()
.Select(textBlock => textBlock.Text)));
// The Go SDK does not yet support Foundry natively. This example uses the
// standard Go SDK as a workaround. WithoutEnvironmentDefaults keeps the
// client from also reading ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN from
// the environment and sending a Claude API credential to your Foundry
// endpoint. Features that Foundry does not support fail server-side rather
// than client-side. For full Foundry support, use the C#, Java, PHP,
// Python, or TypeScript SDKs.
package main
import (
"context"
"fmt"
"os"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/option"
)
func main() {
client := anthropic.NewClient(
option.WithoutEnvironmentDefaults(),
option.WithBaseURL("https://example-resource.services.ai.azure.com/anthropic"),
option.WithAPIKey(os.Getenv("ANTHROPIC_FOUNDRY_API_KEY")),
)
message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
Model: "claude-opus-5-5",
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
})
if err != nil {
panic(err)
}
fmt.Println(message.Content)
}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.foundry.backends.FoundryBackend;
import com.anthropic.models.messages.MessageCreateParams;
void main() {
// Requires env vars: ANTHROPIC_FOUNDRY_API_KEY, ANTHROPIC_FOUNDRY_RESOURCE
AnthropicClient client = AnthropicOkHttpClient.builder()
.backend(FoundryBackend.fromEnv())
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-5-5")
.maxTokens(1024)
.addUserMessage("Hello!")
.build();
client.messages().create(params).content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
use Anthropic\Foundry;
$client = Foundry\Client::withCredentials(
apiKey: getenv...Y'),
baseUrl: 'https://example-resource.services.ai.azure.com/anthropic',
);
$message = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'Hello!']
],
model: 'claude-opus-5-5',
);
echo array_find($message->content, fn ($block) => $block->type === 'text')->text;
# The Ruby SDK does not yet support Foundry natively. This example uses the
# standard Ruby SDK as a workaround. Pass credentials explicitly: without
# them, the client falls back to the ANTHROPIC_API_KEY or
# ANTHROPIC_AUTH_TOKEN environment variables and could send a Claude API
# credential to your Foundry endpoint. Features that Foundry
# does not support fail server-side rather than client-side. For full
# Foundry support, use the C#, Java, PHP, Python, or TypeScript SDKs.
require "anthropic"
client = Anthropic::Client.new(
base_url: "https://example-resource.services.ai.azure.com/anthropic",
api_key: ENV.fetch("ANTHROPIC_FOUNDRY_API_KEY")
)
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{role: "user", content: "Hello!"}]
)
puts message.content.find { it.type == :text }.text
경고: API 키를 안전하게 유지하세요. 버전 관리에 커밋하거나 공개적으로 공유하지 마세요. API 키에 접근할 수 있는 사람은 누구든 당신의 Foundry 리소스를 통해 Claude에 요청할 수 있어요.
Microsoft Entra 인증
Entra ID 인증은 Azure RBAC로 접근을 관리하고, 조직의 ID 관리와 통합하며, API 키를 수동으로 처리하지 않게 해 줘요. Entra ID 토큰을 사용하려면:
- Foundry 리소스에 대해 Microsoft Entra ID 인증을 활성화하세요.
- Entra ID에서 액세스 토큰을 얻으세요.
Authorization: Bearer ***헤더에 토큰을 사용하세요.
Entra ID 사용 예시:
Make request with token. Replace {resource} with your resource name
curl https://{resource}.services.ai.azure.com/anthropic/v1/messages
-H "content-type: application/json"
-H "Authorization: Bearer ***"
-H "anthropic-version: 2023-06-01"
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
```bash CLI
# The ant CLI can send a bearer token with --auth-token, but a set
# ANTHROPIC_API_KEY environment variable takes precedence over it (the CLI
# prints only a console notice), so your request could authenticate with
# the wrong credential. For the Entra ID flow, use the cURL example or one
# of the SDK examples instead.
from anthropic import AnthropicFoundry
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
# Get Microsoft Entra ID token using token provider pattern
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://ai.azure.com/.default"
)
# Create client with Entra ID authentication
client = AnthropicFoundry(
resource="example-resource", # your resource name
azure_ad_token_provider=token_provider, # Use token provider for Entra ID auth
)
# Make request
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)
import AnthropicFoundry from "@anthropic-ai/foundry-sdk";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
// Get Entra ID token using token provider pattern
const credential = new DefaultAzureCredential();
const tokenProvider = getBearerTokenProvider(credential, "https://ai.azure.com/.default");
// Create client with Entra ID authentication
const client = new AnthropicFoundry({
resource: "example-resource", // your resource name
azureADTokenProvider: tokenProvider // Use token provider for Entra ID auth
});
// Make request
const message = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
});
console.log(message.content);
using Anthropic.Foundry;
using Anthropic.Models.Messages;
using Azure.Identity;
var client = new AnthropicFoundryClient(
new AnthropicFoundryIdentityTokenCredentials(
new DefaultAzureCredential(),
"example-resource"
)
);
var response = await client.Messages.Create(new MessageCreateParams
{
Model = "claude-opus-5-5",
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello!" }],
});
Console.WriteLine(
string.Join("", response.Content
.Select(block => block.Value)
.OfType<TextBlock>()
.Select(textBlock => textBlock.Text)));
// The Go SDK does not yet support Foundry natively. This example uses the
// standard Go SDK as a workaround, with a static Entra ID token: automatic
// token refresh is not built in, so your application must refresh tokens
// itself (they typically expire after 1 hour). WithoutEnvironmentDefaults
// keeps the client from also reading ANTHROPIC_API_KEY or
// ANTHROPIC_AUTH_TOKEN from the environment and sending a Claude API
// credential to your Foundry endpoint. For full Foundry support, use the
// C#, Java, PHP, Python, or TypeScript SDKs.
package main
import (
"context"
"fmt"
"os"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/option"
)
func main() {
// Obtain an Entra ID access token, for example using the Azure CLI:
// az account get-access-token --resource https://ai.azure.com \
// --query accessToken -o tsv
client := anthropic.NewClient(
option.WithoutEnvironmentDefaults(),
option.WithBaseURL("https://example-resource.services.ai.azure.com/anthropic"),
option.WithAuthToken(os.Getenv("AZURE_ACCESS_TOKEN")),
)
message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
Model: "claude-opus-5-5",
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
})
if err != nil {
panic(err)
}
fmt.Println(message.Content)
}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.foundry.backends.FoundryBackend;
import com.anthropic.models.messages.MessageCreateParams;
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredentialBuilder;
import java.util.function.Supplier;
void main() {
Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
new DefaultAzureCredentialBuilder().build(),
"https://ai.azure.com/.default"
);
AnthropicClient client = AnthropicOkHttpClient.builder()
.backend(FoundryBackend.builder()
.bearerTokenSupplier(bearerTokenSupplier)
.resource("example-resource")
.build())
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-5-5")
.maxTokens(1024)
.addUserMessage("Hello!")
.build();
client.messages().create(params).content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
use Anthropic\Foundry;
// Obtain an Entra ID access token, for example using the Azure CLI:
// az account get-access-token --resource https://ai.azure.com \
// --query accessToken -o tsv
$token = getenv('AZURE_ACCESS_TOKEN');
$client = Foundry\Client::withCredentials(
authToken: $token,
baseUrl: 'https://example-resource.services.ai.azure.com/anthropic',
);
$message = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'Hello!']
],
model: 'claude-opus-5-5',
);
echo array_find($message->content, fn ($block) => $block->type === 'text')->text;
# The Ruby SDK does not yet support Foundry natively. This example uses the
# standard Ruby SDK as a workaround, with a static Entra ID token: automatic
# token refresh is not built in, so your application must refresh tokens
# itself (they typically expire after 1 hour). Pass credentials explicitly:
# without them, the client falls back to the ANTHROPIC_API_KEY or
# ANTHROPIC_AUTH_TOKEN environment variables. For full Foundry support, use
# the C#, Java, PHP, Python, or TypeScript SDKs.
require "anthropic"
# Obtain an Entra ID access token, for example using the Azure CLI:
# az account get-access-token --resource https://ai.azure.com \
# --query accessToken -o tsv
client = Anthropic::Client.new(
base_url: "https://example-resource.services.ai.azure.com/anthropic",
auth_token: ENV.fetch("AZURE_ACCESS_TOKEN")
)
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{role: "user", content: "Hello!"}]
)
puts message.content.find { it.type == :text }.text
상관 요청 ID (Correlation request IDs)
Foundry는 디버깅과 추적을 위해 HTTP 응답 헤더에 요청 식별자를 포함해요. 지원에 연락할 때 request-id와 apim-request-id(Azure API Management) 값을 모두 제공해 주세요. 그러면 팀이 Anthropic과 Azure 시스템 양쪽에서 요청을 빠르게 찾고 조사할 수 있어요.
기능 지원 (Feature support)
Microsoft Foundry의 Claude는 대부분 Claude 기능을 지원해요. 현재 지원되는 모든 기능은 기능 개요에서 찾을 수 있어요.
컨텍스트 창 (Context window)
Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6은 Microsoft Foundry에서 1M 토큰 컨텍스트 창을 가져요. Claude Sonnet 4.5를 포함한 다른 Claude 모델은 200k 토큰 컨텍스트 창을 가져요.
Microsoft Foundry의 Claude에서 지원되지 않는 Claude 기능
- Admin API
- Advisor 도구
- Claude Managed Agents
- Compliance API
- Models API
- Message Batches API
- 서버 측 폴백(
fallbacks매개변수. 대신 클라이언트 측 폴백 패턴 사용) - 컴퓨터 사용 및 browser use 도구셋(
computer_toolset_20260801과browser_toolset_20260801은 현재 Microsoft Foundry에서 사용할 수 없음. 베타 컴퓨터 사용 도구 버전은 계속 사용 가능)
Azure에 호스팅될 때 지원되지 않는 추가 기능
다음 기능은 Anthropic에 호스팅된 배포에서 사용할 수 있지만 Azure에 호스팅된 배포에서는 지원되지 않아요:
- 코드 실행
web_search_20250305와web_fetch_20250910보다 이후 버전의 웹 검색 및 웹 패치 도구. Azure에 호스팅된 배포는 이러한 기본 버전만 지원하므로, 동적 필터링, 응답 포함, 캐시 우회는 사용할 수 없어요.- Agent Skills
- 프로그래매틱 도구 호출
- Files API
Azure에 호스팅된 배포에 대해 이러한 기능을 사용하는 요청은 설계상 400 Bad Request 오류를 반환해요. Claude Code는 Azure에 호스팅된 배포를 감지해 기능 집합을 자동으로 적응시켜요.
API 응답 (API responses)
Microsoft Foundry의 Claude에서 온 API 응답은 표준 Claude API 응답 형식을 따르고, 응답 본문의 usage 객체를 포함해요. 이는 요청에 대한 상세 토큰 소비 정보를 제공해요. usage 객체는 모든 플랫폼(Claude API, Amazon Bedrock, Claude Platform on AWS, Foundry, Google Cloud)에서 일관돼요.
Foundry 특유의 응답 헤더에 대한 자세한 내용은 상관 요청 ID를 참고하세요.
API 모델 ID와 배포 (API model IDs and deployments)
수명 주기 용어(Deprecated, Retired)는 모델 폐기에서 정의돼요. Microsoft Foundry는 Claude API 수명 주기 일정을 따르고 있어요.
다음 Claude 모델을 Foundry를 통해 사용할 수 있어요:
| 모델 | 기본 배포 이름 | Hosted on Azure | Hosted on Anthropic |
|---|---|---|---|
| Claude Fable 5.1 | claude-fable-5-1 |
✓ | |
| Claude Mythos 5.1 (제한적 가용성) | claude-mythos-5-1 |
✓ | |
| Claude Fable 5 | claude-fable-5 |
✓ | |
| Claude Mythos 5 (제한적 가용성) | claude-mythos-5 |
✓ | |
| Claude Opus 5.5 | claude-opus-5-5 |
✓ | ✓ |
| Claude Opus 5 | claude-opus-5 |
✓ | ✓ |
| Claude Opus 4.8 | claude-opus-4-8 |
✓ | ✓ |
| Claude Opus 4.7 | claude-opus-4-7 |
✓ | |
| Claude Opus 4.6 | claude-opus-4-6 |
✓ | |
| Claude Opus 4.5 | claude-opus-4-5 |
✓ | |
| Claude Sonnet 5 | claude-sonnet-5 |
✓ | ✓ |
| Claude Sonnet 4.6 | claude-sonnet-4-6 |
✓ | |
| Claude Sonnet 4.5 | claude-sonnet-4-5 |
✓ | |
| Claude Haiku 4.5 | claude-haiku-4-5 |
✓ | ✓ |
기본적으로 배포 이름은 앞선 표의 모델 ID와 일치해요. 하지만 Foundry 포털에서 다른 이름의 맞춤 배포를 만들어 별도의 구성, 버전, 속도 제한을 관리할 수 있어요. API 요청에는 (반드시 모델 ID가 아니라) 배포 이름을 사용하세요.
정보: Claude Mythos Preview는 Microsoft Foundry에서 초대받은 고객에게 제공되는 연구 미리보기예요.
팁: 더 새로운 Claude 모델로 업그레이드하시나요? Claude Code에서
/claude-api migrate를 실행해 코드베이스 전반에 모델 ID 교체와 호환성이 깨지는 매개변수 변경을 적용하세요. 이 스킬은 코드가 대상으로 하는 클라우드 플랫폼을 감지해 그 플랫폼에 맞게 모델 ID 형식과 기능 변경을 조정해요. 더 새로운 Claude 모델로 마이그레이션을 참고하세요.
청구 (Billing)
Microsoft Foundry의 Claude는 Azure Marketplace를 통해 청구돼요. 사용량은 Claude 소비 단위(CCU)로 표시되고, 시간 단위로 계량되며, Azure 청구서에 월 단위로 소급 청구돼요. CCU는 선불 크레딧이 아니에요. CCU 잔액이나 약정은 없어요.
CCU 가격, 변환 메커니즘, 모델별 토큰 요금은 Microsoft Foundry의 Claude 가격을 참고하세요.
호스팅 옵션 간 마이그레이션
기존 배포를 한 호스팅 옵션에서 다른 옵션으로 이동하려면:
- 모델의 다른 호스팅 버전(Hosted on Azure 또는 Hosted on Anthropic)의 새 배포를 만드세요. 같은 Foundry 리소스나 새 리소스에 만들 수 있어요.
- 애플리케이션을 업데이트해
model매개변수에 새 배포 이름을 전달하세요. - 트래픽이 이동했으면 옛 배포를 삭제하세요.
새 배포가 같은 Foundry 리소스에 있으면 엔드포인트 URL과 인증은 변경되지 않아요. 새 리소스를 만들었다면 애플리케이션의 엔드포인트와 자격 증명을 그것을 가리키도록 업데이트하세요.
모니터링과 로깅 (Monitoring and logging)
Azure는 표준 Azure 패턴을 통해 Claude 사용량에 대한 모니터링과 로깅을 제공해요:
- Azure Monitor: API 사용량, 지연 시간, 오류율 추적
- Azure Log Analytics: 요청/응답 로그 쿼리와 분석
- Cost Management: Claude 사용량과 관련된 비용 모니터링과 예측
Anthropic은 사용 패턴을 이해하고 잠재적 문제를 조사하기 위해 활동을 최소 30일 단위로 로깅할 것을 권장해요.
참고: Azure의 로깅 서비스는 Azure 구독 안에서 구성돼요. 로깅을 활성화해도 Microsoft나 Anthropic이 청구와 서비스 운영에 필요한 것 이상으로 당신의 콘텐츠에 접근하지 않아요.
문제 해결 (Troubleshooting)
인증 오류
오류: 401 Unauthorized 또는 Invalid API key
- 해결: API 키가 올바른지 확인하세요. 배포의 Details 탭(Build > Models 아래)의 Foundry 포털에서 찾을 수 있어요.
- 해결: 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
- 해결: 올바른 배포 이름을 사용하고 있는지 확인하세요. 맞춤 배포를 만들지 않았다면 기본 모델 ID(예: claude-opus-5)를 사용하세요.
- 해결: 모델/배포가 Azure 지역에서 사용 가능한지 확인하세요.
오류: Invalid model parameter
- 해결: model 매개변수는 배포 이름을 포함해야 하고, 이는 Foundry 포털에서 맞춤 설정할 수 있어요. 배포가 존재하고 올바르게 구성되었는지 확인하세요.