Implementar modelos Claude no Microsoft Foundry usando Bicep ou Terraform

O Claude on Foundry Starter Kit ajuda-te a implementar modelos Anthropic Claude para o Microsoft Foundry usando o Azure Developer CLI (azd). Também ajuda a configurar a autenticação local e a chamar o modelo implementado a partir do Claude Code ou Python.

Neste artigo, você aprenderá a:

  • Implemente o Claude Sonnet no Microsoft Foundry usando a variante Bicep do kit inicial.
  • Configure os valores de atestação necessários do fornecedor de modelos Anthropic.
  • Configure o código Claude para usar o modelo hospedado no Foundry.
  • Chame o modelo Claude implementado a partir do Python usando o Microsoft Entra ID.
  • Personalize a implementação do Terraform, mais famílias de modelos, outras regiões ou capacidades diferentes.

Importante

Executar azd up com este kit inicial aceita os termos do Anthropic Marketplace e envia os valores de atestação CLAUDE_ORGANIZATION_NAME, CLAUDE_COUNTRY_CODE e CLAUDE_INDUSTRY nos pedidos. Defina valores que descrevam a organização real usando o modelo. Para mais detalhes, consulte os Termos de utilização.

Guia de início rápido

Este "cenário ideal" implementa o Claude Sonnet com o Bicep em eastus2 com capacidade de 25 (25.000 tokens por minuto). Usa-o primeiro para chegar a uma implementação funcional, depois passa para Personalizar a implementação se precisares de Terraform, várias famílias de modelos, outra região ou capacidade diferente.

Precisa de uma subscrição do Azure elegível para 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 posterior. Se a sua conta puder criar atribuições de funções, o QuickStart também concede ao seu utilizador acesso para invocação de modelos, para que os exemplos possam ser executados imediatamente.

Clonar, configurar e implementar

Se a sua subscrição elegível para Claude estiver num tenant não padrão, adicione o ID do tenant a ambos os comandos de iniciação de sessão.

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, US, e technology por valores para a organização real usando Claude. Se a tua conta não conseguir criar atribuições de funções, ignora ASSIGN_RBAC e pede a um administrador para conceder acesso à invocação do modelo antes de executares os exemplos.

Verificar e executar o Código Claude

A partir da raiz do repositório, verifique a configuração gerada e o estado de implementação. A opção skip evita uma chamada em tempo real ao Claude durante a verificação.

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

. .\claude-code.env.ps1
claude

Executa o exemplo de Python

Escreva os azd resultados em .env.local, instale as dependências e execute o exemplo de execução única com o ID do Microsoft Entra.

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 implementação do Claude usando Bicep ou Terraform. Configura a autenticação local para o Microsoft Entra ID e fornece amostras funcionais de código Claude e Python. Inclui também verificações preliminares para problemas comuns de marketplace, região e quotas, para que possa resolver bloqueios antes do aprovisionamento. Para mais detalhes, veja O que a implementação cria e Personalize a implementação.

Pré-requisitos

  • Uma subscrição do Azure elegível para implementar modelos Anthropic Claude no Microsoft Foundry. A disponibilidade do modelo Claude depende do tipo de subscrição, estado de faturação, região e regiões suportadas pela Anthropic.
  • Permissões para criar e gerir os recursos do Azure alvo. Normalmente, precisa de Contributor ou Owner na subscrição ou no grupo de recursos de destino.
  • Acesso ao Azure Marketplace para ofertas de modelos de parceiros.
  • CLI do Azure.
  • CLI do desenvolvedor do Azure.
  • Git.
  • Python 3.10 ou posterior para os exemplos de Python.
  • Terraform 1.6 ou posterior, se escolheres a variante Terraform.

Dica

O repositório também suporta GitHub Codespaces e VS Code Dev Containers. Esses ambientes incluem as ferramentas de desenvolvimento necessárias, por isso são uma boa escolha se não quiseres instalar az, azd, e Python localmente.

O que a implementação cria

O kit inicial cria estes recursos e ficheiros de configuração locais:

  • Um grupo de recursos Azure para o azd ambiente.
  • Uma conta Microsoft Foundry.
  • Um projeto da Microsoft Foundry.
  • Uma ou mais implementações de modelos Claude na conta Foundry.
  • Uma atribuição opcional de função para a invocação do modelo.
  • Scripts locais de ativação do Claude Code na raiz do repositório.
  • Configuração do espaço de trabalho do Claude que associa o Claude Code a uma família de modelos implementada.
  • Definições opcionais da extensão do VS Code ao definir CLAUDE_WRITE_VSCODE_SETTINGS=true.
  • azd as saídas do ambiente, incluindo o nome da conta Foundry, o URL de base, o ponto final do projeto e os nomes das implementações.

Personalizar a implantação

Use esta secção quando quiser variar o caminho do Quickstart, como usar o Terraform, selecionar uma região diferente, implementar várias famílias Claude ou alterar a capacidade. Se já completou o QuickStart, pode avançar para usar o Claude Code com o modelo implementado ou Chamar o Claude a partir do Python.

Clone o kit inicial

Clone o kit inicial e mude para o repositório:

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

Opcionalmente, inspecione o catálogo Claude ativo antes de escolher os IDs dos modelos. Este assistente é exclusivo do 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 os IDs dos modelos Claude disponíveis na região que planeia implementar.

Escolha uma variante de infraestrutura

O kit inicial inclui duas variantes equivalentes de infraestrutura:

Variant Folder Utilizar quando
Bicep infra-bicep Preferes a infraestrutura nativa do Azure como código.
Terraform infra-terraform Preferes o Terraform e já usas fluxos de trabalho do Terraform.

Mude para uma das pastas variantes:

cd infra-bicep

Ou:

cd infra-terraform

Os restantes comandos deste artigo correm a partir da pasta variante que escolheste.

Iniciar sessão no Azure

Inicie sessão usando tanto o CLI do Azure como o Azure Developer CLI:

az login
azd auth login

Se a sua subscrição elegível para Claude estiver num locatário que não seja o predefinido, 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 implementação:

azd env new my-claude

Se já criaste um ambiente, seleciona-o em vez disso:

azd env select my-claude

Configurar os valores de implementação necessários

Defina os valores da organização utilizados na atestação do fornecedor 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 legal da sua organização, código de país de duas letras e indústria. O kit inicial fornece valores padrão para país e indústria, mas anula-os a menos que US e technology descreva com precisão a organização que utiliza o Claude.

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

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

Definir a região Azure:

azd env set AZURE_LOCATION "eastus2"

O kit inicial suporta regiões onde os modelos Claude selecionados estão disponíveis. O QuickStart usa eastus2. Para uma implementação comum para toda a família, eastus2 e swedencentral alojam atualmente Haiku, Sonnet e Opus. westus2 aloja Sonnet e Opus. A disponibilidade pode mudar, por isso use o script do catálogo ao vivo se não tiver a certeza de que famílias de modelos estão disponíveis na sua região-alvo.

Implementar mais famílias de modelos ou alterar a capacidade

Para uma primeira implementação simples, implemente apenas o Sonnet usando a variável preferida por família:

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

Para implementar múltiplas famílias de modelos na mesma conta Foundry, defina uma ou mais variáveis familiares:

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 familiar não vazia cria uma implementação separada. Deixa uma família por decidir para não o fazer. A configuração mais antiga CLAUDE_MODEL_NAME é uma alternativa legada de implementação única e é usada apenas quando CLAUDE_HAIKU_MODEL, CLAUDE_SONNET_MODEL, e CLAUDE_OPUS_MODEL estão todas vazias.

O QuickStart define a capacidade do Sonnet para 25. Para sobrescrever a capacidade de qualquer família implementada, 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 do modelo

Para que os exemplos do Microsoft Entra ID funcionem imediatamente após a implementação, defina ASSIGN_RBAC=true antes de azd up. O modelo atribui a função de menor privilégio Cognitive Services User na conta Foundry ao ID do principal que azd fornece através de AZURE_PRINCIPAL_ID, pelo que normalmente não precisa de procurar o seu próprio ID de objeto.

azd env set ASSIGN_RBAC true

Definir AZURE_PRINCIPAL_ID manualmente apenas quando precisar de conceder acesso a um utilizador ou principal de serviço diferente:

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

Se não ativares esta opção, ainda podes implementar os recursos. No entanto, você ou um administrador deve conceder permissões de invocação de modelos antes que os exemplos do Microsoft Entra ID possam chamar o modelo.

O kit inicial atribui Cognitive Services User porque é a função com o menor nível de privilégios para a invocação de modelos sem utilização de chave. Se planeia adicionar funcionalidades mais amplas do projeto Foundry mais tarde, como agentes ou avaliadores, pode atribuir funções mais amplas no plano de dados, como Foundry User ou Azure AI Developer separadamente.

Implantar com azd up

Iniciar a implementação:

azd up

O azd up comando executa as seguintes tarefas:

  1. Efetua uma verificação preliminar às definições necessárias, à disponibilidade do catálogo do marketplace e à margem disponível nas quotas.
  2. Cria o grupo de recursos do Azure.
  3. Cria a conta e o projeto da Microsoft Foundry.
  4. Implementa as famílias de modelos Claude selecionadas.
  5. Opcionalmente, atribui o papel de invocação do modelo.
  6. Escreve valores de saída como CLAUDE_BASE_URL, CLAUDE_DEPLOYMENT_NAME e nomes de implementação por família.
  7. Executa o hook postprovision para configurar ficheiros ativadores de Claude Code.

A implantação pode levar vários minutos. As implementações de modelos também podem continuar a ser aprovisionadas após a operação de implementação do ARM expirar. Se isso acontecer, use o script de verificação na secção seguinte para verificar o estado real da implementação antes de voltar a executar azd up.

Verificar a implantação

A partir da raiz do repositório, execute o script de verificação:

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

Para aguardar implementações de modelos que ainda estejam em aprovisionamento, adicione a opção de espera:

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

Para incluir um ciclo completo em tempo real do Claude Code, omita a opção --skip:

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

O script de verificação verifica o ativador gerado, as variáveis de ambiente esperadas, o início de sessão do CLI do Azure, o recurso visível do Foundry, os estados de implementação do modelo e a disponibilidade da CLI do Claude Code.

Use o Claude Code com o modelo implementado

Use a linha de comando Claude Code

Por defeito, o kit inicial escreve scripts ativadores com âmbito de projeto e configuração do espaço de trabalho Claude na raiz do repositório:

  • claude-code.env.ps1 para PowerShell.
  • claude-code.env.sh para Bash, macOS, Linux, Git Bash ou WSL.
  • Configuração do espaço de trabalho Claude para fixar o código Claude numa família de modelos que implementaste.
. .\claude-code.env.ps1
claude

O ativador configura o Claude Code para usar o Microsoft Foundry e define os nomes de implementação das famílias de modelos que implementou. Para cada família implantada, o gancho de pós-provisionamento escreve um valor ANTHROPIC_DEFAULT_<FAMILY>_MODEL no activador para 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 Claude define o predefinido do espaço de trabalho para uma família já implementada, pelo que claude é resolvido para um modelo que existe na sua conta Foundry.

Se o claude comando não estiver instalado, o gancho postprovision imprime o comando de instalação para a tua plataforma. Para que o kit inicial instale automaticamente o Claude Code durante o provisionamento, defina este valor antes de executar azd up:

azd env set CLAUDE_CODE_AUTO_INSTALL true

Opcional: configurar a extensão VS Code

O kit de iniciação não inclui .vscode/settings.json por defeito. Se usar a extensão Claude Code para o VS Code e quiser que o kit inicial a configure, ative essa opção antes de azd up:

azd env set CLAUDE_WRITE_VSCODE_SETTINGS true

Quando ativas esta opção, o hook postprovision escreve ou funde claudeCode.environmentVariables e claudeCode.disableLoginPrompt em, .vscode/settings.json por isso a extensão usa a tua implementação no Foundry em vez de pedir login na conta Anthropic.

Chamar o Claude a partir do Python

O repositório inclui exemplos de Python sob src. Utilize-os para testar o acesso de tipo aplicação com o SDK da Anthropic e o Microsoft Entra ID.

A partir da raiz do repositório, volte à pasta da variante de infraestrutura e grave os resultados 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

Depois cria um ambiente virtual e instala 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 o URL de base do Foundry e envia um pedido à API Messages.

Também podes experimentar as variantes de streaming e de longa duração.

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

Use a amostra de atualização do token para serviços, daemons, notebooks ou outros processos que possam correr mais do que a vida útil de um único token Microsoft Entra ID.

Avançado: teste com uma chave API

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

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

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

Use os FOUNDRY_ACCOUNT_NAME valores e AZURE_RESOURCE_GROUP da saída para definir CLAUDE_API_KEY. Depois, executa o exemplo da chave de API a partir da 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 API são úteis para uma verificação rápida de conectividade, mas não oferecem o mesmo controlo de acesso por utilizador nem os mesmos benefícios no ciclo de vida das credenciais que o Microsoft Entra ID.

Termos de utilização

As variantes Bicep e Terraform enviam ambas um modelProviderData bloco com cada implementação do Claude. Esse bloco inclui organizationName, countryCode, e industry. O fornecedor de recursos dos Serviços Cognitivos utiliza esses valores para aceitar, em seu nome, a oferta do Anthropic Claude no Azure Marketplace, pelo que não é necessária uma confirmação manual em separado durante azd up.

Antes de implementar:

  1. Revise os documentos legais que regem a Claude através do Microsoft Foundry:
  2. Defina os valores de atestação para que descrevam com precisão a sua organização:
    • CLAUDE_ORGANIZATION_NAME: o nome da entidade legal. Este valor é obrigatório e não tem valor predefinido.
    • CLAUDE_COUNTRY_CODE: o código de país de duas letras. O kit inicial por defeito é US.
    • CLAUDE_INDUSTRY: a indústria organizacional. O kit inicial por defeito é technology.
  3. Confirme que a sua subscrição do Azure é elegível para implementar modelos Anthropic Claude no Microsoft Foundry.

Se os valores padrão por país ou indústria não descreverem com precisão a organização que usa o Claude, ignore-os antes de implementar.

Pré-visualize o diálogo que o Foundry mostra no caminho manual e audite a aceitação após azd up

O diálogo "Concordar e prosseguir" do portal Azure para um SKU Claude é gerado a partir dos metadados da oferta ao vivo do Marketplace. Como esse texto do Marketplace pode mudar, use a listagem em tempo real do SKU que planeia implementar em vez de depender de um snapshot copiado.

Após azd up, pode auditar os metadados aceites do acordo do Marketplace usando o CLI do Azure. O comando devolve metadados como o estado aceite, assinatura, data e link de texto da licença. Não devolve o texto completo do 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. Utilize o nome do plano a partir dos metadados da oferta ativa ou das validações do catálogo do kit inicial.

Solução de problemas

Para mais casos, consulte a secção de resolução de problemas do kit de arranque.

Problema O que experimentar
Blocos de elegibilidade para subscrição ou oferta azd up Verifique se a sua conta de subscrição e faturação são elegíveis para modelos Claude no Microsoft Foundry. Se a sua organização exigir aceitação explícita do Marketplace, aceite a oferta correspondente da Anthropic antes de voltar a executar azd up.
A região não está disponível para o modelo selecionado Use uma região onde a família Claude selecionada esteja disponível. O QuickStart usa eastus2; swedencentral também aloja frequentemente Haiku, Soneta e Opus, e westus2 também hospeda Sonet e Opus. A disponibilidade pode mudar, por isso corre pwsh -File .\Get-ClaudeCatalog.ps1 -Latest pela raiz do repositório se não tiveres a certeza.
A quota é insuficiente, ou a quota parece cheia sem implantações ativas Reduza o valor correspondente CLAUDE_*_CAPACITY , elimine implantações não utilizadas ou peça um aumento da quota. As contas Foundry ou AIServices eliminadas de forma recuperável podem reservar quota de TPM durante até 48 horas; liste-as com az cognitiveservices account list-deleted -o table e elimine definitivamente as contas de que já não necessita.
O Terraform falha com um erro opaco 715-123420 Considere isto como um provável excedente de quota, incluindo a quota ocupada por contas eliminadas temporariamente. Execute as verificações preliminares do kit inicial, reveja a margem disponível da quota, reduza a capacidade ou tente novamente com a variante Bicep para apresentar uma mensagem InsufficientQuota mais clara.
Claude Code ou Python devolvem 401 ou 403 Execute az login, confirme que tem sessão iniciada no tenant ao qual pertence o recurso Foundry e verifique se o autor da chamada tem permissões para invocar o modelo, como Cognitive Services User. As novas atribuições RBAC podem demorar alguns minutos até serem propagadas.
GatewayTimeout aparece durante a implementação do modelo A implementação do modelo pode continuar após o fim do tempo de funcionamento do ARM. Antes de reexecutar azd up, execute o script de verificação com -WaitForDeployment ou --wait-for-deployment para verificar o estado real de implementação.

Limpeza de recursos

Quando já não precisares destes recursos, elimina-os da pasta da variante de infraestrutura com azd down:

cd infra-bicep
azd down

Ou:

cd infra-terraform
azd down

Revise os recursos que azd planeia eliminar antes de confirmar. Eliminar o ambiente remove a conta do Foundry, o projeto e as implementações de modelos que o kit inicial criou.

Se estiveres a iterar nas implementações e precisares de recuperar imediatamente a quota de TPM reservada para o Claude, usa a opção de purga quando a tua versão azd o suportar:

azd down --purge

Sem eliminação definitiva, as contas do Foundry ou do AIServices eliminadas de forma recuperável podem continuar a reter a quota de TPM até 48 horas. Se já eliminaste um ambiente sem purgar e a quota continua cheia, usa az cognitiveservices account list-deleted -o table para encontrar contas eliminadas e purgar as contas que já não precisas.

Passos seguintes

  • Last updated on