Microsoft Foundry 中的 Claude

本指南說明如何使用 Anthropic 的其中一個客戶端 SDK 或直接 HTTP 請求，在 Microsoft Foundry 中設定並對 Claude 進行 API 呼叫。當您在 Microsoft Foundry 中存取 Claude 時，Claude 的使用費用會透過 Azure Marketplace 計費。您可以使用最新的 Claude 模型，包括 Claude Opus 5、Claude Opus 4.8 和 Claude Sonnet 5，以及 100 萬 token 上下文視窗等功能，同時透過您的 Azure 訂閱管理成本。

Claude 在 Foundry 資源中提供 Global Standard 和 US Data Zone Standard 部署類型，並透過 Azure Marketplace 以 Claude Consumption Units 計費。詳情請參閱 Microsoft Foundry 中的 Claude 定價。



託管選項

Microsoft Foundry 中的 Claude 模型提供兩種託管選項。您在設定部署時選擇託管選項。



先決條件

開始之前，請確保您具備：

• 有效的 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 快速入門。

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. 使用 Azure 核發的 API 金鑰或 Entra ID（原名 Azure Active Directory）設定存取管理，以進行角色型存取控制。
4. 可選擇將資源設定為私人網路（Azure 虛擬網路）的一部分，以限制對資源的網路存取。
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-5）。無論模型支援多少種託管選項，每個模型在目錄中只會出現一次。
3. 在模型卡片上，選擇 Deploy，然後選擇 Custom settings 以開啟部署設定窗格。如果您改為選擇 Default settings，對於兩種託管選項皆可用的模型，部署會自動設定為託管於 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 下拉式選單中選擇版本。每個託管選項都列為單獨的模型版本，並標示其託管選項（例如，版本 1 為託管於 Anthropic，版本 2 為託管於 Azure）。
6. 選擇 Deploy 並等待佈建完成。
7. 部署完成後，選擇右上方導覽中的 Build，然後選擇左側窗格中的 Models，並開啟您的部署。Details 索引標籤會顯示 Target URI（您的端點 URL）和 Key（您的 API 金鑰）。

如果 New Foundry 切換開關已關閉，則您處於傳統入口網站版面配置。在該版面中，開啟左側窗格中的 Model catalog 以尋找和部署模型，並開啟 Models + endpoints（位於 My assets 下）以檢視您的部署及其端點詳細資料。



驗證

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/）。C# SDK 不會讀取此變數：它一律從資源名稱建構基礎 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. 為您的 Foundry 資源啟用 Microsoft Entra ID 驗證。
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)



關聯請求 ID

Foundry 在 HTTP 回應標頭中包含請求識別碼，用於偵錯和追蹤。聯絡支援團隊時，請同時提供 request-id 和 apim-request-id（Azure API Management）值，以協助團隊在 Anthropic 和 Azure 系統中快速定位和調查您的請求。



功能支援

Microsoft Foundry 中的 Claude 支援大多數 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 在 Microsoft Foundry 上具有 100 萬 token 上下文視窗。其他 Claude 模型（包括 Claude Sonnet 4.5）具有 20 萬 token 上下文視窗。



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 物件，該物件提供您請求的詳細 token 消耗資訊。usage 物件在所有平台（Claude API、Amazon Bedrock、AWS 上的 Claude Platform、Foundry 和 Google Cloud）上都是一致的。

有關 Foundry 專屬回應標頭的詳細資訊，請參閱關聯請求 ID。



API 模型 ID 和部署

生命週期術語（已棄用、已停用）定義於模型棄用。Microsoft Foundry 遵循 Claude API 生命週期排程。

以下 Claude 模型可透過 Foundry 使用：

預設情況下，部署名稱與上表中顯示的模型 ID 相符。但是，您可以在 Foundry 入口網站中建立具有不同名稱的自訂部署，以管理不同的設定、版本或速率限制。在您的 API 請求中使用部署名稱（不一定是模型 ID）。



計費

Microsoft Foundry 中的 Claude 透過 Azure Marketplace 計費。使用量以 Claude Consumption Units（CCU）計價，每小時計量，並在您的 Azure 帳單上按月後付費開立發票。CCU 不是預付點數。沒有 CCU 餘額或承諾用量。

有關 CCU 價格、轉換機制和每個模型的 token 費率，請參閱 Microsoft Foundry 中的 Claude 定價。



在託管選項之間遷移

若要將現有部署從一個託管選項移至另一個：

1. 建立該模型另一個託管版本（託管於 Azure 或託管於 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-opus-5）。
• 解決方案： 確保模型/部署在您的 Azure 區域中可用。

錯誤： Invalid model parameter

• 解決方案： model 參數應包含您的部署名稱，該名稱可在 Foundry 入口網站中自訂。請確認部署存在且已正確設定。



後續步驟



其他資源