Compartilhar via

Como criar um projeto de reconhecimento de entidade nomeada (NER) personalizado

Neste artigo, saiba como configurar os requisitos para iniciar o NER personalizado e criar um projeto.

Pré-requisitos

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

Criar um Recurso de linguagem

Antes de começar a usar o NER personalizado, você precisa de um recurso do Azure Language in Foundry Tools. Recomendamos que você crie seu recurso de idioma e conecte uma conta de armazenamento a ele no portal do Azure. A criação de um recurso no portal do Azure permite que você crie 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 pré-existente e configurá-lo para trabalhar com o reconhecimento personalizado de entidade nomeada.

Você também precisa de uma conta de armazenamento do Azure onde você carrega seus .txt documentos usados para treinar um modelo para extrair entidades.

Observação

  • Você precisa ter uma função de proprietário atribuída no grupo de recursos para criar um recurso de Linguagem.
  • Se você conectar uma conta de armazenamento pré-existente, deverá ter uma função de proprietário atribuída.

Criar recurso de Linguagem e conectar conta de armazenamento

Você pode criar um recurso da seguinte maneira:

  • O Portal do Azure
  • PowerShell

Observação

Você não deve mover a conta de armazenamento para um grupo de recursos ou uma assinatura diferente depois que ela estiver vinculada ao recurso de Linguagem do Azure.

Criar um recurso usando o portal do Azure

  1. Entre no portal do Azure para criar um novo recurso do Azure Language in Foundry Tools.

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

    Captura de tela mostrando a classificação de textos personalizada e o reconhecimento de entidade nomeada personalizada no portal do Azure.

  3. Crie um recurso de Linguagem com os detalhes a seguir.

    Nome Descrição
    Subscrição Sua assinatura do Azure.
    Grupo de recursos Um grupo de recursos que contém seu recurso. É possível usar um grupo existente ou criar um do zero.
    Região A região para seu recurso de linguagem. Por exemplo, "Oeste dos EUA 2".
    Nome Um nome para seu recurso.
    Tipo de preço O tipo de preço do recurso de linguagem. Use a camada Gratuita (F0) para experimentar o serviço.

    Observação

    Se você receber uma mensagem dizendo "sua conta de entrada não é um proprietário do grupo de recursos da conta de armazenamento selecionada", sua conta precisará ter uma função de proprietário atribuída no grupo de recursos antes que você possa criar um recurso de idioma. Entre em contato com o proprietário da assinatura do Azure para obter ajuda.

  4. Na seção Classificação de textos personalizada e reconhecimento de entidade nomeada personalizada, selecione uma conta de armazenamento existente ou Nova conta de armazenamento. Esses valores são para ajudá-lo a começar e não necessariamente os valores da conta de armazenamento que você deseja usar em ambientes de produção. Para evitar a latência durante a criação do projeto, conecte-se a contas de armazenamento na mesma região que o recurso de idioma.

    Valor de conta de armazenamento Valor recomendado
    Nome da conta de armazenamento Qualquer nome
    Tipo de conta de armazenamento LRS (armazenamento com redundância local) padrão

  5. Verifique se a opção Aviso de IA Responsável está marcada. Selecione Examinar + criar na parte inferior da página e depois Criar.

Criar um novo recurso de Linguagem usando o PowerShell

É possível criar um novo recurso e uma conta de armazenamento usando o modelo de CLI e os arquivos de parâmetros a seguir, que estão hospedados no GitHub.

Edite os seguintes valores no arquivo de parâmetros:

Nome do parâmetro Descrição do valor
name Nome do recurso do Language
location Região que hospeda o recurso. Para saber mais, confira Limites de serviço.
sku Tipo de preço do recurso.
storageResourceName O nome da conta de armazenamento
storageLocation Região na qual sua conta de armazenamento está hospedada.
storageSkuType SKU da conta de armazenamento.
storageResourceGroupName Grupo de recursos da conta de armazenamento

Use o comando do PowerShell a seguir para implantar o modelo do ARM (Azure Resource Manager) com os arquivos que você editou.

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

Consulte a documentação do modelo do ARM para saber como implantar modelos e arquivos de parâmetro.

Observação

  • O processo de conexão de uma conta de armazenamento ao recurso de idioma é irreversível. Ele não pode ser desconectado mais tarde.
  • É possível conectar o recurso de linguagem a apenas uma conta de armazenamento.

Usando um recurso linguístico pré-existente

É possível usar um recurso de Linguagem existente para começar a usar o NER personalizado, desde que ele atenda aos requisitos abaixo:

Requisito Descrição
Regiões Verifique se o recurso existente está provisionado em uma das regiões com suporte. Caso contrário, você precisará criar um novo recurso em uma dessas regiões.
Tipo de preço Saiba mais sobre os tipos de preço com suporte.
Identidade gerenciada Habilite a configuração da identidade gerenciada do recurso. Se ela não estiver habilitada, veja a próxima seção.

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

Habilitar o gerenciamento de identidade para o recurso

O recurso de Linguagem deve ter gerenciamento de identidade, para habilitá-lo usando o portal do Azure:

  1. Acessar o recurso de Linguagem
  2. No menu à esquerda, na seção Gerenciamento de Recursos, selecione Identidade
  3. Na guia Atribuído pelo sistema, defina o Status como Ativado

Habilite o recurso de reconhecimento de entidade nomeada personalizada

Habilite o recurso Classificação de textos personalizada/Reconhecimento de entidade nomeada personalizada no portal do Azure.

  1. Acesse o recurso de linguagem no portal do Azure.
  2. No menu do lado esquerdo, na seção Gerenciamento de Recursos, selecione Recursos.
  3. Habilite o recurso Classificação de textos personalizada / Reconhecimento de entidade nomeada personalizada.
  4. Conecte-se à conta de armazenamento.
  5. Escolha Aplicar.

Importante

Verifique se o usuário que está fazendo alterações tenha a função colaborador de dados do blob de armazenamento atribuída a ele.

Adicionar funções necessárias

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

Imagem animada que mostra como definir funções no portal do Azure.

Funções para o recurso Azure Language in Foundry Tools

  1. Acesse a conta de armazenamento e o recurso de Linguagem 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 a conta.

    Você precisa ter a função de proprietário ou colaborador atribuída no recurso de Linguagem.

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

  5. Selecione Selecionar membros

  6. Selecione o nome de usuário. É possível pesquisar nomes de usuário no campo Selecionar. Repita isso para todas as funções.

  7. Repita essas etapas para todas as contas de usuário que precisam de acesso a esse recurso.

Funções para sua conta de armazenamento

  1. Acesse a página da 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 Colaborador de dados do blob de armazenamento na conta de armazenamento.
  4. Em Atribuir acesso a, selecione Identidade Gerenciada.
  5. Selecione Selecionar membros
  6. Selecione a assinatura e Linguagem como a identidade gerenciada. É possível pesquisar nomes de usuário no campo Selecionar.

Funções para seu usuário

Importante

Se você ignorar esta etapa, receberá um erro 403 ao tentar se conectar ao seu projeto personalizado. É importante que o usuário atual tenha essa função para acessar dados de blob da conta de armazenamento, mesmo que você seja o proprietário da conta de armazenamento.

  1. Acesse a página da 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 Colaborador de dados do blob de armazenamento na conta de armazenamento.
  4. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço.
  5. Selecione Selecionar membros
  6. Selecione seu Usuário. É possível pesquisar nomes de usuário no campo Selecionar.

Importante

Se você tiver uma rede virtual ou um ponto de extremidade privado, selecione Permitir que os serviços do Azure na lista de serviços confiáveis acessem essa conta de armazenamento no portal do Azure.

Habilite o CORS para sua conta de armazenamento

Permita os métodos (GET, PUT, DELETE) ao habilitar o CORS (compartilhamento de recursos entre origens). Defina o campo de origens permitido como https://language.cognitive.azure.com. Permita todo o cabeçalho adicionando * aos valores de cabeçalho permitidos e defina a idade máxima como 500.

Captura de tela que mostra como usar o CORS para contas de armazenamento.

Criar um projeto personalizado de reconhecimento de entidade nomeada (API REST)

Depois de configurar o recurso e o contêiner de armazenamento, crie um novo projeto NER personalizado. Um projeto é uma área de trabalho para a criação de 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 os dados, poderá usá-los para começar importando um projeto.

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

Observação

O nome do projeto diferencia maiúsculas e minúsculas em todas as operações.

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

URL de Solicitação

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

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
{API-VERSION} A versão da API que você está chamando. O valor referenciado é para a versão mais recente lançada. Para obter mais informações, confiraCiclo de vida do modelo. 2022-05-01

Cabeçalhos da solicitação

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

Chave Obrigatório Tipo Valor
Ocp-Apim-Subscription-Key Verdade cadeia A chave para o recurso. Usado para autenticação de suas solicitações de API.
Content-Type Verdade cadeia application/merge-patch+json

Corpo da solicitação

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

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "CustomEntityRecognition",
  "description": "Project description",
  "multilingual": "True",
  "storageInputContainerName": "{CONTAINER-NAME}"
}
Chave Espaço reservado Valor Exemplo
projectName {PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
linguagem {LANGUAGE-CODE} Uma cadeia de caracteres que especifica o código de idioma para os documentos usados no projeto. Se o projeto for um projeto multilíngue, selecione o código para o idioma representado com mais frequência nos documentos. Confira Suporte de idioma para saber mais sobre os códigos de idioma compatíveis. en-us
tipoDeProjeto CustomEntityRecognition O tipo de projeto. CustomEntityRecognition
multilíngue true Um valor booliano que permite ter documentos em vários idiomas no conjunto de dados e, quando o modelo é implantado, é possível consultar o modelo em qualquer idioma com suporte, (não necessariamente incluído nos documentos de treinamento). Confira suporte de idioma para saber mais sobre o suporte multilíngue. true
storageInputContainerName {CONTAINER-NAME O nome do contêiner de armazenamento do Azure no qual seus documentos foram carregados. myContainer

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

Essa solicitação retornará um erro se:

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

Importar projeto (API REST)

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

Envie uma solicitaçãoPOST usando o URL, os cabeçalhos e o corpo JSON a seguir para importar o arquivo de rótulos. Verifique se o arquivo de rótulos segue o formato de arquivo aceito.

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}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
{API-VERSION} A versão da API que você está chamando. O valor referenciado aqui é para a versão mais recente lançada. Para obter mais informações, consulteo ciclo de vida do modelo. 2022-05-01

headers

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

Chave Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API.

Corpo

Use o JSON a seguir em sua solicitação. Substitua os valores do espaço reservado pelos seus.

{
    "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
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
Chave Espaço reservado Valor Exemplo
api-version {API-VERSION} A versão da API que você está chamando. A versão usada aqui precisa ser a mesma versão da API na URL. Saiba mais sobre as outras versões de API disponíveis 2022-03-01-preview
projectName {PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
projectKind CustomEntityRecognition O tipo de projeto. CustomEntityRecognition
language {LANGUAGE-CODE} Uma cadeia de caracteres que especifica o código de idioma para os documentos usados no projeto. Se o projeto for um projeto multilíngue, escolha o código de idioma da maioria dos documentos. en-us
multilingual true Um valor booliano que permite ter documentos em vários idiomas no conjunto de dados e, quando o modelo é implantado, é possível consultar o modelo em qualquer idioma com suporte, não necessariamente incluído nos documentos de treinamento. Confira suporte de idioma para obter informações sobre suporte multilíngue. true
storageInputContainerName {NOME DO CONTÊINER} O nome do contêiner de armazenamento do Azure que contém seus documentos carregados. myContainer
entities Matriz que contém todos os tipos de entidade que você tem no projeto e extraídos de seus documentos.
documents Matriz que contém todos os documentos no projeto e lista das entidades rotuladas em cada documento. []
location {DOCUMENT-NAME} O local dos documentos no contêiner de armazenamento. doc1.txt
dataset {DATASET} O conjunto de testes para o qual esse arquivo vai quando dividido antes do treinamento. Para obter mais informações, consulteComo treinar um modelo. Os valores possíveis para esse campo são Train e Test. Train

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} é usado para identificar sua solicitação, pois essa operação é assíncrona. Use esta URL para obter o status da tarefa de importação.

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

  • O recurso selecionado não tem as permissões apropriadas para a conta de armazenamento.
  • O storageInputContainerName especificado não existe.
  • Um código de idioma inválido foi usado ou o tipo de código de idioma não é cadeia de caracteres.
  • O valor multilingual é uma cadeia de caracteres e não um booliano.

Obter detalhes do projeto (API REST)

Use a solicitação GET a seguir para obter os detalhes do projeto. Substitua os valores do espaço reservado pelos seus.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}?api-version={API-VERSION}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
{API-VERSION} A versão da API que você está chamando. Para obter mais informações, consulteo ciclo de vida do modelo. 2022-05-01

headers

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

Chave Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API.

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}"
    }
Valor Espaço reservado Descrição Exemplo
projectKind CustomEntityRecognition O tipo de projeto. CustomEntityRecognition
storageInputContainerName {CONTAINER-NAME} O nome do contêiner de armazenamento do Azure para seus documentos carregados. myContainer
projectName {PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
multilingual true Um valor booliano que permite ter documentos em vários idiomas no conjunto de dados e, quando o modelo é implantado, é possível consultar o modelo em qualquer idioma com suporte, não necessariamente incluído nos documentos de treinamento. Para obter mais informações sobre suporte multilíngue, confira Suporte de linguagem. true
language {LANGUAGE-CODE} Uma cadeia de caracteres que especifica o código de idioma para os documentos usados no projeto. Se o projeto for um projeto multilíngue, escolha o código de idioma para a maioria dos documentos. en-us

Depois de enviar sua solicitação de API, você receberá uma 200 resposta que indica o êxito e o corpo da resposta JSON com os detalhes do projeto.

Excluir projeto (API REST)

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

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
{API-VERSION} A versão da API que você está chamando. O valor referenciado é para a versão mais recente lançada. Para obter mais informações, consulteo ciclo de vida do modelo. 2022-05-01

headers

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

Chave Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API.

Depois de enviar sua solicitação de API, você receberá uma 202 resposta indicando êxito, o que significa que seu projeto é excluído. Uma chamada bem-sucedida resulta em um cabeçalho Operation-Location usado para verificar o status do trabalho.

Próximas etapas

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

  • Depois que o projeto for criado, você poderá começar a rotular seus dados. Esse processo informa ao modelo de extração de entidade como interpretar texto e é usado para treinamento e avaliação.

  • Last updated on