Como criar um projeto personalizado de reconhecimento de entidades nomeadas (NER)

Use este artigo para saber como configurar os requisitos para começar com o NER personalizado e criar um projeto.

Pré-requisitos

Antes de começar a usar o NER personalizado, você precisa:

• Uma assinatura do Azure - Crie uma gratuitamente.

Criar um recurso de idioma

Antes de começares a usar NER personalizado, precisas de um recurso Azure Language no Foundry Tools. Recomendamos que você crie seu recurso de idioma e conecte uma conta de armazenamento a ele no portal do Azure. Criar um recurso no portal do Azure permite criar uma conta de armazenamento do Azure ao mesmo tempo, com todas as permissões necessárias pré-configuradas. Você também pode ler mais no artigo para saber como usar um recurso preexistente e configurá-lo para trabalhar com reconhecimento personalizado de entidade nomeada.

Você também precisa de uma conta de armazenamento do Azure onde carregue seus .txt documentos que são usados para treinar um modelo para extrair entidades.

Criar recurso de idioma e conectar conta de armazenamento

Você pode criar um recurso das seguintes maneiras:

• O portal do Azure
• PowerShell

Criar um novo recurso a partir do portal do Azure

1. Inicie sessão no portal Azure para criar um novo recurso Azure Language no Foundry Tools.

2. Na janela exibida, selecione Classificação de texto personalizada & reconhecimento de entidade nomeada personalizada nos recursos personalizados. Selecione Continuar para criar seu recurso na parte inferior da tela.

   

3. Crie um recurso de idioma com os seguintes detalhes.

   Nome	Descrição
   Subscrição	A sua subscrição do Azure.
   Grupo de recursos	Um grupo de recursos que contém o teu recurso. Você pode usar um existente ou criar um novo.
   Região	A região do seu recurso de idioma. Por exemplo, "West US 2."
   Nome	Um nome para o seu recurso.
   Escalão de preço	A nível de preços para o seu recurso de idioma. Você pode usar a camada Gratuito (F0) para experimentar o serviço.

   Nota

   Se receber uma mensagem a dizer "a sua conta de login não é proprietária do grupo de recursos da conta de armazenamento selecionada", a sua conta precisa de ter uma função de proprietário atribuída ao grupo de recursos antes de poder criar um recurso de Language. Entre em contato com o proprietário da assinatura do Azure para obter assistência.

4. Na seção Classificação de texto personalizada & reconhecimento de entidade nomeada personalizada, selecione uma conta de armazenamento existente ou selecione Nova conta de armazenamento. Estes valores servem para o ajudar a começar, e não necessariamente os valores da conta de armazenamento que pretende usar em ambientes de produção. Para evitar latência durante a construção do seu projeto, ligue-se a contas de armazenamento na mesma região do seu recurso de Língua.

   Valor da conta de armazenamento	Valor recomendado
   Nome da conta de armazenamento	Qualquer nome
   Tipo de conta de armazenamento	Armazenamento local redundante padrão (LRS)

5. Certifique-se de que o Aviso de IA Responsável está assinalado. Selecione Rever + criar na parte inferior da página e, em seguida, selecione Criar.

Criar um novo recurso de idioma usando o PowerShell

Você pode criar um novo recurso e uma conta de armazenamento usando os seguintes arquivos de modelo e parâmetros da CLI, que são hospedados no GitHub.

Edite os seguintes valores no arquivo de parâmetros:

Use o seguinte comando do PowerShell para implantar o modelo ARM (Azure Resource Manager) com os arquivos editados.

New-AzResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile <path-to-arm-template> `
  -TemplateParameterFile <path-to-parameters-file>

Consulte a documentação do modelo ARM para obter informações sobre como implantar modelos e arquivos de parâmetros.

Usando um recurso de idioma preexistente

Você pode usar um recurso de idioma existente para começar a usar o NER personalizado, desde que esse recurso atenda aos requisitos abaixo:

Para usar o reconhecimento personalizado de entidade nomeada, você precisa criar uma conta de armazenamento do Azure se ainda não tiver uma.

Habilite o gerenciamento de identidades para seu recurso

Seu recurso de idioma deve ter gerenciamento de identidade, para habilitá-lo usando o portal Azure:

1. Vá para o seu recurso de idioma
2. No menu à esquerda, na seção Gerenciamento de Recursos, selecione Identidade
3. Na aba Sistema atribuído, certifique-se de definir o Status como Ativado.

Habilitar o recurso personalizado de reconhecimento de entidade nomeada

Certifique-se de habilitar o recurso Classificação de texto personalizada / Reconhecimento de entidade nomeada personalizada do portal do Azure.

1. Vá para o seu recurso de idioma no portal Azure.
2. No menu do lado esquerdo, na seção Gerenciamento de Recursos, selecione Recursos.
3. Ative o recurso de classificação de texto personalizada / reconhecimento de entidades nomeadas personalizadas.
4. Conecte sua conta de armazenamento.
5. Selecione Aplicar.

Adicionar funções necessárias

Use as etapas a seguir para definir as funções necessárias para o seu recurso de idioma e conta de armazenamento.

Papéis para o Azure Language no recurso Foundry Tools

1. Vá para sua conta de armazenamento ou recurso de idioma no portal do Azure.

2. Selecione Controle de acesso (IAM) no painel esquerdo.

3. Selecione Adicionar para Adicionar Atribuições de Função e escolha a função apropriada para sua conta.

   Você deve ter a função de proprietário ou colaborador atribuída em seu recurso de idioma.

4. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço

5. Selecionar membros

6. Selecione seu nome de usuário. Você pode pesquisar nomes de usuário no campo Selecionar . Repita isso para todas as funções.

7. Repita estas etapas para todas as contas de usuário que precisam acessar esse recurso.

Funções para sua conta de armazenamento

1. Aceda à página da sua conta de armazenamento no portal do Azure.
2. Selecione Controle de acesso (IAM) no painel esquerdo.
3. Selecione Adicionar para Adicionar Atribuições de Função e escolha a função de contribuinte de dados de blobs de armazenamento na conta de armazenamento.
4. Em Atribuir acesso a, selecione Identidade gerenciada.
5. Selecionar membros
6. Selecione sua assinatura e Idioma como a identidade gerenciada. Você pode pesquisar nomes de usuário no campo Selecionar .

Funções para o seu utilizador

1. Aceda à página da sua conta de armazenamento no portal do Azure.
2. Selecione Controle de acesso (IAM) no painel esquerdo.
3. Selecione Adicionar para Adicionar Atribuições de Função e escolha a função de contribuinte de dados de blobs de armazenamento na conta de armazenamento.
4. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço.
5. Selecionar membros
6. Selecione o seu Utilizador. Você pode pesquisar nomes de usuário no campo Selecionar .

Ativar CORS para sua conta de armazenamento

Certifique-se de permitir métodos (GET, PUT, DELETE) ao habilitar o CORS (Cross-Origin Resource Sharing). Defina o campo origens autorizadas como https://language.cognitive.azure.com. Permita todos os cabeçalhos adicionando * aos valores de cabeçalho permitidos e defina a idade máxima como 500.

Crie um projeto personalizado de reconhecimento de entidades nomeadas (API REST)

Depois que o contêiner de recursos e armazenamento estiver configurado, crie um novo projeto NER personalizado. Um projeto é uma área de trabalho para construir seus modelos de IA personalizados com base em seus dados. Somente você pode acessar seu projeto junto com outras pessoas que têm acesso ao recurso do Azure que está sendo usado. Se você rotulou dados, pode usá-los para começar importando um projeto.

Para começar a criar um modelo personalizado de reconhecimento de entidade nomeada, você precisa criar um projeto. Criar um projeto permite rotular dados, treinar, avaliar, melhorar e implantar seus modelos.

Crie uma solicitação PATCH usando a seguinte URL, cabeçalhos e corpo JSON para criar seu projeto.

URL do Pedido

Use a seguinte URL para criar um projeto. Substitua os seguintes espaços reservados pelos seus próprios valores.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}

Cabeçalhos da requisição

Use o cabeçalho a seguir para autenticar sua solicitação.

Corpo de solicitação

Use o JSON a seguir em sua solicitação. Substitua os seguintes espaços reservados pelos seus próprios valores.

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "CustomEntityRecognition",
  "description": "Project description",
  "multilingual": "True",
  "storageInputContainerName": "{CONTAINER-NAME}"
}

Essa solicitação retorna uma resposta 201, o que significa que o projeto foi criado.

Esta solicitação retorna um erro se:

• O recurso selecionado não tem permissão adequada para a conta de armazenamento.

Projeto de importação (API REST)

Se você já rotulou dados, pode usá-los para começar a usar o serviço. Certifique-se de que os dados rotulados seguem os formatos de dados aceitos.

Envie uma solicitação POST usando a seguinte URL, cabeçalhos e corpo JSON para importar seu arquivo de etiquetas. Certifique-se de que o ficheiro de etiquetas segue o formato aceite.

Se já existir um projeto com o mesmo nome, os dados desse projeto serão substituídos.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}

Cabeçalhos

Use o cabeçalho a seguir para autenticar sua solicitação.

Corpo

Use o JSON a seguir em sua solicitação. Substitua os valores de espaço reservado pelos seus próprios valores.

{
    "projectFileVersion": "{API-VERSION}",
    "stringIndexType": "Utf16CodeUnit",
    "metadata": {
        "projectName": "{PROJECT-NAME}",
        "projectKind": "CustomEntityRecognition",
        "description": "Trying out custom NER",
        "language": "{LANGUAGE-CODE}",
        "multilingual": true,
        "storageInputContainerName": "{CONTAINER-NAME}",
        "settings": {}
    },
    "assets": {
    "projectKind": "CustomEntityRecognition",
        "entities": [
            {
                "category": "Entity1"
            },
            {
                "category": "Entity2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "entities": [
                    {
                        "regionOffset": 0,
                        "regionLength": 500,
                        "labels": [
                            {
                                "category": "Entity1",
                                "offset": 25,
                                "length": 10
                            },
                            {
                                "category": "Entity2",
                                "offset": 120,
                                "length": 8
                            }
                        ]
                    }
                ]
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "entities": [
                    {
                        "regionOffset": 0,
                        "regionLength": 100,
                        "labels": [
                            {
                                "category": "Entity2",
                                "offset": 20,
                                "length": 5
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Depois de enviar sua solicitação de API, você receberá uma 202 resposta indicando que o trabalho foi enviado corretamente. Nos cabeçalhos de resposta, extraia o valor operation-location. Aqui está um exemplo do formato:

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} é utilizado para identificar o seu pedido, uma vez que esta operação é assíncrona. Use essa URL para obter o estado da tarefa de importação.

Possíveis cenários de erro para esta solicitação:

• O recurso selecionado não tem permissões adequadas para a conta de armazenamento.
• O storageInputContainerName especificado não existe.
• Código de idioma inválido é usado, ou se o tipo de código de idioma não é string.
• multilingual value é uma cadeia de caracteres e não um booleano.

Obtenha detalhes do projeto (API REST)

Use a seguinte solicitação GET para obter os detalhes do seu projeto. Substitua os valores de espaço reservado pelos seus próprios valores.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}?api-version={API-VERSION}

Cabeçalhos

Use o cabeçalho a seguir para autenticar sua solicitação.

Corpo da resposta

    {
        "createdDateTime": "2021-10-19T23:24:41.572Z",
        "lastModifiedDateTime": "2021-10-19T23:24:41.572Z",
        "lastTrainedDateTime": "2021-10-19T23:24:41.572Z",
        "lastDeployedDateTime": "2021-10-19T23:24:41.572Z",
        "projectKind": "CustomEntityRecognition",
        "storageInputContainerName": "{CONTAINER-NAME}",
        "projectName": "{PROJECT-NAME}",
        "multilingual": false,
        "description": "Project description",
        "language": "{LANGUAGE-CODE}"
    }

Depois de enviar o seu pedido de API, recebe uma 200 resposta a indicar sucesso e um corpo de resposta JSON com os detalhes do seu projeto.

Eliminar projeto (API REST)

Quando você não precisar mais do seu projeto, poderá excluí-lo com a seguinte solicitação DELETE . Substitua os valores de espaço reservado pelos seus próprios valores.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}

Cabeçalhos

Use o cabeçalho a seguir para autenticar sua solicitação.

Assim que envia o seu pedido de API, recebe uma 202 resposta a indicar sucesso, o que significa que o seu projeto é eliminado. Uma chamada bem-sucedida resulta num cabeçalho Operation-Location usado para verificar o estado da tarefa.

Próximos passos

• Você deve ter uma ideia do esquema de projeto que você usa para rotular seus dados.

• Depois de criar o projeto, podes começar a etiquetar os teus dados. Esse processo informa ao seu modelo de extração de entidade como interpretar o texto e é usado para treinamento e avaliação.