Déployer des modèles Claude dans Microsoft Foundry à l’aide de Bicep ou Terraform

Le Kit de démarrage Claude on Foundry vous aide à déployer des modèles Anthropic Claude sur Microsoft Foundry à l’aide de Azure Developer CLI (azd). Il vous aide également à configurer l’authentification locale et à appeler le modèle déployé à partir de Claude Code ou de Python.

Dans cet article, vous allez apprendre à :

  • Déployez Claude Sonnet sur Microsoft Foundry à l’aide de la variante Bicep du kit de démarrage.
  • Configurez les valeurs d’attestation requises du fournisseur de modèles Anthropic.
  • Configurez Claude Code pour utiliser le modèle hébergé par Foundry.
  • Appelez le modèle Claude déployé à partir de Python à l’aide de Microsoft Entra ID.
  • Personnalisez le déploiement pour Terraform, plus de familles de modèles, d’autres régions ou une capacité différente.

Important

L’exécution de azd up avec ce kit de démarrage vaut acceptation des conditions d’utilisation d’Anthropic Marketplace et envoie les valeurs d’attestation CLAUDE_ORGANIZATION_NAME, CLAUDE_COUNTRY_CODE et CLAUDE_INDUSTRY dans les requêtes. Définissez des valeurs qui décrivent l’organisation réelle à l’aide du modèle. Pour plus d’informations, consultez Conditions d’utilisation.

Démarrage rapide

Ce « scénario simple » permet de déployer Claude Sonnet à l’aide de Bicep dans eastus2, avec une capacité de 25 (25 000 jetons par minute). Utilisez-le d’abord pour accéder à un déploiement opérationnel, puis passez à Personnaliser le déploiement si vous avez besoin de Terraform, de plusieurs familles de modèles, d’une autre région ou d’une capacité différente.

Vous avez besoin d'un abonnement Azure éligible à Anthropic Claude dans Microsoft Foundry, des autorisations pour créer les ressources cibles, Azure CLI, Azure Developer CLI, Git et Python 3.10 ou version ultérieure. Si votre compte peut créer des attributions de rôle, le guide de démarrage rapide accorde également à votre utilisateur l’autorisation d’invoquer le modèle afin que les exemples puissent être exécutés immédiatement.

Cloner, configurer et déployer

Si votre abonnement éligible à Claude se trouve dans un locataire non par défaut, ajoutez l’ID du locataire aux deux commandes de connexion.

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

Remplacez Contoso, USet technology par des valeurs pour l’organisation réelle à l’aide de Claude. Si votre compte ne peut pas créer d’attributions de rôle, ignorez ASSIGN_RBAC et demandez à un administrateur de vous accorder l’accès à l’invocation du modèle avant d’exécuter les exemples.

Vérifier et exécuter Claude Code

À partir de la racine du dépôt, vérifiez l’état de configuration et de déploiement générés. L’indicateur skip évite un appel Claude en direct pendant la vérification.

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

. .\claude-code.env.ps1
claude

Exécuter l’exemple Python

Écrivez les résultats de azd dans .env.local, installez les dépendances et exécutez l’exemple en une seule fois avec 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

Comment le kit de démarrage aide

Le kit de démarrage automatise le déploiement de Claude à l’aide de Bicep ou Terraform. Il configure l’authentification locale pour Microsoft Entra ID et fournit des exemples fonctionnels pour Claude Code et Python. Il inclut également des vérifications préliminaires pour les problèmes courants liés à la place de marché, à la région et au quota afin de pouvoir corriger les blocages avant l’approvisionnement. Pour plus d’informations, consultez Ce que le déploiement crée et personnalise le déploiement.

Prerequisites

  • Un abonnement Azure éligible au déploiement de modèles Anthropic Claude dans Microsoft Foundry. La disponibilité du modèle Claude dépend du type d’abonnement, du statut de facturation, de la région et des régions prises en charge par Anthropic.
  • Autorisations de création et de gestion des ressources Azure cibles. Vous avez généralement besoin de Contributor ou de Owner au niveau de l’abonnement ou du groupe de ressources cible.
  • Accès à Place de marché Azure pour les offres de modèle partenaire.
  • Azure CLI.
  • Azure Developer CLI.
  • Git.
  • Python 3.10 ou version ultérieure pour les exemples de Python.
  • Terraform 1.6 ou version ultérieure si vous choisissez la variante Terraform.

Conseil / Astuce

Le dépôt prend également en charge GitHub Codespaces et VS Code Dev Containers. Ces environnements incluent les outils de développement requis. Ils sont donc un bon choix si vous ne souhaitez pas installeraz, azdet Python localement.

Ce que le déploiement crée

Le kit de démarrage crée ces ressources et fichiers de configuration locaux :

  • Groupe de ressources Azure pour l’environnementazd.
  • Un compte Microsoft Foundry.
  • Un projet Microsoft Foundry.
  • Un ou plusieurs déploiements de modèles Claude dans le compte Foundry.
  • Affectation facultative de rôle pour l’invocation du modèle.
  • Scripts d’activation locaux de Claude Code à la racine du dépôt.
  • Configuration de l’espace de travail Claude qui associe Claude Code à une famille de modèles déployés.
  • Paramètres d’extension VS Code facultatifs lorsque vous définissez CLAUDE_WRITE_VSCODE_SETTINGS=true.
  • sorties d’environnement azd, notamment le nom du compte Foundry, l’URL de base, le point de terminaison du projet et les noms de déploiement.

Personnaliser le déploiement

Utilisez cette section lorsque vous souhaitez modifier le chemin de démarrage rapide, comme l’utilisation de Terraform, la sélection d’une autre région, le déploiement de plusieurs familles Claude ou la modification de la capacité. Si vous avez déjà terminé le guide de démarrage rapide, vous pouvez passer à l’avance à l’utilisation de Claude Code avec le modèle déployé ou appeler Claude à partir de Python.

Cloner le kit de démarrage

Clonez le kit de démarrage et passez au dépôt :

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

Si vous le souhaitez, inspectez le catalogue Claude actif avant de choisir les ID de modèle. Cet assistant n’est disponible qu’en PowerShell dans le kit de démarrage.

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

Le catalogue change au fil du temps. Utilisez la sortie du script pour confirmer les ID de modèle Claude disponibles dans la région que vous envisagez de déployer.

Choisir une variante d’infrastructure

Le kit de démarrage comprend deux variantes d’infrastructure équivalentes :

Variant Dossier À utiliser lorsque
Bicep infra-bicep Vous privilégiez l’infrastructure as code native Azure.
Terraform infra-terraform Vous préférez Terraform et utilisez déjà des flux de travail Terraform.

Passez à l’un des dossiers de variantes :

cd infra-bicep

Ou:

cd infra-terraform

Le reste des commandes de cet article s’exécute à partir du dossier variant que vous avez choisi.

Connectez-vous à Azure

Connectez-vous à l’aide de Azure CLI et de l’interface CLI Azure développeur :

az login
azd auth login

Si votre abonnement à Claude est associé à un locataire autre que le locataire par défaut, spécifiez le locataire :

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

Créer un azd environnement

Créez un azd environnement pour stocker la configuration du déploiement :

azd env new my-claude

Si vous avez déjà créé un environnement, sélectionnez-le à la place :

azd env select my-claude

Configurer les valeurs de déploiement requises

Définissez les valeurs d’organisation utilisées pour l’attestation du fournisseur de modèles Claude :

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

Remplacez les exemples de valeurs par le nom de l’entité juridique de votre organisation, le code de pays à deux lettres et le secteur d’activité. Le kit de démarrage fournit des valeurs par défaut pour le pays et l’industrie, mais les remplace, sauf si US et technology décrit avec précision l’organisation qui utilise Claude.

La valeur du secteur doit être en minuscules. Les valeurs prises en charge sont les suivantes :

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

Définissez la région Azure :

azd env set AZURE_LOCATION "eastus2"

Le kit de démarrage prend en charge les régions où les modèles Claude sélectionnés sont disponibles. Le démarrage rapide utilise eastus2. Pour un déploiement multifamille standard, eastus2 et swedencentral hébergent actuellement Haiku, Sonnet et Opus. westus2 héberge Sonnet et Opus. La disponibilité peut changer. Utilisez donc le script de catalogue en direct si vous ne savez pas quelles familles de modèles sont disponibles dans votre région cible.

Déployer davantage de familles de modèles ou modifier la capacité

Pour un premier déploiement simple, déployez uniquement Sonnet à l’aide de la variable par famille préférée :

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

Pour déployer plusieurs familles de modèles dans le même compte Foundry, définissez une ou plusieurs variables de famille :

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

Chaque variable de famille non vide crée un déploiement distinct. Laissez une famille non renseignée pour l’ignorer. L’ancien paramètre CLAUDE_MODEL_NAME est une solution de repli héritée pour déploiement unique et n’est utilisé que lorsque CLAUDE_HAIKU_MODEL, CLAUDE_SONNET_MODEL et CLAUDE_OPUS_MODEL sont tous vides.

Le démarrage rapide définit la capacité Sonnet sur 25. Pour remplacer la capacité de n’importe quelle famille déployée, définissez la variable de capacité correspondante :

azd env set CLAUDE_SONNET_CAPACITY 25

Les valeurs de capacité sont mesurées en milliers de jetons par minute. Par exemple, 25 demande 25 000 TPM.

Configurer l’accès à l’invocation de modèle

Pour que les exemples Microsoft Entra ID fonctionnent immédiatement après le déploiement, défini ASSIGN_RBAC=true avant azd up. Le modèle attribue au compte Foundry le rôle Cognitive Services User avec le niveau de privilèges minimal à l’identifiant du principal que azd fournit via AZURE_PRINCIPAL_ID, de sorte que vous n’avez normalement pas besoin de rechercher vous-même votre propre identifiant d’objet.

azd env set ASSIGN_RBAC true

Définissez AZURE_PRINCIPAL_ID manuellement uniquement lorsque vous devez accorder l’accès à un autre utilisateur ou principal de service :

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

Si vous n’activez pas cette option, vous pouvez toujours déployer les ressources. Toutefois, vous ou un administrateur devez accorder des autorisations pour invoquer le modèle avant que les exemples de Microsoft Entra ID puissent appeler le modèle.

Le kit de démarrage attribue Cognitive Services User, car il s’agit du rôle aux privilèges les plus restreints pour l’invocation de modèle sans clé. Si vous envisagez d’ajouter des fonctionnalités de projet Foundry plus larges ultérieurement, telles que des agents ou des évaluateurs, vous pouvez accorder des rôles de plan de données plus larges tels que Foundry User ou Azure AI Developer séparément.

Déployer avec azd up

Exécutez le déploiement :

azd up

La azd up commande effectue ces tâches :

  1. Exécute une vérification préalable des paramètres requis, de la disponibilité du catalogue de la place de marché et de la marge de quota disponible.
  2. Crée le groupe de ressources Azure.
  3. Crée le compte et le projet Microsoft Foundry.
  4. Déploie les familles de modèles Claude sélectionnées.
  5. Permet d’attribuer, si nécessaire, le rôle d’invocation du modèle.
  6. Écrit des valeurs de sortie telles que CLAUDE_BASE_URL, CLAUDE_DEPLOYMENT_NAMEet des noms de déploiement par famille.
  7. Exécute le hook postprovision pour configurer les fichiers d’activateur Claude Code.

Le déploiement peut prendre plusieurs minutes. Les déploiements de modèles peuvent également poursuivre le provisionnement après que l’opération de déploiement ARM a renvoyé une erreur d’expiration du délai. Si cela se produit, utilisez le script de vérification dans la section suivante pour vérifier l’état de déploiement réel avant la réexécution azd up.

Vérifier le déploiement

À partir de la racine du dépôt, exécutez le script de vérification :

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

Pour attendre les déploiements de modèles qui sont toujours en cours d’approvisionnement, ajoutez l’indicateur d’attente :

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

Pour inclure un aller-retour Claude Code en direct, omettez l’indicateur skip :

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

Le script de vérification vérifie l’activateur généré, les variables d’environnement attendues, la connexion à Azure CLI, la visibilité de la ressource Foundry, les états de déploiement des modèles et la disponibilité de Claude Code CLI.

Utiliser Claude Code avec le modèle déployé

Utiliser l’interface CLI Claude Code

Par défaut, le kit de démarrage génère des scripts d’activation propres au projet ainsi que la configuration d’espace de travail de Claude à la racine du dépôt :

  • claude-code.env.ps1 pour PowerShell.
  • claude-code.env.sh pour Bash, macOS, Linux, Git Bash ou WSL.
  • Configuration de l’espace de travail Claude permettant d’épingler Claude Code à une famille de modèles que vous avez déployée.
. .\claude-code.env.ps1
claude

L’activateur configure Claude Code pour qu’il utilise Microsoft Foundry et définit les noms de déploiement pour les familles de modèles que vous avez déployées. Pour chaque famille déployée, le hook de postprovisionnement écrit une valeur ANTHROPIC_DEFAULT_<FAMILY>_MODEL dans l’activateur afin que Claude Code puisse rediriger vers Haiku, Sonnet ou Opus lorsque ces déploiements existent. La configuration de l’espace de travail Claude associe la valeur par défaut de l’espace de travail à une famille déployée, de sorte que claude correspond à un modèle qui existe dans votre compte Foundry.

Si la claude commande n’est pas installée, le hook postprovision imprime la commande d’installation de votre plateforme. Pour que le kit de démarrage installe Automatiquement Claude Code lors de l’approvisionnement, définissez cette valeur avant d’exécuter azd up:

azd env set CLAUDE_CODE_AUTO_INSTALL true

Facultatif : configurer l’extension VS Code

Le kit de démarrage n’écrit .vscode/settings.json pas par défaut. Si vous utilisez l’extension Claude Code pour VS Code et souhaitez que le kit de démarrage la configure, activez cette option avant azd up :

azd env set CLAUDE_WRITE_VSCODE_SETTINGS true

Lorsque vous activez cette option, le hook postprovision écrit ou fusionne claudeCode.environmentVariables et claudeCode.disableLoginPrompt dans .vscode/settings.json afin que l’extension utilise votre déploiement Foundry au lieu de demander de se connecter à un compte Anthropic.

Appelez Claude à partir de Python

Le dépôt inclut des exemples Python sous src. Utilisez-les pour tester l’accès de type application avec le kit de développement logiciel (SDK) Anthropic et Microsoft Entra ID.

Depuis la racine du dépôt, revenez au dossier de la variante d’infrastructure et écrivez les sorties azd dans .env.local à la racine du dépôt :

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

Créez ensuite un environnement virtuel et installez les dépendances :

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

Exécutez l’exemple en une seule exécution :

python src\hello_claude.py

L’exemple charge CLAUDE_BASE_URL et CLAUDE_DEPLOYMENT_NAME, obtient un jeton Microsoft Entra ID pour https://ai.azure.com/.default, crée un client Anthropic avec l’URL de base de Foundry et envoie une requête à l’API Messages.

Vous pouvez également essayer les variantes de streaming et de longue durée.

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

Utilisez l’exemple d’actualisation des jetons pour les services, les démons, les notebooks ou d’autres processus qui peuvent s’exécuter plus longtemps que la durée de vie d’un seul jeton Microsoft Entra ID.

Avancé : tester avec une clé API

Utilisez Microsoft Entra ID pour les scénarios de développement et de production normaux. Pour les tests locaux rapides, le dépôt inclut également un exemple de clé API.

Depuis la racine du dépôt, accédez au dossier de la variante d’infrastructure et récupérez le nom du compte Foundry et le groupe de ressources :

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

Utilisez les valeurs FOUNDRY_ACCOUNT_NAME et AZURE_RESOURCE_GROUP dans la sortie pour définir CLAUDE_API_KEY. Ensuite, exécutez l’exemple de clé API à partir de la racine du dépôt :

$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

Les clés API sont utiles pour une vérification rapide de la connectivité, mais elles ne fournissent pas les mêmes avantages de contrôle d'accès par utilisateur et de cycle de vie des informations d'identification que Microsoft Entra ID.

Conditions d’utilisation

Les variantes Bicep et Terraform envoient toutes deux un bloc modelProviderData à chaque déploiement de Claude. Ce bloc inclut organizationName, countryCodeet industry. Le fournisseur de ressources Cognitive Services utilise ces valeurs pour accepter l'offre de Place de marché Azure pour Anthropic Claude en votre nom. Il n'existe donc aucun clic manuel distinct pendant azd up.

Avant de déployer :

  1. Passez en revue les documents juridiques qui régissent Claude via Microsoft Foundry :
  2. Définissez les valeurs d’attestation afin qu’elles décrivent avec précision votre organisation :
    • CLAUDE_ORGANIZATION_NAME: nom de l’entité juridique. Cette valeur est requise et n’a pas de valeur par défaut.
    • CLAUDE_COUNTRY_CODE: code de pays à deux lettres. La valeur par défaut du kit de démarrage est US.
    • CLAUDE_INDUSTRY: le secteur des organisations. La valeur par défaut du kit de démarrage est technology.
  3. Vérifiez que votre abonnement Azure est éligible pour déployer des modèles Anthropic Claude dans Microsoft Foundry.

Si les valeurs par défaut pour le pays ou l’industrie ne décrivent pas avec précision l’organisation qui utilise Claude, remplacez-les avant de déployer.

Prévisualiser la boîte de dialogue affichée par Foundry dans le parcours manuel, et vérifier l’acceptation après azd up

La boîte de dialogue « Accepter et continuer » du portail Azure pour un SKU Claude est générée à partir des métadonnées en temps réel de l’offre Marketplace. Étant donné que le texte de la Place de marché peut changer, utilisez la liste dynamique pour la référence SKU que vous envisagez de déployer au lieu de vous appuyer sur un instantané copié.

Après azd up, vous pouvez vérifier les métadonnées du contrat Marketplace accepté à l’aide d’Azure CLI. La commande retourne des métadonnées telles que l’état accepté, la signature, la date et le lien de texte de licence. Cela ne renvoie pas l’intégralité du texte de la boîte de dialogue du portail.

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

Pour les autres références SKU Claude, remplacez la --product valeur par l’offre de la Place de marché correspondante. Utilisez le nom du forfait figurant dans les métadonnées de l’offre active ou dans les contrôles du catalogue du kit de démarrage.

Résolution des problèmes

Pour plus de cas, consultez la section de résolution des problèmes du kit de démarrage.

Problème Que faire
Blocs d’éligibilité de l’abonnement ou de l’offre azd up Vérifiez que votre abonnement et votre compte de facturation sont éligibles pour les modèles Claude dans Microsoft Foundry. Si votre organisation exige une acceptation explicite du Marketplace, acceptez l’offre Anthropic correspondante avant de relancer azd up.
La région n’est pas disponible pour le modèle sélectionné Utilisez une région où la famille Claude sélectionnée est disponible. Le guide de démarrage rapide utilise eastus2; swedencentral héberge également souvent Haiku, Sonnet et Opus, et westus2 héberge Sonnet et Opus. La disponibilité peut changer. Par conséquent, exécutez pwsh -File .\Get-ClaudeCatalog.ps1 -Latest à partir de la racine du dépôt si vous n’êtes pas sûr.
Le quota est insuffisant, ou le quota apparaît plein sans déploiements en direct Réduisez la valeur correspondante CLAUDE_*_CAPACITY , supprimez les déploiements inutilisés ou demandez une augmentation du quota. Les comptes Foundry ou AIServices supprimés de manière réversible peuvent réserver le quota TPM pendant jusqu’à 48 heures ; listez-les avec az cognitiveservices account list-deleted -o table et videz les comptes dont vous n’avez plus besoin.
Terraform échoue avec une erreur opaque 715-123420 Traitez-le comme un échec probable du quota, y compris le quota détenu par des comptes supprimés de manière réversible. Exécutez les vérifications préalables du kit de démarrage, examinez la marge disponible du quota, réduisez la capacité ou réessayez avec la version Bicep pour faire apparaître un message InsufficientQuota plus clair.
Claude Code ou Python retourne 401 ou 403 Exécutez az login, vérifiez que vous êtes connecté au locataire auquel appartient la ressource Foundry et vérifiez que l’appelant dispose de l’autorisation d’invoquer le modèle, par exemple Cognitive Services User. Les affectations RBAC récentes peuvent prendre quelques minutes pour se propager.
GatewayTimeout s’affiche pendant le déploiement du modèle Le déploiement de modèle peut continuer après l’expiration de l’opération ARM. Avant de réexécuter azd up, exécutez le script de vérification avec -WaitForDeployment ou --wait-for-deployment pour vérifier l’état réel du déploiement.

Nettoyer les ressources

Lorsque vous n’avez plus besoin des ressources, supprimez-les avec azd down dans le dossier de variante d’infrastructure :

cd infra-bicep
azd down

Ou:

cd infra-terraform
azd down

Passez en revue les ressources qui azd prévoient de supprimer avant de confirmer. La suppression de l’environnement supprime le compte Foundry, le projet et les déploiements de modèles créés par le kit de démarrage.

Si vous apportez des modifications successives aux déploiements et que vous devez récupérer immédiatement le quota TPM réservé pour Claude, utilisez l’option de purge lorsque votre version azd la prend en charge :

azd down --purge

En l’absence de purge, les comptes Foundry ou AIServices supprimés de façon réversible peuvent continuer à conserver un quota TPM pendant jusqu’à 48 heures. Si vous avez déjà supprimé un environnement sans purger et que le quota apparaît toujours plein, utilisez cette option az cognitiveservices account list-deleted -o table pour rechercher les comptes supprimés et vider les comptes dont vous n’avez plus besoin.

Étapes suivantes

  • Last updated on