Suporte a documentos nativos para a Linguagem de IA do Azure (versão prévia)

  • Artigo

Importante

  • O suporte a documentos nativos é uma versão prévia fechada. Para solicitar acesso ao recurso de suporte a documentos nativos, conclua e envie o formulário Candidatar-se para acesso à versão prévia do Serviço de Linguagem.

  • 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 Disponibilidade Geral (GA), 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 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.

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 a documentos nativos elimina a necessidade de pré-processamento de texto antes de usar os recursos de recurso do Azure AI Language. Atualmente, o suporte a documentos nativos está disponível para os seguintes recursos:

  • Informações de identificação pessoal (PII). O recurso de detecção de PII pode identificar, categorizar e redigir informações confidenciais em texto não estruturado. A API PiiEntityRecognition dá suporte ao processamento de documentos nativos.

  • Sumarização de documentos. 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.

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 ≤ 1 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 é pré-instalado na maioria dos 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

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

  • 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 de serviços de IA do Azure 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 grupo de recursos ou adicionar o recurso a um grupo de recursos 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 um RBAC (identidade gerenciada) atribuído 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:

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

Captura de tela de um URL de armazenamento com token SAS anexado.

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

Dica

Como estamos processando um único arquivo (blob), recomendamos delegar o acesso SAS no nível do blob.

Cabeçalhos e parâmetros de solicitação

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 PII

Para este início rápido, 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 projeto. 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 pii-detection.json no diretório native-document.

  3. Copie e cole a seguinte amostra de solicitação de PII (Informações de Identificação Pessoal) em seu arquivo pii-detection.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

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

  • O valor location da origem é a URL da SAS para o documento de origem (blob), não a URL da SAS do contêiner de origem.

  • Os valores possíveis de redactionPolicy são UseRedactionCharacterWithRefId (padrão) ou UseEntityTypeName. Para obter mais informações, consulte os Parâmetros do PiiTask.

Executar a solicitação POST

  1. Veja a estrutura preliminar da solicitação POST:

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

  2. Antes de executar a solicitação POST, substitua {your-language-resource-endpoint} e {your-key} pelos valores da instância do serviço de idioma 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, consulte a segurança dos serviços de IA do Azure.

    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"

    Terminal/prompt de comando

       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. Veja abaixo um 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=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

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:

Captura de tela mostrando o valor do local da operação na resposta POST.

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 preliminar da solicitação GET:

      GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-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=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}"

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

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.

Próximas etapas

Visão geral da detecção de PII Visão geral da Sumarização de Documentos