Como usar resumo de documentos nativos (versão prévia)

Importante

• As versões de visualização pública da Linguagem de IA do Azure fornecem acesso antecipado aos recursos que estão em desenvolvimento ativo.
• Recursos, abordagens e processos podem ser alterados antes da GA (Disponibilidade Geral), com base nos comentários do usuário.

A Linguagem de IA do Azure é um serviço baseado em nuvem que aplica recursos de NLP (Processamento de Linguagem Natural) a dados baseados em texto. O resumo do documento usa o processamento de linguagem natural para gerar resumos extrativos (extração de frase saliente) ou abstrativos (extração de palavras contextuais) para documentos. As APIs AbstractiveSummarization e ExtractiveSummarization dão suporte ao processamento de documentos nativos. Um documento nativo se refere ao formato de arquivo usado para criar o documento original, como Microsoft Word (docx) ou um formato portátil de documento (pdf). O suporte a documentos nativos elimina a necessidade de pré-processamento de texto antes de usar os recursos de recurso do Azure AI Language. 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 no contêiner de destino do seu Armazenamento de Blobs do Azure.

Formatos de documento com suporte

Os aplicativos usam formatos de arquivo nativos para criar, salvar ou abrir documentos nativos. Atualmente, as funcionalidades PII e Sumarização de documentos dão suporte aos seguintes formatos de documento nativo:

Tipo de arquivo	Extensão de arquivo	Descrição
Texto	.txt	Um documento de texto não formatado.
Adobe PDF	.pdf	Um documento formatado em formato portátil de documento.
Microsoft Word	.docx	Um arquivo de documento do Microsoft Word.

Diretrizes de entrada

Formatos de arquivo com suporte

Tipo	suporte e limitações
PDFs	PDFs totalmente verificados não têm suporte.
Texto em imagens	Não há suporte para imagens digitais com texto incorporado.
Tabelas digitais	Não há suporte para tabelas em documentos verificados.

Tamanho do documento

Atributo	Limite de entrada
Número total de documentos por solicitação	≤ 20
Tamanho total do conteúdo por solicitação	≤ 10 MB

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 à API REST.

  Observação

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

• Se o cURL não estiver instalado, aqui estão os links de instalação para sua plataforma:

  • Windows.
  • Mac ou Linux.

• Uma conta do Azure ativa. Se você não tem uma, crie uma conta gratuita.

• Uma conta de Armazenamento de Blobs do Azure. Você precisará criar contêineres na sua conta de armazenamento de blobs do Azure para os arquivos de origem e destino:

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

• Um recurso de linguagem de serviço único (não um recurso do Azure AI Foundry de vários serviços):

  Preencha os campos de detalhes do Projeto de recurso de linguagem e da instância da seguinte maneira:

  1. Assinatura. Selecione uma das suas assinaturas do Azure disponíveis.

  2. Grupo de Recursos. Você pode criar um novo grupo de recursos ou adicionar o recurso a um grupo de recursos pré-existente que compartilhe o mesmo ciclo de vida e as mesmas permissões e políticas.

  3. Região do recurso. Escolha Global, a menos que seu negócio ou aplicativo exija uma região específica. Se você estiver planejando usar uma identidade gerenciada atribuída pelo sistema para autenticação, escolha uma região geográfica como Oeste dos EUA.

  4. Nome. Insira o nome escolhido para o recurso. O nome escolhido deve ser exclusivo dentro do Azure.

  5. Tipo de preço. Use o tipo de preço gratuito (Free F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.

  6. Selecione Examinar + criar.

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

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

Recuperar a chave e o ponto de extremidade do serviço de idioma

As solicitações para o serviço de idioma exigem uma chave somente leitura e um ponto de extremidade personalizado para autenticar o acesso.

1. Se você tiver criado um novo recurso, depois que ele for implantado, selecione Ir para o recurso. Se você tiver um recurso de serviço de idioma existente, navegue diretamente até sua página de recursos.

2. No trilho à esquerda, em Gerenciamento de Recursos, selecione Chaves e Ponto de Extremidade.

3. Você pode copiar e colar seus key e language service instance endpoint nos exemplos de código para autenticar sua solicitação no serviço de linguagem. Apenas uma chave é necessária para fazer uma chamada à API.

Criar contêineres de armazenamento de blobs do Azure

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

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

Autenticação

Seu recurso de linguagem precisa ter acesso concedido à sua conta de armazenamento antes que ele possa criar, ler ou excluir blobs. Há dois métodos primários que você pode usar para conceder acesso aos seus dados de armazenamento:

• Tokens SAS (assinatura de acesso compartilhado). Os tokens SAS de delegação de usuário são protegidos com credenciais do Microsoft Entra. Um token SAS oferece acesso seguro e delegado aos recursos da conta de armazenamento do Azure.

• RBAC (controle de acesso baseado em função) de identidade gerenciada. 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) acrescentados como cadeias de caracteres de consulta. Cada token é atribuído a um blob específico (arquivo).

• O contêiner ou o blob de origem deve ter acesso de leitura e lista designado.
• O contêiner ou blob de destino deve ter acesso de gravação e lista designados.

A API de sumarização extrativa usa técnicas de processamento de linguagem natural para localizar orações-chave em um documento de texto não estruturado. Essas orações transmitem coletivamente a ideia principal do documento.

O resumo de extração retorna uma pontuação de classificação como parte da resposta do sistema, junto com orações extraídas e sua posição nos documentos originais. A pontuação de classificação é um indicador de relevância de uma oração em relação à ideia principal de um documento. O modelo atribui uma pontuação entre 0 e 1 (ambos inclusos) para cada oração e retorna as orações pontuadas mais altas de acordo com a solicitação. Por exemplo, se você solicitar um resumo de três orações, o serviço retornará as três orações com as pontuações mais altas.

Existe outro recurso na Linguagem de IA do Azure, a extração de frase-chave, que pode extrair informações essenciais. Para decidir entre extração de frase-chave e resumo extrativo, aqui estão considerações úteis:

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

Determinar como processar os dados (opcional)

Enviar dados

Os documentos são enviados para a API como cadeias de caracteres de texto. A análise é executada após o recebimento da solicitação. 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 isso é indicado 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 do resumo de texto

Quando você recebe os resultados da detecçã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 enviar para resumo, que é extraído usando o artigo do blog da Microsoft Uma representação holística em relação à IA integrativa. Este artigo é apenas um exemplo. A API pode aceitar texto de entrada mais longo. Para obter mais informações, consulteos limites de dados e de serviço.

"Na Microsoft, estamos nos esforçando para que a IA (inteligência artificial) supere as técnicas atuais. Para isso, usamos uma abordagem mais holística e centrada no aprendizado e na compreensão das pessoas. Como Diretor de Tecnologia dos Serviços de IA do Azure, tenho trabalhado para transformar essa busca em realidade com uma equipe de cientistas e engenheiros incríveis. Na minha função, eu adoto uma perspectiva exclusiva para visualizar a relação entre três atributos de cognição humana: texto (X), sinais sensoriais auditivos ou visuais (Y) e multilínge (Z). Na interseção de todos os três, há mágica, o que chamamos de código XYZ, conforme ilustrado na Figura 1, uma representação conjunta para criar uma IA mais poderosa que possa falar, ouvir, ver e entender melhor os seres humanos. Acreditamos que o código XYZ permitirá realizar nossa visão de longo prazo: aprendizado de transferência entre domínios, modalidades e idiomas abrangentes. A meta é ter modelos pré-treinados que possam aprender representações em conjunto para dar suporte a uma ampla variedade de tarefas de IA downstream, de maneira muito similar a como os humanos fazem hoje. Nos últimos cinco anos, alcançamos o desempenho humano em parâmetros de comparação no reconhecimento de fala conversacional, tradução de máquina, resposta a perguntas conversacionais, compreensão de leitura de máquina e legenda de imagem. Esses cinco avanços nos forneceram fortes sinais em direção à nossa aspiração mais ambiciosa de produzir um salto nas funcionalidades de IA, alcançando um aprendizado multissensorial e multilíngue mais próximo de como os humanos aprendem e entendem. Acredito que o código XYZ conjunto é um componente fundamental dessa aspitação, se fundamentado com fontes de conhecimento externas nas tarefas de IA downstream."

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

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

Sumarização extrativa:

• "Na Microsoft, estamos nos esforçando para que a IA (inteligência artificial) supere as técnicas atuais. Para isso, usamos uma abordagem mais holística e centrada no aprendizado e na compreensão das pessoas."
• "Acreditamos que o código XYZ permitirá realizar nossa visão de longo prazo: aprendizado de transferência entre domínios, modalidades e idiomas abrangentes."
• "A meta é ter modelos pré-treinados que possam aprender representações em conjunto para dar suporte a uma ampla variedade de tarefas de IA downstream, de maneira muito similar a como os humanos fazem hoje."

Sumarização abstrativa:

• "A Microsoft está adotando uma abordagem mais holística e centrada no aprendizado e na compreensão das pessoas. Acreditamos que o código XYZ permitirá realizar nossa visão de longo prazo: aprendizado de transferência entre domínios, modalidades e idiomas abrangentes. Nos últimos cinco anos, alcançamos desempenho humano nos parâmetros de comparação."

Experimentar o resumo extrativo de texto

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

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

Você também pode usar o parâmetro sortby para especificar em qual ordem as orações extraídas são retornadas: Offset ou Rank, Offset é o padrão.

valor do parâmetro	Descrição
Classificação	Ordena as frases de acordo com a relevância para o documento de entrada, como decidido pelo serviço.
Deslocamento	Mantém a ordem original em que as frases aparecem no documento de entrada.

Experimentar o resumo abstrativo de texto

O exemplo a seguir é iniciado com o resumo abstrativo de texto:

1. Copie o seguinte comando em um editor de texto. O exemplo de BASH usa o caractere de continuação de linha \. Se o console ou o 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 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. Faça as alterações a seguir no comando quando necessário:

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

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

4. Cole o comando do editor de texto na janela do prompt de comando e, em seguida, execute-o.

5. Obtenha operation-location do cabeçalho de resposta. O valor parece semelhante à 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 comando cURL a seguir. Substitua <my-job-id> pelo valor de ID numérica recebido do cabeçalho de resposta 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>"

Resposta JSON de exemplo do resumo de texto abstrativo

{
    "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	Descrição
-X POST <endpoint>	Especifica o ponto de extremidade de recurso de idioma para acessar a API.
--header Content-Type: application/json	Tipo de conteúdo para enviar dados JSON.
--header "Ocp-Apim-Subscription-Key:<key>	Especifica a chave de recurso de linguagem para acessar a API.
-data	O arquivo JSON que contém os dados que você deseja passar com sua solicitação.

Os comandos cURL a seguir são executados por meio de um shell BASH. Edite esses comandos com o nome do recurso, a chave do recurso e os valores de JSON desejados. Tente analisar documentos nativos selecionando o projeto de exemplo de código Personally Identifiable Information (PII) ou Document Summarization:

Documento de exemplo de resumo

Neste projeto, você precisa de um documento de origem carregado no contêiner de origem. Você pode baixar nosso documento de exemplo do Microsoft Word ou Adobe PDF para este início rápido. O idioma de origem é o inglês.

Compilar a solicitação POST

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

2. Crie um novo arquivo json chamado document-summarization.json no diretório native-document.

3. Copie e cole a amostra de solicitação da Sumarização de Documentos em seu arquivo document-summarization.json. Substitua {your-source-container-SAS-URL} e {your-target-container-SAS-URL} pelos valores da instância de contêineres da conta de Armazenamento do portal do Azure:

Amostra de solicitação

  {
  "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 instância de recurso de linguagem do portal do Azure.

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Para obter mais informações, confira a segurança dos serviços de IA 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"

Terminal/prompt de comando

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"

Resposta de exemplo:

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 POST (jobId)

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

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

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

2. Veja 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 essas alterações:

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

   • Substitua {your-language-resource-endpoint} e {your-key} pelos valores da instância do serviço de idioma no portal do Azure.

Solicitação 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}"

Examinar a resposta

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

Resposta de exemplo

{
  "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 a conclusão bem-sucedida:

• Os documentos analisados podem ser encontrados no contêiner de destino.
• O método POST bem-sucedido retorna um código de resposta 202 Accepted 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 os recursos

Se quiser limpar e remover uma assinatura dos Serviços de IA do Azure, você poderá excluir o recurso ou grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

• Portal do Azure
• Azure CLI

Próximas etapas

Visão geral do resumo do documento