Compartir vía

Compatibilidad de documentos nativos con Lenguaje de Azure AI (versión preliminar)

  • Artículo

Importante

  • La compatibilidad con documentos nativos es una versión preliminar validada. Para solicitar acceso a la característica de compatibilidad con documentos nativos, complete y envíe el formulario Solicitar acceso a las versiones preliminares del servicio de lenguaje.

  • Las versiones preliminares públicas de Lenguaje de Azure AI proporcionan acceso anticipado a las características que están en desarrollo activo.

  • Antes de la disponibilidad general (GA), las características, los enfoques y los procesos podrían cambiar en función de los comentarios de los usuarios.

Lenguaje de Azure AI es un servicio basado en la nube que aplica características de procesamiento del lenguaje natural (NLP) a datos basados en texto. La funcionalidad de compatibilidad con documentos nativos permite enviar solicitudes de API de forma asincrónica, empleando un cuerpo de solicitud HTTP POST para enviar los datos y una 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 de Azure AI. 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 DCP puede identificar, clasificar y censurar información confidencial en texto no estructurado. La API PiiEntityRecognition admite el procesamiento nativo de documentos.

  • Resumen de documentos. El resumen de documentos usa el procesamiento de lenguaje natural para generar resúmenes mediante extracción (extracción de frases destacadas) o abstracción (extracción de palabras contextuales) para documentos. Las API 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 funcionalidades de PII y resumen de documentos admiten los siguientes formatos de documento nativos:

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

Directrices de entrada

Formatos de archivos admitidos

Tipo Compatibilidad y limitaciones
PDF No se admiten archivos PDF totalmente digitalizados.
Texto dentro de imágenes No se admiten imágenes digitales con texto incrustado.
Tablas digitales No se admiten tablas en documentos digitalizados.

Tamaño del documento

Attribute Límite de entrada
Número total de documentos por solicitud ≤ 20
Tamaño total del contenido por solicitud ≤ 1 MB

Incluir documentos nativos con una solicitud HTTP

Comencemos:

  • Para este proyecto, usaremos 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 las distribuciones tanto de Windows 10 y Windows 11 como 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

  • Si cURL no está instalada, estos son los vínculos de instalación para su plataforma:

  • Una cuenta de Azure activa. En caso de no tener ninguna, puede crear una cuenta gratuita.

  • Una cuenta de Azure Blob Storage. También tendrá que crear contenedores en la cuenta de Azure Blob Storage para los archivos de origen y destino:

    • Contenedor de origen. En este contenedor se cargan los archivos nativos para su análisis (obligatorio).
    • Contenedor de destino. En este contenedor se almacenan los archivos traducidos (obligatorio).

  • Un recurso de Lenguaje de servicio único (no un recurso multiservicio de servicios de Azure AI):

    Complete los campos de detalles de proyecto e instancia de Lenguaje de la siguiente manera:

    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 ya existente 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. Plan de tarifa. Puede usar el plan de tarifa gratis (Free F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.

    6. Seleccione Revisar + crear.

    7. Revise los términos de servicio y seleccione Crear para implementar el recurso.

    8. Una vez que el recurso se implemente correctamente, seleccione Ir al recurso.

Recuperación de la clave y del punto de conexión de servicio de lenguaje

Las solicitudes al servicio de lenguaje requieren una clave de solo lectura y un punto de conexión personalizado para autenticar el acceso.

  1. Si ha creado un nuevo recurso, después de implementarlo, seleccione Ir al recurso. Si ya tiene un recurso del servicio de lenguaje, vaya directamente a la página del recurso.

  2. En el raíl izquierdo, en Administración de recursos, seleccione Claves y punto de conexión.

  3. Puede copiar y pegar key y language service instance endpoint en los ejemplos de código para autenticar la solicitud en el servicio de lenguaje. Solo se necesita una clave para realizar una llamada API.

Creación de contenedores de Azure Blob Storage

Cree contenedores en la cuenta de Azure Blob Storage de los archivos de origen y destino.

  • Contenedor de origen. En este contenedor se cargan los archivos nativos para su análisis (obligatorio).
  • Contenedor de destino. En este contenedor se almacenan los archivos traducidos (obligatorio).

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:

Para este proyecto, autenticamos el acceso a las direcciones URL de source location 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.

Screenshot of a storage url with SAS token appended.

  • 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 solo archivo (blob), se recomienda el acceso SAS delegado en el nivel de blob.

Parámetros y encabezados de solicitud

parámetro Descripción
-X POST <endpoint> Especifica el punto de conexión del recurso de lenguaje 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 del recurso de lenguaje para acceder a la API.
-data Archivo JSON que contiene los datos que desea pasar con la solicitud.

Los siguientes comandos de cURL se ejecutan desde un shell de BASH. Edite estos comandos con sus propios valores de nombre de recurso, clave de recurso y 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 de Microsoft Word o Adobe PDF para este proyecto. El idioma de origen es inglés.

Creación de la solicitud POST

  1. Utilice el editor o IDE que prefiera para crear un directorio para la aplicación denominado native-document.

  2. Cree un nuevo archivo JSON denominado pii-detection.json en el directorio de documentos nativos.

  3. Copie y pegue la siguiente solicitud de ejemplo de información de identificación personal (PII) en el archivo pii-detection.json. Sustituya {your-source-container-SAS-URL} y {your-target-container-SAS-URL} por los valores de la instancia de contenedores de la cuenta de almacenamiento de Azure Portal:

Solicitud de ejemplo

{
    "displayName": "Extracting Location & US Region",
    "analysisInput": {
        "documents": [
            {
                "language": "en-US",
                "id": "Output-excel-file",
                "source": {
                    "location": "{your-source-blob-with-SAS-URL}"
                },
                "target": {
                    "location": "{your-target-container-with-SAS-URL}"
                }
            } 
        ]
    },
    "tasks": [
        {
            "kind": "PiiEntityRecognition",
            "parameters":{
                "excludePiiCategories" : ["PersonType", "Category2", "Category3"],
                "redactionPolicy": "UseRedactionCharacterWithRefId" 
            }
        }
    ]
}

  • El valor del location de origen es la dirección URL de SAS del documento de origen (blob), no la dirección URL de SAS del contenedor de origen.

  • Los posibles valores de redactionPolicy son UseRedactionCharacterWithRefId (valor predeterminado) o UseEntityTypeName. Para obtener más información, veaparámetros PiiTask.

Ejecución de la solicitud POST

  1. Esta es la estructura preliminar de la solicitud POST:

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

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

    Importante

    Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública. En el caso de producción, use una forma segura de almacenar sus credenciales y acceder a ellas, como Azure Key Vault. Para más información, consulteSeguridad de servicios de Azure AI.

    PowerShell

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

    command prompt/terminal

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

  3. 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=2023-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 (POST) (jobId)

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

Screenshot showing the operation-location value in the POST response.

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

  1. 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.

  2. Esta es la estructura preliminar de la solicitud GET:

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

  3. 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 servicio de lenguaje en Azure Portal.

Solicitud GET

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-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=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

Examen de la respuesta

Recibe una respuesta 200 (Success) con la salida JSON. El campo estado indica el resultado de la operación. Si la operación no está completa, el valor de estado es "running" o "notStarted", y debe volver a llamar a la API, ya sea manualmente o mediante un script. Se recomienda un intervalo de uno o varios segundos entre llamadas.

Respuesta de muestra

{
  "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 completarse correctamente:

  • Los documentos analizados se pueden encontrar en el contenedor de destino.
  • El método POST correcto devuelve un código de respuesta 202 Accepted que indica que el servicio ha creado la solicitud por lotes.
  • La solicitud POST también ha devuelto encabezados de respuesta, entre los que se incluye Operation-Location, que proporciona un valor utilizado en las solicitudes GET posteriores.

Limpieza de recursos

Si quiere limpiar y eliminar una suscripción de servicios de Azure AI, puede eliminar el recurso o el grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.

Pasos siguientes

Introducción la detección de PIIIntroducción al resumen de documentos