Inicio rápido: Configuración de recursos de Microsoft Foundry

En este inicio rápido, creará un proyecto Microsoft Foundry e implementará un modelo. Si está gestionando un equipo, también concede acceso a los miembros del equipo. Después de completar estos pasos, usted o el equipo pueden empezar a compilar aplicaciones de inteligencia artificial mediante el modelo implementado.

Para el desarrollo del agente, conecte también Azure Monitor Application Insights para almacenar seguimientos del agente.

Sugerencia

En este inicio rápido se muestra cómo crear recursos para compilar un agente con una configuración básica. Para ver escenarios más avanzados que usan sus propios recursos, consulte Configuración del entorno para el desarrollo del agente.

Requisitos previos

  • Una cuenta de Azure con una suscripción activa. Si no tiene una, cree una cuenta de free Azure, que incluye una suscripción de evaluación gratuita.
  • Si va a crear el proyecto por sí mismo:
    • Acceso a un rol que le permite crear un recurso foundry, como el propietario de la cuenta de Foundry o el propietario de Foundry en la suscripción o el grupo de recursos. Para obtener más información sobre los permisos, consulte Control de acceso basado en roles para Microsoft Foundry.

      Importante

      Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

  • Si va a crear el proyecto para un equipo:
    • Acceso a una función que le permite completar las asignaciones de funciones, como por ejemplo Propietario. Para obtener más información sobre los permisos, consulte Control de acceso basado en roles para Microsoft Foundry.
    • Una lista de direcciones de correo electrónico de usuario, o identificadores de grupo de seguridad de Microsoft Entra, para los miembros del equipo que necesitan acceso.
  • Para ver los seguimientos del agente: acceso de lectura al recurso de Application Insights conectado, como Log Analytics Reader. Un administrador puede conceder este acceso. Consulte Conceder acceso a los rastros para conocer los requisitos de las tablas protegidas y el espacio de trabajo.
  • Para asignar roles de lector de rastros: permiso Microsoft.Authorization/roleAssignments/write en el ámbito de destino. Contributor por sí solo no concede este permiso. Si no puede asignar roles, pida a un administrador que asigne el acceso necesario.

Si usa el CLI de Azure en lugar del portal, el rol Colaborador o Propietario del grupo de recursos es suficiente para crear el recurso y el proyecto. Aún necesitas un rol que pueda asignar roles, como Owner, para conceder acceso a los miembros del equipo.

Seleccione el método preferido mediante las siguientes pestañas:

  • Instale el CLI de Azure versión 2.80.0 o posterior. Compruebe la versión con az versiony ejecute az upgrade si necesita una más reciente.

    La versión 2.80.0 agregó los az cognitiveservices account project comandos que usan estos pasos. En una versión anterior, los comandos producen un error con unrecognized arguments o 'project' is misspelled or not recognized by the system.

  • Inicie sesión en Azure:

    az login

Creación de un proyecto

Cree un proyecto de Foundry para organizar el trabajo. El proyecto contiene modelos, agentes y otros recursos que usa el equipo.

Sugerencia

Cree el proyecto en la región Oeste de EE. UU. 3 si desea probar un modelo instantáneo (versión preliminar).

Note

Estos pasos requieren el CLI de Azure versión 2.80.0 o posterior y el rol Colaborador o Propietario en el grupo de recursos. Ejecute az version para comprobar la versión y az upgrade si necesita una más reciente. Ejecute az login para iniciar sesión antes de empezar. Para consultar las regiones admitidas, consulte Compatibilidad regional.

  1. Cree un grupo de recursos o use uno existente. Por ejemplo, cree my-foundry-rg en eastus:

    az group create --name my-foundry-rg --location eastus

    Compruebe que el grupo de recursos existe:

    az group show --name my-foundry-rg --query properties.provisioningState --output tsv

    La salida muestra Succeeded.

  2. Cree el recurso Foundry con la administración de proyectos habilitada. Por ejemplo, cree my-foundry-resource en el my-foundry-rg grupo de recursos:

    az cognitiveservices account create \
    --name my-foundry-resource \
    --resource-group my-foundry-rg \
    --kind AIServices \
    --sku S0 \
    --location eastus \
    --custom-domain my-foundry-resource \
    --assign-identity \
    --allow-project-management true

    Use estos valores:

    Parameter propósito
    --assign-identity Crea la identidad administrada que requiere la administración del proyecto. Sin ella, la creación del proyecto falla con un error que indica que debe habilitarse una identidad administrada en el recurso.
    --allow-project-management Habilita la administración de proyectos. No puede cambiar esta configuración después de crear el recurso.
    --custom-domain Debe ser único globalmente. Si se establece my-foundry-resource, el comando falla con CustomDomainInUse. Elija otro nombre y vuelva a ejecutar el comando.

  3. Cree un proyecto. Por ejemplo, cree my-foundry-project en :my-foundry-resource

    az cognitiveservices account project create \
    --name my-foundry-resource \
    --resource-group my-foundry-rg \
    --project-name my-foundry-project \
    --location eastus

  4. Compruebe que el recurso está aprovisionado:

    az cognitiveservices account show \
    --name my-foundry-resource \
    --resource-group my-foundry-rg \
    --query properties.provisioningState --output tsv

    La salida debe mostrar Succeeded. Si la salida muestra un estado diferente, compruebe los permisos, la disponibilidad de regiones y las cuotas de recursos. Para obtener más ayuda, consulte Creación de un recurso de varios servicios.

  5. Compruebe que se creó el proyecto:

    az cognitiveservices account project show \
    --name my-foundry-resource \
    --resource-group my-foundry-rg \
    --project-name my-foundry-project \
    --query properties.provisioningState --output tsv

    La salida debe mostrar Succeeded. Si se produce un error en el comando con un mensaje que indica que se debe habilitar una identidad administrada, confirme que creó el recurso con --assign-identity.

Referencia: az cognitiveservices account project

Conexión de Application Insights para el seguimiento de agentes

Antes de ejecutar un inicio rápido del agente, complete esta configuración en el portal de Foundry.

Revise la seguridad y la privacidad del seguimiento y la retención de datos y el costo antes de habilitar el seguimiento.

Siga Conectar Application Insights a su proyecto de Foundry. Compruebe y reutilice una conexión existente.

Note

Si la conexión existente usa Project Managed Identity o la organización requiere la ingesta solo con Entra, mantenga la configuración aprobada. Consulte Configurar la autenticación de Microsoft Entra para la ingesta de seguimiento.

En el caso de los agentes hospedados en Foundry, la conexión habilita el seguimiento del lado servidor. Para los agentes que se ejecutan en su propia aplicación, configure también el seguimiento del lado cliente.

Conceder acceso a los rastros

La persona o el grupo que visualiza las trazas necesita Log Analytics Reader en el recurso de Application Insights conectado o acceso heredado equivalente. Para las tablas de seguimiento protegidas, conceda también Privileged Monitoring Data Reader.

Consulte Requisitos previos de seguimiento y Asignación de roles de Azure mediante el portal de Azure para obtener instrucciones detalladas.

Para las consultas con ámbito de área de trabajo o áreas de trabajo que requieren permisos de área de trabajo, consulte Administración del acceso a las áreas de trabajo de Log Analytics.

Verificar el primer rastro del agente

Continúe con la implementación del modelo o el inicio rápido del agente. Tras la primera solicitud del agente, siga Verificar que el rastreo funciona para confirmar que aparece un nuevo rastro. Una respuesta correcta por sí sola no confirma que se almacenaron las trazas.

Si no aparece ningún seguimiento, consulte Solución de problemas de seguimiento.

Implementación de un modelo

Implemente un modelo que pueda usar. En este ejemplo se usa gpt-5-mini, pero puede elegir cualquier modelo disponible.

Sugerencia

Para probar un modelo de acceso instantáneo (versión preliminar), puede omitir este paso.

  1. Enumere los modelos disponibles en su región para que pueda confirmar el nombre y la versión del modelo:

    az cognitiveservices model list \
    --location eastus \
    --query "[?model.name=='gpt-5-mini'].{version:model.version,skus:join(',',model.skus[].name)}" \
    --output table

  2. Implemente el modelo:

    az cognitiveservices account deployment create \
    --name my-foundry-resource \
    --resource-group my-foundry-rg \
    --deployment-name gpt-5-mini \
    --model-name gpt-5-mini \
    --model-version "2025-08-07" \
    --model-format OpenAI \
    --sku-capacity 10 \
    --sku-name GlobalStandard

    Si se produce un error en el comando con DeploymentModelNotSupported, el modelo, la versión o la SKU no están disponibles en la región. Use la salida del paso anterior para elegir una combinación admitida.

  3. Compruebe que la implementación se ha realizado correctamente:

    az cognitiveservices account deployment show \
    --name my-foundry-resource \
    --resource-group my-foundry-rg \
    --deployment-name gpt-5-mini \
    --query properties.provisioningState --output tsv

    La salida muestra Succeeded cuándo está lista la implementación.

Referencia: az cognitiveservices account deployment

Obtención de los detalles de conexión del proyecto

Para conectarte a través del código, necesitas el punto de conexión del proyecto. Si administra este proyecto para otros usuarios, envíeles este endpoint junto con el nombre de implementación.

Obtenga el endpoint del proyecto:

az cognitiveservices account project show \
    --name my-foundry-resource \
    --resource-group my-foundry-rg \
    --project-name my-foundry-project \
    --query 'properties.endpoints."AI Foundry API"' --output tsv

El resultado es el punto de conexión del proyecto, con la forma https://my-foundry-resource.services.ai.azure.com/api/projects/my-foundry-project. Use este valor en otros inicios rápidos y tutoriales.

Para administradores: concesión de acceso

Si administra un equipo, asigne el rol Usuario de Foundry a los miembros del equipo para que puedan usar el proyecto y los modelos implementados. Este rol proporciona los permisos mínimos necesarios para compilar y probar aplicaciones de IA. Para otros roles que pueda necesitar asignar, consulte Control de acceso basado en roles para Microsoft Foundry.

  1. Obtenga el identificador de recurso del proyecto:

    PROJECT_ID=$(az cognitiveservices account project show \
    --name my-foundry-resource \
    --resource-group my-foundry-rg \
    --project-name my-foundry-project \
    --query id -o tsv)

  2. Asigne el rol Usuario de Foundry a un miembro del equipo:

    Importante

    Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

    az role assignment create \
    --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
    --assignee "user@contoso.com" \
    --assignee-principal-type User \
    --scope $PROJECT_ID

Note

Dado que los roles de RBAC de Foundry se cambiaron recientemente de nombre, use el identificador de definición de rol (GUID) en lugar del nombre del rol en el código para evitar problemas durante la implementación del cambio de nombre:

  • Usuario de Foundry: 53ca6127-db72-4b80-b1b0-d745d6d5456d
  • Propietario de la fundición: c883944f-8b7b-4483-af10-35834be79c4a
  • Propietario de la cuenta de Foundry: e47c6f54-e4a2-4754-9501-8e0985b135e1
  • Administrador de proyectos de Foundry: eadc314b-1a2d-4efa-be10-5d325db5065e

Para agregar un grupo de seguridad en lugar de un usuario individual:

az role assignment create \
    --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
    --assignee-object-id "<security-group-object-id>" \
    --assignee-principal-type Group \
    --scope $PROJECT_ID

  1. Compruebe la asignación de roles:

    az role assignment list \
    --scope $PROJECT_ID \
    --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
    --output table

Referencia: az role assignment

Comprobación del acceso de los miembros del equipo

Pida a un miembro del equipo que compruebe su acceso iniciando sesión en Microsoft Foundry y seleccionando el proyecto en la lista de proyectos.

Si el miembro del equipo no puede acceder al proyecto, compruebe que la asignación de roles se completó correctamente. Compruebe que ha usado la dirección de correo electrónico correcta o el identificador del grupo de seguridad. Asegúrese de que la cuenta de Azure del miembro del equipo esté en el mismo inquilino Microsoft Entra.

Para confirmar que el modelo implementado está disponible, pida al miembro del equipo que seleccione Compilar en el panel superior derecho y, a continuación, Modelos en el panel izquierdo.

Limpieza de recursos

Cuando ya no desee este proyecto, elimine el grupo de recursos para eliminar todos los recursos asociados a él.

az group delete --name my-foundry-rg --yes --no-wait

La eliminación se ejecuta en segundo plano. Para confirmar que el grupo de recursos ha desaparecido, ejecute:

az group exists --name my-foundry-rg

La salida muestra false cuándo finaliza la eliminación.

Paso siguiente

Inicio rápido de Microsoft Foundry

  • Se actualizó por última vez el