Uso seguro de Azure OpenAI en los datos

Use este artículo para aprender a usar Azure OpenAI en los datos de forma segura mediante la protección de datos y recursos con el control de acceso basado en roles, redes virtuales y puntos de conexión privados de Microsoft Entra ID.

Este artículo solo es aplicable cuando se usa Azure OpenAI en los datos con texto. No se aplica a Azure OpenAI en los datos con imágenes.

Arquitectura de ingesta de datos

Cuando se usa Azure OpenAI en los datos para ingerir datos de Azure Blob Storage, archivos locales o direcciones URL en Búsqueda de Azure AI, se usa el siguiente proceso para procesar los datos.

• Los pasos 1 y 2 solo se usan para la carga de archivos.
• La descarga de direcciones URL a Blob Storage no se muestra en este diagrama. Una vez que las páginas web se descargan de Internet y se cargan en Blob Storage, los pasos 3 en adelante son los mismos.
• Se crean dos indexadores, dos índices, dos orígenes de datos y una aptitud personalizada en el recurso de Búsqueda de Azure AI.
• El contenedor de fragmentos se crea en Blob Storage.
• Si la ingesta la desencadena una actualización programada, el proceso de ingesta se inicia desde el paso 7.
• La API preprocessing-jobs de Azure OpenAI implementa el protocolo de API web de aptitud del cliente de Búsqueda de Azure AI y procesa los documentos de una cola.
• Azure OpenAI:
  1. Usa internamente el primer indexador creado anteriormente para descifrar los documentos.
  2. Usa un algoritmo basado en heurística para realizar fragmentaciones, respetando los diseños de tabla y otros elementos de formato en el límite del fragmento para garantizar la mejor calidad de fragmentación.
  3. Si decide habilitar la búsqueda de vectores, Azure OpenAI usa la implementación de inserción seleccionada para vectorizar los fragmentos internamente.
• Cuando se procesan todos los datos que supervisa el servicio, Azure OpenAI desencadena otro indexador.
• El indexador almacena los datos procesados en un servicio de Búsqueda de Azure AI.

Para las identidades administradas usadas en las llamadas de servicio, solo se admiten las identidades administradas asignadas por el sistema. Las identidades administradas asignadas por el usuario no se admiten.

Arquitectura de inferencia

Cuando envía llamadas API para chatear con un modelo de Azure OpenAI sobre sus datos, el servicio necesita recuperar los campos de índice durante la inferencia para realizar la asignación de campos automáticamente si la asignación de campos no se establece explícitamente en la solicitud. Por lo tanto, el servicio requiere que la identidad de Azure OpenAI tenga el rol Search Service Contributor para el servicio de búsqueda incluso durante la inferencia.

Si se proporciona una implementación de inserción en la solicitud de inferencia, Azure OpenAI vectorizará la consulta reescrita y Búsqueda de Azure AI buscará vectores y consultas.

Control de acceso de nivel de documento

Nota:

El control de acceso de nivel de documento solo se admite para la búsqueda de Azure AI.

Azure OpenAI en los datos le permite restringir los documentos que se pueden usar en respuestas para distintos usuarios con filtros de seguridad de Búsqueda de Azure AI. Al habilitar el acceso a nivel de documento, los resultados de búsqueda devueltos por Azure AI Search y utilizados para generar una respuesta se recortarán en función de la pertenencia al grupo Microsoft Entra del usuario. Solo puede habilitar el acceso de nivel de documento en los índices de Azure AI Search existentes. Para habilitar el acceso de nivel de documento:

1. Siga los pasos de la documentación de Azure AI Search para registrar su aplicación y crear usuarios y grupos.

2. Indexe los documentos con sus grupos permitidos. Asegúrese de que los nuevos campos de seguridad tienen el esquema siguiente:

   {"name": "group_ids", "type": "Collection(Edm.String)", "filterable": true }
   

   group_ids es el nombre de campo predeterminado. Si usa un nombre de campo diferente, como my_group_ids, puede asignar el campo en la asignación de campos de índice.

3. Asegúrese de que cada documento confidencial del índice tiene el valor establecido correctamente en este campo de seguridad para indicar los grupos permitidos del documento.

4. En Azure OpenAI Studio, agregue el origen de datos. En la sección asignación de campos de índice, puede asignar cero o un valor al campo grupos permitidos, siempre y cuando el esquema sea compatible. Si el campo Grupos permitidos no está asignado, no se habilitará el acceso de nivel de documento.

Azure OpenAI Studio

Una vez conectado el índice Azure AI Search, sus respuestas en el estudio tendrán acceso a los documentos en función de los permisos de Microsoft Entra del usuario conectado.

Aplicación web

Si usa una aplicación web publicada, debe volver a implementarla para actualizar a la versión más reciente. La última versión de la aplicación web incluye la capacidad de recuperar los grupos de la cuenta Microsoft Entra del usuario conectado, almacenarlos en caché e incluir los ID de grupo en cada solicitud de API.

API

Cuando utilice la API, pase el parámetro filter en cada solicitud de API. Por ejemplo:

{
    "messages": [
        {
            "role": "user",
            "content": "who is my manager?"
        }
    ],
    "dataSources": [
        {
            "type": "AzureCognitiveSearch",
            "parameters": {
                "endpoint": "'$AZURE_AI_SEARCH_ENDPOINT'",
                "key": "'$AZURE_AI_SEARCH_API_KEY'",
                "indexName": "'$AZURE_AI_SEARCH_INDEX'",
                "filter": "my_group_ids/any(g:search.in(g, 'group_id1, group_id2'))"
            }
        }
    ]
}

• my_group_ids es el nombre de campo que seleccionó para grupos permitidos durante la asignación de campos.
• group_id1, group_id2 son grupos atribuidos al usuario que ha iniciado sesión. La aplicación cliente puede recuperar y almacenar en caché los grupos de usuarios.

Configuración de recurso

Use las secciones siguientes para configurar los recursos para un uso seguro óptimo. Incluso si planea proteger solo parte de los recursos, debe seguir todos los pasos que se indican a continuación.

En este artículo se describe la configuración de red relacionada con la deshabilitación de la red pública para los recursos de Azure OpenAI, los recursos de búsqueda de Azure AI y las cuentas de almacenamiento. No se admite el uso de redes seleccionadas con reglas IP, ya que las direcciones IP de los servicios son dinámicas.

Sugerencia

Puede utilizar el script bash disponible en GitHub para validar su configuración y determinar si se cumplen todos los requisitos enumerados aquí.

Creación de un grupo de recursos

Cree un grupo de recursos para poder organizar todos los recursos pertinentes. Los recursos del grupo de recursos incluyen, entre otros:

• Una red virtual
• Tres servicios clave: uno de Azure OpenAI, una instancia de Búsqueda de Azure AI, una cuenta de almacenamiento
• Tres puntos de conexión privados; cada uno está vinculado a un servicio clave
• Tres interfaces de red; cada una está asociada a un punto de conexión privado
• Una puerta de enlace de red virtual para el acceso desde máquinas cliente locales
• Una aplicación web con red virtual integrada
• Una zona DNS privada, para que la aplicación web busque la dirección IP de Azure OpenAI

Creación de una red virtual

La red virtual tiene tres subredes.

1. La primera subred se usa para las direcciones IP privadas de los tres puntos de conexión privados.
2. La segunda subred se crea automáticamente al crear la puerta de enlace de red virtual.
3. La tercera subred está vacía y se usa para la integración de red virtual saliente de la aplic. web.

Tenga en cuenta que Microsoft crea la red virtual administrada por Microsoft y usted no puede verla. Azure OpenAI usa la red virtual administrada por Microsoft para acceder de forma segura a Búsqueda de Azure AI.

Configuración de Azure OpenAI

Subdominio personalizado habilitado

Si ha creado Azure OpenAI a través de Azure Portal, el subdominio personalizado ya debería haberse creado. El subdominio personalizado es necesario para la autenticación basada en Microsoft Entra ID y la zona DNS privada.

Habilitación de una entidad administrada

Para permitir que Búsqueda de Azure AI y la cuenta de almacenamiento reconozcan el servicio Azure OpenAI a través de la autenticación de Microsoft Entra ID, debe asignar una identidad administrada para el servicio Azure OpenAI. La forma más fácil es activar la identidad administrada asignada por el sistema en Azure Portal.

Para establecer las identidades administradas a través de la API de administración, consulte la documentación de referencia de la API de administración.

"identity": {
  "principalId": "12345678-abcd-1234-5678-abc123def",
  "tenantId": "1234567-abcd-1234-1234-abcd1234",
  "type": "SystemAssigned, UserAssigned", 
  "userAssignedIdentities": {
    "/subscriptions/1234-5678-abcd-1234-1234abcd/resourceGroups/my-resource-group",
    "principalId": "12345678-abcd-1234-5678-abcdefg1234", 
    "clientId": "12345678-abcd-efgh-1234-12345678"
  }
}

Habilitación del servicio de confianza

Para permitir que Búsqueda de Azure AI llame a preprocessing-jobs de Azure OpenAI como API web de aptitudes personalizadas cuando Azure OpenAI no tiene acceso a la red pública, debe configurar Azure OpenAI para admitir Búsqueda de Azure AI como un servicio de confianza basado en la identidad administrada. Azure OpenAI identifica el tráfico de su instancia de Búsqueda de Azure AI comprobando las notificaciones en JSON Web Token (JWT). Búsqueda de Azure AI debe usar la autenticación de identidad administrada asignada por el sistema para llamar a la API web de aptitud personalizada.

Establezca networkAcls.bypass como AzureServices desde la API de administración. Para más información, consulte el artículo sobre redes virtuales.

Este paso solo se puede omitir si tiene un vínculo privado compartido para el recurso de Búsqueda de Azure AI.

Deshabilitación del acceso a una red pública

Puede deshabilitar el acceso a la red pública del recurso de Azure OpenAI en Azure Portal.

Para permitir el acceso al servicio Azure OpenAI desde las máquinas cliente, como el uso de Azure OpenAI Studio, debe crear conexiones de punto de conexión privado que se conecten al recurso de Azure OpenAI.

Configuración de Búsqueda de Azure AI

Puede usar el plan de tarifa básico y versiones posteriores para la configuración siguiente. No es necesario, pero si usa el plan de tarifa S2, verá opciones adicionales disponibles para la selección.

Habilitación de una entidad administrada

Para permitir que los demás recursos reconozcan Búsqueda de Azure AI mediante la autenticación de Microsoft Entra ID, debe asignar una identidad administrada para Búsqueda de Azure AI. La manera más fácil es activar la identidad administrada asignada por el sistema en Azure Portal.

Habilitación del control de acceso basado en roles

A medida que Azure OpenAI usa la identidad administrada para acceder a Búsqueda de Azure AI, debe habilitar el control de acceso basado en roles en Búsqueda de Azure AI. Para hacerlo en Azure Portal, seleccione Ambas en la pestaña Claves de Azure Portal.

Para habilitar el control de acceso basado en roles a través de la API de REST, establezca authOptions como aadOrApiKey. Para más información, consulte el artículo sobre el RBAC de Búsqueda de Azure AI.

"disableLocalAuth": false,
"authOptions": { 
    "aadOrApiKey": { 
        "aadAuthFailureMode": "http401WithBearerChallenge"
    }
}

Para usar Azure OpenAI Studio, no se puede deshabilitar la autenticación basada en la clave de API para Búsqueda de Azure AI, ya que Azure OpenAI Studio usa la clave de API para llamar a la API de Búsqueda de Azure AI desde el explorador.

Sugerencia

Para una mayor seguridad, cuando esté listo para la producción y ya no necesite utilizar Azure OpenAI Studio para las pruebas, se recomienda deshabilitar la clave de API. Consulte el artículo sobre el RBAC de Azure AI Search para obtener más información.

Deshabilitación del acceso a una red pública

Puede deshabilitar el acceso a la red pública del recurso de Búsqueda de Azure AI en Azure Portal.

Para permitir el acceso al recurso de Búsqueda de Azure AI desde las máquinas cliente, como el uso de Azure OpenAI Studio, debe crear conexiones de punto de conexión privado que se conecten al recurso de Búsqueda de Azure AI.

Nota:

Para permitir el acceso al recurso de Búsqueda de Azure AI desde el recurso de Azure OpenAI, debe enviar un formulario de aplicación. La solicitud se revisará en 5 días laborables y nos pondremos en contacto con usted por correo electrónico para comunicarle los resultados. Si es apto, aprovisionará el punto de conexión privado en la red virtual administrada por Microsoft y enviará una solicitud de conexión de punto de conexión privado al servicio de búsqueda; por último, deberá aprobar la solicitud.

El recurso de punto de conexión privado se aprovisiona en un inquilino administrado de Microsoft, mientras que el recurso vinculado está en el inquilino. No puede acceder al recurso de punto de conexión privado haciendo clic en el vínculo del punto de conexión privado (en fuente azul) en la pestaña Acceso privado de la página Redes. En su lugar, haga clic en otra parte de la fila y, a continuación, podrá hacer clic en el botón Aprobar de arriba.

Obtenga más información sobre el flujo de trabajo de aprobación manual.

Creación de un vínculo privado compartido

Sugerencia

Si usa un plan de tarifa básico o estándar, o si es la primera vez que configura todos los recursos de forma segura, debe omitir este tema avanzado.

Esta sección solo es aplicable al recurso de búsqueda del plan de tarifa S2, ya que requiere compatibilidad con puntos de conexión privados para indexadores con un conjunto de aptitudes.

Para crear un vínculo privado compartido desde el recurso de búsqueda que se conecta al recurso de Azure OpenAI, consulte la documentación de búsqueda. Seleccione Tipo de recurso como Microsoft.CognitiveServices/accounts e Id. de grupo como openai_account.

Con el vínculo privado compartido, el paso ocho del diagrama de arquitectura de ingesta de datos se cambia de omitir el servicio de confianza a punto de conexión privado.

El vínculo privado compartido de Búsqueda de Azure AI que creó también se encuentra en una red virtual administrada por Microsoft, no en la red virtual. La diferencia en comparación con el otro punto de conexión privado administrado creado anteriormente es que el punto de conexión privado [1] administrado de Azure OpenAI a Azure Cognitive Search se aprovisiona a través de la aplicación de formulario, mientras que el punto de conexión privado [2] administrado de Azure Cognitive Search a Azure OpenAI se aprovisiona a través de Azure Portal o la API de REST de Azure Cognitive Search.

Configuración de la cuenta de almacenamiento

Habilitación del servicio de confianza

Para permitir el acceso a la cuenta de almacenamiento desde Azure OpenAI y Búsqueda de Azure AI cuando la cuenta de almacenamiento no tiene acceso a la red pública, debe configurar la cuenta de almacenamiento para admitir Azure OpenAI y Búsqueda de Azure AI como servicios de confianza basados en la identidad administrada.

En Azure Portal, vaya a la pestaña redes de la cuenta de almacenamiento, elija "Redes seleccionadas" y, a continuación, seleccione Permitir que los servicios de Azure en la lista de servicios de confianza accedan a esta cuenta de almacenamiento y haga clic en Guardar.

Nota:

La característica de servicio de confianza solo está disponible con la línea de comandos descrita anteriormente y no se puede realizar mediante Azure Portal.

Deshabilitación del acceso a una red pública

Puede deshabilitar el acceso a la red pública de la cuenta de almacenamiento en Azure Portal.

Para permitir el acceso a la cuenta de almacenamiento desde las máquinas cliente, como el uso de Azure OpenAI Studio, debe crear conexiones de punto de conexión privado que se conecten al almacenamiento de blobs.

Asignaciones de roles

Hasta ahora, ya ha configurado cada recurso para que funcione de forma independiente. A continuación, debe permitir que los servicios se autoricen mutuamente.

Role	Persona asignada	Resource	Descripción
Search Index Data Reader	Azure OpenAI	Azure AI Search	El servicio de inferencia consulta los datos del índice.
Search Service Contributor	Azure OpenAI	Azure AI Search	El servicio de inferencia consulta el esquema de índice para la asignación de campos automáticos. El servicio de ingesta de datos crea un índice, orígenes de datos, un conjunto de aptitudes, un indexador y consulta el estado del indexador.
Storage Blob Data Contributor	Azure OpenAI	Cuenta de almacenamiento	Lee del contenedor de entrada y escribe el resultado del preproceso en el contenedor de salida.
Cognitive Services OpenAI Contributor	Azure AI Search	Azure OpenAI	Habilidad personalizada
Storage Blob Data Contributor	Azure AI Search	Cuenta de almacenamiento	Lee el blob y escribe el almacén de conocimiento.

En la tabla anterior, Assignee significa la identidad administrada asignada por el sistema de ese recurso.

El administrador debe tener el rol Owner en estos recursos para agregar asignaciones de roles.

Consulte la documentación de RBAC de Azure para obtener instrucciones sobre cómo establecer estos roles en Azure Portal. Puede usar el script disponible en GitHub para agregar las asignaciones de roles mediante programación.

Para permitir que los desarrolladores usen estos recursos para compilar aplicaciones, el administrador debe agregar la identidad de los desarrolladores con las siguientes asignaciones de roles a los recursos.

Rol	Resource	Descripción
Cognitive Services OpenAI Contributor	Azure OpenAI	Llama a la API de ingesta pública desde Azure OpenAI Studio. El rol Contributor no es suficiente, ya que, si solo tiene el rol Contributor, no puede llamar a la API del plano de datos a través de la autenticación de Microsoft Entra ID y se requiere dicha autenticación en la configuración de seguridad descrita en este artículo.
Cognitive Services User	Azure OpenAI	Enumere las claves de API de Azure OpenAI Studio.
Contributor	Azure AI Search	Enumera las claves de API para enumerar índices de Azure OpenAI Studio.
Contributor	Cuenta de almacenamiento	Enumera SAS de cuenta para cargar archivos desde Azure OpenAI Studio.
Contributor	El grupo de recursos o la suscripción de Azure en la que el desarrollador necesita implementar la aplicación web	Implemente la aplicación web en la suscripción de Azure del desarrollador.

Configuración de la puerta de enlace y el cliente

Para acceder al servicio Azure OpenAI desde las máquinas cliente locales, uno de los enfoques es configurar Azure VPN Gateway y el cliente VPN de Azure.

Siga esta guía para crear una puerta de enlace de red virtual para la red virtual.

Siga esta guía para agregar la configuración de punto a sitio y habilitar la autenticación basada en Microsoft Entra ID. Descargue el paquete de configuración del perfil de cliente VPN de Azure, descomprima e importe el archivo AzureVPN/azurevpnconfig.xml en el cliente VPN de Azure.

Configure el archivo hosts de máquina local para que apunte los nombres de host de los recursos a las direcciones IP privadas de la red virtual. El archivo hosts se encuentra en C:\Windows\System32\drivers\etc para Windows y en /etc/hosts en Linux. Ejemplo:

10.0.0.5 contoso.openai.azure.com
10.0.0.6 contoso.search.windows.net
10.0.0.7 contoso.blob.core.windows.net

Azure OpenAI Studio

Debe poder usar todas las características de Azure OpenAI Studio, incluida la ingesta y la inferencia, desde las máquinas cliente locales.

Aplicación web

La aplicación web se comunica con el recurso de Azure OpenAI. Dado que el recurso de Azure OpenAI tiene deshabilitada la red pública, la aplicación web debe configurarse para usar el punto de conexión privado de la red virtual para acceder al recurso de Azure OpenAI.

La aplicación web debe resolver el nombre de host de Azure OpenAI en la dirección IP privada del punto de conexión privado para Azure OpenAI. Por lo tanto, primero debe configurar la zona DNS privada para la red virtual.

1. Cree una zona DNS privada en el grupo de recursos.
2. Agregue un registro DNS. IP es la dirección IP privada del punto de conexión privado para el recurso de Azure OpenAI y puede obtener la dirección IP de la interfaz de red asociada al punto de conexión privado de Azure OpenAI.
3. Vincule la zona DNS privada a la red virtual para que la aplicación web integrada en esta red virtual pueda usar esta zona DNS privada.

Al implementar la aplicación web desde Azure OpenAI Studio, seleccione la misma ubicación con la red virtual y seleccione una SKU adecuada para que pueda admitir la característica de integración de red virtual.

Una vez implementada la aplicación web, en la pestaña Redes de Azure Portal, configure la integración de red virtual de tráfico saliente de la aplicación web, elija la tercera subred reservada para la aplicación web.

Uso de la API

Asegúrese de que la credencial de inicio de sesión tenga el rol Cognitive Services OpenAI Contributor en el recurso de Azure OpenAI y ejecute az login primero.

Ingestion API

Consulte el artículo de referencia de API de ingesta para obtener más información sobre los objetos de solicitud y de respuesta usados por la API de ingesta.

Más notas:

• JOB_NAME en la ruta de acceso de API se usará como nombre de índice en Búsqueda de Azure AI.
• Use el encabezado Authorization en lugar de la clave de API.
• Establezca explícitamente el encabezado storageEndpoint.
• Use el formato ResourceId= para el encabezado storageConnectionString, de modo que Azure OpenAI y Búsqueda de Azure AI usen la identidad administrada para autenticar la cuenta de almacenamiento, que es necesaria para omitir las restricciones de red.
• No establezca el encabezado searchServiceAdminKey. La identidad asignada por el sistema del recurso de Azure OpenAI se usa para autenticar Búsqueda de Azure AI.
• No establezca embeddingEndpoint ni embeddingKey. En su lugar, use el encabezado embeddingDeploymentName para habilitar la vectorización de texto.

Ejemplo de envío de un trabajo

accessToken=$(az account get-access-token --resource https://cognitiveservices.azure.com/ --query "accessToken" --output tsv)
curl -i -X PUT https://my-resource.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/vpn1025a?api-version=2023-10-01-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $accessToken" \
-H "storageEndpoint: https://mystorage.blob.core.windows.net/" \
-H "storageConnectionString: ResourceId=/subscriptions/1234567-abcd-1234-5678-1234abcd/resourceGroups/my-resource/providers/Microsoft.Storage/storageAccounts/mystorage" \
-H "storageContainer: my-container" \
-H "searchServiceEndpoint: https://mysearch.search.windows.net" \
-H "embeddingDeploymentName: ada" \
-d \
'
{
}
'

Ejemplo de obtención del estado de un trabajo

accessToken=$(az account get-access-token --resource https://cognitiveservices.azure.com/ --query "accessToken" --output tsv)
curl -i -X GET https://my-resource.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/abc1234?api-version=2023-10-01-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $accessToken"

API de inferencia

Consulte el artículo de referencia de API de inferencia para obtener más información sobre los objetos de solicitud y de respuesta usados por la API de inferencia.