Configurar la autenticación para Agentic Retrieval en Foundry Local

Para la implementación de Agentic Retrieval, registre una aplicación, cree roles de la aplicación y asigne usuarios o grupos en Microsoft Entra ID. Este artículo forma parte de la lista de comprobación de requisitos previos para la implementación y también es un requisito previo para Inicio rápido: Instalar Agentic Retrieval. Si el entorno usa operaciones desconectadas, el registro de aplicaciones y la asignación de roles deben realizarse desde la CLI. Consulte Instalación de operaciones desconectadas en Azure Local.

Es posible que tenga que trabajar con el administrador de Microsoft Entra o en la nube para configurar la autenticación.

Importante

Recuperación de agentes en Foundry local está actualmente en VERSIÓN PRELIMINAR. Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

Prerrequisitos

Antes de comenzar, asegúrese de que tiene:

  • Una suscripción de Azure activa. Si no tiene una suscripción de servicio, cree una cuenta gratuita antes de comenzar.
  • Permisos de Microsoft Entra ID:
    • Permisos para crear una aplicación de Microsoft Enterprise Entra.
    • Capacidad de agregar usuarios y grupos nuevos o existentes de Microsoft Entra a la aplicación.

Registro de una aplicación en Microsoft Entra ID

Cree y configure el registro de una aplicación para Agentic Retrieval en su tenant de Microsoft Entra ID.

  1. En Azure Portal, vaya a Microsoft Entra ID.

  2. Vaya al inquilino adecuado y seleccione Administrar>registros de aplicaciones.

  3. Seleccione Nuevo registro para crear un registro de aplicación.

    Captura de pantalla que muestra la nueva opción de registro en la parte superior de la página de registro de la aplicación.

  4. Escriba EdgeRAG como Nombre.

  5. Seleccione Cuentas en cualquier directorio organizativo (cualquier inquilino de Microsoft Entra ID: multiinquilino).

  6. Seleccione Registrar.

    Captura de pantalla que muestra los campos de la página registrar una aplicación donde se agrega un nombre de aplicación y se seleccionan los tipos de cuenta admitidos.

  7. Una vez registrada la aplicación, vaya al registro y seleccione Administrar>autenticación.

  8. Seleccione Agregar una plataforma>Aplicación de una sola página.

  9. Especifique el nombre de dominio (por ejemplo, https://arcrag.contoso.com/) como URI de redirección.

    Captura de pantalla que muestra la página de aplicación de página única en la que se configuran direcciones URL de redireccionamiento y mucho más.

  10. Seleccione Configurar.

  11. En Tipos de cuenta compatibles, seleccione Cuentas en cualquier directorio organizativo (cualquier tenant de Microsoft Entra ID - Multitenant).

    Captura de pantalla que muestra las opciones de los tipos de cuenta admitidos con la última opción seleccionada.

  12. Seleccione + Agregar una plataforma>Aplicaciones móviles y de escritorio.

  13. En URI de redirección, seleccione https://login.microsoftonline.com/common/oauth2/nativeclient.

  14. Seleccione Configurar.

Crear roles de la aplicación para Recuperación de agentes

En el registro de aplicaciones de Recuperación de agentes, cree roles de aplicación para los desarrolladores de aplicaciones de IA y los usuarios finales del punto de conexión de chat.

  1. En el registro de aplicaciones, en el menú de la izquierda, en Administrar, seleccione Roles de aplicación.

  2. Cree dos roles de aplicación. Uno para EdgeRAGDeveloper y otro para EdgeRAGEndUser. Use los valores adecuados enumerados en la tabla que sigue a la imagen.

    Captura de pantalla que muestra los dos roles de aplicación creados para el desarrollador y el usuario.

    Campo Value
    Nombre para mostrar EdgeRAGDeveloper o EdgeRAGEndUser
    Tipos de miembros permitido Usuarios o grupos
    Value EdgeRAGDeveloper o EdgeRAGEndUser
    Description EdgeRAGDeveloper o EdgeRAGEndUser
    ¿Quiere habilitar este rol de aplicación? Comprobado

  3. Cuando haya finalizado, cierre la página Roles de la aplicación.

Asignar usuarios o grupos a roles

A continuación, en el inquilino de Microsoft Entra ID, asigne usuarios o grupos a los roles que creó para Recuperación de agentes.

  1. En el inquilino de Microsoft Entra ID, en el menú de la izquierda en Administrar, seleccione Aplicaciones empresariales.
  2. Busque y seleccione la aplicación EdgeRag que ha creado.
  3. Vaya a Administrar>Propiedades.
  4. Deshabilite Asignación requerida.
  5. En el menú de la izquierda, seleccione Usuarios y grupos>Agregar usuario o grupo.
  6. Seleccione usuarios y grupos y asigne el rol EdgeRAGDeveloper o EdgeRAGEndUser según corresponda. Asigne ambos roles a los desarrolladores que trabajan en la solución de chat.
  7. Cuando haya finalizado, cierre la página Usuarios y grupos .

Crear roles de la aplicación para el acceso a colecciones

El EdgeRAGEndUser rol por sí solo no concede acceso a las consultas. Cada usuario final también necesita un rol de aplicación cuyo valor coincida exactamente con cada nombre de colección que pueda consultar.

Comience con la colección predeterminada edgeragapp que se crea al implementar la extensión. Si no especifica una colección durante la ingesta, los datos se ingieren en edgeragapp. Después de la implementación, cree y asigne un rol de aplicación coincidente para cada colección adicional que agregue.

Cree y asigne roles de la aplicación de colección para edgeragapp y cada colección adicional antes de que los usuarios finales consulten los datos. La ingesta de datos se realiza correctamente sin estos roles, pero las consultas producen un error con 403 Forbidden.

Creación de un rol de aplicación de recopilación

  1. En el portal Azure, vaya a Microsoft Entra ID>Registros de aplicaciones y seleccione el registro de la aplicación Agentes y herramientas.

  2. En el menú de la izquierda, en Administrar, seleccione Roles de aplicación.

  3. Seleccione Crear rol de aplicación.

  4. Cree un rol de aplicación para la colección predeterminada edgeragapp o una colección que cree después de instalar la extensión. Use los valores siguientes:

    Campo Value
    Nombre para mostrar Un nombre descriptivo (por ejemplo, Colección predeterminada o Colección de documentos financieros)
    Tipos de miembros permitido Usuarios o grupos
    Value Nombre exacto de la colección. Para la colección predeterminada, use edgeragapp. Este valor debe coincidir con el nombre de la colección usado en la API.
    Description Descripción del acceso a la colección (por ejemplo, Concede acceso de consulta a la colección edgeragapp predeterminada)
    ¿Quiere habilitar este rol de aplicación? Comprobado

  5. Seleccione Aplicar.

  6. Después de la implementación, si crea recopilaciones adicionales, repita estos pasos para cada colección (por ejemplo, finance-docs).

Asignar usuarios a los roles de la aplicación de recopilación

  1. En el inquilino de Microsoft Entra ID, en el menú de la izquierda en Administrar, seleccione Aplicaciones empresariales.
  2. Busque y seleccione la aplicación EdgeRag .
  3. En el menú de la izquierda, seleccione Usuarios y grupos>Agregar usuario o grupo.
  4. Seleccione los usuarios o grupos que necesitan acceder a la colección.
  5. Seleccione el rol de aplicación de recopilación (por ejemplo, edgeragapp para la colección predeterminada).
  6. Completa la tarea.

Example

En la tabla siguiente se muestra un ejemplo de asignaciones de roles de aplicación de recopilación:

Nombre de colección Valor del rol de aplicación Usuarios asignados
edgeragapp edgeragapp Todos los usuarios finales del chat
finance-docs finance-docs Equipo de finanzas
hr-data hr-data Equipo de RR. HH.

En el momento de realizar la consulta, un usuario que consulte edgeragapp debe tener el rol de aplicación edgeragapp en su token. La misma regla se aplica a cada colección adicional (por ejemplo, finance-docs). De lo contrario, se deniega la solicitud con 403 Forbidden.

Para obtener más información sobre cómo las recopilaciones usan RBAC, consulte Colecciones y RBAC.

(Opcional) Registro de una aplicación local de Foundry

Si usa Foundry Local como punto de conexión del modelo, necesita un segundo registro de aplicación para identificar el servicio de inferencia Foundry. Este registro proporciona el valor de foundryClientId utilizado para el ámbito del token de identidad administrada (<client_id>/.default).

Registro de la aplicación Purpose Valor clave
Aplicación Agentes y herramientas (EdgeRAG) Identifica la extensión de Agentes y herramientas para la autenticación de Microsoft Entra (validación de JWT en puntos de conexión externos). auth.clientId - se transfiere a la extensión Agentes y herramientas.
Aplicación local de Foundry Identifica el servicio de inferencia de Foundry. Se utiliza como alcance de audiencia del token de identidad administrada. foundryClientId - se pasa al operador de inferencia y a la extensión Agents and Tools.

Para obtener instrucciones sobre cómo crear el registro de aplicaciones local de Foundry, consulte Configuración de la autenticación para Foundry Local.

Importante

foundryClientId y byom-api-key son mutuamente excluyentes. Cuando se establece foundryClientId, Agents and Tools usa exclusivamente la autenticación mediante token de identidad administrada. No se necesita ningún secreto de clave de API y, si existe, se omite. Cuando foundryClientId no se establece, se requiere un byom-api-key secreto de Kubernetes. Elija un método de autenticación por implementación.

Después de implementar la extensión, configure las asignaciones de roles de identidad administrada local de Foundry. Para ver los pasos, consulte Configurar la autenticación de inferencia local de Foundry para Agentic Retrieval.

(Opcional) Obtención de id. de aplicación e inquilino

Si tiene previsto usar el inicio rápido o desea implementar la recuperación agente mediante la línea de comandos, obtenga el identificador de aplicación para el registro que creó y el identificador de inquilino.

  1. En Azure Portal, busque registro de aplicaciones.
  2. Seleccione el registro de Agentic Retrieval que ha creado.
  3. Copie el identificador de aplicación (cliente) y el identificador de directorio (inquilino).
  4. Pegue los valores en una aplicación como el Bloc de notas de Windows para usarlo más adelante.

Paso siguiente

Instalación de componentes de redes y observabilidad

  • Last updated on