Implante modelos Claude no Microsoft Foundry usando Bicep ou Terraform

O kit inicial do Claude on Foundry ajuda você a implantar modelos Claude da Anthropic no Microsoft Foundry usando a Azure Developer CLI (azd). Ele também ajuda você a configurar a autenticação local e chamar o modelo implantado do Claude Code ou Python.

Neste artigo, você aprenderá como:

  • Implante o Claude Sonnet no Microsoft Foundry usando a variante Bicep do kit de início.
  • Configure os valores de atestado do provedor de modelo da Anthropic necessários.
  • Configure o Claude Code para usar o modelo hospedado pela Foundry.
  • Chame o modelo Claude implantado de Python usando Microsoft Entra ID.
  • Personalize a implantação do Terraform com mais famílias de modelos, outras regiões ou uma capacidade diferente.

Importante

Executar azd up com este kit de início aceita os termos do Anthropic Marketplace e envia os valores de atestado CLAUDE_ORGANIZATION_NAME, CLAUDE_COUNTRY_CODE e CLAUDE_INDUSTRY com as solicitações. Defina valores que descrevem a organização real usando o modelo. Para obter detalhes, consulte Termos de uso.

QuickStart

Esse "caminho feliz" implanta o Claude Sonnet usando o Bicep em eastus2 com capacidade 25 (25.000 tokens por minuto). Use-o primeiro para obter uma implantação funcional e, em seguida, vá para Personalizar a implantação se precisar usar o Terraform, várias famílias de modelos, outra região ou uma capacidade diferente.

Você precisa de uma assinatura do Azure elegível para usar o Anthropic Claude no Microsoft Foundry, permissões para criar os recursos de destino, CLI do Azure, Azure Developer CLI, Git e Python 3.10 ou mais recente. Se sua conta puder criar atribuições de função, o Início Rápido também concederá acesso à invocação do modelo de usuário para que os exemplos possam ser executados imediatamente.

Clonar, configurar e implantar

Se a assinatura elegível para o Claude estiver em um locatário não padrão, adicione a ID do locatário a ambos os comandos de entrada.

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

Substitua Contoso, USe technology por valores para a organização real usando Claude. Se sua conta não puder criar atribuições de função, pule ASSIGN_RBAC e peça a um administrador que conceda acesso para invocar o modelo antes de executar os exemplos.

Verificar e executar o Claude Code

Na raiz do repositório, verifique a configuração gerada e o estado da implantação. O sinalizador para ignorar evita uma chamada ao vivo do Claude durante a verificação.

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

. .\claude-code.env.ps1
claude

Executar o exemplo de Python

Grave as saídas azd em .env.local, instale as dependências e execute a amostra de execução única com o 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

Como o kit inicial ajuda

O kit inicial automatiza a implantação de Claude usando Bicep ou Terraform. Ele configura a autenticação local para Microsoft Entra ID e fornece exemplos de Claude Code e Python funcionais. Isso também inclui verificações de pré-lançamento para problemas comuns relacionados a marketplace, região e cota, de maneira que você possa corrigir impedimentos antes do provisionamento. Para obter mais detalhes, consulte o que a implantação cria e personalize a implantação.

Pré-requisitos

  • Uma assinatura Azure qualificada para implantar modelos Anthropic Claude no Microsoft Foundry. A disponibilidade do modelo Claude depende do tipo de assinatura, do status de cobrança, da região e das regiões com suporte da Anthropic.
  • Permissões para criar e gerenciar os recursos de Azure de destino. Normalmente, você precisa de Contributor ou Owner na assinatura ou no grupo de recursos de destino.
  • Acesso a Azure Marketplace para ofertas de modelo de parceiro.
  • CLI do Azure.
  • CLI do Desenvolvedor do Azure.
  • Git.
  • Python 3.10 ou posterior para os exemplos de Python.
  • Terraform 1.6 ou versão posterior, caso escolha a variante Terraform.

Dica

O repositório também dá suporte a GitHub codespaces e contêineres de desenvolvimento do VS Code. Esses ambientes incluem as ferramentas de desenvolvedor necessárias, portanto, elas serão uma boa opção se você não quiser instalar aze azdPython localmente.

O que a implantação cria

O kit inicial cria esses recursos e arquivos de configuração locais:

  • Um grupo de recursos Azure para o azd ambiente.
  • Uma conta do Microsoft Foundry.
  • Um projeto do Microsoft Foundry.
  • Uma ou mais implantações do modelo Claude na conta Foundry.
  • Uma atribuição de função opcional para invocação de modelo.
  • Scripts ativadores locais de código do Claude na raiz do repositório.
  • Configuração do espaço de trabalho do Claude que vincula o Claude Code a uma família de modelos implantada.
  • Configurações de extensão opcionais do VS Code quando você define CLAUDE_WRITE_VSCODE_SETTINGS=true.
  • azd saídas de ambiente, inclusive o nome da conta do Foundry, a URL base, o ponto de extremidade do projeto e os nomes de implantação.

Personalizar a implementação

Use esta seção quando quiser variar o caminho de Início Rápido, como usar o Terraform, selecionar uma região diferente, implantar várias famílias Claude ou alterar a capacidade. Se você já concluiu o Início Rápido, poderá pular para usar o Claude Code com o modelo implantado ou Chamar Claude de Python.

Clonar o kit inicial

Clone o kit de início e a alteração no repositório:

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

Opcionalmente, inspecione o catálogo ativo do Claude antes de escolher os IDs de modelo. Este assistente está disponível apenas para PowerShell no kit inicial.

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

O catálogo muda ao longo do tempo. Use a saída do script para confirmar quais IDs de modelos Claude estão disponíveis na região em que você planeja fazer a implantação.

Escolher uma variante de infraestrutura

O kit inicial inclui duas variantes de infraestrutura equivalentes:

Variant Folder Usar quando
Bicep infra-bicep Você prefere infraestrutura nativa do Azure como código.
Terraform infra-terraform Você prefere o Terraform e já usa fluxos de trabalho do Terraform.

Altere para uma das pastas variantes:

cd infra-bicep

Ou:

cd infra-terraform

O restante dos comandos neste artigo é executado na pasta variant escolhida.

Entrar no Azure

Faça login usando a CLI do Azure e a Azure Developer CLI:

az login
azd auth login

Se a assinatura elegível para o Claude estiver em um locatário não padrão, especifique o locatário:

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

Criar um ambiente azd

Crie um azd ambiente para armazenar a configuração de implantação:

azd env new my-claude

Se você já criou um ambiente, selecione-o em vez disso:

azd env select my-claude

Configurar valores de implantação necessários

Defina os valores da organização usados para a certificação do provedor do modelo Claude:

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

Substitua os valores de exemplo pelo nome da entidade jurídica da sua organização, pelo código do país de duas letras e pelo setor. O kit inicial fornece valores padrão para país e setor, mas substitua esses valores, a menos que US e technology descrevam com precisão a organização que usa o Claude.

O valor da indústria deve estar em minúsculas. Os valores suportados são:

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

Defina a região Azure:

azd env set AZURE_LOCATION "eastus2"

O kit inicial dá suporte a regiões em que os modelos claude selecionados estão disponíveis. O Início Rápido usa eastus2. Para uma implantação de toda a família comum, eastus2 e swedencentral atualmente hospedam Haiku, Sonnet e Opus. westus2 hospeda Sonnet e Opus. A disponibilidade pode mudar, portanto, use o script de catálogo dinâmico se você não tiver certeza de quais famílias de modelos estão disponíveis em sua região de destino.

Implantar mais famílias de modelos ou alterar a capacidade

Para uma primeira implantação simples, implante somente o Sonnet usando a variável preferencial por família:

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

Para implantar várias famílias de modelos na mesma conta do Foundry, defina uma ou mais variáveis de família:

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

Cada variável de família não vazia cria uma implantação separada. Deixe uma família indefinida para ignorá-la. A configuração CLAUDE_MODEL_NAME anterior é um fallback de implantação única herdado e só é usada quando CLAUDE_HAIKU_MODEL, CLAUDE_SONNET_MODEL e CLAUDE_OPUS_MODEL estão todos vazios.

O QuickStart configura a capacidade do Sonnet para 25. Para substituir a capacidade de qualquer família implantada, defina a variável de capacidade correspondente:

azd env set CLAUDE_SONNET_CAPACITY 25

Os valores de capacidade são medidos em milhares de tokens por minuto. Por exemplo, 25 solicita 25.000 TPM.

Configurar o acesso à invocação de modelo

Para que os exemplos do Microsoft Entra ID funcionem imediatamente após a implantação, defina ASSIGN_RBAC=true antes de azd up. O modelo atribui a função Cognitive Services User de menos privilégio na conta do Foundry à ID da entidade fornecida por azd por meio de AZURE_PRINCIPAL_ID, de maneira que você normalmente não precisa procurar a própria ID de objeto.

azd env set ASSIGN_RBAC true

Defina AZURE_PRINCIPAL_ID manualmente somente quando precisar conceder acesso a um usuário ou entidade de serviço diferente:

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

Se você não habilitar essa opção, ainda poderá implantar os recursos. No entanto, você ou um administrador deve conceder permissões de invocação de modelo antes que os exemplos de Microsoft Entra ID possam chamar o modelo.

O kit de início atribui Cognitive Services User porque se trata da função de menos privilégio para invocação do modelo sem chave. Se você planeja adicionar recursos de projeto mais amplos do Foundry mais tarde, como agentes ou avaliadores, poderá conceder funções mais amplas do plano de dados, como Foundry User ou Azure AI Developer separadamente.

Implantar com azd up

Execute a implantação:

azd up

O azd up comando executa estas tarefas:

  1. Executa uma verificação de pré-lançamento para configurações necessárias, disponibilidade de catálogo do marketplace e reserva dinâmica de cota.
  2. Cria o grupo de recursos do Azure.
  3. Cria a conta e o projeto do Microsoft Foundry.
  4. Implanta as famílias de modelos Claude selecionadas.
  5. Opcionalmente, atribui a função de invocação de modelo.
  6. Grava valores de saída, como CLAUDE_BASE_URL, CLAUDE_DEPLOYMENT_NAME e nomes de implantação por família.
  7. Executa o hook de pós-provisionamento para configurar os arquivos ativadores do Claude Code.

A implantação pode levar vários minutos. As implantações de modelo também podem continuar o provisionamento depois que a operação de implantação do ARM retornar um tempo limite. Se isso acontecer, use o script de verificação na próxima seção para verificar o estado real da implantação antes de executar novamente azd up.

Verificar a implantação

Na raiz do repositório, execute o script de verificação:

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

Para aguardar as implantações de modelo ainda em provisionamento, adicione o sinalizador de espera:

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

Para incluir uma viagem de ida e volta do Claude Code ao vivo, omita o sinalizador para ignorar:

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

O script de verificação verifica o ativador gerado, as variáveis de ambiente esperadas, o login na CLI do Azure, o recurso do Foundry visível, os estados de implantação dos modelos e a disponibilidade da CLI do Claude Code.

Usar o Claude Code com o modelo implantado

Usar a CLI do Claude Code

Por padrão, o kit de início grava scripts de ativador com o projeto de escopo e a configuração do espaço de trabalho do Claude na raiz do repositório:

  • claude-code.env.ps1 para o PowerShell.
  • claude-code.env.sh para Bash, macOS, Linux, Git Bash ou WSL.
  • Configuração do workspace do Claude para vincular o Claude Code a uma família de modelos que você implantou.
. .\claude-code.env.ps1
claude

O ativador configura o Claude Code para usar Microsoft Foundry e define os nomes de implantação para as famílias de modelos implantadas. Para cada família implantada, o gancho de pós-provisionamento grava um valor ANTHROPIC_DEFAULT_<FAMILY>_MODEL no ativador, de maneira que o Claude Code possa direcionar para Haiku, Sonnet ou Opus quando essas implantações estiverem disponíveis. A configuração do espaço de trabalho do Claude fixa o padrão do espaço de trabalho como uma família implantada, logo, claude é resolvido para um modelo existente na conta do Foundry.

Se o comando claude não estiver instalado, o hook de pós-provisionamento exibirá o comando de instalação para a sua plataforma. Para que o kit inicial instale o Claude Code automaticamente durante o provisionamento, defina esse valor antes de executar azd up:

azd env set CLAUDE_CODE_AUTO_INSTALL true

Opcional: configurar a extensão do VS Code

O kit de inicialização não grava .vscode/settings.json por padrão. Se você usa a extensão VS Code do Claude Code e deseja que o kit de início a configure, aceite antes de azd up:

azd env set CLAUDE_WRITE_VSCODE_SETTINGS true

Quando você habilita essa opção, o gancho de pós-provisionamento grava ou mescla claudeCode.environmentVariables e claudeCode.disableLoginPrompt em .vscode/settings.json, de maneira que a extensão use a implantação do Foundry, em vez de solicitar o logon em uma conta da Anthropic.

Chame Claude de Python

O repositório inclui exemplos de Python em src. Use-os para testar o acesso do tipo aplicativo com o SDK da Anthropic e o Microsoft Entra ID.

Na raiz do repositório, retorne para a pasta da variante de infraestrutura e grave as saídas de azd em .env.local na raiz do repositório:

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

Em seguida, crie um ambiente virtual e instale dependências:

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

Execute o exemplo de execução única:

python src\hello_claude.py

O exemplo carrega CLAUDE_BASE_URL e CLAUDE_DEPLOYMENT_NAME, obtém um token do Microsoft Entra ID para https://ai.azure.com/.default, cria um cliente Anthropic com a URL base do Foundry e envia uma solicitação à API Messages.

Você também pode experimentar as variantes de streaming e de longa duração.

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

Use o exemplo de renovação de token para serviços, daemons, notebooks ou outros processos que possam ficar em execução por mais tempo do que a duração de um único token do Microsoft Entra ID.

Avançado: teste com uma chave de API

Use Microsoft Entra ID para cenários normais de desenvolvimento e produção. Para testes locais rápidos, o repositório também inclui um exemplo de chave de API.

Na raiz do repositório, mude para a pasta variante de infraestrutura e obtenha o nome da conta do Foundry e o grupo de recursos:

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

Use os valores FOUNDRY_ACCOUNT_NAME e AZURE_RESOURCE_GROUP da saída para definir CLAUDE_API_KEY. Em seguida, execute o exemplo de chave de API na raiz do repositório:

$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

As chaves de API são úteis para uma verificação rápida de conectividade, mas não fornecem os mesmos benefícios de controle de acesso por usuário e ciclo de vida de credenciais que Microsoft Entra ID.

Termos de uso

As variantes Bicep e Terraform enviam um bloco modelProviderData com cada implantação do Claude. Esse bloco inclui organizationName, countryCodee industry. O provedor de recursos dos Serviços Cognitivos usa esses valores para aceitar, em seu nome, a oferta do Azure Marketplace para o Anthropic Claude, portanto, não é necessário fazer uma confirmação manual separada durante azd up.

Antes de implantar:

  1. Examine os documentos legais que regem Claude por meio do Microsoft Foundry:
  2. Defina os valores de atestado para que eles descrevam com precisão sua organização:
    • CLAUDE_ORGANIZATION_NAME: o nome da entidade jurídica. Este valor é obrigatório e não tem valor padrão.
    • CLAUDE_COUNTRY_CODE: o código do país de duas letras. O padrão do kit inicial é US.
    • CLAUDE_INDUSTRY: o setor de organizações. O padrão do kit inicial é technology.
  3. Confirme se sua assinatura de Azure está qualificada para implantar modelos Anthropic Claude no Microsoft Foundry.

Se os valores padrão de país ou setor não descreverem com precisão a organização que usa o Claude, substitua esses valores antes de fazer a implantação.

Visualize a caixa de diálogo que a Foundry mostra na etapa manual e verifique a aceitação após azd up

A caixa de diálogo "Aceitar e continuar" do portal do Azure para um SKU do Claude é gerada com base nos metadados da oferta do Marketplace. Como esse texto do Marketplace pode mudar, use a listagem ativa da SKU que você pretende implantar, em vez de confiar em uma captura copiada.

Depoisazd up, você pode auditar os metadados aceitos do contrato do Marketplace usando CLI do Azure. O comando retorna metadados como o estado aceito, a assinatura, a data e o link de texto da licença. Ele não retorna o texto completo da caixa de diálogo do portal.

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

Para outros SKUs do Claude, substitua o valor --product pela oferta correspondente do Marketplace. Use o nome do plano com base nos metadados da oferta ativa ou nas verificações de catálogo do kit de início.

Resolução de problemas

Para obter mais casos, consulte a seção de solução de problemas do kit inicial.

Problema O que testar
Blocos de elegibilidade de assinatura ou oferta azd up Verifique se sua assinatura e sua conta de cobrança estão qualificadas para modelos Claude no Microsoft Foundry. Se a organização exigir aceitação do Marketplace explícita, aceite a oferta da Anthropic correspondente antes de executar novamente azd up.
A região não está disponível para o modelo selecionado Use uma região em que a família Claude selecionada esteja disponível. O Início Rápido usa eastus2; swedencentral também normalmente hospeda Haiku, Sonnet e Opus e westus2 hospeda Sonnet e Opus. A disponibilidade pode ser alterada, portanto, execute pwsh -File .\Get-ClaudeCatalog.ps1 -Latest a partir da raiz do repositório se você não tiver certeza.
A cota insuficiente ou aparenta ter acabado sem implantações ativas Reduza o valor de correspondência CLAUDE_*_CAPACITY, exclua implantações não utilizadas ou solicite um aumento de cota. As contas do Foundry ou do AIServices com exclusão reversível podem reservar uma cota de TPM por até 48 horas; liste-as com az cognitiveservices account list-deleted -o table e limpe as contas das quais você não precisa mais.
O Terraform falha com um erro pouco claro 715-123420 Trate isso como uma provável falha na cota, inclusive a cota mantida por contas com exclusão reversível. Execute as verificações de pré-lançamento do kit de início, examine a reserva dinâmica da cota, diminua a capacidade ou tente novamente com a variante do Bicep para exibir uma mensagem InsufficientQuota mais clara.
Claude Code ou Python retorna 401 ou 403 Execute az login, confirme se você está conectado ao locatário que possui o recurso Foundry e verifique se o chamador tem permissão para invocar o modelo, como Cognitive Services User. As novas atribuições de RBAC podem levar alguns minutos para serem propagadas.
GatewayTimeout aparece durante a implantação do modelo A implantação do modelo pode continuar após o tempo limite da operação do ARM. Antes de executar novamente azd up, execute o script de verificação com -WaitForDeployment ou --wait-for-deployment para verificar o estado real da implantação.

Limpar os recursos

Quando você não precisar mais dos recursos, exclua-os com azd down da pasta da variante de infraestrutura:

cd infra-bicep
azd down

Ou:

cd infra-terraform
azd down

Examine os recursos que azd planeja excluir antes de confirmar. A exclusão do ambiente remove a conta, o projeto e as implantações de modelo do Foundry criados pelo kit de início.

Se você estiver iterando em implantações e precisar recuperar imediatamente a cota de TPM do Claude reservada, use a opção de limpeza quando a versão azd der suporte a isso:

azd down --purge

Sem limpar, as contas do Foundry ou do AIServices com exclusão reversível podem continuar retendo a cota de TPM por até 48 horas. Se você já excluiu um ambiente sem limpeza e a cota ainda aparece cheia, use az cognitiveservices account list-deleted -o table para localizar contas excluídas e limpar as contas de que você não precisa mais.

Próximas Etapas 

  • Last updated on