Introducción a la seguridad de documentos de chat para Python

Al compilar una aplicación de chat mediante el patrón RAG con sus propios datos, asegúrese de que cada usuario recibe una respuesta en función de sus permisos. Siga el proceso de este artículo para agregar el control de acceso de documentos a la aplicación de chat.

Un usuario autorizado debe tener acceso a las respuestas contenidas en los documentos de la aplicación de chat.

Un usuario no autorizado no debe tener acceso a las respuestas de documentos protegidos que no tienen autorización para ver.

Nota:

En este artículo se usan una o varias plantillas de aplicaciones de IA como base para los ejemplos e instrucciones del artículo. Las plantillas de aplicaciones de IA le proporcionan implementaciones de referencia bien mantenidas y fáciles de implementar que le ayudan a garantizar un punto inicial de alta calidad para sus aplicaciones de IA.

Introducción a la arquitectura

Sin la característica de seguridad de documentos, la aplicación de chat empresarial tiene una arquitectura sencilla mediante Azure AI Search y Azure OpenAI. Una respuesta se determina a partir de consultas a Azure AI Search donde se almacenan los documentos, en combinación con una respuesta de un modelo GPT de Azure OpenAI. No se usa ninguna autenticación de usuario en este flujo sencillo.

Para agregar seguridad a los documentos, debe actualizar la aplicación de chat empresarial:

• Agregue la autenticación de cliente a la aplicación de chat con Microsoft Entra.
• Agregue lógica del lado servidor para rellenar un índice de búsqueda con acceso de usuario y grupo.

Azure AI Search no proporciona permisos nativos de nivel de documento y no puede variar los resultados de búsqueda desde dentro de un índice por permisos de usuario. En su lugar, la aplicación puede usar filtros de búsqueda para asegurarse de que un documento es accesible para un usuario específico o para un grupo específico. Dentro del índice de búsqueda, cada documento debe tener un campo filtrable que almacene información de identidad de usuario o grupo.

Dado que la autorización no está contenida de forma nativa en Azure AI Search, debe agregar un campo para contener información de usuario o grupo y, a continuación , filtrar los documentos que no coincidan. Para implementar esta técnica, debe:

• Cree un campo de control de acceso a documentos en el índice dedicado a almacenar los detalles de los usuarios o grupos con acceso a documentos.
• Rellene el campo de control de acceso del documento con los detalles de usuario o grupo pertinentes.
• Actualice este campo de control de acceso siempre que haya cambios en los permisos de acceso de usuario o grupo.
• Si las actualizaciones de índice se programan con un indexador, los cambios se seleccionan en la siguiente ejecución del indexador. Si no usa un indexador, debe volver a indexar manualmente.

En este artículo, el proceso de protección de documentos en Azure AI Search es posible con scripts de ejemplo , que se ejecutarían como administrador de búsqueda. Los scripts asocian un único documento a una sola identidad de usuario. Puede tomar estos scripts y aplicar sus propios requisitos de seguridad y producción para escalar a sus necesidades.

Determinación de la configuración de seguridad

La solución proporciona variables de entorno booleanas para activar las características necesarias para la seguridad del documento en este ejemplo.

Parámetro	Fin
AZURE_USE_AUTHENTICATION	Cuando se establece trueen , habilita el inicio de sesión de usuario en la aplicación de chat y la autenticación de App Service. Habilita Use oid security filter en la configuración del desarrollador de la aplicación de chat.
AZURE_ENFORCE_ACCESS_CONTROL	Cuando se establece en true, requiere autenticación para cualquier acceso a documentos. La configuración del desarrollador para la seguridad de grupo y oid se activará y deshabilitará para que no se puedan deshabilitar desde la interfaz de usuario.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS	Cuando se establece trueen , esta opción permite a los usuarios autenticados buscar en documentos que no tienen asignados controles de acceso, incluso cuando se requiere el control de acceso. Este parámetro solo se debe usar cuando AZURE_ENFORCE_ACCESS_CONTROL está habilitado.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS	Cuando se establece trueen , esta opción permite a los usuarios no autenticados usar la aplicación, incluso cuando se aplica el control de acceso. Este parámetro solo se debe usar cuando AZURE_ENFORCE_ACCESS_CONTROL está habilitado.

Use las secciones siguientes para comprender los perfiles de seguridad admitidos en este ejemplo. En este artículo se configura el perfil de empresa.

Empresa: cuenta requerida + filtro de documento

Cada usuario del sitio debe iniciar sesión y el sitio contiene contenido que es público para todos los usuarios. El filtro de seguridad de nivel de documento se aplica a todas las solicitudes.

Variables de entorno:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true

Uso mixto: cuenta opcional + filtro de documento

Cada usuario del sitio puede iniciar sesión y el sitio contiene contenido que es público para todos los usuarios. El filtro de seguridad de nivel de documento se aplica a todas las solicitudes.

Variables de entorno:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true
• AZURE_ENABLE_UNAUTHENTICATED_ACCESS=true

Requisitos previos

Un entorno de contenedor de desarrollo está disponible con todas las dependencias necesarias para completar este artículo. Puede ejecutar el contenedor de desarrollo en GitHub Codespaces (en un navegador) o localmente utilizando Visual Studio Code.

Para usar este artículo, necesita los siguientes requisitos previos:

• Suscripción de Azure. Crear una cuenta gratuita
• Permisos de cuenta de Azure: la cuenta de Azure debe tener
  • Permiso para administrar aplicaciones en el identificador de Microsoft Entra.
  • Permisos microsoft.authorization/roleAssignments/write, como administrador de acceso de usuario o propietario.
• Acceso concedido a Azure OpenAI en la suscripción de Azure que quiera. Actualmente, solo la aplicación concede acceso a este servicio. Para solicitar acceso a Azure OpenAI, rellene el formulario en https://aka.ms/oai/access.

Necesita más requisitos previos en función de su entorno de desarrollo preferido.

Codespaces (recomendado)

• Cuenta de GitHub

Visual Studio Code

• CLI de desarrollo de Azure
• Docker Desktop: inicie Docker Desktop si no se está ejecutando ya
• Visual Studio Code
• Extensión del contenedor de desarrollo

Entorno de desarrollo abierto

Comience ahora con un entorno de desarrollo que tenga todas las dependencias instaladas para completar este artículo.

Codespaces de GitHub (recomendado)

GitHub Codespaces ejecuta un contenedor de desarrollo administrado por GitHub con Visual Studio Code para la web como interfaz de usuario. Para obtener el entorno de desarrollo más sencillo, utilice Codespaces de GitHub de modo que tenga las herramientas y dependencias de desarrollador correctas preinstaladas para completar este artículo.

Importante

Todas las cuentas de GitHub pueden usar Codespaces durante un máximo de 60 horas gratis cada mes con 2 instancias principales. Para obtener más información, consulte Almacenamiento y horas de núcleo incluidas mensualmente en GitHub Codespaces.

1. Inicie el proceso para crear una nueva instancia de GitHub Codespace en la rama main del repositorio de GitHub Azure-Samples/azure-search-openai-demo.

2. Haga clic con el botón derecho del ratón en el botón siguiente y seleccione Abrir vínculo en ventanas nuevas para disponer al mismo tiempo del entorno de desarrollo y de la documentación.

   

3. En la página Crear codespace, revise las opciones de configuración de codespace y, después, seleccione Crear nuevo codespace

   

4. Espere a que se inicie Codespace. Este proceso de startup puede tardar unos minutos.

5. En el terminal de la parte inferior de la pantalla, inicie sesión en Azure con Azure Developer CLI.

   azd auth login
   

6. Complete el proceso de autenticación.

7. Las tareas restantes de este artículo tienen lugar en el contexto de este contenedor de desarrollo.

Visual Studio Code

La extensión de contenedores de desarrollo para Visual Studio Code requiere que Docker esté instalado en el equipo local. La extensión aloja el contenedor de desarrollo de forma local utilizando el host Docker con las herramientas y dependencias de desarrollo correctas preinstaladas para completar este artículo.

1. Cree un directorio local en el equipo para el proyecto.

   mkdir my-intelligent-app && cd my-intelligent-app
   

2. Abra Visual Studio Code en ese directorio:

   code .
   

3. Abra un nuevo terminal en Visual Studio Code.

4. Ejecute el siguiente comando de AZD para traer el repositorio de GitHub al equipo local.

   azd init -t azure-search-openai-demo
   

5. Abra la paleta de comandos, busque y seleccione Contenedores de desarrollo: Abrir carpeta en contenedor para abrir el proyecto en un contenedor de desarrollo. Espere hasta que se abra el contenedor de desarrollo antes de continuar.

6. Inicie sesión en Azure con Azure Developer CLI.

   azd auth login
   

   Copie el código del terminal y péguelo en un navegador. Siga las instrucciones para autenticarse con su cuenta Azure.

7. Los demás ejercicios de este proyecto tienen lugar en el contexto de este contenedor de desarrollo.

Obtención de información necesaria con la CLI de Azure

Obtenga el identificador de suscripción y el identificador de inquilino con el siguiente comando de la CLI de Azure. Copie el valor que se va a usar como .AZURE_TENANT_ID

az account list --query "[].{subscription_id:id, name:name, tenantId:tenantId}" -o table

Si recibe un error sobre la directiva de acceso condicional del inquilino, necesita un segundo inquilino sin una directiva de acceso condicional.

• El primer inquilino, asociado a su cuenta de usuario, se usa para la variable de AZURE_TENANT_ID entorno.
• El segundo inquilino, sin acceso condicional, se usa para que la variable de AZURE_AUTH_TENANT_ID entorno acceda a Microsoft Graph. Para los inquilinos con una directiva de acceso condicional, busque el identificador de un segundo inquilino sin una directiva de acceso condicional o cree un nuevo inquilino.

Establecimiento de variables de entorno

1. Ejecute los comandos siguientes para configurar la aplicación para el perfil enterprise .

   azd env set AZURE_USE_AUTHENTICATION true
   azd env set AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS true
   azd env set AZURE_ENFORCE_ACCESS_CONTROL true
   

2. Ejecute el siguiente comando para establecer el inquilino, que autoriza al usuario a iniciar sesión en el entorno de la aplicación hospedada. Reemplace por <YOUR_TENANT_ID> el identificador de inquilino.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Nota:

Si tiene una directiva de acceso condicional en el inquilino de usuario, debe especificar un inquilino de autenticación.

Implementación de la aplicación de chat en Azure

La implementación incluye la creación de los recursos de Azure, la carga de los documentos, la creación de las aplicaciones de identidad de Microsoft Entra (cliente y servidor) y la activación de la identidad para el recurso de hospedaje.

1. Ejecute el siguiente comando de la Azure Developer CLI para aprovisionar los recursos de Azure e implementar el código fuente:

   azd up
   

2. Use la tabla siguiente para responder a las solicitudes de implementación de AZD:

   Prompt	Respuesta
   Nombre del entorno	Use un nombre corto con información de identificación como el alias y la aplicación: tjones-secure-chat.
   Subscription	Seleccione una suscripción en la que crear los recursos.
   Ubicación de los recursos de Azure	Seleccione una ubicación cerca de usted.
   Ubicación de documentIntelligentResourceGroupLocation	Seleccione una ubicación cerca de usted.
   Ubicación de openAIResourceGroupLocation	Seleccione una ubicación cerca de usted.

   Espere 5 o 10 minutos después de implementar la aplicación para permitir que la aplicación se inicie.

3. Una vez que la aplicación se ha implementado correctamente, aparece una URL en el terminal.

4. Seleccione esa URL etiquetada (✓) Done: Deploying service webapp para abrir la aplicación de chat en un navegador.

   

5. Acepte el elemento emergente de autenticación de la aplicación.

6. Cuando se muestre la aplicación de chat, observe en la esquina superior derecha que el usuario ha iniciado sesión.

7. Abra Configuración del desarrollador y observe que estas opciones están seleccionadas y atenuadas (deshabilitadas para cambiar).

   • Uso del filtro de seguridad oid
   • Uso del filtro de seguridad de grupos

8. Seleccione la tarjeta con What does a product manager do?.

9. Recibe una respuesta como: The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

   

Abrir el acceso a un documento para un usuario

Active los permisos del documento exacto para que pueda obtener la respuesta. Estos requieren varios fragmentos de información:

• Azure Storage
  • Nombre de cuenta
  • Nombre del contenedor
  • Dirección URL de blob/documento para role_library.pdf
• Identificador del usuario en Microsoft Entra ID

Una vez que se conoce esta información, actualice el campo de índice oids de Azure AI Search para el role_library.pdf documento.

Obtención de la dirección URL de un documento en el almacenamiento

1. En la .azure carpeta de la raíz del proyecto, busque el directorio del entorno y abra el .env archivo con ese directorio.

2. Busque la AZURE_STORAGE_ACCOUNT entrada y copie su valor.

3. Use los siguientes comandos de la CLI de Azure para obtener la dirección URL del blob role_library.pdf en el contenedor de contenido .

   az storage blob url \
       --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
       --container-name 'content' \
       --name 'role_library.pdf' 
   

   Parámetro	Fin
   --account-name	Nombre de la cuenta de Azure Storage
   --container-name	El nombre del contenedor de este ejemplo es content
   --name	El nombre del blob de este paso es role_library.pdf

4. Copie la dirección URL del blob para usarla más adelante.

Obtención del identificador de usuario

1. En la aplicación chap, seleccione Configuración de desarrollador.
2. En la sección Notificaciones de token de identificador, copie el objectidentifier. Esto se conoce en la sección siguiente como USER_OBJECT_ID.

Proporcionar acceso de usuario a un documento en Azure Search

1. Use el siguiente script para cambiar el oids campo en Azure AI Search para role_library.pdf para que tenga acceso a él.

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action add \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parámetro	Fin
   -v	Salida detallada.
   --acl-type	Identificadores de objeto de grupo o usuario (OID): oids
   --acl-action	Agregue a un campo Índice de búsqueda. Otras opciones incluyen remove, remove_all, list.
   --Acl	Grupo o usuario USER_OBJECT_ID
   --URL	Ubicación del archivo en Azure Storage, como https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. No rodear la dirección URL con comillas en el comando de la CLI.

2. La salida de la consola de este comando es similar a la siguiente:

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action add --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   Adding acl 00000000-0000-0000-0000-000000000000 to 58 search documents
   

3. Opcionalmente, use el siguiente comando para comprobar que el permiso aparece en la lista del archivo en Azure AI Search.

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action list \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parámetro	Fin
   -v	Salida detallada.
   --acl-type	Grupo o usuario (oids): oids
   --acl-action	Enumerar un campo oidsde índice de búsqueda . Otras opciones incluyen remove, remove_all, list.
   --Acl	Grupo o usuario USER_OBJECT_ID
   --URL	Ubicación del archivo en Azure Storage, como https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. No rodear la dirección URL con comillas en el comando de la CLI.

4. La salida de la consola de este comando es similar a la siguiente:

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action view --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   [00000000-0000-0000-0000-000000000000]
   

   La matriz al final de la salida incluye el USER_OBJECT_ID y se usa para determinar si el documento se usa en la respuesta con Azure OpenAI.

Comprobación de que Azure AI Search contiene el USER_OBJECT_ID

1. Abra Azure Portal y busque AI Search.

2. Seleccione el recurso de búsqueda en la lista.

3. Seleccione Administración de búsquedas:> índices.

4. Seleccione gptkbindex.

5. Seleccione Ver:> vista JSON.

6. Reemplace el json por el siguiente JSON.

   {
     "search": "*",
     "select": "sourcefile, oids",
     "filter": "oids/any()"
   }
   

   Esto busca en todos los documentos donde el oids campo tiene cualquier valor y devuelve los sourcefilecampos , y oids .

7. role_library.pdf Si no tiene el oid, vuelva a la sección Proporcionar acceso de usuario a un documento en Azure Search y complete los pasos.

Comprobación del acceso de usuario al documento

Si completó los pasos pero no vio la respuesta correcta, compruebe que la USER_OBJECT_ID se ha establecido correctamente en Azure AI Search para esa role_library.pdf.

1. Vuelva a la aplicación de chat. Es posible que tenga que volver a iniciar sesión.

2. Escriba la misma consulta para que el role_library contenido se use en la respuesta de Azure OpenAI: What does a product manager do?.

3. Vea el resultado, que ahora incluye la respuesta adecuada del documento de la biblioteca de roles.

   

Limpieza de recursos

Limpieza de los recursos de Azure

Los recursos Azure creados en este artículo se facturan a su suscripción Azure. Si no espera necesitar estos recursos en el futuro, elimínelos para evitar incurrir en más gastos.

Ejecute el siguiente comando de la Azure Developer CLI para eliminar los recursos de Azure y eliminar el código de origen:

azd down --purge

Limpiar GitHub Codespaces

GitHub Codespaces

La eliminación del entorno de GitHub Codespaces garantiza que pueda maximizar la cantidad de derechos de horas gratuitas por núcleo que obtiene para su cuenta.

Importante

Para obtener más información sobre los derechos de la cuenta de GitHub, consulte Almacenamiento y horas de núcleo incluidas mensualmente en GitHub Codespaces.

1. Inicie sesión en el panel de GitHub Codespaces (https://github.com/codespaces).

2. Busque los espacios de código que se ejecutan actualmente procedentes del repositorio de GitHub Azure-Samples/azure-search-openai-demo.

   

3. Abra el menú contextual del codespace y, a continuación, seleccione Eliminar.

   

Visual Studio Code

No es necesario limpiar el entorno local, pero puede detener el contenedor de desarrollo en ejecución y volver a ejecutar Visual Studio Code en el contexto de un área de trabajo local.

1. Abra la Paleta de comandos, busque los comandos de contenedores de desarrollo y, a continuación, seleccione Contenedores de desarrollo: volver a abrir la carpeta localmente.

   

Sugerencia

Visual Studio Code detendrá el contenedor de desarrollo en ejecución, pero el contenedor todavía existe en Docker en un estado detenido. Siempre tiene la opción de eliminar la instancia de contenedor, la imagen de contenedor y los volúmenes de Docker para liberar más espacio en la máquina local.

Obtener ayuda

Este repositorio de muestras ofrece información para la resolución de problemas.

Solución de problemas

En esta sección se ofrece solución de problemas específicos de este artículo.

Proporcionar inquilino de autenticación

Cuando la autenticación se encuentra en un inquilino independiente de la aplicación de hospedaje, debe establecer ese inquilino de autenticación con el siguiente proceso.

1. Ejecute el siguiente comando para configurar el ejemplo para usar un segundo inquilino para el inquilino de autenticación.

   azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
   

   Parámetro	Fin
   AZURE_AUTH_TENANT_ID	Si AZURE_AUTH_TENANT_ID se establece, es el inquilino que hospeda la aplicación.

2. Vuelva a implementar la solución con el siguiente comando.

   azd up
   

Pasos siguientes

• Crear una aplicación de chat con la arquitectura de soluciones de mejores prácticas de Azure OpenAI
• Control de acceso en aplicaciones de IA generativa con Búsqueda de Azure AI
• Cree una solución OpenAI preparada para la empresa con Azure API Management
• Superar el vector de búsqueda con capacidades híbridas de recuperación y clasificación