Detección y redacción de PII en documentos nativos

Sugerencia

Antes de escribir código, pruebe la detección de PII basada en documentos en el portal de Microsoft Foundry. El entorno de pruebas carga un documento de ejemplo preparado, lo envía a través del canal asíncrono existente para datos de identificación personal (PII) basado en archivos nativos y muestra el resultado censurado junto al original. Los resultados incluyen categorías de entidades, puntuaciones de confianza y resultados con fidelidad al archivo. Para obtener instrucciones paso a paso, consulta Usar el entorno de pruebas de PII de documentos en Microsoft Foundry.

Language es un servicio basado en la nube que aplica características de procesamiento de lenguaje natural (NLP) a datos basados en texto. La funcionalidad de compatibilidad con documentos nativos le permite enviar solicitudes de API de forma asincrónica, mediante un cuerpo de solicitud HTTP POST para enviar los datos y la cadena de consulta de solicitud HTTP GET para recuperar los resultados del estado. Los documentos procesados se encuentran en el contenedor de destino de Azure Blob Storage.

Un documento nativo hace referencia al formato de archivo usado para crear el documento original, como Microsoft Word (docx) o un archivo de documento portátil (pdf). La compatibilidad con documentos nativos elimina la necesidad de preprocesamiento de texto antes de usar las funcionalidades de recursos de lenguaje. Actualmente, la compatibilidad con documentos nativos está disponible para las siguientes funcionalidades:

Información de identificación personal (PII). La característica de detección de PII puede identificar, clasificar y censurar información confidencial en texto no estructurado. La PiiEntityRecognition API admite el procesamiento nativo de documentos.
Resumen de documentos. El resumen de documentos usa el procesamiento de lenguaje natural para generar resúmenes extractivos (extracción de frases destacadas) o resúmenes abstractos (extracción de palabras contextuales) para documentos. AbstractiveSummarization y ExtractiveSummarization admiten el procesamiento nativo de documentos.

Formatos de documento admitidos

Las aplicaciones usan formatos de archivo nativos para crear, guardar o abrir documentos nativos. Actualmente, las capacidades de PII y de resumen de documentos admiten los siguientes formatos de documento nativos:

Tipo de archivo	Extensión de archivo	Descripción
Texto	`.txt`	Un documento de texto sin formato.
PDF	`.pdf`	Un archivo de documento portátil con formato de documento y archivos PDF escaneados.
Microsoft Word	`.docx`	Un archivo de documento Microsoft Word.

Instrucciones de entrada

Formatos de archivo admitidos

Tipo	soporte y limitaciones
Texto dentro de imágenes	No se admiten imágenes digitales con texto incrustado.
Tablas digitales	No se admiten tablas en documentos escaneados.

Tamaño del documento

Atributo	Límite de entrada
Número total de documentos por solicitud	≤ 40
Tamaño total de contenido por solicitud	≤ 10 MB

Incluir documentos nativos con una solicitud HTTP

Comencemos:

Para este proyecto, usamos la herramienta de línea de comandos cURL para realizar llamadas a la API REST.

Nota

El paquete cURL está preinstalado en la mayoría de Windows 10 y Windows 11 y la mayoría de las distribuciones de macOS y Linux. Puede comprobar la versión del paquete con los siguientes comandos: Windows: curl.exe -V macOS curl -V Linux: curl --version
Una cuenta activa de Azure. Si no tiene una, puede crear una cuenta gratuita.
Una cuenta de Azure Blob Storage. También debe crear contenedores en la cuenta de Azure Blob Storage para los archivos de origen y de destino:
- Contenedor de origen. Este contenedor es donde se cargan los archivos nativos para su análisis (obligatorio).
- Contenedor de destino. Este contenedor es donde se almacenan los archivos analizados (obligatorios).
Un recurso de lenguaje de un solo servicio (no un recurso de Microsoft Foundry de varios servicios):

Complete los campos de detalles del proyecto y de la instancia de recursos de lenguaje de Azure como se indica a continuación:
1. Suscripción. Seleccione una de las suscripciones de Azure disponibles.
2. Grupo de recursos. Puede crear un nuevo grupo de recursos o agregar el recurso a un grupo de recursos preexistente que comparta el mismo ciclo de vida, permisos y directivas.
3. Región del recurso. Elija Global a menos que su empresa o aplicación requiera una región específica. Si planea usar una identidad administrada asignada por el sistema para la autenticación, elija una región geográfica como Oeste de EE. UU.
4. Nombre. Escriba el nombre que eligió para el recurso. El nombre que elija debe ser único en Azure.
5. Nivel de precios. Puede usar el plan de tarifa gratis (Free F0) para probar el servicio y actualizarlo más adelante a un nivel de pago para producción.
6. Seleccione Revisar y crear.
7. Revise los términos del servicio y seleccione Crear para implementar el recurso.
8. Una vez que el recurso se implemente correctamente, seleccione Ir al recurso.

Obtenga su clave y el punto de conexión de lenguaje

Las solicitudes a Azure Language requieren una clave de solo lectura y un punto de conexión personalizado para autenticar el acceso.

Si ha creado un nuevo recurso, después de implementarlo, seleccione Ir al recurso. Si tiene un recurso de idioma existente, vaya directamente a la página de recursos.
En el raíl izquierdo, en Administración de recursos, seleccione Claves y punto de conexión.
Puede copiar y pegar key y Language instance endpoint en los fragmentos de código para autenticar su solicitud en Azure Language. Solo es necesaria una clave para realizar una llamada API.

Creación de contenedores de Azure Blob Storage

Crear contenedores en la cuenta de Azure Blob Storage para archivos de origen y destino.

Contenedor de origen. Este contenedor es donde se cargan los archivos nativos para su análisis (obligatorio).
Contenedor de destino. Este contenedor es donde se almacenan los archivos analizados (obligatorios).

Autenticación

Debe conceder al recurso de lenguaje acceso a su cuenta de almacenamiento antes de que pueda crear, leer o eliminar blobs. Hay dos métodos principales que puede usar para conceder acceso a los datos de almacenamiento:

Tokens de firma de acceso compartido (SAS). Los tokens de SAS de delegación de usuarios se protegen con credenciales de Microsoft Entra. Los tokens de SAS proporcionan acceso seguro y delegado a los recursos de la cuenta de almacenamiento de Azure.
Control de acceso basado en roles (RBAC) de identidad administrada. Las identidades administradas para los recursos de Azure son entidades de servicio que crean una identidad de Microsoft Entra y permisos específicos para los recursos administrados de Azure.

Para este proyecto, autenticamos el acceso a las direcciones source location URL y target location con tokens de firma de acceso compartido (SAS) anexados como cadenas de consulta. Cada token se asigna a un blob (archivo) específico.

Captura de pantalla de una dirección URL de almacenamiento con el token de SAS anexado.

El contenedor de origen o blob debe designar acceso de lectura y de lista.
El destino contenedor o blob debe designar escritura y acceso.

Sugerencia

Dado que estamos procesando un único archivo (blob), se recomienda delegar el acceso de SAS en el nivel de blob.

Encabezados y parámetros de solicitud

parámetro	Descripción
`-X POST <endpoint>`	Especifica el punto de conexión del recurso de idioma para acceder a la API.
`--header Content-Type: application/json`	Tipo de contenido para enviar datos JSON.
`--header "Ocp-Apim-Subscription-Key:<key>`	Especifica la clave de recurso para Azure Language, necesaria para acceder a la API.
`-data`	Archivo JSON que contiene los datos que desea pasar con la solicitud.

Los siguientes comandos cURL se ejecutan desde un shell de BASH. Edite estos comandos con su propio nombre de recurso, clave de recurso y valores JSON. Pruebe a analizar documentos nativos seleccionando el proyecto de ejemplo de código Personally Identifiable Information (PII) o Document Summarization.

Documento de ejemplo de PII

Para este inicio rápido, necesita un documento de origen cargado en el contenedor de origen. Puede descargar nuestro documento de ejemplo Microsoft Word o Adobe PDF para este proyecto. El idioma de origen es inglés.

Construir la solicitud POST

Con el editor o IDE preferidos, cree un directorio para la aplicación denominada native-document.
Cree un nuevo archivo JSON denominado pii-detection.json en el directorio native-document .
Copie y pegue el siguiente ejemplo de solicitud de información de identificación personal (PII) en el pii-detection.json archivo. Reemplace {your-source-container-SAS-URL} y {your-target-container-SAS-URL} por valores de la instancia de contenedores de la cuenta de almacenamiento del portal de Azure:

Ejemplo de solicitud

{ 
    "displayName": "Document PII Redaction example", 
    "analysisInput": { 
        "documents": [ 
            { 
                "language": "en-US", 
                "id": "Output-1", 
                "source": { 
                    "location": "{your-source-blob-with-SAS-URL}" 
                }, 
                "target": { 
                    "location": "{your-target-container-with-SAS-URL}" 
                } 
            } 
        ] 
    }, 
    "tasks": [ 
        { 
            "kind": "PiiEntityRecognition", 
            "taskName": "Redact PII Task 1", 
            "parameters": { 
                "redactionPolicy": { 
                    "policyKind": "entityMask"  // Optional. Defines redactionPolicy; changes behavior based on value. Options: noMask, characterMask (default), and entityMask. 
                }, 
                "piiCategories": [ 
                    "Person", 
                    "Organization" 
                ], 
                "excludeExtractionData": false  // Default is false. If true, only the redacted document is stored, without extracted entities data. 
            } 
        } 
    ] 
}

El valor de origen location es la dirección URL de SAS del documento de origen (blob), no la dirección URL de SAS del contenedor de origen.
Las redactionPolicypolicyKind opciones son noMask, characterMask (valor predeterminado) y entityMask. Para obtener más información, consulteParámetros de PiiTask.

Ejecución de la solicitud POST

Esta es la estructura preliminar de la solicitud POST:

   POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview

Antes de ejecutar la solicitud POST, reemplace {your-language-resource-endpoint} y {your-key} por los valores de la instancia del lenguaje del portal de Azure.

Importante

Recuerde quitar la clave del código cuando haya terminado y nunca publicarla públicamente. Para producción, use una forma segura de almacenar y acceder a sus credenciales, como Azure Key Vault. Para obtener más información, consulte la seguridad de Herramientas de Foundry.

PowerShell

   cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

símbolo del sistema/terminal

   curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

Esta es una respuesta de ejemplo:

HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2024-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

Respuesta de POST ("jobId")

Recibe una respuesta 202 (Success) que incluye un encabezado Operation-Location de solo lectura. El valor de este encabezado contiene un jobId que se puede consultar para obtener el estado de la operación asincrónica y recuperar los resultados mediante una solicitud GET :

Captura de pantalla que muestra el valor de ubicación de la operación en la respuesta POST.

Obtención de resultados de análisis (solicitud GET)

Después de que la solicitud POST se haya ejecutado correctamente, sondee el encabezado operation-location devuelto en la solicitud POST para ver los datos procesados.

Esta es la estructura preliminar de la solicitud GET :

  GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview

Antes de ejecutar el comando, realice estos cambios:
- Reemplace {jobId} por el encabezado Operation-Location de la respuesta POST.
- Reemplace {your-language-resource-endpoint} y {your-key} por los valores de la instancia de lenguaje en Azure Portal.

Solicitud GET

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

Examen de la respuesta

Recibe una respuesta 200 (Éxito) con un resultado en formato JSON. El campo de estado indica el resultado de la operación. Si la operación no está completa, el valor de estado es "en ejecución" o "notStarted", y debe llamar a la API de nuevo, ya sea manualmente o a través de un script. Se recomienda un intervalo de un segundo o más entre llamadas.

Nota

El entorno de pruebas del portal de Microsoft Foundry muestra los mismos elementos en una interfaz de usuario visual: las categorías de entidades y las puntuaciones de confianza aparecen en el panel Detalles, y el documento censurado se muestra en paralelo con el original para reflejar los resultados de fidelidad del archivo. Esta interfaz de usuario visual corresponde directamente a los dos artefactos de salida que la API escribe en el contenedor de destino: un archivo nativo redactado y un archivo de resultados JSON estructurado que contiene entidades extraídas.

Respuesta de ejemplo

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "PiiEntityRecognitionLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.docx"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-09-01"
        }
      }
    ]
  }
}

Tras la finalización correcta:

Los documentos analizados se pueden encontrar en el contenedor de destino.
El método POST correcto devuelve un 202 Accepted código de respuesta que indica que el servicio creó la solicitud por lotes.
La solicitud POST también devolvió encabezados de respuesta, incluido Operation-Location que proporciona un valor usado en las solicitudes GET posteriores.

Limpieza de recursos

Para limpiar y quitar un recurso de inteligencia artificial de Azure, puede eliminar el recurso individual o todo el grupo de recursos. Si elimina el grupo de recursos, también se eliminan todos los recursos contenidos en .

Pasos siguientes

Introducción a la detección de PII

Comentarios

¿Le resultó útil esta página?

Last updated on 2026-07-22