Suporte nativo de documentos para a Linguagem de IA do Azure (visualização)

  • Artigo

Importante

  • O suporte nativo a documentos é uma visualização fechada. Para solicitar acesso ao recurso nativo de suporte a documentos, preencha e envie o formulário Solicitar acesso às visualizações do Serviço de Idiomas.

  • As versões de visualização pública do Azure AI Language fornecem acesso antecipado a recursos que estão em desenvolvimento ativo.

  • Recursos, abordagens e processos podem mudar, antes da Disponibilidade Geral (GA), com base nos comentários dos usuários.

O Azure AI Language é um serviço baseado na nuvem que aplica recursos de Processamento de Linguagem Natural (NLP) 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 em seu contêiner de destino do 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 nativo a documentos elimina a necessidade de pré-processamento de texto antes de usar os recursos de recursos da Linguagem de IA do Azure. Atualmente, o suporte nativo a documentos está disponível para os seguintes recursos:

  • Informações de identificação pessoal (PII). O recurso de deteção de PII pode identificar, categorizar e redigir informações confidenciais em texto não estruturado. A PiiEntityRecognition API suporta processamento nativo de documentos.

  • Resumo de documentos. 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 AbstractiveSummarization APIs suportam ExtractiveSummarization processamento nativo de documentos.

Formatos de documento suportados

Os aplicativos usam formatos de arquivo nativos para criar, salvar ou abrir documentos nativos. Atualmente, os recursos de PII e resumo de documentos suportam os seguintes formatos de documentos nativos:

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

Diretrizes de entrada

Formatos de ficheiro suportados

Type Suporte e Limitações
PDFs Não há suporte para PDFs totalmente digitalizados.
Texto dentro de imagens Não há suporte para imagens digitais com texto incorporado.
Mesas digitais Não há suporte para tabelas em documentos digitalizados.

Tamanho do documento

Atributo Limite de entrada
Número total de documentos por pedido ≤ 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 de API REST.

    Nota

    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

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

  • 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 de linguagem de serviço único (não um recurso de serviços de IA do Azure multisserviço):

    Preencha os campos de detalhes do projeto de recurso de idioma e da instância da seguinte maneira:

    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 pré-existente 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 (RBAC) 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 Rever + 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.

Recuperar seu ponto de extremidade de serviço de chave e 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ê criou um novo recurso, depois que ele for implantado, selecione Ir para recurso. Se você tiver um recurso de serviço de idioma existente, navegue diretamente para sua página de recurso.

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

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

Criar contêineres de Armazenamento de 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:

Para este projeto, autenticamos o source location acesso às URLs 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.

Captura de ecrã de um url de armazenamento com o token SAS anexado.

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

Gorjeta

Como estamos processando um único arquivo (blob), recomendamos que você delegue o acesso SAS no nível de blob.

Solicitar cabeçalhos e parâmetros

parâmetro Description
-X POST <endpoint> Especifica seu ponto de extremidade de recurso de idioma para acessar a API.
--header Content-Type: application/json O tipo de conteúdo para enviar dados JSON.
--header "Ocp-Apim-Subscription-Key:<key> Especifica a chave de recurso Language para acessar a API.
-data O arquivo JSON que contém os dados que você deseja passar com sua solicitação.

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 Document Summarization exemplo de Personally Identifiable Information (PII) código:

Documento de exemplo de PII

Para este início rápido, você precisa de um documento de origem carregado em seu contêiner de origem. Você pode baixar nosso documento de exemplo do Microsoft Word ou Adobe PDF para este projeto. 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 pii-detection.json em seu diretório de documento nativo.

  3. Copie e cole o seguinte exemplo de solicitação de informações pessoalmente identificáveis (PII) em seu pii-detection.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

{
    "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 de origem location é a URL SAS do documento de origem (blob), não a URL SAS do contêiner de origem.

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

Executar a solicitação POST

  1. Aqui está 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 sua instância de serviço de idioma do portal do Azure.

    Importante

    Lembre-se de remover a chave do seu código quando terminar e nunca publicá-la 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 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"

    prompt de comando / 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. Aqui está 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 um jobId que pode ser consultado 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 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 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 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 de serviço de Language no portal do Azure.

Obter pedido

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

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.

Próximos passos

Visão geral da deteção de PII Visão geral do resumo de documentos