使用 Bicep 或 Terraform 在 Microsoft Foundry 中部署 Claude 模型

Claude on Foundry 入門套件可透過 Azure Developer CLIazd（）將 Anthropic Claude 模型部署至 Microsoft Foundry。 它也幫助你設定本地認證，並從 Claude Code 或 Python 呼叫已部署的模型。

在本文中，您將學會如何：

  • 使用 Bicep 版本的入門套件，將 Claude Sonnet 部署到 Microsoft Foundry。
  • 設定所需的 Anthropic 模型-提供者證明值。
  • 將 Claude Code 設定為使用 Foundry 託管的模型。
  • 使用 Microsoft Entra ID，從 Python 呼叫已部署的 Claude 模型。
  • 可依 Terraform、更多模型族、其他區域或其他容量自訂部署方式。

Important

使用此入門套件執行 azd up 即表示接受 Anthropic Marketplace 條款，並會隨請求一併傳送證明值 CLAUDE_ORGANIZATION_NAME、CLAUDE_COUNTRY_CODE 和 CLAUDE_INDUSTRY。 設定用模型描述真實組織的數值。 詳情請參閱 使用條款。

快速入門

這條「快樂路徑」透過使用 Bicep eastus2 以容量25（每分鐘 25,000 代幣）部署 Claude Sonnet。 先用它來達到可運作的部署，然後如果需要 Terraform、多個模型家族、其他區域或不同容量，再轉到 自訂部署 。

你需要一個符合 Microsoft Foundry 中 Anthropic Claude 資格的 Azure 訂閱，並有建立目標資源的權限，還有 Azure CLI、Azure Developer CLI、Git 以及 Python 3.10 或更新版本。 如果你的帳號能建立角色指派，快速啟動也會授權你的使用者模型調用權限，讓樣本能立即執行。

複製、配置與部署

如果你的 Claude 符合資格的訂閱屬於非預設租戶，請在兩個登入指令中加入租戶 ID。

git clone https://github.com/Azure-Samples/claude.git
cd claude\infra-bicep

az login
azd auth login

azd env new my-claude
azd env set CLAUDE_ORGANIZATION_NAME "Contoso"
azd env set CLAUDE_COUNTRY_CODE "US"
azd env set CLAUDE_INDUSTRY "technology"
azd env set AZURE_LOCATION "eastus2"
azd env set CLAUDE_SONNET_MODEL "claude-sonnet-4-6"
azd env set CLAUDE_SONNET_CAPACITY 25
azd env set ASSIGN_RBAC true

azd up

使用 Claude 將 Contoso、US 和 technology 替換為實際組織的值。 如果你的帳號無法建立角色指派，跳過 ASSIGN_RBAC 並讓管理員授權模型調用權限再執行範例。

驗證並執行 Claude 程式碼

在儲存庫根目錄中，驗證已產生的設定與部署狀態。 跳過旗標可避免在進行驗證時發出即時的 Claude 呼叫。

cd ..
pwsh -File .\scripts\verify-claude-code.ps1 -SkipClaudeCall -WaitForDeployment

. .\claude-code.env.ps1
claude

執行 Python 範例

將輸出寫入 .env.localazd，安裝相依性，並使用 Microsoft Entra ID 執行一次性範例。

cd infra-bicep
azd env get-values | Out-File -Encoding utf8 ..\.env.local
cd ..
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python src\hello_claude.py

入門套件如何提供協助

入門套件可透過 Bicep 或 Terraform 自動化部署 Claude。 它為 Microsoft Entra ID 配置本地認證，並提供可運作的 Claude Code 與 Python 範例。 它也包含針對常見 Marketplace、市集區域及配額問題的事前檢查，讓你能在佈建前先排除阻礙。 更多細節請參閱「部署所創造的內容」並「自訂部署」。

先決條件

  • 可在 Microsoft Foundry 中部署 Anthropic Claude 模型的 Azure 訂閱。 Claude 模型的可用性取決於訂閱類型、帳單狀態、區域以及 Anthropic 支援的區域。
  • 建立和管理目標 Azure 資源的權限。 你通常必須在訂閱或目標資源群組上具有 Contributor 或 Owner。
  • 可進入 Azure Marketplace 以獲取合作夥伴模式的服務。
  • Azure CLI。
  • Azure 開發人員 CLI。
  • Git。
  • Python 範例需使用 Python 3.10 以上版本。
  • 如果您選擇 Terraform 變體，則需使用 Terraform 1.6 以上版本。

Tip

該倉庫也支援 GitHub Codespaces 和 VS Code 開發容器。 這些環境包含必要的開發工具，所以如果你不想在本地安裝 az、 和 azdPython，這些環境是不錯的選擇。

部署所創造的

入門套件會建立以下資源與本地設定檔：

  • 一個用於azd環境的 Azure 資源群組。
  • 一個 Microsoft Foundry 帳號。
  • 一個 Microsoft Foundry 專案。
  • 在 Foundry 帳號中部署一個或多個 Claude 模型。
  • 模型叫用時的可選角色指派。
  • 在 repo 根節點放置本地 Claude Code 啟用腳本。
  • Claude 工作區設定，將 Claude Code 釘選到已部署的模型族。
  • 當您設定 CLAUDE_WRITE_VSCODE_SETTINGS=true 時，可選用的 VS Code 擴充功能設定。
  • azd 環境輸出，包括 Foundry 帳號名稱、基礎 URL、專案端點及部署名稱。

自訂部署

當你想改變快速入門路徑，例如使用 Terraform、選擇不同區域、部署多個 Claude 家族，或更改容量時，請使用此區塊。 如果你已經完成快速開始，可以直接跳至 搭配已部署的模型使用 Claude Code，或 從 Python 呼叫 Claude。

複製入門套件

複製入門套件，然後切換至該存放庫目錄：

git clone https://github.com/Azure-Samples/claude.git
cd claude

可選擇在選擇型號 ID 前，先檢查即時的 Claude 目錄。 這個輔助工具在入門套件中僅支援 PowerShell。

pwsh -File .\Get-ClaudeCatalog.ps1 -Latest

目錄會隨時間改變。 使用腳本輸出確認你計畫部署區域內可用的 Claude 型號 ID。

選擇基礎設施變體

入門套件包含兩種等效的基礎設施變體：

Variant Folder 何時使用
Bicep infra-bicep 你偏好用 Azure 原生基礎架構作為程式碼。
Terraform infra-terraform 你偏好 Terraform 並且已經在使用 Terraform 的工作流程。

切換到其中一個變體資料夾：

cd infra-bicep

或者：

cd infra-terraform

本文中其他指令都是從你選擇的變體資料夾執行。

登入 Azure

請同時使用Azure CLI和Azure Developer CLI登入：

az login
azd auth login

如果您的 Claude 適用訂閱屬於非預設租戶，請指定租戶：

az login --tenant <tenant-id>
azd auth login --tenant-id <tenant-id>

創造一個 azd 環境

建立 azd 一個環境來儲存部署設定：

azd env new my-claude

如果你已經建立了環境，請選擇它：

azd env select my-claude

設定所需的部署值

設定 Claude 模型提供者證明資料所使用的組織值：

azd env set CLAUDE_ORGANIZATION_NAME "Contoso"
azd env set CLAUDE_COUNTRY_CODE "US"
azd env set CLAUDE_INDUSTRY "technology"

請將範例值替換為貴組織的法人名稱、兩字母國家代碼及產業。 入門套件提供國家和產業的預設值，但除非準確UStechnology描述使用 Claude 的組織，否則會覆蓋這些值。

產業值必須為小寫。 支援的值為：

  • technology
  • finance
  • healthcare
  • education
  • retail
  • manufacturing
  • government
  • media
  • other

設定 Azure 區域：

azd env set AZURE_LOCATION "eastus2"

入門套件支援所選 Claude 模型可用的區域。 快速入門使用 eastus2。 對於常見的全系列部署，eastus2 和 swedencentral 目前承載 Haiku、Sonnet 和 Opus。 westus2 支援 Sonnet 和 Opus。 可用性可能會變動，如果你不確定目標區域有哪些型號家族可用，請使用 live catalog 腳本。

部署更多模型系列或變更容量

若要進行首次的簡單部署，只部署 Sonnet，請使用每個產品家族的首選變數：

azd env set CLAUDE_SONNET_MODEL "claude-sonnet-4-6"

要將多個模型族部署到同一個 Foundry 帳號中，請設定一個或多個族變數：

azd env set CLAUDE_HAIKU_MODEL "claude-haiku-4-5"
azd env set CLAUDE_SONNET_MODEL "claude-sonnet-4-6"
azd env set CLAUDE_OPUS_MODEL "<opus-model-id-from-catalog>"

每個非空的家族變數都會建立一個獨立的部署。 讓一個家庭不設定，跳過它。 舊 CLAUDE_MODEL_NAME 設定是舊有的單一部署備援，僅在 CLAUDE_HAIKU_MODEL、 CLAUDE_SONNET_MODEL、 CLAUDE_OPUS_MODEL 皆為空時使用。

快速啟動將 Sonnet 容量設定為 25。 若要覆蓋任何已部署家庭的容量，請設定匹配容量變數：

azd env set CLAUDE_SONNET_CAPACITY 25

容量值以每分鐘數千個代幣計算。 例如，25 請求 25,000 TPM。

設定模型叫用權限

為了讓 Microsoft Entra ID 範例在部署後立即生效，請在 之前設定ASSIGN_RBAC=trueazd up。 範本會將 Foundry 帳戶上的最低權限Cognitive Services User角色指派給 azd透過AZURE_PRINCIPAL_ID提供的主體 ID，因此您通常不需要自行查找自己的物件 ID。

azd env set ASSIGN_RBAC true

只有在需要授權不同使用者或服務主體存取時，才手動設定 AZURE_PRINCIPAL_ID ：

azd env set AZURE_PRINCIPAL_ID "<object-id>"
azd env set ASSIGN_RBAC true

即使不啟用這個選項，你仍然可以部署資源。 然而，您必須或管理員先授權模型調用權限，才能讓 Microsoft Entra ID 範例呼叫該模型。

入門套件會指派 Cognitive Services User，因為它是無金鑰模型叫用所需的最低權限角色。 如果您計劃之後新增更廣泛的 Foundry 專案功能，例如代理或評估器，您可以另外授與更廣泛的資料平面角色，例如 Foundry User 或 Azure AI Developer。

使用azd up部署

執行部署：

azd up

該 azd up 指令執行以下任務：

  1. 會針對所需設定、市集目錄的可用性及配額餘量進行事前檢查。
  2. 建立 Azure 資源群組。
  3. 建立 Microsoft Foundry 帳號與專案。
  4. 部署所選的 Claude 模型系列。
  5. 可選擇性地指派模型調用角色。
  6. 會寫入輸出值，例如 CLAUDE_BASE_URL、CLAUDE_DEPLOYMENT_NAME 以及各系列的部署名稱。
  7. 執行 postprovision hook 來設定 Claude Code 啟用檔。

部署可能需要數分鐘的時間。 即使 ARM 部署作業因逾時而返回，模型部署仍可繼續進行佈建。 如果發生這種情況，請使用下一節的驗證腳本檢查實際部署狀態，再重新執行 azd up。

驗證部署

從 repo 根執行驗證腳本：

cd ..
pwsh -File .\scripts\verify-claude-code.ps1 -SkipClaudeCall

若要等待仍在配置中的模型部署，請新增等待標記：

pwsh -File .\scripts\verify-claude-code.ps1 -SkipClaudeCall -WaitForDeployment

若要包含即時的 Claude Code 完整往返流程，請省略 skip 旗標：

pwsh -File .\scripts\verify-claude-code.ps1

驗證腳本會檢查產生的啟用器、預期的環境變數、Azure CLI 登入、可見的 Foundry 資源、模型部署狀態，以及 Claude Code CLI 可用性。

在已部署的模型中使用 Claude 程式碼

使用 Claude Code CLI

預設情況下，入門套件會在倉庫根目錄撰寫專案範圍的啟動腳本和 Claude 工作區設定：

  • claude-code.env.ps1 適用於 PowerShell。
  • claude-code.env.sh 適用於 Bash、macOS、Linux、Git Bash 或 WSL。
  • 透過 Claude 工作區設定，將 Claude Code 固定至你已部署的模型系列。
. .\claude-code.env.ps1
claude

啟用器會設定 Claude Code 以使用 Microsoft Foundry，並為你部署的模型族設定部署名稱。 對於每個已部署的系列，postprovision 鉤子都會將 ANTHROPIC_DEFAULT_<FAMILY>_MODEL 值寫入 activator，讓 Claude Code 能在這些部署存在的情況下路由至 Haiku、Sonnet 或 Opus。 Claude 工作區設定會將工作區的預設模型固定為已部署的模型系列，因此 claude 會對應到你 Foundry 帳戶中已有的模型。

如果沒有安裝該 claude 指令，Postprovision 鉤子會為你的平台印出安裝指令。 要讓入門套件在配置時自動安裝 Claude Code，執行前 azd up先設定以下值：

azd env set CLAUDE_CODE_AUTO_INSTALL true

可選：設定 VS Code 擴充功能

入門套件預設不會寫入 .vscode/settings.json 。 如果你使用 Claude Code VS Code 擴充功能，並希望由入門套件為其進行設定，請在 azd up 之前選擇加入：

azd env set CLAUDE_WRITE_VSCODE_SETTINGS true

啟用此選項後，postprovision hook 會將 claudeCode.environmentVariables 和 claudeCode.disableLoginPrompt 寫入或合併到 .vscode/settings.json 中，讓擴充功能使用你的 Foundry 部署，而不是提示你登入 Anthropic 帳號。

用 Python 聯絡 Claude

此存放庫在 src 下包含 Python 範例。 利用它們來測試使用 Anthropic SDK 和 Microsoft Entra ID 的應用程式式存取。

從存放區根目錄，切換回基礎架構變體資料夾，並將 azd 的輸出寫入位於存放區根目錄的 .env.local：

cd infra-bicep # or: cd infra-terraform
azd env get-values | Out-File -Encoding utf8 ..\.env.local

接著建立虛擬環境並安裝相依性：

cd ..
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

執行單次範例：

python src\hello_claude.py

範例會載入 CLAUDE_BASE_URL 和 CLAUDE_DEPLOYMENT_NAME、取得用於 https://ai.azure.com/.default 的 Microsoft Entra ID 權杖、使用 Foundry 基底 URL 建立 Anthropic 用戶端，並傳送 Messages API 要求。

你也可以試用串流和長時間執行版本。

python src\chat_stream.py
python src\hello_claude_token_refresh.py

對於服務、常駐程式、Notebook 或其他執行時間可能長於單一 Microsoft Entra ID 權杖存留期限的處理程序，請使用權杖重新整理範例。

進階：用 API 金鑰測試

一般開發和生產情境請使用 Microsoft Entra ID。 為了快速本地測試，該倉庫也包含 API 金鑰範例。

從 repo 根目錄，切換到 infrastructure variant 資料夾，取得 Foundry 帳號名稱和資源群組：

cd infra-bicep # or: cd infra-terraform
azd env get-values

使用輸出中的 FOUNDRY_ACCOUNT_NAME 和 AZURE_RESOURCE_GROUP 值來設定 CLAUDE_API_KEY。 接著，從倉庫根執行 API 金鑰範例：

$env:CLAUDE_API_KEY = (az cognitiveservices account keys list `
  --name "<foundry-account-name>" `
  --resource-group "<resource-group-name>" `
  --query key1 -o tsv)

cd ..
python src\hello_claude_apikey.py

API 金鑰對於快速連線檢查很有用，但它們無法提供像 Microsoft Entra ID 那樣的每位使用者存取控制和憑證生命週期優勢。

使用規定

Bicep 和 Terraform 版本在每次 Claude 部署時都會傳送一個 modelProviderData 區塊。 該區塊包含 organizationName、 countryCode、 industry和 。 認知服務資源提供者會使用這些值，代表您接受 Azure Marketplace 上 Anthropic Claude 的供應項目，因此在 azd up 期間不需要另外手動點選確認。

部署前：

  1. 透過 Microsoft Foundry 檢視管理 Claude 的法律文件：
  2. 設定認證值，使其能準確描述您的組織：
    • CLAUDE_ORGANIZATION_NAME： 法人名稱。 此值為必需且無預設值。
    • CLAUDE_COUNTRY_CODE：兩字母國家代碼。 入門套組的預設是 US。
    • CLAUDE_INDUSTRY：組織產業。 入門套組的預設是 technology。
  3. 確認您的 Azure 訂閱是否符合在 Microsoft Foundry 中部署 Anthropic Claude 模型的資格。

如果國家或產業的預設設定無法準確描述使用 Claude 的組織，部署前先覆蓋它們。

預覽 Foundry 在手動流程中顯示的對話方塊，並在 azd up 之後稽核接受情況

Azure 入口網站中適用於 Claude SKU 的「同意並繼續」對話方塊，是根據 Marketplace 供應項目的即時中繼資料產生的。 由於 Marketplace 上的文字內容可能會變動，請使用你計劃部署之 SKU 的即時刊載頁面，而不要依賴複製的快照。

之後azd up，你可以使用 Azure CLI 審核已接受的市場協議元資料。 指令會回傳中繼資料，例如已接受的狀態、簽章、日期和授權文字連結。 它不會回傳完整的入口對話文字。

az term show `
  --publisher anthropic `
  --product anthropic-claude-sonnet-4-6-offer `
  --plan <plan-name>

對於其他 Claude SKU，請將 --product 的值替換為相符的 Marketplace 優惠方案。 使用來自即時優惠中繼資料或入門套件目錄檢查中的方案名稱。

故障排除

更多案例請參考 入門套件故障排除章節。

Problem 可嘗試的項目
訂閱或優惠資格限制 azd up 請確認您的訂閱與帳單帳號是否符合 Microsoft Foundry 中 Claude 型號的資格。 如果您的組織明確要求市場接受，請在重新執行azd up前接受匹配的 Anthropic 報價。
所選模型不適用於此區域 使用所選 Claude 系列可用的區域。 快速入門使用 eastus2；swedencentral 也常提供 Haiku、Sonnet 和 Opus，而 westus2 提供 Sonnet 和 Opus。 可用性可能會變動，所以如果不確定，可以從 repo 根執行 pwsh -File .\Get-ClaudeCatalog.ps1 -Latest 。
配額不足，或配額似乎已滿卻沒有實際部署 降低配對 CLAUDE_*_CAPACITY 值、刪除未使用的部署，或要求增加配額。 已虛刪除的 Foundry 或 AIServices 帳戶最多可保留 TPM 配額達 48 小時；使用 az cognitiveservices account list-deleted -o table 列出這些帳戶，然後清除不再需要的帳戶。
Terraform 因意義不明的 715-123420 錯誤而失敗 請將此視為可能的配額失敗，包括軟刪除帳號持有的配額。 執行入門套件的前置檢查、檢視配額餘量、調降容量，或改用 Bicep 變體重試，以顯示更清楚的 InsufficientQuota 訊息。
Claude Code 或 Python 會回傳 401 或 403 執行 az login，確認您已登入至擁有 Foundry 資源的租用戶，並確認呼叫者具有模型叫用權限，例如 Cognitive Services User。 新的 RBAC 指派可能需要幾分鐘才能完成。
GatewayTimeout 在模型部署期間出現 模型部署可在 ARM 操作逾時後繼續進行。在重執行azd up前，先執行驗證-WaitForDeployment--wait-for-deployment腳本，檢查實際部署狀態。

清理資源

當你不再需要這些資源時，請從基礎架構變體資料夾中使用 azd down 刪除它們：

cd infra-bicep
azd down

或者：

cd infra-terraform
azd down

在確認前，先先檢視那些 azd 打算刪除的資源。 刪除環境會刪除由入門套件建立的 Foundry 帳戶、專案和模型部署。

如果你正在迭代部署，且需要立即恢復保留的 Claude TPM 配額，請在你的 azd 版本支援時使用清除選項：

azd down --purge

若未執行清除作業，已軟刪除的 Foundry 或 AIServices 帳戶最多仍會占用 TPM 配額 48 小時。 如果你已經刪除環境且未清除，且配額仍滿，請使用 az cognitiveservices account list-deleted -o table 來尋找已刪除的帳號並清除不再需要的帳號。

下一步

  • 上次更新時間：