Distribuire i modelli Claude in Microsoft Foundry usando Bicep o Terraform

Il Claude on Foundry Starter Kit consente di distribuire i modelli Claude di Anthropic in Microsoft Foundry tramite Azure Developer CLI (azd). Consente inoltre di configurare l'autenticazione locale e chiamare il modello distribuito da Claude Code o Python.

In questo articolo vengono illustrate le operazioni seguenti:

  • Distribuire Claude Sonnet in Microsoft Foundry usando la variante Bicep dello starter kit.
  • Configurare i valori di attestazione richiesti del fornitore di modelli Anthropic.
  • Configurare Claude Code per l'uso del modello ospitato da Foundry.
  • Chiamare il modello Claude distribuito da Python usando Microsoft Entra ID.
  • Personalizzare la distribuzione per Terraform, più famiglie di modelli, altre aree o capacità diversa.

Importante

L'esecuzione di azd up con questo starter kit comporta l'accettazione dei termini di Anthropic Marketplace e invia con le richieste i valori di attestazione CLAUDE_ORGANIZATION_NAME, CLAUDE_COUNTRY_CODE e CLAUDE_INDUSTRY. Impostare i valori che descrivono l'organizzazione reale usando il modello. Per informazioni dettagliate, vedere Condizioni per l'utilizzo.

Guida introduttiva

Questo "percorso felice" distribuisce Claude Sonnet usando Bicep in eastus2 con capacità 25 (25.000 token al minuto). Usalo prima per ottenere una distribuzione funzionante, poi passa a Personalizzare la distribuzione se hai bisogno di Terraform, più famiglie di modelli, un'altra area geografica o una capacità diversa.

È necessaria una sottoscrizione di Azure idonea per Anthropic Claude in Microsoft Foundry, autorizzazioni per creare le risorse di destinazione, interfaccia della riga di comando di Azure, interfaccia della riga di comando per sviluppatori Azure, Git e Python 3.10 o versione successiva. Se l'account dispone delle autorizzazioni per creare assegnazioni di ruolo, la guida introduttiva concede all'utente anche l'accesso per richiamare il modello, così che gli esempi possano essere eseguiti immediatamente.

Clonare, configurare e distribuire

Se la sottoscrizione idonea per Claude si trova in un tenant non predefinito, aggiungere l'ID tenant a entrambi i comandi di accesso.

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

Sostituire Contoso, USe technology con i valori per l'organizzazione reale usando Claude. Se il tuo account non può creare assegnazioni di ruolo, salta ASSIGN_RBAC e chiedi a un amministratore di concederti l'accesso per richiamare il modello prima di eseguire gli esempi.

Verificare ed eseguire Claude Code

Dalla radice del repository verificare la configurazione generata e lo stato della distribuzione. Il flag skip evita una chiamata in tempo reale a Claude durante la verifica.

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

. .\claude-code.env.ps1
claude

Eseguire l'esempio di Python

Scrivere gli output di azd in .env.local, installare le dipendenze ed eseguire l'esempio a esecuzione singola con 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

Come aiuta lo starter kit

Lo starter kit automatizza la distribuzione di Claude usando Bicep o Terraform. Configura l'autenticazione locale per Microsoft Entra ID e fornisce esempi di claude code e Python funzionanti. Comprende anche controlli preliminari per individuare problemi comuni relativi a marketplace, area geografica e quota, così da poter risolvere i problemi bloccanti prima del provisioning. Per ulteriori dettagli, vedere Che cosa crea la distribuzione e Personalizzare la distribuzione.

Prerequisiti

  • Sottoscrizione di Azure idonea per la distribuzione di modelli di Anthropic Claude in Microsoft Foundry. La disponibilità del modello Claude dipende dal tipo di sottoscrizione, dallo stato di fatturazione, dall'area geografica e dalle aree supportate Anthropic.
  • Autorizzazioni per creare e gestire le risorse di Azure di destinazione. In genere è necessario Contributor o Owner nella sottoscrizione o nel gruppo di risorse di destinazione.
  • Accesso alle Azure Marketplace per le offerte di modelli partner.
  • interfaccia della riga di comando di Azure.
  • Interfaccia della riga di comando per sviluppatori di Azure.
  • Git.
  • Python 3.10 o versione successiva per gli esempi di Python.
  • Terraform 1.6 o versione successiva se si sceglie la variante Terraform.

Tip

Il repository supporta anche GitHub Codespaces e i contenitori di sviluppo di VS Code. Questi ambienti includono gli strumenti di sviluppo necessari, quindi rappresentano una buona scelta se non si vuole installare az, azde Python in locale.

Cosa crea la distribuzione

Lo starter kit crea queste risorse e i file di configurazione locali:

  • Gruppo di risorse Azure per l'ambienteazd.
  • Un account Microsoft Foundry
  • Un progetto di Microsoft Foundry.
  • Una o più distribuzioni di modelli Claude nell'account Foundry.
  • Assegnazione opzionale di un ruolo per l'invocazione del modello.
  • Script locali di attivazione di Claude Code nella radice del repository.
  • Configurazione dell'area di lavoro Claude che aggiunge Claude Code a una famiglia di modelli distribuita.
  • Impostazioni facoltative dell'estensione di VS Code quando si imposta CLAUDE_WRITE_VSCODE_SETTINGS=true.
  • azd valori restituiti dall'ambiente, inclusi il nome dell'account Foundry, l'URL di base, l'endpoint del progetto e i nomi delle distribuzioni.

Personalizzare la distribuzione

Usare questa sezione quando si vuole variare il percorso di avvio rapido, ad esempio l'uso di Terraform, la selezione di un'area diversa, la distribuzione di più famiglie Claude o la modifica della capacità. Se la guida introduttiva è già stata completata, è possibile passare direttamente a Usare Claude Code con il modello distribuito o Chiamare Claude da Python.

Clona lo starter kit

Clonare lo starter kit e passare al repository:

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

Facoltativamente, consulta il catalogo Claude in tempo reale prima di scegliere gli ID dei modelli. Questo helper è disponibile solo per PowerShell nello starter kit.

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

Il catalogo cambia nel tempo. Usare l'output dello script per verificare quali ID modello Claude sono disponibili nell'area che si prevede di distribuire.

Scegliere una variante dell'infrastruttura

Lo starter kit include due varianti di infrastruttura equivalenti:

Variant Folder Usa quando
Bicep infra-bicep Preferisci l'infrastruttura come codice nativa di Azure.
Terraform infra-terraform Preferisci Terraform e utilizzi già workflow di Terraform.

Passare a una delle cartelle varianti:

cd infra-bicep

O:

cd infra-terraform

Il resto dei comandi di questo articolo viene eseguito dalla cartella variant scelta.

Accedere ad Azure

Accedere usando sia interfaccia della riga di comando di Azure che l'interfaccia della riga di comando per sviluppatori di Azure:

az login
azd auth login

Se la sottoscrizione idonea per Claude si trova in un tenant non predefinito, specificare il tenant:

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

Creare un azd ambiente

Creare un azd ambiente per archiviare la configurazione della distribuzione:

azd env new my-claude

Se è già stato creato un ambiente, selezionarlo:

azd env select my-claude

Configurare i valori di distribuzione necessari

Impostare i valori dell'organizzazione utilizzati per l'attestazione del provider di modelli Claude:

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

Sostituire i valori di esempio con il nome della persona giuridica dell'organizzazione, il codice paese a due lettere e il settore. Il kit di avvio fornisce valori predefiniti per paese e settore, ma sostituiscili a meno che US e technology non descrivano accuratamente l'organizzazione che utilizza Claude.

Il valore del settore deve essere minuscolo. I valori supportati sono:

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

Imposta l'area geografica di Azure:

azd env set AZURE_LOCATION "eastus2"

Lo starter kit supporta le aree in cui sono disponibili i modelli Claude selezionati. Il QuickStart usa eastus2. Per una comune implementazione per tutte le famiglie, eastus2 e swedencentral ospitano attualmente Haiku, Sonnet e Opus. westus2 ospita Sonnet e Opus. La disponibilità può cambiare, quindi usare lo script del catalogo live se non si è certi delle famiglie di modelli disponibili nell'area di destinazione.

Distribuisci più famiglie di modelli o modifica la capacità

Per una prima distribuzione semplice, distribuire solo Sonnet usando la variabile preferita per ogni famiglia:

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

Per distribuire più famiglie di modelli nello stesso account Foundry, impostare una o più variabili di famiglia:

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>"

Ogni variabile di famiglia non vuota crea una distribuzione separata. Lascia una famiglia non impostata per saltarla. L'impostazione precedente CLAUDE_MODEL_NAME è un fallback di distribuzione singola legacy e viene usata solo quando CLAUDE_HAIKU_MODEL, CLAUDE_SONNET_MODELe CLAUDE_OPUS_MODEL sono tutti vuoti.

QuickStart imposta la capacità di Sonnet su 25. Per eseguire l'override della capacità per qualsiasi famiglia distribuita, impostare la variabile di capacità corrispondente:

azd env set CLAUDE_SONNET_CAPACITY 25

I valori di capacità vengono misurati in migliaia di token al minuto. Ad esempio, 25 richiede 25.000 TPM.

Configurare l'accesso alle chiamate al modello

Affinché gli esempi di Microsoft Entra ID funzionino immediatamente dopo la distribuzione, impostare ASSIGN_RBAC=true prima di azd up. Il modello assegna il ruolo con privilegi Cognitive Services User minimi nell'account Foundry all'ID entità fornito azd tramite AZURE_PRINCIPAL_ID, quindi in genere non è necessario cercare il proprio ID oggetto.

azd env set ASSIGN_RBAC true

Impostare AZURE_PRINCIPAL_ID manualmente solo quando è necessario concedere l'accesso a un utente o a un'entità servizio diversa:

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

Se non si abilita questa opzione, è comunque possibile distribuire le risorse. Tuttavia, tu o un amministratore dovete concedere le autorizzazioni per l'invocazione del modello prima che gli esempi di Microsoft Entra ID possano richiamare il modello.

Il kit di avvio assegna Cognitive Services User perché è il ruolo con privilegi minimi per l'invocazione del modello senza chiave. Se si prevede di aggiungere funzionalità di progetto Foundry più ampie in un secondo momento, ad esempio agenti o analizzatori, è possibile concedere ruoli più ampi del piano dati, ad esempio Foundry User o Azure AI Developer separatamente.

Distribuisci con azd up

Avviare la distribuzione:

azd up

Il azd up comando esegue queste attività:

  1. Esegue una verifica preliminare delle impostazioni necessarie, della disponibilità del catalogo del Marketplace e del margine disponibile della quota.
  2. Crea il gruppo di risorse Azure.
  3. Crea l'account Microsoft Foundry e il progetto.
  4. Distribuisce le famiglie di modelli Claude selezionate.
  5. Assegna facoltativamente il ruolo di invocazione del modello.
  6. Scrive valori di output come CLAUDE_BASE_URL, CLAUDE_DEPLOYMENT_NAME e i nomi di distribuzione per famiglia.
  7. Esegue l'hook postprovision per configurare i file di attivazione di Claude Code.

La distribuzione può richiedere alcuni minuti. Le distribuzioni dei modelli possono anche continuare il processo di provisioning dopo che l'operazione di distribuzione ARM si conclude con un timeout. In tal caso, usare lo script di verifica nella sezione successiva per controllare lo stato di distribuzione effettivo prima di eseguire nuovamente azd up.

Verificare la distribuzione

Dalla radice del repository eseguire lo script di verifica:

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

Per attendere le distribuzioni del modello ancora in fase di provisioning, aggiungere il flag di attesa:

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

Per includere un round trip live con Claude Code, omettere il flag skip:

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

Lo script di verifica controlla l'attivatore generato, le variabili di ambiente previste, l'accesso ad interfaccia della riga di comando di Azure, la risorsa Foundry visibile, gli stati di distribuzione del modello e la disponibilità della CLI di Claude Code.

Usare Claude Code con il modello distribuito

Usa la CLI di Claude Code

Per impostazione predefinita, lo starter kit scrive script di attivazione a livello di progetto e la configurazione dello spazio di lavoro di Claude nella radice del repository:

  • claude-code.env.ps1 per PowerShell.
  • claude-code.env.sh per Bash, macOS, Linux, Git Bash o WSL.
  • Configurazione del workspace di Claude per associare Claude Code a una famiglia di modelli che hai distribuito.
. .\claude-code.env.ps1
claude

L'attivatore configura Claude Code per l'uso di Microsoft Foundry e imposta i nomi di distribuzione per le famiglie di modelli distribuite. Per ogni famiglia distribuita, l’hook di post-provisioning scrive un valore ANTHROPIC_DEFAULT_<FAMILY>_MODEL nell’attivatore in modo che Claude Code possa indirizzare le richieste a Haiku, Sonnet o Opus quando tali distribuzioni sono disponibili. La configurazione dell'area di lavoro Claude vincola il valore predefinito dell'area di lavoro a una famiglia distribuita, quindi claude viene risolto come un modello presente nel tuo account Foundry.

Se il comando claude non è installato, l'hook di postprovision stampa il comando di installazione per la tua piattaforma. Per fare in modo che lo starter kit installi Claude Code automaticamente durante il provisioning, impostare questo valore prima di eseguire azd up:

azd env set CLAUDE_CODE_AUTO_INSTALL true

Facoltativo: configurare l'estensione VS Code

Lo starter kit non scrive .vscode/settings.json per impostazione predefinita. Se utilizzi l'estensione Claude Code per VS Code e vuoi che lo starter kit la configuri, aderisci prima di azd up:

azd env set CLAUDE_WRITE_VSCODE_SETTINGS true

Quando abiliti questa opzione, l'hook postprovision scrive o unisce claudeCode.environmentVariables e claudeCode.disableLoginPrompt in .vscode/settings.json in modo che l'estensione usi il deployment di Foundry invece di chiedere di accedere con un account Anthropic.

Chiama Claude da Python

Il repository include esempi Python in src. Usarli per testare l'accesso in stile applicazione con Anthropic SDK e Microsoft Entra ID.

Dalla radice del repository, tornare alla cartella della variante dell'infrastruttura e scrivere gli output di azd in .env.local nella radice del repository:

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

Creare quindi un ambiente virtuale e installare le dipendenze:

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

Esegui l'esempio one-shot:

python src\hello_claude.py

L'esempio carica CLAUDE_BASE_URL e CLAUDE_DEPLOYMENT_NAME, ottiene un token di Microsoft Entra ID per https://ai.azure.com/.default, crea un client Anthropic con l'URL di base Foundry e invia una richiesta API Messages.

È anche possibile provare le varianti di streaming e a esecuzione prolungata.

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

Usare l'esempio di aggiornamento del token per servizi, daemon, notebook o altri processi che potrebbero essere eseguiti più a lungo della durata di un singolo token Microsoft Entra ID.

Avanzate: test con una chiave API

Usare Microsoft Entra ID per scenari di sviluppo e produzione normali. Per i test locali rapidi, il repository include anche un esempio di chiave API.

Dalla radice del repository passare alla cartella infrastructure variant e ottenere il nome dell'account Foundry e il gruppo di risorse:

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

Usare i valori FOUNDRY_ACCOUNT_NAME e AZURE_RESOURCE_GROUP nell'output per impostare CLAUDE_API_KEY. Eseguire quindi l'esempio di chiave API dalla radice del repository:

$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

Le chiavi API sono utili per un controllo rapido della connettività, ma non offrono gli stessi vantaggi del ciclo di vita delle credenziali e del controllo di accesso per utente come Microsoft Entra ID.

Condizioni per l'utilizzo

Le varianti Bicep e Terraform inviano entrambe un blocco modelProviderData con ogni distribuzione di Claude. Questo blocco include organizationName, countryCode e industry. Il provider di risorse di Servizi cognitivi utilizza questi valori per accettare per conto dell'utente l'offerta di Azure Marketplace per Anthropic Claude, quindi non è necessario alcun clic manuale separato durante azd up.

Prima di distribuire:

  1. Esaminare i documenti legali che regolano Claude tramite Microsoft Foundry:
  2. Impostare i valori di attestazione in modo che descrivano in modo accurato l'organizzazione:
    • CLAUDE_ORGANIZATION_NAME: nome della persona giuridica. Questo valore è obbligatorio e non ha un valore predefinito.
    • CLAUDE_COUNTRY_CODE: codice paese a due lettere. Il valore predefinito del starter kit è US.
    • CLAUDE_INDUSTRY: il settore delle organizzazioni. Il valore predefinito del starter kit è technology.
  3. Verificare che la sottoscrizione Azure sia idonea per distribuire modelli Anthropic Claude in Microsoft Foundry.

Se le impostazioni predefinite per il paese o il settore non descrivono accuratamente l'organizzazione che usa Claude, eseguirne l'override prima della distribuzione.

Visualizza in anteprima la finestra di dialogo mostrata da Foundry nel percorso manuale e verifica l'accettazione dopo azd up

La finestra di dialogo "Accetta e continua" del portale di Azure per uno SKU Claude viene generata dai metadati dell'offerta live del Marketplace. Poiché il testo del Marketplace può cambiare, usare l'inserzione live per lo SKU che si prevede di distribuire invece di basarsi su uno snapshot copiato.

Dopo azd up, è possibile controllare i metadati del contratto del Marketplace accettati usando interfaccia della riga di comando di Azure. Il comando restituisce metadati, ad esempio lo stato accettato, la firma, la data e il collegamento di testo della licenza. Non restituisce il testo completo della finestra di dialogo del portale.

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

Per altri SKU Claude, sostituire il --product valore con l'offerta marketplace corrispondente. Usa il nome del piano dai metadati dell'offerta attiva o dalle verifiche nel catalogo dello starter kit.

Troubleshooting

Per altri casi, vedere la sezione relativa alla risoluzione dei problemi del kit di avvio.

Problema Cosa provare
Blocchi di idoneità per la sottoscrizione o l'offerta azd up Verificare che l'abbonamento e l'account di fatturazione siano idonei per i modelli Claude in Microsoft Foundry. Se la tua organizzazione richiede l'accettazione esplicita del Marketplace, accetta l'offerta Anthropic corrispondente prima di rieseguire azd up.
L'area non è disponibile per il modello selezionato Usa un'area in cui è disponibile la famiglia Claude selezionata. QuickStart usa eastus2; anche swedencentral ospita comunemente Haiku, Sonnet e Opus e westus2 ospita Sonnet e Opus. La disponibilità può cambiare, quindi eseguire pwsh -File .\Get-ClaudeCatalog.ps1 -Latest dalla radice del repository, se non si è certi.
La quota non è sufficiente o la quota viene visualizzata piena senza distribuzioni attive Ridurre il valore corrispondente CLAUDE_*_CAPACITY , eliminare le distribuzioni inutilizzate o richiedere un aumento della quota. Gli account Foundry o AIServices eliminati temporaneamente possono riservare la quota di TPM per un massimo di 48 ore; visualizzali in elenco con az cognitiveservices account list-deleted -o table ed elimina definitivamente gli account che non ti servono più.
Terraform non riesce con un errore poco chiaro 715-123420 Consideri questo come un probabile problema di quota, compresa la quota occupata dagli account eliminati temporaneamente. Esegui i controlli preliminari del kit di avvio, verifica il margine disponibile della quota, riduci la capacità oppure riprova con la variante Bicep per visualizzare un messaggio InsufficientQuota più chiaro.
Claude Code o Python restituisce 401 o 403 Esegui az login, conferma di aver eseguito l'accesso al tenant proprietario della risorsa di Foundry e verifica che il chiamante disponga delle autorizzazioni per l'invocazione del modello, ad esempio Cognitive Services User. La propagazione delle nuove assegnazioni RBAC può richiedere alcuni minuti.
GatewayTimeout viene visualizzato durante la distribuzione del modello La distribuzione del modello può continuare dopo il timeout dell'operazione arm. Prima di eseguire nuovamente azd up, eseguire lo script di verifica con -WaitForDeployment o --wait-for-deployment per controllare lo stato effettivo della distribuzione.

Pulire le risorse

Quando le risorse non sono più necessarie, eliminarle con azd down dalla cartella variant dell'infrastruttura:

cd infra-bicep
azd down

O:

cd infra-terraform
azd down

Esaminare le risorse che azd prevede di eliminare prima di confermare. L'eliminazione dell'ambiente elimina l'account Foundry, il progetto e le distribuzioni del modello creati dallo starter kit.

Se stai eseguendo iterazioni sulle distribuzioni e hai bisogno di recuperare immediatamente la quota TPM riservata di Claude, usa l'opzione di svuotamento se la versione azd la supporta:

azd down --purge

Senza l’eliminazione definitiva, gli account Foundry o AIServices eliminati temporaneamente possono continuare a occupare una quota TPM per un massimo di 48 ore. Se è già stato eliminato un ambiente senza eliminare e la quota appare ancora piena, usare az cognitiveservices account list-deleted -o table per trovare gli account eliminati ed eliminare gli account non più necessari.

Passaggi successivi

  • Last updated on