Implementación de modelos de Claude en Microsoft Foundry mediante Bicep o Terraform

El Kit de inicio de Claude on Foundry le ayuda a implementar modelos de Anthropic Claude en Microsoft Foundry mediante Azure CLI para desarrolladores (azd). También le ayuda a configurar la autenticación local y llamar al modelo implementado desde Claude Code o Python.

En este artículo aprenderá a:

  • Implemente Claude Sonnet en Microsoft Foundry mediante la variante Bicep del kit de inicio.
  • Configure los valores de certificación necesarios del proveedor de modelos Anthropic.
  • Configure Claude Code para usar el modelo hospedado en Foundry.
  • Llame al modelo de Claude implementado desde Python mediante Microsoft Entra ID.
  • Personalice la implementación para Terraform, más familias de modelos, otras regiones o capacidad diferente.

Importante

Al ejecutar azd up con este kit de inicio, se aceptan las condiciones de Anthropic Marketplace y se envían los valores de certificación CLAUDE_ORGANIZATION_NAME, CLAUDE_COUNTRY_CODE y CLAUDE_INDUSTRY junto con las solicitudes. Establezca valores que describen la organización real mediante el modelo. Para obtener más información, consulte Términos de uso.

Inicio rápido

Esta "ruta óptima" implementa Claude Sonnet mediante Bicep en eastus2 con una capacidad de 25 (25 000 tokens por minuto). Úselo primero para llegar a una implementación en funcionamiento y, a continuación, vaya a Personalizar la implementación si necesita Terraform, varias familias de modelos, otra región o capacidad diferente.

Necesita una suscripción de Azure que sea apta para Anthropic Claude en Microsoft Foundry, permisos para crear los recursos de destino, CLI de Azure, CLI de Azure para desarrolladores, Git y Python 3.10 o posterior. Si su cuenta puede crear asignaciones de roles, QuickStart también concede a su usuario acceso para invocar el modelo, de modo que los ejemplos puedan ejecutarse de inmediato.

Clonar, configurar e implementar

Si su suscripción válida para Claude se encuentra en un inquilino que no sea el predeterminado, agregue el Id. del inquilino a ambos comandos de inicio de sesión.

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

Reemplace Contoso, US y technology por los valores correspondientes a la organización real con Claude. Si su cuenta no puede crear asignaciones de roles, omita ASSIGN_RBAC y haga que un administrador le conceda acceso para invocar el modelo antes de ejecutar los ejemplos.

Comprobación y ejecución de Claude Code

En la raíz del repositorio, compruebe el estado de implementación y la configuración generados. El indicador skip evita una llamada en directo a Claude durante la verificación.

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

. .\claude-code.env.ps1
claude

Ejecución del ejemplo de Python

Escriba los resultados de azd en .env.local, instale las dependencias y ejecute el ejemplo de ejecución única 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

Cómo ayuda el kit de inicio

El kit de inicio automatiza la implementación de Claude mediante Bicep o Terraform. Configura la autenticación local para Microsoft Entra ID y proporciona ejemplos de trabajo de Claude Code y Python. Además, incluye comprobaciones previas para detectar problemas habituales relacionados con el mercado, la región y las cuotas, de modo que pueda resolver los obstáculos antes de proceder al aprovisionamiento. Para obtener más información, consulte Qué crea el despliegue y Personalizar el despliegue.

Prerequisites

  • Una suscripción Azure que es apta para implementar modelos de Anthropic Claude en Microsoft Foundry. La disponibilidad del modelo Claude depende del tipo de suscripción, del estado de facturación, de la región y de las regiones admitidas por Anthropic.
  • Permisos para crear y administrar los recursos de Azure de destino. Normalmente, necesita Contributor o Owner sobre la suscripción o el grupo de recursos de destino.
  • Acceso a Azure Marketplace para ofertas de modelos de asociados.
  • CLI de Azure.
  • CLI para desarrolladores de Azure.
  • Git.
  • Python 3.10 o posterior para los ejemplos de Python.
  • Terraform 1.6 o posterior si elige la variante de Terraform.

Tip

El repositorio también admite GitHub codespaces y contenedores de desarrollo de VS Code. Estos entornos incluyen las herramientas de desarrollo necesarias, por lo que son una buena opción si no desea instalar az, azdy Python localmente.

Lo que crea el despliegue

El kit de inicio crea estos recursos y archivos de configuración local:

  • Un grupo de recursos Azure para el azd entorno.
  • Una cuenta de Microsoft Foundry.
  • Un proyecto de Microsoft Foundry.
  • Una o varias implementaciones de modelos de Claude en la cuenta de Foundry.
  • Una asignación de rol opcional para la invocación del modelo.
  • Scripts de activación de Claude Code local en la raíz del repositorio.
  • Configuración del área de trabajo de Claude que ancla Claude Code a una familia de modelos implementada.
  • Configuración opcional de la extensión de VS Code al establecer CLAUDE_WRITE_VSCODE_SETTINGS=true.
  • Salidas del entorno azd, incluyendo el nombre de la cuenta de Foundry, la URL base, el punto final del proyecto y los nombres de las implementaciones.

Personalización de la implementación

Use esta sección cuando quiera variar la ruta de inicio rápido, como usar Terraform, seleccionar otra región, implementar varias familias de Claude o cambiar la capacidad. Si ya ha completado el inicio rápido, puede ir directamente a Usar Claude Code con el modelo implementado o Llamar a Claude desde Python.

Clonación del kit de inicio

Clone el kit de inicio y cambie al repositorio:

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

Si lo desea, consulte el catálogo actual de Claude antes de elegir los identificadores de los modelos. Este ayudante es solo para PowerShell en el kit de inicio.

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

El catálogo cambia con el tiempo. Use la salida del script para confirmar qué identificadores de modelo de Claude están disponibles en la región que planea implementar.

Elección de una variante de infraestructura

El kit de inicio incluye dos variantes de infraestructura equivalentes:

Variant Folder Se utiliza cuando
Bicep infra-bicep Prefiere la infraestructura como código nativa de Azure.
Terraform infra-terraform Prefiere Terraform y ya usa flujos de trabajo de Terraform.

Cambie a una de las carpetas variantes:

cd infra-bicep

O bien:

cd infra-terraform

El resto de los comandos de este artículo se ejecutan desde la carpeta variant que eligió.

Iniciar sesión en Azure

Inicie sesión con CLI de Azure y CLI de Azure para desarrolladores:

az login
azd auth login

Si su suscripción válida para Claude se encuentra en un inquilino que no sea el predeterminado, especifique el inquilino:

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

Creación de un azd entorno

Cree un azd entorno para almacenar la configuración de implementación:

azd env new my-claude

Si ya ha creado un entorno, selecciónelo en su lugar:

azd env select my-claude

Configuración de los valores de implementación necesarios

Establezca los valores de la organización usados para la atestación del proveedor de modelos de Claude:

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

Reemplace los valores de ejemplo por el nombre de entidad jurídica de la organización, el código de país de dos letras y el sector. El kit de inicio proporciona valores predeterminados para el país y el sector, pero cámbielos a menos que US y technology describan con precisión la organización que utiliza Claude.

El valor del sector debe estar en minúsculas. Los valores admitidos son:

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

Establezca la región de Azure:

azd env set AZURE_LOCATION "eastus2"

El kit de inicio admite regiones en las que están disponibles los modelos de Claude seleccionados. El inicio rápido usa eastus2. Para un despliegue común para toda la familia, eastus2 y swedencentral alojan actualmente Haiku, Sonnet y Opus. westus2 hospeda Sonnet y Opus. La disponibilidad puede cambiar, por lo que debe usar el script de catálogo activo si no está seguro de qué familias de modelos están disponibles en la región de destino.

Implementar más familias de modelos o cambiar la capacidad

Para una primera implementación sencilla, implemente solo Sonnet mediante la variable preferida por familia:

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

Para implementar varias familias de modelos en la misma cuenta de Foundry, establezca una o varias variables de familia:

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 variable de familia que no esté vacía crea un despliegue independiente. Deje una familia sin definir para omitirla. La configuración más antigua CLAUDE_MODEL_NAME es un mecanismo heredado de reserva para un solo despliegue y solo se usa cuando CLAUDE_HAIKU_MODEL, CLAUDE_SONNET_MODEL y CLAUDE_OPUS_MODEL están todos vacíos.

QuickStart establece la capacidad de Sonnet en 25. Para anular la capacidad de cualquier familia desplegada, establezca la variable de capacidad correspondiente:

azd env set CLAUDE_SONNET_CAPACITY 25

Los valores de capacidad se miden en miles de tokens por minuto. Por ejemplo, 25 solicita 25 000 TPM.

Configuración del acceso a la invocación del modelo

Para que los ejemplos de Microsoft Entra ID funcionen inmediatamente después de la implementación, establezca ASSIGN_RBAC=true antes de azd up. La plantilla asigna el rol de Cognitive Services User con el mínimo de privilegios, en la cuenta de Foundry al ID de entidad que azd proporciona a través de AZURE_PRINCIPAL_ID, por lo que, normalmente, no es necesario que busque su propio Id. de objeto.

azd env set ASSIGN_RBAC true

Establezca AZURE_PRINCIPAL_ID manualmente solo cuando necesite conceder acceso a otro usuario o entidad de servicio:

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

Si no habilita esta opción, todavía puede implementar los recursos. Sin embargo, usted o un administrador deben conceder permisos de invocación de modelo antes de que los ejemplos de Microsoft Entra ID puedan llamar al modelo.

El kit de inicio asigna Cognitive Services User porque es el rol con privilegios mínimos para la invocación de modelos sin claves. Si planea agregar características más amplias del proyecto Foundry más adelante, como agentes o evaluadores, puede conceder roles más amplios del plano de datos, como Foundry User o Azure AI Developer por separado.

Implementación con azd up

Ejecute la implementación:

azd up

El azd up comando realiza estas tareas:

  1. Ejecuta una verificación previa de la configuración requerida, la disponibilidad del catálogo del marketplace y el margen de cuota disponible.
  2. Crea el grupo de recursos Azure.
  3. Crea la cuenta y el proyecto Microsoft Foundry.
  4. Implementa las familias de modelos de Claude seleccionadas.
  5. Opcionalmente, asigna el rol para invocar el modelo.
  6. Escribe valores de salida como CLAUDE_BASE_URL, CLAUDE_DEPLOYMENT_NAMEy nombres de implementación por familia.
  7. Ejecuta el enlace posterior al aprovisionamiento para configurar archivos activadores de Claude Code.

La implementación puede tardar varios minutos. Las implementaciones de modelos también pueden continuar el aprovisionamiento después de que la operación de implementación de ARM devuelva un tiempo de espera agotado. Si esto sucede, use el script de verificación en la sección siguiente para comprobar el estado de implementación real antes de volver a ejecutar azd up.

Comprobación de la implementación

Desde la raíz del repositorio, ejecute el script de verificación:

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

Para esperar a que las implementaciones de modelo que aún se están aprovisionando finalicen, agregue el indicador de espera:

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

Para incluir una ronda completa de Claude Code en tiempo real, omita el indicador de omisión:

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

El script de verificación comprueba el activador generado, las variables de entorno esperadas, el inicio de sesión en CLI de Azure, el recurso de Foundry visible, los estados de implementación del modelo y la disponibilidad de la CLI de Claude Code.

Uso de Claude Code con el modelo implementado

Uso de la CLI de Claude Code

De forma predeterminada, el kit de inicio genera scripts de Activator para el ámbito del proyecto y la configuración del espacio de trabajo de Claude en la raíz del repositorio:

  • claude-code.env.ps1 para PowerShell.
  • claude-code.env.sh para Bash, macOS, Linux, Git Bash o WSL.
  • Configuración del área de trabajo de Claude para anclar Claude Code a una familia de modelos que implementó.
. .\claude-code.env.ps1
claude

El activador configura Claude Code para usar Microsoft Foundry y establece los nombres de implementación para las familias de modelos que implementó. Para cada familia implementada, el enlace de posaprovisionamiento escribe un valor ANTHROPIC_DEFAULT_<FAMILY>_MODEL en el activador para que Claude Code pueda dirigir a Haiku, Sonnet u Opus cuando existan esas implementaciones. La configuración del área de trabajo de Claude ancla el área de trabajo de forma predeterminada a una familia implementada, por lo que claude se resuelve en un modelo que existe en la cuenta de Foundry.

Si el comando claude no está instalado, el hook de postaprovisionamiento muestra el comando de instalación para su plataforma. Para que el kit de inicio instale Claude Code automáticamente durante el aprovisionamiento, establezca este valor antes de ejecutar azd up:

azd env set CLAUDE_CODE_AUTO_INSTALL true

Opcional: configurar la extensión de VS Code

El kit de inicio no escribe .vscode/settings.json de forma predeterminada. Si usa la extensión de VS Code de Claude Code y quiere que el kit de inicio la configure, active esta opción antes de azd up:

azd env set CLAUDE_WRITE_VSCODE_SETTINGS true

Al habilitar esta opción, el enlace de posaprovisionamiento escribe o combina claudeCode.environmentVariables y claudeCode.disableLoginPrompt en .vscode/settings.json, por lo que la extensión usa su implementación de Foundry en lugar de pedir que inicie sesión en una cuenta de Anthropic.

Llamar a Claude desde Python

El repositorio incluye ejemplos de Python en src. Úsalos para probar el acceso de tipo aplicación con el SDK de Anthropic y Microsoft Entra ID.

Desde la raíz del repositorio, vuelva a entrar en la carpeta de la variante de infraestructura y escriba la salida de azd en .env.local en la raíz del repositorio:

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

A continuación, cree un entorno virtual e instale las dependencias:

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

Ejecute el ejemplo de captura única:

python src\hello_claude.py

El ejemplo carga CLAUDE_BASE_URL y CLAUDE_DEPLOYMENT_NAME, obtiene un token de Microsoft Entra ID para https://ai.azure.com/.default, crea un cliente Anthropic con la dirección URL base de Foundry y envía una solicitud de API messages.

También puede probar las variantes de streaming y de ejecución prolongada.

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

Use el ejemplo de actualización de tokens para servicios, demonios, notebooks u otros procesos que puedan ejecutarse durante más tiempo del que dura un único token de Microsoft Entra ID.

Avanzado: prueba con una clave de API

Use Microsoft Entra ID para escenarios de desarrollo y producción normales. Para realizar pruebas locales rápidas, el repositorio también incluye un ejemplo de clave de API.

Desde la raíz del repositorio, vaya a la carpeta de la variante de infraestructura y obtenga el nombre de la cuenta de Foundry y el grupo de recursos:

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

Utiliza los valores de FOUNDRY_ACCOUNT_NAME y AZURE_RESOURCE_GROUP de la salida para establecer CLAUDE_API_KEY. A continuación, ejecute el ejemplo de clave de API desde la raíz del repositorio:

$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

Las claves de API son útiles para una comprobación rápida de conectividad, pero no proporcionan las mismas ventajas del control de acceso por usuario y del ciclo de vida de credenciales que Microsoft Entra ID.

Términos de uso

Las variantes Bicep y Terraform envían un bloque modelProviderData con cada implementación de Claude. Ese bloque incluye organizationName, countryCodey industry. El proveedor de recursos de Cognitive Services utiliza esos valores para aceptar en su nombre la oferta de Azure Marketplace para Anthropic Claude, por lo que no se requiere ninguna aceptación manual por separado durante azd up.

Antes de implementar:

  1. Revise los documentos legales que rigen Claude a través de Microsoft Foundry:
  2. Establezca los valores de atestación para describir con precisión su organización:
    • CLAUDE_ORGANIZATION_NAME: el nombre de la entidad jurídica. Este valor es obligatorio y no tiene ningún valor predeterminado.
    • CLAUDE_COUNTRY_CODE: el código de país de dos letras. El valor predeterminado del kit de inicio es US.
    • CLAUDE_INDUSTRY: el sector de la organización. El valor predeterminado del kit de inicio es technology.
  3. Confirme que la suscripción de Azure es apta para implementar modelos de Anthropic Claude en Microsoft Foundry.

Si los valores predeterminados para el país o el sector no describen con precisión la organización que usa Claude, invalide los valores antes de implementarlos.

Previsualizar el cuadro de diálogo que muestra Foundry en la ruta manual y auditar la aceptación después de azd up

El cuadro de diálogo "Aceptar y continuar" del portal de Azure para una SKU de Claude se genera a partir de los metadatos de la oferta de Marketplace activa. Dado que el texto de Marketplace puede cambiar, use la lista activa de la SKU que planea implementar en lugar de confiar en una instantánea copiada.

Después de azd up, puede auditar los metadatos del acuerdo de Marketplace aceptado mediante CLI de Azure. El comando devuelve metadatos como el estado aceptado, la firma, la fecha y el vínculo de texto de licencia. No devuelve el texto del cuadro de diálogo del portal completo.

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

Para otros SKU de Claude, reemplace el valor --product por la oferta correspondiente de Marketplace. Usa el nombre del plan de los metadatos de la oferta activa o de las validaciones del catálogo del kit de inicio.

Troubleshooting

Para consultar más casos, consulte la sección de resolución de problemas del kit de inicio.

Problema Qué probar
Bloques de requisitos de suscripción o de oferta azd up Compruebe que la suscripción y la cuenta de facturación son aptas para los modelos de Claude en Microsoft Foundry. Si su organización requiere una aceptación explícita de Marketplace, acepte la oferta correspondiente de Anthropic antes de volver a ejecutar azd up.
La región no está disponible para el modelo seleccionado Use una región en la que esté disponible la familia Claude seleccionada. El Inicio rápido usa eastus2; swedencentral también suele hospedar Haiku, Sonnet y Opus, y westus2 hospeda Sonnet y Opus. La disponibilidad puede cambiar, así que ejecute pwsh -File .\Get-ClaudeCatalog.ps1 -Latest desde la raíz del repositorio si tiene dudas.
La cuota no es suficiente o la cuota aparece llena sin implementaciones activas Reduzca el valor coincidente CLAUDE_*_CAPACITY , elimine las implementaciones sin usar o solicite un aumento de cuota. Las cuentas de Foundry o AIServices eliminadas temporalmente pueden reservar la cuota de TPM durante un máximo de 48 horas; enumerarlas con az cognitiveservices account list-deleted -o table y purgar cuentas que ya no necesite.
Terraform falla con un error poco claro 715-123420 Trate esto como un posible fallo de cuota, incluida la cuota retenida por cuentas eliminadas temporalmente. Ejecute las comprobaciones previas del kit de inicio, revise el margen disponible de cuota, reduzca la capacidad o vuelva a intentarlo con la variante de Bicep para que aparezca un mensaje InsufficientQuota más claro.
Claude Code o Python devuelve 401 o 403 Ejecute az login, confirme que ha iniciado sesión en el inquilino que es propietario del recurso Foundry y compruebe que la identidad que realiza la llamada tiene permisos para invocar modelos, como Cognitive Services User. Las asignaciones de RBAC nuevas pueden tardar unos minutos en propagarse.
GatewayTimeout aparece durante la implementación del modelo La implementación del modelo puede continuar después de que se agote el tiempo de espera de la operación de ARM. Antes de volver a ejecutar azd up, ejecute el script de comprobación con -WaitForDeployment o --wait-for-deployment para comprobar el estado de implementación real.

Limpieza de recursos

Cuando ya no necesite los recursos, elimínelos con azd down de la carpeta de variantes de infraestructura:

cd infra-bicep
azd down

O bien:

cd infra-terraform
azd down

Revise los recursos que azd planea eliminar antes de confirmarlo. Al eliminar el entorno, se elimina la cuenta de Foundry, el proyecto y las implementaciones de modelos que creó el kit de inicio.

Si está iterando en implementaciones y necesita recuperar de inmediato la cuota de TPM reservada para Claude, use la opción de purga cuando su versión de azd la admita:

azd down --purge

Sin purgar, las cuentas de Foundry o AIServices eliminadas temporalmente pueden seguir manteniendo la cuota de TPM durante un máximo de 48 horas. Si ya ha eliminado un entorno sin realizar la purga y la cuota sigue apareciendo como completa, use az cognitiveservices account list-deleted -o table para localizar las cuentas eliminadas y purgar las que ya no necesita.

Pasos siguientes

  • Last updated on