Traiga su propio modelo al Servicio de Agente de Foundry

Foundry Agent Service permite conectarse y usar modelos hospedados detrás de sus puertas de enlace de IA, como Azure API Management u otras puertas de enlace de modelos de IA no administradas por Azure. Esta funcionalidad, denominada trae tu propio modelo, le permite mantener el control sobre los puntos de conexión del modelo mientras usa las funcionalidades del agente Foundry.

Importante

Para los fines de esta documentación, BYOM models hace referencia a modelos de terceros que trae a Foundry y no incluye Azure Direct Models. Foundry Agent Service admite la capacidad de traer su propio modelo (BYOM). Si usted usa Foundry Agent Service para interactuar con los modelos BYOM, lo hace bajo su propio riesgo. Los modelos BYOM se consideran productos no Microsoft bajo los términos de Microsoft producto y se rigen por sus propios términos de licencia.

Si usa Foundry Agent Service para interactuar con los modelos BYOM, usted es responsable de implementar sus propias mitigaciones de IA responsables dentro de Foundry Agent Service, tales como metaprompt, filtros de contenido u otros sistemas de seguridad.

Si usa Foundry Agent Service para interactuar con los modelos BYOM, es responsable de asegurarse de que el uso del modelo BYOM cumpla con sus requisitos de manejo de datos. Usted es responsable de revisar todos los datos que se comparten con modelos BYOM y comprender las prácticas de terceros para la retención y la ubicación de los datos. Es su responsabilidad gestionar si sus datos fluirán fuera de los límites geográficos y de cumplimiento de su organización de Azure y cualesquiera implicaciones relacionadas con el uso de modelos BYOM.

Esta funcionalidad permite a las organizaciones:

  • Mantenga el control sobre los puntos finales del modelo resguardados por la infraestructura empresarial existente.
  • Integre de forma segura con gateways empresariales mediante políticas de seguridad existentes.
  • Cree agentes que usen modelos sin exponerlos públicamente.
  • Aplique los requisitos de cumplimiento y gobernanza al acceso al modelo de inteligencia artificial.

Diagrama que muestra la arquitectura del gateway de IA con flujos desde el Servicio de Agentes hasta el gateway y los modelos que están detrás.

En este artículo, creará una conexión de puerta de enlace al punto de conexión del modelo de IA, implementará un agente de solicitud que enruta las solicitudes a través de la puerta de enlace y comprobará el flujo de un extremo a otro.

Requisitos previos

  • Una suscripción Azure. Cree uno gratis.
  • Un proyecto Microsoft Foundry.
  • Acceda a las credenciales de la puerta de enlace de IA empresarial, como una clave de suscripción de API Management, una clave de API para otra puerta de enlace de modelos de IA que no sea de Azure o las credenciales de un proveedor de OAuth 2.0 mediante credenciales de cliente.
  • Para administrar conexiones a través de la línea de comandos:

Permisos necesarios

Necesita las siguientes asignaciones de roles:

Recurso Rol necesario
Proyecto de fundición Usuario de Azure AI o superior
Grupo de recursos (para la implementación de conexiones) Colaborador

Cree una conexión de modelo

Usa el portal de Foundry para crear una conexión a tu modelo.

Puede elegir modelos detrás de un recurso de Azure API Management existente o una puerta de enlace de modelos de IA que no sea de Azure. Mediante estos pasos, puede agregar varios modelos que implementan la API de finalizaciones de chat de OpenAI.

Para agregar una conexión de modelo en el portal de Foundry:

  1. Inicie sesión en Microsoft Foundry.

  2. Seleccione Operar>Consola de Administración.

  3. Abra la pestaña Todos los proyectos .

  4. En la lista de proyectos, busque el proyecto y seleccione el vínculo en la columna Recurso primario .

  5. Seleccione la pestaña Modelos conectados al administrador y, a continuación, seleccione Agregar. Captura de pantalla de modelos externos en el portal de Foundry.

    Se abre el Asistente para agregar conexión de modelo .

  6. En la página Connection Type, seleccione Azure API Management y, a continuación, seleccione un nombre de recurso y una implementación de modelos de API Management existentes. El modelo debe implementar la API de finalizaciones de chat compatibles con OpenAI.

    Captura de pantalla de la selección de un recurso de API Management en el portal de Foundry.

  7. En la página Autenticación , seleccione una opción para autenticarse en API Management.

    Seleccione una clave de API, como una clave de suscripción de API Management, o identidad administrada si se configura en el proyecto Foundry.

    • Clave de API: escriba el valor de clave en el campo proporcionado. Opcionalmente, especifique un nombre de encabezado de clave de API que se usará al pasar la clave de API si la puerta de enlace requiere un encabezado personalizado.

    • Identidad administrada: en Audiencia, escriba el servicio de destino para el token de identidad administrada, como https://cognitiveservices.azure.com/. Para obtener la configuración necesaria de API Management, consulte Configuración de la autenticación de identidad administrada para API Management.

  8. En la página Configuración del modelo, configure al menos una implementación de modelos que aparecerá en Foundry para su uso con agentes.

    1. Seleccione + Agregar modelo.
    2. Escriba un nombre de implementación (usado en llamadas API) y el nombre correspondiente y nombre para mostrar.
    3. Guarde la configuración del modelo.

    Repita los pasos anteriores para agregar más modelos a la conexión si es necesario.

  9. En la página Opciones avanzadas , siga estos pasos:

    1. Escriba una versión de API si es necesaria para las implementaciones del modelo.
    2. Inhabilite la configuración Incluir nombre de implementación en la ruta de acceso de la URL si su puerta de enlace expone la API de finalización de chat en una ruta al estilo de Azure OpenAI que incluye el nombre de la implementación (por ejemplo, /deployments/{deploymentName}/chat/completions). Deje la configuración deshabilitada si la puerta de enlace usa una ruta de acceso de estilo OpenAI sin el nombre de implementación (por ejemplo, /chat/completions) y se basa en otros mecanismos de enrutamiento para dirigir las solicitudes a la implementación correcta del modelo.
    3. Seleccione + Agregar encabezado para agregar un encabezado estático que se debe incluir en las solicitudes a la puerta de enlace. Repita esta operación para agregar varios encabezados si es necesario.

  10. Seleccione Agregar.

Configuración de la autenticación de identidad administrada para API Management

Para configurar la autenticación Managed Identity en API Management, complete la siguiente configuración en Azure:

  1. Habilite la identidad administrada en el recurso del proyecto Foundry.

    1. En el portal Azure, vaya al recurso Foundry.

    2. Vaya a Proyectos> seleccione > del proyecto.

    3. Habilite cualquiera de las siguientes opciones:

      • Identidad administrada asignada por el sistema o
      • Identidad administrada asignada por el usuario .

    4. Para la validación de tokens en API Management, obtenga el identificador de aplicación (cliente) de la identidad administrada.

      1. En primer lugar, obtenga el ID de la identidad administrada a partir de la configuración correspondiente en su proyecto.
      2. Busque ese identificador de objeto en Microsoft Entra ID aplicaciones empresariales para buscar el identificador de aplicación (cliente) correspondiente.

  2. Valide el token de identidad administrada en API Management.

    En la directiva de entrada de API Management, use la directiva validate-azure-ad-token para validar los tokens de las solicitudes de Microsoft Foundry.

    • Establezca el elemento audience al mismo valor que configuró en el campo de conexión Audiencia de Foundry.
    • Configure el identificador de la aplicación de identidad administrada en client-application-ids.

    Ejemplo:

    <validate-azure-ad-token tenant-id="{{your-tenant-id}}" header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized">
   <client-application-ids>
      <application-id>{{managed-identity-client-id}}</application-id>
   </client-application-ids>
   <audiences>
      <audience>{{audience-configured-in-foundry-connection}}</audience>
   </audiences>
</validate-azure-ad-token>

La conexión se crea y aparece en la lista de la pestaña Modelos conectados al administrador .

Implementaciones de modelos conectados al administrador

Foundry implementa automáticamente los modelos que agrega a través de una conexión, por lo que puede usarlos en los proyectos.

  • Cada modelo que agregue en el Asistente para conexiones corresponde a una implementación en Foundry.

  • Puede seleccionar una implementación conectada al administrador al configurar el modelo de un agente. Foundry enruta automáticamente las solicitudes de los agentes a estas implementaciones a través de la puerta de enlace conectada.

Cree una conexión de modelo

Usa CLI de Azure para crear una conexión con los modelos detrás de tu puerta de enlace de IA.

El servicio de agente admite dos tipos de conexión: conexiones API Management y conexiones Model Gateway.

Elija el tipo de conexión que coincida con la puerta de enlace:

Tipo de conexión Usar cuando Valor de categoría
API Management Ya utiliza Azure API Management para el enrutamiento de modelos y desea configuraciones predeterminadas inteligentes para el API Management. ApiManagement
Puerta de enlace de modelos Usas OpenAI, MuleSoft o un gateway personalizado y necesitas descubrimiento de modelos estáticos o dinámicos. ModelGateway

Para obtener especificaciones de conexión detalladas, consulte los ejemplos de conexión connection en GitHub.

Implementación de la conexión

  1. Descargue o clone el repositorio de ejemplos Foundry y localice la plantilla de Bicep para su tipo de conexión en el directorio indicado por infrastructure/infrastructure-setup-bicep/01-connections/. El directorio contiene archivos Bicep independientes y archivos de parámetros para las conexiones API Management y Model Gateway.

  2. Implemente la conexión ejecutando az deployment group create con el grupo de recursos, el archivo de plantilla de Bicep y el archivo de parámetros correspondiente. Reemplace los valores de marcador de posición en el archivo de parámetros por la dirección URL del punto de conexión de puerta de enlace y las credenciales antes de la implementación. Para obtener la referencia de comandos completa, consulte az deployment group create.

    Propina

    Una implementación correcta devuelve provisioningState: Succeeded en la salida del comando.

  3. Compruebe la conexión en el portal de Foundry. Vaya al portal de Foundry y seleccione el proyecto. Vaya a Recursos conectados en la configuración del proyecto. La nueva conexión aparece con un estado Activo y la dirección URL del punto final de la puerta de enlace que usted especificó.

Crear un agente de comandos con la conexión del modelo

Después de crear la conexión, cree y ejecute un agente de solicitud de instrucciones que use modelos ubicados detrás de su pasarela. La diferencia clave de un agente estándar es el formato de nombre de implementación del modelo: <connection-name>/<model-name>.

  1. Establezca las siguientes variables de entorno:

    Variable Valor Ejemplo
    FOUNDRY_PROJECT_ENDPOINT Dirección URL del punto de conexión del proyecto https://<your-ai-services-account>.services.ai.azure.com/api/projects/<project-name>
    FOUNDRY_MODEL_DEPLOYMENT_NAME <connection-name>/<model-name> my-apim-connection/gpt-4o

  2. Inicialice un AIProjectClient con el punto de conexión y DefaultAzureCredential, a continuación, llame a agents.create_version() con un PromptAgentDefinition. Establezca el parámetro model al valor FOUNDRY_MODEL_DEPLOYMENT_NAME.

    Una llamada correcta devuelve un objeto de agente con sus idcampos , namey version rellenados.

  3. Obtenga el cliente de OpenAI con project.get_openai_client(), cree una conversación con conversations.create()y envíe una solicitud con responses.create(). Pase la referencia del agente en extra_body como {"agent_reference": {"name": agent.name, "type": "agent_reference"}}.

    Una respuesta exitosa devuelve el texto de respuesta del modelo, lo que confirma que el agente está siendo enrutado a través de tu puerta de enlace.

    Nota

    Si se produce un model not found error en la respuesta, compruebe que el FOUNDRY_MODEL_DEPLOYMENT_NAME valor usa el formato <connection-name>/<model-name>.

  4. Elimine la conversación y la versión del agente una vez que se completen las pruebas.

Para obtener un ejemplo de trabajo completo, consulte los ejemplos del SDK de agent en GitHub. Para obtener más información sobre la API, consulte AIProjectClient y PromptAgentDefinition.

Comprobación de la implementación

Después de desplegar su agente, confirme que la canalización completa funciona correctamente:

  1. Comprobar el estado de conexión : en el portal de Foundry, vaya a Recursos conectados en la configuración del proyecto. Compruebe que la conexión muestra un estado Activo . Si el estado es Inactivo, compruebe la dirección URL y las credenciales del punto de conexión de la puerta de enlace.

  2. Enviar un mensaje de prueba : use el SDK para crear una conversación y enviar una solicitud como se describe en la sección anterior. Una respuesta correcta devuelve el texto de respuesta del modelo, lo que confirma que el agente puede llegar al modelo a través de la puerta de enlace.

  3. Revisión de los registros de puerta de enlace : confirme que las solicitudes se enrutan correctamente. Para API Management, compruebe API Management analytics en el portal de Azure. Para otras puertas de enlace, revise el registro de solicitudes de la puerta de enlace. Debería ver las solicitudes recibidas desde el endpoint del servicio de agentes.

Propina

Si se produce algún error en algún paso, consulte la sección Solución de problemas comunes para conocer los pasos de resolución.

Detalles del tipo de conexión

En esta sección se proporcionan detalles de referencia sobre cada tipo de conexión y sus opciones de configuración.

Conexión de gestión de API

Las conexiones de API Management proporcionan valores predeterminados inteligentes y siguen las convenciones estándar de API Management:

Configuración Valor predeterminado
Enumeración del punto de conexión de implementaciones /deployments
Obtener el punto de conexión de implementación /deployments/{deploymentName}
Proveedor AzureOpenAI

Prioridad de configuración:

  1. Valores de metadatos explícitos (prioridad más alta).
  2. Valores predeterminados estándar de API Management (alternativa).

Métodos de autenticación:

  • Clave de API : autenticación de clave de suscripción estándar.
  • Microsoft Entra ID: integración de identidades empresariales.

Conexión de modelos de puerta de enlace

Las conexiones de puerta de enlace de modelos proporcionan una interfaz unificada para conectarse a varios proveedores de modelos de IA. Estas conexiones admiten la detección de modelos estáticos y dinámicos:

  • Detección estática : los modelos están predefinidos en los metadatos de conexión. Ideal para implementaciones fijas y listas de modelos aprobados por la empresa.
  • Detección dinámica : los modelos se detectan en tiempo de ejecución mediante puntos de conexión de API. Lo mejor para cambiar con frecuencia las implementaciones y los catálogos administrados por el proveedor.

Los tipos de autenticación admitidos son clave de API y OAuth 2.0. Las claves de API se almacenan de forma segura y se hace referencia a ellas a través del sistema de credenciales.

Solución de problemas comunes

Problema Resolución
La conexión muestra el estado inactivo Compruebe que la dirección URL del punto de conexión de puerta de enlace es accesible y que las credenciales de autenticación son válidas.
El agente devuelve model not found un error Confirme que el FOUNDRY_MODEL_DEPLOYMENT_NAME valor usa el formato correcto: <connection-name>/<model-name>.
Errores de tiempo de espera de la puerta de enlace Compruebe que los puntos de conexión de puerta de enlace son accesibles desde la red del servicio del agente. Para las redes privadas, consulte la guía de aislamiento de red en la sección Limitaciones.
Errores de autenticación En API Management, compruebe la clave de suscripción. En Model Gateway, compruebe la clave de API o la configuración de OAuth 2.0.

Configuraciones admitidas

  • Solo los agentes de aviso en el SDK de agentes admiten esta función.
  • Herramientas de agente compatibles: Intérprete de código, Funciones, Búsqueda de archivos, OpenAPI, Foundry IQ, SharePoint grounding, Fabric Agente de datos, MCP y Automatización del explorador.
  • Configuraciones de red admitidas:
    • Se admite la conectividad pública tanto para API Management como para gateways autohospedadas.
    • Para el aislamiento de red completo:
      • API Management como tu puerta de enlace AI: Implementa Foundry y API Management juntos utilizando esta plantilla de GitHub.
      • Pasarela autohospedada: asegúrese de que los puntos de conexión de la pasarela sean accesibles dentro de la red virtual utilizada por el Servicio del Agente.

Contenido relacionado

  • Last updated on