Microsoft Foundry의 Claude

이 가이드는 Anthropic의 클라이언트 SDK 중 하나 또는 직접 HTTP 요청을 사용하여 Microsoft Foundry에서 Claude를 설정하고 API 호출을 수행하는 과정을 안내합니다. Microsoft Foundry에서 Claude에 액세스하면 Azure Marketplace에서 Claude 사용량에 대한 요금이 청구되므로, Azure 구독을 통해 비용을 관리하면서 Claude의 최신 기능에 액세스할 수 있습니다.

Claude는 Foundry 리소스에서 Global Standard 및 US Data Zone Standard 배포 유형으로 제공되며, Azure Marketplace를 통해 Claude Consumption Unit 단위로 요금이 청구됩니다. 자세한 내용은 가격 책정을 참조하세요.



호스팅 옵션

Microsoft Foundry의 Claude 모델은 두 가지 호스팅 옵션으로 제공됩니다. 배포를 구성할 때 호스팅 옵션을 선택합니다.



사전 요구 사항

시작하기 전에 다음 사항을 확인하세요:

• 활성 Azure 구독
• Foundry에 대한 액세스
• Azure CLI 설치 (선택 사항, 리소스 관리용)



SDK 설치

Anthropic의 클라이언트 SDK는 플랫폼별 패키지 또는 클라이언트 클래스를 통해 Foundry를 지원합니다.



프로비저닝

Foundry는 2단계 계층 구조를 사용합니다. 리소스는 보안 및 청구 구성을 포함하고, 배포는 API를 통해 호출하는 모델 인스턴스입니다. 먼저 Foundry 리소스를 생성한 다음, 그 안에 하나 이상의 Claude 배포를 생성합니다.



Foundry 리소스 프로비저닝

Azure에서 서비스를 사용하고 관리하는 데 필요한 Foundry 리소스를 생성하세요. 다음 지침에 따라 Foundry 리소스를 생성할 수 있습니다. 또는 Foundry 리소스 생성을 포함하는 Foundry 프로젝트를 생성하는 것으로 시작할 수도 있습니다.

리소스를 프로비저닝하려면:

1. Foundry 포털로 이동하세요
2. 새 Foundry 리소스를 생성하거나 기존 리소스를 선택하세요
3. Azure에서 발급한 API 키 또는 역할 기반 액세스 제어를 위한 Entra ID(이전 Azure Active Directory)를 사용하여 액세스 관리를 구성하세요
4. 선택적으로 보안 강화를 위해 리소스를 프라이빗 네트워크(Azure Virtual Network)의 일부로 구성하세요
5. 리소스 이름을 기록해 두세요. API 엔드포인트에서 {resource}로 사용됩니다(예: https://{resource}.services.ai.azure.com/anthropic/v1/*)



Foundry 배포 생성

리소스를 생성한 후, Claude 모델을 배포하여 API 호출에 사용할 수 있도록 하세요. 다음 단계는 새로운 Foundry 포털(New Foundry 토글이 켜진 상태)을 설명합니다:

1. Foundry 포털에 로그인하세요. 포털 홈페이지에서 오른쪽 상단 탐색 메뉴의 Discover를 선택한 다음, 왼쪽 창에서 Models를 선택하여 모델 카탈로그를 여세요.
2. Claude 모델(예: claude-opus-4-8)을 검색하고 선택하세요. 각 모델은 지원하는 호스팅 옵션 수와 관계없이 카탈로그에 한 번만 표시됩니다.
3. 모델 카드에서 Deploy를 선택한 다음 Custom settings를 선택하여 배포 설정 창을 여세요. 대신 Default settings를 선택하면 두 호스팅 옵션 모두에서 사용 가능한 모델의 경우 배포가 자동으로 Hosted on Azure로 구성됩니다.
4. 첫 번째 Claude 배포 시 Azure Marketplace 약관을 검토하고, 업종을 선택한 다음, Agree and Proceed를 선택하여 약관에 동의하고 Azure Marketplace 제품을 구독하세요.
5. 배포를 구성하세요:
   • 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).
6. Deploy를 선택하고 프로비저닝이 완료될 때까지 기다리세요.
7. 배포가 완료되면 오른쪽 상단 탐색 메뉴에서 Build를 선택한 다음, 왼쪽 창에서 Models를 선택하고 배포를 여세요. Details 탭에 Target URI(엔드포인트 URL)와 Key(API 키)가 표시됩니다.



인증

Microsoft Foundry의 Claude는 API 키와 Entra ID 토큰이라는 두 가지 인증 방법을 지원합니다. 두 방법 모두 https://{resource}.services.ai.azure.com/anthropic/v1/* 형식의 Azure 호스팅 엔드포인트를 사용합니다.



API 키 인증

Foundry Claude 리소스를 프로비저닝한 후 Foundry 포털에서 API 키를 얻을 수 있습니다:

1. Foundry 포털에서 오른쪽 상단 탐색 메뉴의 Build를 선택한 다음, 왼쪽 창에서 Models를 선택하세요.
2. Claude 배포를 열고 Details 탭을 선택하세요.
3. Key 값을 복사하세요(엔드포인트를 위해 Target URI도 기록해 두세요).
4. 요청에서 api-key 또는 x-api-key 헤더를 사용하거나 SDK에 제공하세요.

Foundry SDK는 API 키와 리소스 이름 또는 기본 URL 중 하나가 필요합니다. C#, Java, PHP, Python 및 TypeScript SDK는 다음 환경 변수가 정의된 경우 자동으로 읽습니다:

• ANTHROPIC_FOUNDRY_API_KEY - API 키
• ANTHROPIC_FOUNDRY_RESOURCE - 리소스 이름(예: example-resource)
• ANTHROPIC_FOUNDRY_BASE_URL - 리소스 이름의 대안; 전체 기본 URL(예: https://example-resource.services.ai.azure.com/anthropic/)

API 키 사용 예시:



Microsoft Entra 인증

보안 강화 및 중앙 집중식 액세스 관리를 위해 Entra ID 토큰을 사용할 수 있습니다:

1. Foundry 리소스에 대해 Entra 인증을 활성화하세요
2. Entra ID에서 액세스 토큰을 얻으세요
3. Authorization: Bearer {TOKEN} 헤더에 토큰을 사용하세요

Entra ID 사용 예시:



상관 관계 요청 ID

Foundry는 디버깅 및 추적을 위해 HTTP 응답 헤더에 요청 식별자를 포함합니다. 지원팀에 문의할 때 request-id와 apim-request-id 값을 모두 제공하면 팀이 Anthropic 및 Azure 시스템 전반에서 요청을 빠르게 찾고 조사하는 데 도움이 됩니다.



기능 지원

Microsoft Foundry의 Claude는 Claude의 강력한 기능 대부분을 지원합니다. 현재 지원되는 모든 기능은 기능 개요에서 확인할 수 있습니다.



컨텍스트 윈도우

Claude Fable 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 및 Claude Sonnet 4.6은 Microsoft Foundry에서 100만 토큰 컨텍스트 윈도우를 제공합니다. Claude Sonnet 4.5를 포함한 다른 Claude 모델은 20만 토큰 컨텍스트 윈도우를 제공합니다.



Microsoft Foundry의 Claude에서 지원되지 않는 Claude 기능

• 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 응답

Microsoft Foundry의 Claude에서 제공하는 API 응답은 표준 Claude API 응답 형식을 따릅니다. 여기에는 응답 본문의 usage 객체가 포함되며, 이는 요청에 대한 자세한 토큰 소비 정보를 제공합니다. usage 객체는 모든 플랫폼(Claude API, Foundry, AWS의 Claude Platform, Amazon Bedrock 및 Google Cloud)에서 일관됩니다.

Foundry 전용 응답 헤더에 대한 자세한 내용은 상관 관계 요청 ID를 참조하세요.



API 모델 ID 및 배포

수명 주기 용어(Deprecated, Retired)는 모델 지원 중단에 정의되어 있습니다. Microsoft Foundry는 Claude API 수명 주기 일정을 따릅니다.

다음 Claude 모델은 Foundry를 통해 사용할 수 있습니다:

기본적으로 배포 이름은 앞의 표에 표시된 모델 ID와 일치합니다. 그러나 Foundry 포털에서 서로 다른 구성, 버전 또는 속도 제한을 관리하기 위해 다른 이름으로 사용자 지정 배포를 생성할 수 있습니다. API 요청에서는 배포 이름(반드시 모델 ID일 필요는 없음)을 사용하세요.



청구

Microsoft Foundry의 Claude는 Azure Marketplace를 통해 청구됩니다. 사용량은 Claude Consumption Unit(CCU)으로 표시되며, 시간 단위로 측정되고 Azure 청구서에 월별 후불로 청구됩니다. CCU는 선불 크레딧이 아니며, CCU 잔액이나 약정이 없습니다.

CCU 가격, 변환 방식 및 모델별 토큰 요금은 Microsoft Foundry의 Claude 가격 책정을 참조하세요.



호스팅 옵션 간 마이그레이션

기존 배포를 한 호스팅 옵션에서 다른 호스팅 옵션으로 이동하려면:

1. 모델의 다른 호스팅 버전(Hosted on Azure 또는 Hosted on Anthropic)으로 새 배포를 생성하세요. 동일한 Foundry 리소스 내에 생성하거나 새 리소스에 생성할 수 있습니다.
2. 애플리케이션을 업데이트하여 model 매개변수에 새 배포 이름을 전달하세요.
3. 트래픽이 이동한 후 이전 배포를 삭제하세요.

새 배포가 동일한 Foundry 리소스에 있는 경우 엔드포인트 URL과 인증은 변경되지 않습니다. 새 리소스를 생성한 경우 애플리케이션의 엔드포인트와 자격 증명을 새 리소스를 가리키도록 업데이트하세요.



모니터링 및 로깅

Azure는 표준 Azure 패턴을 통해 Claude 사용량에 대한 포괄적인 모니터링 및 로깅 기능을 제공합니다:

• 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

• 해결 방법: 올바른 배포 이름을 사용하고 있는지 확인하세요. 사용자 지정 배포를 생성하지 않은 경우 기본 모델 ID(예: claude-sonnet-4-6)를 사용하세요.
• 해결 방법: 모델/배포가 Azure 지역에서 사용 가능한지 확인하세요.

오류: Invalid model parameter

• 해결 방법: model 매개변수에는 Foundry 포털에서 사용자 지정할 수 있는 배포 이름이 포함되어야 합니다. 배포가 존재하고 올바르게 구성되었는지 확인하세요.



추가 리소스

• Foundry 문서: ai.azure.com/catalog
• Azure 가격 책정: azure.microsoft.com/en-us/pricing/details/ai-foundry
• Anthropic 가격 세부 정보: 모델 가격 책정
• 인증 가이드: 인증 참조
• Azure 포털: portal.azure.com