Uso del resumen de documentos nativos (versión preliminar)

Importante

• Las versiones preliminares públicas de Lenguaje de Azure AI proporcionan acceso anticipado a las características que están en desarrollo activo.
• Las características, los enfoques y los procesos pueden cambiar, antes de la disponibilidad general (GA), 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. 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. 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. 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.

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
Mensaje de 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

Atributo	Límite de entrada
Número total de documentos por solicitud	≤ 20
Tamaño total del contenido por solicitud	≤ 10 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 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

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

  • Windows.
  • Mac o Linux.

• 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 de Azure AI Foundry multiservicio):

  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. Nivel de precios. 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:

• Tokens de firma de acceso compartido (SAS). Los tokens de SAS de delegación de usuarios se protegen con credenciales de Microsoft Entra. Un token de SAS proporciona acceso delegado y seguro 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 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.

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

La API de resumen extractivo usa técnicas de procesamiento de lenguaje natural para buscar oraciones clave en un documento de texto no estructurado. Estas oraciones transmiten colectivamente la idea principal del documento.

El resumen extractivo devuelve una puntuación de clasificación como parte de la respuesta del sistema, junto con las oraciones extraídas y su posición en los documentos originales. Una puntuación de clasificación es un indicador de lo pertinente que se determina que es una oración para la idea principal de un documento. El modelo proporciona una puntuación de entre 0 y 1 (ambos inclusive) a cada oración y devuelve las oraciones con mayor puntuación por solicitud. Por ejemplo, si solicita un resumen de tres oraciones, el servicio devuelve las tres oraciones con mayor puntuación.

Lenguaje de Azure AI incluye otra característica, la extracción de frases clave, que permite extraer información clave. Para decidir entre la extracción de frases clave y el resumen extractivo, estas son consideraciones útiles:

• La extracción de frases clave devuelve frases, mientras que el resumen mediante extracción devuelve oraciones.
• El resumen mediante extracción devuelve oraciones junto con una puntuación de clasificación y las oraciones clasificadas superiores se devuelven por solicitud.
• El resumen mediante extracción también devuelve la siguiente información de posición:
  • Desplazamiento: posición inicial de cada oración extraída.
  • Longitud: la longitud de cada frase extraída.

Determinación de cómo procesar los datos (opcional)

Envío de datos

Los documentos se envían a la API como cadenas de texto. El análisis se realiza tras la recepción de la solicitud. Como la API es asincrónica, es posible que haya un retraso entre el envío de una solicitud de API y la recepción de los resultados.

Cuando use esta característica, los resultados de la API estarán disponibles durante 24 horas desde el momento en que se ingiera la solicitud y se le indique en la respuesta. Después de este período de tiempo, los resultados se purgan y ya no están disponibles para la recuperación.

Obtención de resultados de resumen de texto

Cuando obtiene los resultados de la detección de idioma, puede transmitir los resultados a una aplicación o guardar la salida en un archivo en el sistema local.

Este es un ejemplo de contenido que puede enviar para su resumen, que se extrae mediante el artículo de blog de Microsoft Una representación holística hacia la inteligencia artificial integradora. Este artículo es solo un ejemplo. La API puede aceptar texto de entrada más largo. Para obtener más información, consultelímites de datos y servicios.

"En Microsoft, hemos estado en una búsqueda para avanzar en la inteligencia artificial más allá de las técnicas existentes, al adoptar un enfoque más holístico y centrado en el hombre para aprender y comprender. Como director de tecnología de servicios de Azure AI, he estado trabajando con un equipo de científicos e ingenieros increíbles para convertir esta misión en una realidad. En mi función, disfruto de una perspectiva única al observar la relación entre tres atributos de la cognición humana: texto monolingüe (X), señales sensoriales auditivas o visuales (Y) y multilingüe (Z). En la intersección de los tres, hay magia—que llamamos código XYZ, como se muestra en la figura 1—, una representación conjunta para crear una inteligencia artificial más eficaz que pueda hablar, escuchar, ver y comprender mejor a los humanos. Creemos que el código XYZ nos permitirá cumplir nuestra visión a largo plazo: conseguir un aprendizaje de transferencia entre dominios, así como modalidades e idiomas que se expanden. El objetivo es tener modelos previamente entrenados que puedan aprender conjuntamente representaciones para respaldar una amplia gama de tareas de IA posteriores, de manera similar a como lo hacen los humanos hoy en día. En los últimos cinco años, hemos logrado el rendimiento humano en las pruebas comparativas en el reconocimiento de voz conversacional, la traducción automática, la respuesta a preguntas conversacionales, la comprensión de lectura automática y los subtítulos de imágenes. Estos cinco avances nos dieron fuertes señales hacia nuestra aspiración más ambiciosa de generar un salto en las capacidades de la IA, logrando un aprendizaje multi-sensorial y multilingüe que se alinea más estrechamente con cómo los humanos aprenden y entienden. Creo que el código conjunto XYZ es un componente fundamental de esta aspiración, si se fundamenta en fuentes de conocimiento externas para las tareas de IA posteriores.

La solicitud de la API de resumen de texto se procesa al recibir la solicitud mediante la creación de un trabajo para el backend de la API. Si el trabajo se completa correctamente, se devolverá la salida de la API. La salida está disponible para su recuperación durante 24 horas. Después de este tiempo, se purgará. Debido a la compatibilidad con varios idiomas y con Emojis, la respuesta podría contener desplazamientos de texto. Para obtener más información, consultecómo procesar desplazamientos.

Cuando se usa el ejemplo anterior, la API podría devolver estas oraciones resumidas:

Resumen mediante extracción:

• "En Microsoft, hemos estado en una búsqueda para avanzar en la inteligencia artificial más allá de las técnicas existentes, al adoptar un enfoque más holístico y centrado en el hombre para aprender y comprender".
• "Creemos que el código XYZ nos permitirá cumplir nuestra visión a largo plazo: conseguir un aprendizaje de transferencia entre dominios, así como modalidades e idiomas que se expanden".
• "El objetivo es obtener modelos entrenados previamente que puedan aprender de forma combinada representaciones que admitan una amplia gama de tareas de IA descendentes, de forma similar a como lo hacen los usuarios hoy en día".

Resumen mediante extracción:

• Microsoft está adoptando un enfoque más holístico y centrado en el ser humano para el aprendizaje y la comprensión. Creemos que el código XYZ nos permitirá cumplir nuestra visión a largo plazo: conseguir un aprendizaje de transferencia entre dominios, así como modalidades e idiomas que se expanden. En los últimos cinco años, hemos logrado un rendimiento más humano en las pruebas comparativas".

Probar resumen extractivo de texto

Puede usar el resumen extractivo de texto para obtener resúmenes de artículos, trabajos o documentos. Para ver un ejemplo, consulte el artículo de inicio rápido.

Puede usar el parámetro sentenceCount para guiar cuántas oraciones se devuelven; el valor predeterminado es 3. El rango es de 1 a 20.

También puede usar el parámetro sortby para especificar en qué orden se devolverán las oraciones extraídas; puede ser Offset o Rank, y el valor predeterminado es Offset.

valor del parámetro	Descripción
Rango	Ordena las oraciones según su pertinencia para el documento de entrada, según lo decida el servicio.
Desplazar	Mantiene el orden original en el que aparecen las oraciones en el documento de entrada.

Probar resumen abstracto de texto

En el ejemplo siguiente se inicia con el resumen abstracto de texto:

1. Copie el comando siguiente en un editor de texto. En el ejemplo de BASH se usa el carácter de continuación de línea \. Si la consola o el terminal utiliza un carácter de continuación de línea diferente, utilice ese carácter en su lugar.

curl -i -X POST https://<your-language-resource-endpoint>/language/analyze-text/jobs?api-version=2023-04-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>" \
-d \
' 
{
  "displayName": "Text Abstractive Summarization Task Example",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "At Microsoft, we have been on a quest to advance AI beyond existing techniques, by taking a more holistic, human-centric approach to learning and understanding. As Chief Technology Officer of Azure AI services, I have been working with a team of amazing scientists and engineers to turn this quest into a reality. In my role, I enjoy a unique perspective in viewing the relationship among three attributes of human cognition: monolingual text (X), audio or visual sensory signals, (Y) and multilingual (Z). At the intersection of all three, there's magic—what we call XYZ-code as illustrated in Figure 1—a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We believe XYZ-code enables us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. The goal is to have pretrained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today. Over the past five years, we have achieved human performance on benchmarks in conversational speech recognition, machine translation, conversational question answering, machine reading comprehension, and image captioning. These five breakthroughs provided us with strong signals toward our more ambitious aspiration to produce a leap in AI capabilities, achieving multi-sensory and multilingual learning that is closer in line with how humans learn and understand. I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks."
      }
    ]
  },
  "tasks": [
    {
      "kind": "AbstractiveSummarization",
      "taskName": "Text Abstractive Summarization Task 1",
    }
  ]
}
'

2. Realice los siguientes cambios en el comando donde sea necesario:

   • Reemplace el valor your-language-resource-key por su clave.
   • Reemplace la primera parte de la dirección URL de la solicitud (your-language-resource-endpoint) por la dirección URL de su punto de conexión.

3. Abra una ventana del símbolo del sistema (por ejemplo: BASH).

4. Pegue el comando del editor de texto en la ventana del símbolo del sistema y ejecute el comando.

5. Obtenga el valor de operation-location del encabezado de respuesta. El valor tiene un aspecto similar a la siguiente dirección URL:

https://<your-language-resource-endpoint>/language/analyze-text/jobs/12345678-1234-1234-1234-12345678?api-version=2022-10-01-preview

6. Para obtener los resultados de la solicitud, use el siguiente comando cURL. Asegúrese de reemplazar <my-job-id> por el valor de identificador numérico que recibió del encabezado de respuesta operation-location anterior:

curl -X GET https://<your-language-resource-endpoint>/language/analyze-text/jobs/<my-job-id>?api-version=2022-10-01-preview \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>"

Respuesta JSON de ejemplo de resumen de texto abstracto

{
    "jobId": "cd6418fe-db86-4350-aec1-f0d7c91442a6",
    "lastUpdateDateTime": "2022-09-08T16:45:14Z",
    "createdDateTime": "2022-09-08T16:44:53Z",
    "expirationDateTime": "2022-09-09T16:44:53Z",
    "status": "succeeded",
    "errors": [],
    "displayName": "Text Abstractive Summarization Task Example",
    "tasks": {
        "completed": 1,
        "failed": 0,
        "inProgress": 0,
        "total": 1,
        "items": [
            {
                "kind": "AbstractiveSummarizationLROResults",
                "taskName": "Text Abstractive Summarization Task 1",
                "lastUpdateDateTime": "2022-09-08T16:45:14.0717206Z",
                "status": "succeeded",
                "results": {
                    "documents": [
                        {
                            "summaries": [
                                {
                                    "text": "Microsoft is taking a more holistic, human-centric approach to AI. We've developed a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We've achieved human performance on benchmarks in conversational speech recognition, machine translation, ...... and image captions.",
                                    "contexts": [
                                        {
                                            "offset": 0,
                                            "length": 247
                                        }
                                    ]
                                }
                            ],
                            "id": "1"
                        }
                    ],
                    "errors": [],
                    "modelVersion": "latest"
                }
            }
        ]
    }
}

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 resumen

Para este proyecto, 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 inicio rápido. 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 document-summarization.json en el directorio de documentos nativos.

3. Copie y pegue la solicitud de ejemplo de resumen de documentos en el archivo document-summarization.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

  {
  "tasks": [
    {
      "kind": "ExtractiveSummarization",
      "parameters": {
        "sentenceCount": 6
      }
    }
  ],
  "analysisInput": {
    "documents": [
      {
        "source": {
          "location": "{your-source-blob-SAS-URL}"
        },
        "targets": {
          "location": "{your-target-container-SAS-URL}"
        }
      }
    ]
  }
}

Ejecución de la solicitud POST

Antes de ejecutar la solicitud POST, reemplace {your-language-resource-endpoint} y {your-key} por el valor del punto de conexión de la instancia del recurso 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 los servicios de Azure AI.

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 "@document-summarization.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 "@document-summarization.json"

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 (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:

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

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

2. Esta es la estructura de la solicitud GET:

   GET {cognitive-service-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-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=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

Recibes una respuesta 200 (Éxito) 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 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": "ExtractiveSummarizationLROResults",
        "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/ExtractiveSummarization-0001/input.result.json"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-02-01-preview"
        }
      }
    ]
  }
}

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.

• Azure Portal
• Azure CLI

Pasos siguientes

Información general sobre el resumen de documentos