Como usar o resumo nativo de documentos (pré-visualização)

Language é um serviço baseado na cloud que aplica funcionalidades de Processamento de Linguagem Natural (PLN) a dados baseados em texto. A sumarização de documentos usa processamento de linguagem natural para gerar resumos extrativos (extração de frases salientes) ou abstratos (extração contextual de palavras) para documentos. Ambas as APIs AbstractiveSummarization e ExtractiveSummarization suportam o processamento nativo de documentos. Um documento nativo refere-se ao formato de arquivo usado para criar o documento original, como o Microsoft Word (docx) ou um arquivo de documento portátil (pdf). O suporte nativo a documentos elimina a necessidade de pré-processamento de texto antes de utilizar as capacidades de recursos da Linguagem. O recurso nativo de suporte a documentos permite que você envie solicitações de API de forma assíncrona, usando um corpo de solicitação HTTP POST para enviar seus dados e uma cadeia de caracteres de consulta de solicitação HTTP GET para recuperar os resultados de status. Seus documentos processados estão localizados em seu contêiner de destino do Armazenamento de Blobs do Azure.

Formatos de documento suportados

Os aplicativos usam formatos de arquivo nativos para criar, salvar ou abrir documentos nativos. Atualmente, a capacidade de PII e de resumo de documentos suporta os seguintes formatos de documento nativo:

Diretrizes de entrada

Formatos de ficheiro suportados

Tamanho do documento

Incluir documentos nativos com uma solicitação HTTP

Vamos começar:

• Para este projeto, usamos a ferramenta de linha de comando cURL para fazer chamadas de API REST.

  Observação

  O pacote cURL está pré-instalado na maioria das distribuições Windows 10 e Windows 11 e na maioria das distribuições macOS e Linux. Você pode verificar a versão do pacote com os seguintes comandos: Windows: curl.exe -V macOS curl -V Linux: curl --version

• Uma conta ativa do Azure. Se não tiver uma, poderá criar uma conta gratuita.

• Uma conta de Armazenamento de Blob do Azure. Você também precisa criar contêineres em sua conta de Armazenamento de Blob do Azure para seus arquivos de origem e de destino:

  • Recipiente de origem. Este contêiner é onde você carrega seus arquivos nativos para análise (obrigatório).
  • Recipiente de destino. Este contêiner é onde seus arquivos analisados são armazenados (obrigatório).

• Um recurso linguístico de serviço único (não um recurso Microsoft Foundry multi-serviço):

  Complete os campos do projeto e da instância do recurso Azure Language da seguinte forma:

  1. Subscrição. Selecione uma das suas subscrições do Azure disponíveis.

  2. Grupo de Recursos. Você pode criar um novo grupo de recursos ou adicionar seu recurso a um grupo de recursos preexistente que compartilha o mesmo ciclo de vida, permissões e políticas.

  3. Região de Recursos. Escolha Global , a menos que sua empresa ou aplicativo exija uma região específica. Se você estiver planejando usar uma identidade gerenciada atribuída ao sistema para autenticação, escolha uma região geográfica como West US.

  4. Nome. Introduza o nome que escolheu para o seu recurso. O nome escolhido deve ser exclusivo no Azure.

  5. Escalão de preço. Você pode usar o nível de preço gratuito (Free F0) para experimentar o serviço e atualizar posteriormente para um nível pago para produção.

  6. Selecione Revisar + Criar.

  7. Revise os termos de serviço e selecione Criar para implantar seu recurso.

  8. Depois que o recurso for implantado com êxito, selecione Ir para o recurso.

Recupere a sua chave e o endpoint da linguagem

Os pedidos para o Azure Language requerem uma chave de leitura e um endpoint personalizado para autenticar o acesso.

1. Se você criou um novo recurso, depois que ele for implantado, selecione Ir para recurso. Se tiver um recurso de Língua existente, navegue diretamente para a sua página de recursos.

2. No trilho esquerdo, em Gestão de Recursos, selecione Chaves e Ponto de Extremidade.

3. Podes copiar e colar o teu key e o teu Language instance endpoint nos exemplos de código para autenticar o teu pedido na Azure Language. Só é necessária uma chave para fazer uma chamada à API.

Criar contentores de Armazenamento Blob do Azure

Crie contêineres em sua conta de Armazenamento de Blob do Azure para arquivos de origem e de destino.

• Recipiente de origem. Este contêiner é onde você carrega seus arquivos nativos para análise (obrigatório).
• Recipiente de destino. Este contêiner é onde seus arquivos analisados são armazenados (obrigatório).

Autenticação

Seu recurso de idioma precisa de acesso concedido à sua conta de armazenamento antes de poder criar, ler ou excluir blobs. Há dois métodos principais que você pode usar para conceder acesso aos seus dados de armazenamento:

• Tokens de assinatura de acesso compartilhado (SAS). Os tokens SAS de delegação de usuários são protegidos com credenciais do Microsoft Entra. Os tokens SAS fornecem acesso seguro e delegado a recursos em sua conta de armazenamento do Azure.

• Controle de acesso baseado em função de identidade gerenciada (RBAC). As identidades gerenciadas para recursos do Azure são entidades de serviço que criam uma identidade do Microsoft Entra e permissões específicas para recursos gerenciados do Azure.

Para este projeto, autenticamos o acesso às URLs source location e target location com tokens SAS (Assinatura de Acesso Compartilhado) anexados como cadeias de caracteres de consulta. Cada token é atribuído a um blob (arquivo) específico.

• Seu contêiner ou blob de origem deve conceder acesso de leitura e listagem.
• O contêiner ou blob de destino deve designar acesso de gravação e acesso de leitura.

A API de resumo extrativo usa técnicas de processamento de linguagem natural para localizar frases-chave em um documento de texto não estruturado. Estas frases transmitem coletivamente a ideia principal do documento.

A sumarização extrativa retorna uma pontuação de classificação como parte da resposta do sistema, juntamente com as frases extraídas e sua posição nos documentos originais. Uma pontuação de classificação é um indicador de quão relevante uma frase é determinada para a ideia principal de um documento. O modelo atribui uma pontuação entre 0 e 1 (inclusive) a cada frase e devolve as frases com a pontuação mais elevada por pedido. Por exemplo, se você solicitar um resumo de três frases, o serviço retornará as três frases mais bem pontuadas.

Há outra funcionalidade na Linguagem, a extração de frases-chave, que pode extrair informação-chave. Para decidir entre a extração de frases-chave e a sumarização extrativa, aqui estão considerações úteis:

• A extração de frases-chave retorna frases, enquanto a sumarização extrativa retorna frases.
• A sumarização extrativa retorna frases juntamente com uma pontuação de classificação, e as sentenças mais bem classificadas são retornadas por solicitação.
• O resumo extrativo também retorna as seguintes informações posicionais:
  • Offset: A posição inicial de cada frase extraída.
  • Comprimento: O comprimento de cada frase extraída.

Determinar como processar os dados (opcional)

Envio de dados

Você envia documentos para a API como cadeias de texto. A análise é realizada aquando da receção do pedido. Como a API é assíncrona, pode haver um atraso entre o envio de uma solicitação de API e o recebimento dos resultados.

Quando você usa esse recurso, os resultados da API ficam disponíveis por 24 horas a partir do momento em que a solicitação foi ingerida e são indicados na resposta. Após esse período de tempo, os resultados são limpos e não estão mais disponíveis para recuperação.

Obter resultados de resumo de texto

Quando você obtém resultados da deteção de idioma, pode transmitir os resultados para um aplicativo ou salvar a saída em um arquivo no sistema local.

Aqui está um exemplo de conteúdo que você pode submeter para sumarização, que é extraído usando o artigo do blog da Microsoft A holistic representation towards integrative AI. Este artigo é apenas um exemplo. A API pode aceitar texto de entrada mais longo. Para obter mais informações, consulteLimites de dados e serviços.

"Na Microsoft, estamos em uma busca para avançar a IA além das técnicas existentes, adotando uma abordagem mais holística e centrada no ser humano para aprender e compreender. Como Diretor de Tecnologia da Foundry Tools, tenho trabalhado com uma equipa de cientistas e engenheiros incríveis para transformar esta missão em realidade. Na minha função, desfruto de uma perspetiva única na visualização da relação entre três atributos da cognição humana: texto monolingue (X), sinais sensoriais áudio ou visuais (Y) e multilingue (Z). Na interseção de todos os três, há magia — o que chamamos de código XYZ, conforme ilustrado na Figura 1 — uma representação conjunta para criar uma IA mais poderosa que pode falar, ouvir, ver e entender melhor os seres humanos. Acreditamos que o código XYZ nos permite cumprir nossa visão de longo prazo: aprendizagem de transferência entre domínios, abrangendo modalidades e idiomas. O objetivo é ter modelos pré-treinados que possam aprender em conjunto representações para apoiar uma ampla gama de tarefas de IA a jusante, da mesma forma que os humanos fazem hoje. Nos últimos cinco anos, alcançamos o desempenho humano em benchmarks em reconhecimento de fala conversacional, tradução automática, resposta a perguntas conversacionais, compreensão de leitura automática e legendagem de imagens. Esses cinco avanços nos forneceram sinais fortes em direção à nossa aspiração mais ambiciosa de produzir um salto nas capacidades de IA, alcançando uma aprendizagem multissensorial e multilíngue que está mais próxima de como os humanos aprendem e entendem. Acredito que o código conjunto XYZ é um componente fundamental dessa aspiração, quando baseado em fontes de conhecimento externas na fase subsequente das tarefas de IA.

A solicitação da API de resumo de texto é processada após o recebimento da solicitação, criando um trabalho para o back-end da API. Se o trabalho for bem-sucedido, a saída da API será retornada. A saída está disponível para recuperação por 24 horas. Após esse tempo, a saída é limpa. Devido ao suporte multilíngue e ao suporte a emojis, a resposta pode conter desvios de texto. Para obter mais informações, vejacomo processar deslocamentos.

Quando você usa o exemplo anterior, a API pode retornar estas frases resumidas:

Resumo extrativo:

• "Na Microsoft, estamos em uma busca para avançar a IA além das técnicas existentes, adotando uma abordagem mais holística e centrada no ser humano para aprender e compreender."
• "Acreditamos que o código XYZ nos permite cumprir nossa visão de longo prazo: aprendizagem de transferência entre domínios, abrangendo modalidades e idiomas."
• "O objetivo é ter modelos pré-treinados que possam aprender conjuntamente representações para apoiar uma ampla gama de tarefas de IA a jusante, da mesma forma que os humanos fazem hoje."

Resumo abstrato:

• "A Microsoft está adotando uma abordagem mais holística e centrada no ser humano para aprender e compreender. Acreditamos que o código XYZ nos permite cumprir nossa visão de longo prazo: aprendizagem de transferência entre domínios, abrangendo modalidades e idiomas. Nos últimos cinco anos, atingimos o desempenho humano em benchmarks em."

Experimente o resumo extrativo de texto

Você pode usar o resumo extrativo de texto para obter resumos de artigos, trabalhos ou documentos. Para ver um exemplo, consulte o artigo de início rápido.

Você pode usar o sentenceCount parâmetro para orientar quantas frases são retornadas, sendo 3 o padrão. O intervalo é de 1 a 20.

Você também pode usar o sortby parâmetro para especificar em que ordem as sentenças extraídas são retornadas - ou OffsetRank, com Offset sendo o padrão.

Experimente o resumo abstrato do texto

O exemplo a seguir ajuda você a começar com o resumo abstrato de texto:

1. Copie o comando seguinte para um editor de texto. O exemplo BASH usa o caractere de continuação de \ linha. Se o console ou terminal usar um caractere de continuação de linha diferente, use esse caractere.

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 Foundry Tools, 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. Faça as alterações seguintes ao comando, se for necessário:

   • Substitua o valor your-language-resource-key pela sua chave.
   • Substitua a primeira parte da URL your-language-resource-endpoint da solicitação pela URL do ponto de extremidade.

3. Abra uma janela de prompt de comando (por exemplo: BASH).

4. Cole o comando do editor de texto na janela do prompt de comando e execute o comando.

5. Obtenha o operation-location cabeçalho da resposta. O valor é semelhante ao seguinte URL:

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

6. Para obter os resultados da solicitação, use o seguinte comando cURL. Certifique-se de substituir <my-job-id> pelo valor de ID numérico que você recebeu do cabeçalho de resposta anterior operation-location :

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>"

Exemplo de resumo de texto abstrato Resposta JSON

{
    "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"
                }
            }
        ]
    }
}

Os seguintes comandos cURL são executados a partir de um shell BASH. Edite esses comandos com seu próprio nome de recurso, chave de recurso e valores JSON. Tente analisar documentos nativos selecionando o projeto ou Personally Identifiable Information (PII) exemplo de Document Summarization código:

Documento de exemplo de resumo

Para este projeto, você precisa de um documento de fonte carregado no seu contentor de fonte. Você pode baixar nosso documento de exemplo do Microsoft Word ou Adobe PDF para este início rápido. A língua de partida é o inglês.

Criar a solicitação POST

1. Usando seu editor ou IDE preferido, crie um novo diretório para seu aplicativo chamado native-document.

2. Crie um novo arquivo json chamado document-summarization.json em seu diretório de documento nativo.

3. Copie e cole o exemplo de solicitação de resumo de documento em seu document-summarization.json arquivo. Substitua {your-source-container-SAS-URL} e {your-target-container-SAS-URL} por valores da instância de contêineres de conta de armazenamento do portal do Azure:

Solicitar amostra

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

Executar a solicitação POST

Antes de executar a solicitação POST, substitua {your-language-resource-endpoint} e {your-key} pelo valor do ponto de extremidade da sua instância de recurso de linguagem no portal do Azure.

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"

prompt de comando / 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"

Exemplo de resposta:

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

Resposta do servidor POST (jobId)

Você recebe uma resposta 202 (Êxito) que inclui um cabeçalho só de leitura Operation-Location. O valor desse cabeçalho contém um jobId que pode ser consultado para obter o status da operação assíncrona e recuperar os resultados usando uma solicitação GET:

Obter resultados de análise (solicitação GET)

1. Após a solicitação POST bem-sucedida, pesquise o cabeçalho do local da operação retornado na solicitação POST para exibir os dados processados.

2. Aqui está a estrutura da solicitação GET :

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

3. Antes de executar o comando, faça estas alterações:

   • Substitua {jobId} pelo cabeçalho Operation-Location da resposta POST.

   • Substitua {your-language-resource-endpoint} e {your-key} pelos valores da sua instância Language no portal Azure.

Obter pedido

    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}"

Examinar a resposta

Você recebe uma resposta 200 (Sucesso) com saída JSON. O campo status indica o resultado da operação. Se a operação não estiver concluída, o valor de status será "running" ou "notStarted", e você deverá chamar a API novamente, manualmente ou por meio de um script. Recomendamos um intervalo de um segundo ou mais entre as chamadas.

Resposta da amostra

{
  "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"
        }
      }
    ]
  }
}

Após conclusão bem-sucedida

• Os documentos analisados podem ser encontrados no seu contêiner de destino.
• O método POST bem-sucedido retorna um código de 202 Accepted resposta indicando que o serviço criou a solicitação em lote.
• A solicitação POST também retornou cabeçalhos de resposta, incluindo Operation-Location que fornece um valor usado em solicitações GET subsequentes.

Limpar recursos

Para limpar e remover um recurso de IA do Azure, você pode excluir o recurso individual ou todo o grupo de recursos. Se você excluir o grupo de recursos, todos os recursos contidos também serão excluídos.

• portal do Azure
• CLI do Azure

Próximos passos