Infraestructura de agente hospedada con la CLI para desarrolladores de Azure

Importante

Los elementos marcados como versión preliminar en este artículo se encuentran actualmente en versión preliminar. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y Microsoft no lo recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

La CLI para desarrolladores de Azure (azd) puede generar Bicep o infraestructura de Terraform a partir de los servicios declarados en azure.yaml. Elija Terraform con azd ai agent init --infra=terraform, o Bicep con --infra=bicep. La ejecución azd provision aplica la infraestructura seleccionada.

El aprovisionamiento de infraestructura y la implementación del agente son independientes. Terraform o Bicep administra los recursos auxiliares de Azure; azd deploy crea la versión del plano de datos del agente alojado. Para administrar el propio agente con Terraform en lugar de azd, consulte Implementación de un agente hospedado con Terraform.

Qué se suministra

De forma predeterminada, azd ai agent init no crea archivos de infraestructura como código. Utiliza --infra o --infra=bicep para añadir infraestructura de Bicep. Use --infra=terraform para agregar la infraestructura de Terraform y establecer infra.provider: terraform.

Al agregar infraestructura de Bicep, las plantillas se basan en el repositorio azd-ai-starter-basic y crean los siguientes recursos de Azure:

Resource propósito
Grupo de recursos Organiza todos los recursos. Con el nombre rg-<agent-name>
Cuenta de AI Services La cuenta de Microsoft Foundry.
Proyecto de fundición Hospeda las funcionalidades del agente y la inteligencia artificial.
Implementaciones de modelos Los modelos que usa el agente, por ejemplo gpt-4.1-mini.
Azure Container Registry (Registro de Contenedores de Azure) Almacena las imágenes de contenedor del agente.
Application Insights Supervisión y telemetría del rendimiento del agente.
Área de trabajo de Log Analytics Recopilación centralizada de registros.
Identidad administrada La identidad asignada por el sistema al proyecto que autentica el modelo de identidad del agente en Microsoft Entra ID y contiene las asignaciones de roles de la plataforma.

Las plantillas crean más recursos condicionalmente, en función de los servicios y dependencias declarados en azure.yaml:

  • Configuración de la funcionalidad del agente: declare los recursos de Azure que contienen el estado del agente, los datos vectoriales y los archivos. Establézcalos cuando necesite que los agentes usen el almacenamiento que posee.
  • Grounding with Bing o Grounding with Bing Custom Search: para la herramienta de búsqueda web.
  • Búsqueda de Azure AI -- para fundamentar la búsqueda.
  • Azure Storage: para las operaciones de archivo.

Estructura del proyecto

Para Bicep, un proyecto generado tiene la siguiente estructura:

infra/
|-- main.bicep                 # Main deployment template (subscription-scoped)
|-- main.parameters.json       # Parameter bindings to azd environment variables
|-- abbreviations.json         # Naming convention abbreviations
\-- core/
    |-- ai/                    # Foundry account, project, and connections
    |-- host/                  # Container registry
    |-- monitor/               # Application Insights and Log Analytics
    |-- search/                # Azure AI Search (conditional)
    \-- storage/               # Azure Storage (conditional)

Cómo fluyen los parámetros

Para Bicep, el main.parameters.json archivo asigna azd variables de entorno a parámetros:

{
  "environmentName": { "value": "${AZURE_ENV_NAME}" },
  "location": { "value": "${AZURE_LOCATION}" },
  "aiFoundryResourceName": { "value": "${AZURE_AI_ACCOUNT_NAME}" },
  "aiProjectDeploymentsJson": { "value": "${AI_PROJECT_DEPLOYMENTS=[]}" }
}

Durante azd provision, azd resuelve estas ${VAR} referencias del entorno (.azure/<env>/.env) y las pasa a la implementación de Bicep. Los resultados de la implementación, como el punto de conexión del proyecto de Foundry, el nombre de la implementación del modelo y el punto de conexión del Container Registry, se vuelven a escribir en el entorno para que los utilicen azd deploy, azd ai agent run y los comandos de recursos azd ai.

Infraestructura de Terraform

Para un nuevo proyecto, azd ai agent init --infra=terraform genera archivos como los siguientes:

infra/
|-- main.tf
|-- provider.tf
|-- variables.tf
|-- outputs.tf
|-- main.tfvars.json
\-- .azd-foundry

Los servicios basados en contenedores también pueden generar container-registry.tf. Los proyectos existentes pueden conservar su infraestructura y recibir una capa independiente de Foundry bajo infra/foundry/. Use el diseño generado real en lugar de mover archivos entre capas.

La configuración de Terraform aprovisiona la cuenta de Foundry, el proyecto, las implementaciones de modelos y los recursos relacionados necesarios para los servicios seleccionados. La creación del registro de contenedores depende del modo de implementación y de la configuración de la imagen.

main.tfvars.json enlaza las entradas de infraestructura a los valores de entorno azd. outputs.tf expone valores como el punto de conexión del proyecto Foundry para azd tras el aprovisionamiento. Estos enlaces forman parte del flujo de trabajo azd; no suponga que un archivo de parámetros generado funciona sin cambios con un independiente terraform apply.

Para personalizar la infraestructura de Terraform, edite los archivos generados .tf , conserve las salidas necesarias para los servicios del agente y ejecute azd provision. Revise el plan de Terraform antes de aplicar los cambios de infraestructura.

Estado de Terraform y CI/CD

Los archivos generados no arrancan un back-end de estado remoto. Para los despliegues en equipo, configure el estado respaldado por Azure Storage, claves de estado independientes para cada entorno y los permisos de backend necesarios antes de configurar CI/CD.

Consulte Configurar CI/CD con Terraform para el flujo de implementación y Usar Terraform con azd para la configuración de backend.

Limitaciones de la expulsión de Terraform

La ruta de expulsión de Terraform no admite la configuración del servicio network: en la extensión actual de agentes de Foundry. Revise las restricciones de recursos existentes antes de expulsar un proyecto que ya tiene infraestructura. Ejection no es una migración general del estado de Bicep a Terraform, y eliminar recursos de producción no es un requisito previo para adoptar Terraform.

Recursos existentes

Las plantillas de Bicep admiten la conexión a los recursos de Azure existentes en lugar de crear nuevos. Esto resulta útil cuando el equipo ya tiene infraestructura compartida.

Recurso existente Variables de entorno que se van a establecer
Cuenta de AI Services AZURE_AI_ACCOUNT_NAME
Container Registry AZURE_CONTAINER_REGISTRY_RESOURCE_ID y AZURE_CONTAINER_REGISTRY_ENDPOINT
Application Insights APPLICATIONINSIGHTS_CONNECTION_STRING y APPLICATIONINSIGHTS_RESOURCE_ID

Establezca estas variables con azd env set antes de ejecutar azd provision.

Personalización de la infraestructura

El infra/ directorio es la infraestructura estándar azd . Para añadir o cambiar recursos de Bicep:

  1. Edite infra/main.bicep o agregue nuevos módulos en infra/core/.
  2. Añade nuevos parámetros a main.parameters.json con enlaces ${VAR}.
  3. Establezca las variables de entorno correspondientes azd con azd env set.
  4. Ejecute azd provision para aplicar los cambios.

Los cambios en los archivos de Bicep persisten entre implementaciones.

Restricciones de región

La plantilla main.bicep restringe location a las regiones en las que se admiten agentes hospedados. Si necesita implementar en una región que no esté en la lista de regiones permitidas, actualice el decorador @allowed en main.bicep.

Contenido relacionado

  • Last updated on