Guia de início rápido: reconhecimento personalizado de entidade nomeada

  • Artigo

Use este artigo para começar a criar um projeto NER personalizado onde você pode treinar modelos personalizados para reconhecimento de entidade personalizada. Um modelo é um software de inteligência artificial que é treinado para fazer uma determinada tarefa. Para este sistema, os modelos extraem entidades nomeadas e são treinados aprendendo com dados marcados.

Neste artigo, usamos o Language Studio para demonstrar conceitos-chave de Reconhecimento de Entidade Nomeada (NER) personalizado. Como exemplo, construiremos um modelo NER personalizado para extrair entidades relevantes de contratos de empréstimo, tais como:

  • Data do acordo
  • Nome, morada, cidade e estado do mutuário
  • Nome, morada, cidade e estado do credor
  • Montantes de empréstimos e juros

Pré-requisitos

Criar um novo recurso de linguagem de IA do Azure e uma conta de armazenamento do Azure

Antes de poder usar o NER personalizado, você precisará criar um recurso de linguagem de IA do Azure, que lhe dará as credenciais necessárias para criar um projeto e começar a treinar um modelo. Você também precisará de uma conta de armazenamento do Azure, onde poderá carregar seu conjunto de dados que será usado para criar seu modelo.

Importante

Para começar rapidamente, recomendamos a criação de um novo recurso de linguagem de IA do Azure usando as etapas fornecidas neste artigo. Usar as etapas neste artigo permitirá que você crie o recurso de idioma e a conta de armazenamento ao mesmo tempo, o que é mais fácil do que fazê-lo mais tarde.

Se você tiver um recurso pré-existente que gostaria de usar, precisará conectá-lo à conta de armazenamento. Consulte as orientações para usar um recurso pré-existente para obter informações.

Criar um novo recurso a partir do portal do Azure

  1. Entre no portal do Azure para criar um novo recurso de linguagem de IA do Azure.

  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.

    A screenshot showing custom text classification & custom named entity recognition in the Azure portal.

  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 conterá seu recurso. Você pode usar um existente ou criar um novo.
    País/Região A região do seu recurso Idioma. Por exemplo, "West US 2".
    Nome Um nome para o seu recurso.
    Escalão de preço A camada de preço para seu recurso de idioma. Você pode usar a camada Gratuito (F0) para experimentar o serviço.

    Nota

    Se você receber uma mensagem dizendo "sua conta de login não é proprietária 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 de poder criar um recurso de idioma. 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. Esses valores são para ajudá-lo a começar, e não necessariamente os valores da conta de armazenamento que você desejará usar em ambientes de produção. Para evitar latência durante a criação do projeto, conecte-se a contas de armazenamento na mesma região do recurso Idioma.

    Valor da conta de armazenamento Valor recomendado
    Nome da conta de armazenamento Qualquer nome
    Storage account type LRS padrão

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

Carregar dados de amostra para o contêiner de blob

Depois de criar uma conta de armazenamento do Azure e conectá-la ao seu recurso de idioma, você precisará carregar os documentos do conjunto de dados de exemplo para o diretório raiz do contêiner. Estes documentos serão posteriormente utilizados para treinar o seu modelo.

  1. Baixe o conjunto de dados de exemplo do GitHub.

  2. Abra o arquivo .zip e extraia a pasta que contém os documentos.

  3. No portal do Azure, navegue até a conta de armazenamento que você criou e selecione-a.

  4. Na sua conta de armazenamento, selecione Contêineres no menu à esquerda, localizado abaixo de Armazenamento de dados. Na tela exibida, selecione + Contêiner. Dê ao contêiner o nome example-data e deixe o nível de acesso público padrão.

    A screenshot showing the main page for a storage account.

  5. Depois que o contêiner for criado, selecione-o. Em seguida, selecione o botão Carregar para selecionar os .txt arquivos que .json você baixou anteriormente.

    A screenshot showing the button for uploading files to the storage account.

O conjunto de dados de amostra fornecido contém 20 contratos de empréstimo. Cada acordo inclui duas partes: um mutuante e um mutuário. Você pode usar o arquivo de exemplo fornecido para extrair informações relevantes para: ambas as partes, uma data de contrato, um valor de empréstimo e uma taxa de juros.

Criar um projeto personalizado de reconhecimento de entidade nomeada

Depois que sua conta de recursos e armazenamento estiver configurada, crie um novo projeto NER personalizado. Um projeto é uma área de trabalho para criar seus modelos de ML personalizados com base em seus dados. O seu projeto só pode ser acedido por si e por outras pessoas que tenham acesso ao recurso linguístico que está a ser utilizado.

  1. Entre no Language Studio. Será exibida uma janela para permitir que você selecione sua assinatura e recurso de idioma. Selecione o recurso de idioma que você criou na etapa acima.

  2. Na seção Extrair informações do Language Studio, selecione Reconhecimento personalizado de entidade nomeada.

    A screenshot showing the location of custom NER in the Language Studio landing page.

  3. Selecione Criar novo projeto no menu superior da página de projetos. Criar um projeto permitirá que você marque dados, treine, avalie, melhore e implante seus modelos.

    A screenshot of the project creation page.

  4. Depois de clicar em Criar novo projeto, aparecerá uma janela para permitir que você conecte sua conta de armazenamento. Se você já tiver conectado uma conta de armazenamento, verá o armazenamento contabilizado conectado. Caso contrário, escolha sua conta de armazenamento na lista suspensa exibida e selecione Conectar conta de armazenamento, isso definirá as funções necessárias para sua conta de armazenamento. Esta etapa possivelmente retornará um erro se você não estiver atribuído como proprietário na conta de armazenamento.

    Nota

    • Você só precisa fazer essa etapa uma vez para cada novo recurso usado.
    • Esse processo é irreversível, se você conectar uma conta de armazenamento ao seu recurso de idioma, não poderá desconectá-la mais tarde.
    • Você só pode conectar seu recurso de idioma a uma conta de armazenamento.

    A screenshot showing the storage connection screen.

  5. Insira as informações do projeto, incluindo um nome, uma descrição e o idioma dos arquivos em seu projeto. Se você estiver usando o conjunto de dados de exemplo, selecione Inglês. Você não poderá alterar o nome do seu projeto mais tarde. Selecione Seguinte

    Gorjeta

    Seu conjunto de dados não precisa estar totalmente no mesmo idioma. Você pode ter vários documentos, cada um com diferentes idiomas suportados. Se o conjunto de dados contiver documentos de idiomas diferentes ou se você esperar texto de idiomas diferentes durante o tempo de execução, selecione a opção habilitar conjunto de dados multilíngue ao inserir as informações básicas para seu projeto. Esta opção pode ser ativada posteriormente na página Configurações do projeto.

  6. Selecione o contêiner onde você carregou seu conjunto de dados. Se você já tiver rotulado dados, certifique-se de que eles seguem o formato suportado e selecione Sim, meus arquivos já estão rotulados e eu formatei o arquivo de rótulos JSON e selecione o arquivo de rótulos no menu suspenso. Selecione Seguinte.

  7. Revise os dados inseridos e selecione Criar projeto.

Preparar o modelo

Normalmente, depois de criar um projeto, você vai em frente e começa a marcar os documentos que você tem no contêiner conectado ao seu projeto. Para este início rápido, você importou um conjunto de dados marcado de exemplo e inicializou seu projeto com o arquivo de tags JSON de exemplo.

Para começar a treinar o seu modelo a partir do Language Studio:

  1. Selecione Trabalhos de treinamento no menu do lado esquerdo.

  2. Selecione Iniciar um trabalho de treinamento no menu superior.

  3. Selecione Treinar um novo modelo e digite o nome do modelo na caixa de texto. Você também pode substituir um modelo existente selecionando essa opção e escolhendo o modelo que deseja substituir no menu suspenso. A substituição de um modelo treinado é irreversível, mas não afetará os modelos implantados até que você implante o novo modelo.

    Create a new training job

  4. Selecione o método de divisão de dados. Você pode escolher Dividir automaticamente o conjunto de testes dos dados de treinamento, onde o sistema dividirá seus dados rotulados entre os conjuntos de treinamento e teste, de acordo com as porcentagens especificadas. Ou você pode usar uma divisão manual de dados de treinamento e teste, essa opção só é habilitada se você tiver adicionado documentos ao seu conjunto de testes durante a rotulagem de dados. Consulte Como treinar um modelo para obter informações sobre a divisão de dados.

  5. Selecione o botão Trem .

  6. Se você selecionar o ID do Trabalho de Treinamento na lista, um painel lateral aparecerá onde você poderá verificar o progresso do Treinamento, o status do Trabalho e outros detalhes para este trabalho.

    Nota

    • Apenas trabalhos de formação concluídos com sucesso gerarão modelos.
    • O treinamento pode levar algum tempo entre alguns minutos e várias horas com base no tamanho dos dados rotulados.
    • Só pode ter um trabalho de preparação em execução de cada vez. Não pode iniciar outro trabalho de preparação no mesmo projeto sem que o trabalho em execução esteja concluído.

Implementar o modelo

Geralmente, depois de treinar um modelo, você revisaria seus detalhes de avaliação e faria melhorias , se necessário. Neste início rápido, você apenas implantará seu modelo e o disponibilizará para experimentar no Language studio, ou poderá chamar a API de previsão.

Para implantar seu modelo a partir do Language Studio:

  1. Selecione Implantando um modelo no menu do lado esquerdo.

  2. Selecione Adicionar implantação para iniciar um novo trabalho de implantação .

    A screenshot showing the deployment button

  3. Selecione Criar nova implantação para criar uma nova implantação e atribuir um modelo treinado na lista suspensa abaixo. Você também pode substituir uma implantação existente selecionando essa opção e selecionando o modelo treinado que deseja atribuir a ela na lista suspensa abaixo.

    Nota

    A substituição de uma implantação existente não requer alterações na chamada da API de previsão, mas os resultados obtidos serão baseados no modelo recém-atribuído.

    A screenshot showing the deployment screen

  4. Selecione Implantar para iniciar o trabalho de implantação.

  5. Depois que a implantação for bem-sucedida, uma data de expiração aparecerá ao lado dela. A expiração da implantação é quando o modelo implantado não estará disponível para ser usado para previsão, o que normalmente acontece doze meses após a expiração de uma configuração de treinamento.

Testar o seu modelo

Depois que o modelo for implantado, você poderá começar a usá-lo para extrair entidades do texto por meio da API de previsão. Para este início rápido, você usará o Language Studio para enviar a tarefa de reconhecimento de entidade personalizada e visualizar os resultados. No conjunto de dados de exemplo que você baixou anteriormente, você pode encontrar alguns documentos de teste que você pode usar nesta etapa.

Para testar seus modelos implantados de dentro do Language Studio:

  1. Selecione Testando implantações no menu do lado esquerdo.

  2. Selecione a implantação que você deseja testar. Você só pode testar modelos atribuídos a implantações.

  3. Para projetos multilingues, na lista pendente de línguas, selecione a língua do texto que está a testar.

  4. Selecione a implantação que você deseja consultar/testar na lista suspensa.

  5. Pode introduzir o texto que pretende submeter ao pedido ou carregar um .txt ficheiro para utilizar.

  6. Selecione Executar o teste no menu superior.

  7. Na guia Resultado, você pode ver as entidades extraídas do seu texto e seus tipos. Você também pode exibir a resposta JSON na guia JSON .

A screenshot showing the model test results.

Clean up resources (Limpar recursos)

Quando você não precisar mais do seu projeto, poderá excluí-lo usando o Language Studio. Selecione Reconhecimento personalizado de entidade nomeada (NER) na parte superior, selecione o projeto que deseja excluir e selecione Excluir no menu superior.

Pré-requisitos

Criar um novo recurso de linguagem de IA do Azure e uma conta de armazenamento do Azure

Antes de poder usar o NER personalizado, você precisará criar um recurso de linguagem de IA do Azure, que lhe dará as credenciais necessárias para criar um projeto e começar a treinar um modelo. Você também precisará de uma conta de armazenamento do Azure, onde poderá carregar seu conjunto de dados que será usado na criação de seu modelo.

Importante

Para começar rapidamente, recomendamos criar um novo recurso de Linguagem de IA do Azure usando as etapas fornecidas neste artigo, que permitirão criar o recurso de Idioma e criar e/ou conectar uma conta de armazenamento ao mesmo tempo, o que é mais fácil do que fazê-lo mais tarde.

Se você tiver um recurso pré-existente que gostaria de usar, precisará conectá-lo à conta de armazenamento. Consulte criar projeto para obter informações.

Criar um novo recurso a partir do portal do Azure

  1. Entre no portal do Azure para criar um novo recurso de linguagem de IA do Azure.

  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.

    A screenshot showing custom text classification & custom named entity recognition in the Azure portal.

  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 conterá seu recurso. Você pode usar um existente ou criar um novo.
    País/Região A região do seu recurso Idioma. Por exemplo, "West US 2".
    Nome Um nome para o seu recurso.
    Escalão de preço A camada de preço para seu recurso de idioma. Você pode usar a camada Gratuito (F0) para experimentar o serviço.

    Nota

    Se você receber uma mensagem dizendo "sua conta de login não é proprietária 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 de poder criar um recurso de idioma. 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. Esses valores são para ajudá-lo a começar, e não necessariamente os valores da conta de armazenamento que você desejará usar em ambientes de produção. Para evitar latência durante a criação do projeto, conecte-se a contas de armazenamento na mesma região do recurso Idioma.

    Valor da conta de armazenamento Valor recomendado
    Nome da conta de armazenamento Qualquer nome
    Storage account type LRS padrão

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

Carregar dados de amostra para o contêiner de blob

Depois de criar uma conta de armazenamento do Azure e conectá-la ao seu recurso de idioma, você precisará carregar os documentos do conjunto de dados de exemplo para o diretório raiz do contêiner. Estes documentos serão posteriormente utilizados para treinar o seu modelo.

  1. Baixe o conjunto de dados de exemplo do GitHub.

  2. Abra o arquivo .zip e extraia a pasta que contém os documentos.

  3. No portal do Azure, navegue até a conta de armazenamento que você criou e selecione-a.

  4. Na sua conta de armazenamento, selecione Contêineres no menu à esquerda, localizado abaixo de Armazenamento de dados. Na tela exibida, selecione + Contêiner. Dê ao contêiner o nome example-data e deixe o nível de acesso público padrão.

    A screenshot showing the main page for a storage account.

  5. Depois que o contêiner for criado, selecione-o. Em seguida, selecione o botão Carregar para selecionar os .txt arquivos que .json você baixou anteriormente.

    A screenshot showing the button for uploading files to the storage account.

O conjunto de dados de amostra fornecido contém 20 contratos de empréstimo. Cada acordo inclui duas partes: um mutuante e um mutuário. Você pode usar o arquivo de exemplo fornecido para extrair informações relevantes para: ambas as partes, uma data de contrato, um valor de empréstimo e uma taxa de juros.

Obtenha suas chaves de recursos e ponto de extremidade

  1. Vá para a página de visão geral dos recursos no portal do Azure

  2. No menu do lado esquerdo, selecione Teclas e Ponto de extremidade. Você usará o ponto de extremidade e a chave para as solicitações de API

    A screenshot showing the key and endpoint page in the Azure portal

Criar um projeto NER personalizado

Depois que sua conta de recursos e armazenamento estiver configurada, crie um novo projeto NER personalizado. Um projeto é uma área de trabalho para criar seus modelos de ML personalizados com base em seus dados. O seu projeto só pode ser acedido por si e por outras pessoas que tenham acesso ao recurso linguístico que está a ser utilizado.

Use o arquivo de tags que você baixou dos dados de exemplo na etapa anterior e adicione-o ao corpo da solicitação a seguir.

Acionar trabalho de projeto de importação

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}
Marcador de Posição valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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 última versão lançada. Consulte Ciclo de vida do modelo para saber mais sobre outras versões de API disponíveis. 2022-05-01

Cabeçalhos

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

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Corpo

Use o JSON a seguir em sua solicitação. Substitua os valores de espaço reservado abaixo 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
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
Key Marcador de Posição valor Exemplo
api-version {API-VERSION} A versão da API que você está chamando. A versão usada aqui deve ser a mesma versão da API na URL. Saiba mais sobre 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 seu tipo de projeto. CustomEntityRecognition
language {LANGUAGE-CODE} Uma cadeia de caracteres especificando o código de idioma para os documentos usados em seu projeto. Se o seu projeto for multilingue, escolha o código linguístico da maioria dos documentos. en-us
multilingual true Um valor booleano que permite que você tenha documentos em vários idiomas em seu conjunto de dados e, quando seu modelo é implantado, você pode consultar o modelo em qualquer idioma suportado (não necessariamente incluído em seus documentos de treinamento. Consulte Suporte de idiomas para obter informações sobre suporte multilíngue. true
storageInputContainerName {NOME DO CONTÊINER} O nome do contêiner de armazenamento do Azure onde você carregou seus documentos. myContainer
entities Matriz contendo todos os tipos de entidade que você tem no projeto. Estes são os tipos de entidade que serão extraídos dos seus documentos.
documents Matriz contendo todos os documentos em seu projeto e lista das entidades rotuladas dentro de cada documento. []
location {DOCUMENT-NAME} A localização dos documentos no recipiente de armazenamento. Como todos os documentos estão na raiz do contêiner, este deve ser o nome do documento. doc1.txt
dataset {DATASET} O conjunto de testes para o qual este arquivo irá quando dividido antes do treinamento. Consulte Como treinar um modelo para obter mais informações sobre como seus dados são divididos. Os valores possíveis para este 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 operation-location valor. Será formatado da seguinte forma:

{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. Você usará essa URL para obter o status do trabalho 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.

Obter status de trabalho de importação

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

URL do Pedido

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
Marcador de Posição valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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
{JOB-ID} O ID para localizar o status de treinamento do seu modelo. Esse valor está no valor do location cabeçalho que você recebeu na etapa anterior. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que você está chamando. O valor referenciado aqui é para a última versão lançada. Consulte Ciclo de vida do modelo para saber mais sobre outras versões de API disponíveis. 2022-05-01

Cabeçalhos

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

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Preparar o modelo

Normalmente, depois de criar um projeto, você vai em frente e começa a marcar os documentos que você tem no contêiner conectado ao seu projeto. Para este início rápido, você importou um conjunto de dados marcado de exemplo e inicializou seu projeto com o arquivo de tags JSON de exemplo.

Iniciar trabalho de formação

Depois que seu projeto for importado, você poderá começar a treinar seu modelo.

Envie uma solicitação POST usando a seguinte URL, cabeçalhos e corpo JSON para enviar um trabalho de treinamento. Substitua os valores de espaço reservado abaixo pelos seus próprios valores.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}
Marcador de Posição valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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 última versão lançada. Consulte Ciclo de vida do modelo para saber mais sobre outras versões de API disponíveis. 2022-05-01

Cabeçalhos

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

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Corpo do pedido

Use o JSON a seguir no corpo da solicitação. O modelo será dado assim que o {MODEL-NAME} treinamento for concluído. Só empregos de formação bem sucedidos produzirão modelos.

{
	"modelLabel": "{MODEL-NAME}",
	"trainingConfigVersion": "{CONFIG-VERSION}",
	"evaluationOptions": {
		"kind": "percentage",
		"trainingSplitPercentage": 80,
		"testingSplitPercentage": 20
	}
}
Key Marcador de Posição valor Exemplo
modelLabel {MODEL-NAME} O nome do modelo que será atribuído ao seu modelo depois de treinado com sucesso. myModel
trainingConfigVersion {CONFIG-VERSION} Esta é a versão do modelo que será usada para treinar o modelo. 2022-05-01
avaliaçãoOpções Opção para dividir seus dados entre conjuntos de treinamento e teste. {}
variante percentage Métodos de divisão. Os valores possíveis são percentage ou manual. Consulte Como treinar um modelo para obter mais informações. percentage
formaçãoSplitPercentage 80 Porcentagem dos dados marcados a serem incluídos no conjunto de treinamento. O valor recomendado é 80. 80
testingSplitPercentage 20 Porcentagem dos dados marcados a serem incluídos no conjunto de testes. O valor recomendado é 20. 20

Nota

O trainingSplitPercentage e só são necessários se Kind for definido como percentage e testingSplitPercentage a soma de ambas as percentagens deve ser igual a 100.

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 location valor. Será formatado da seguinte forma:

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

{JOB-ID} é utilizado para identificar o seu pedido, uma vez que esta operação é assíncrona. Você pode usar essa URL para obter o status de treinamento.

Obter status de trabalho de treinamento

O treinamento pode levar entre 10 e 30 minutos para este conjunto de dados de amostra. Você pode usar a solicitação a seguir para continuar pesquisando o status do trabalho de treinamento até que ele seja concluído com êxito.

Use a seguinte solicitação GET para obter o status do progresso do treinamento do seu modelo. Substitua os valores de espaço reservado abaixo pelos seus próprios valores.

URL do Pedido

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
Marcador de Posição valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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
{JOB-ID} O ID para localizar o status de treinamento do seu modelo. Esse valor está no valor do location cabeçalho que você recebeu na etapa anterior. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que você está chamando. O valor referenciado aqui é para a última versão lançada. Consulte Ciclo de vida do modelo para saber mais sobre outras versões de API disponíveis. 2022-05-01

Cabeçalhos

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

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Organismo de resposta

Depois de enviar a solicitação, você receberá a seguinte resposta.

{
  "result": {
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{CONFIG-VERSION}",
    "estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2022-04-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "{JOB-ID}",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

Implementar o modelo

Geralmente, depois de treinar um modelo, você revisaria os detalhes da avaliação e faria melhorias, se necessário. Neste início rápido, você apenas implantará seu modelo e o disponibilizará para experimentar no Language Studio, ou poderá chamar a API de previsão.

Iniciar trabalho de implantação

Envie uma solicitação PUT usando a seguinte URL, cabeçalhos e corpo JSON para enviar um trabalho de implantação. Substitua os valores de espaço reservado abaixo pelos seus próprios valores.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}
Marcador de Posição valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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
{DEPLOYMENT-NAME} O nome da sua implantação. Esse valor diferencia maiúsculas de minúsculas. staging
{API-VERSION} A versão da API que você está chamando. O valor referenciado aqui é para a última versão lançada. Consulte Ciclo de vida do modelo para saber mais sobre outras versões de API disponíveis. 2022-05-01

Cabeçalhos

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

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Corpo do pedido

Use o JSON a seguir no corpo da sua solicitação. Use o nome do modelo que você atribui à implantação.

{
  "trainedModelLabel": "{MODEL-NAME}"
}
Key Marcador de Posição valor Exemplo
trainedModelLabel {MODEL-NAME} O nome do modelo que será atribuído à sua implantação. Você só pode atribuir modelos treinados com sucesso. Esse valor diferencia maiúsculas de minúsculas. myModel

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 operation-location valor. Será formatado da seguinte forma:

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

{JOB-ID} é utilizado para identificar o seu pedido, uma vez que esta operação é assíncrona. Você pode usar essa URL para obter o status da implantação.

Obter o status do trabalho de implantação

Use a seguinte solicitação GET para consultar o status do trabalho de implantação. Você pode usar a URL recebida da etapa anterior ou substituir os valores de espaço reservado abaixo por seus próprios valores.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
Marcador de Posição valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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
{DEPLOYMENT-NAME} O nome da sua implantação. Esse valor diferencia maiúsculas de minúsculas. staging
{JOB-ID} O ID para localizar o status de treinamento do seu modelo. Isso está no valor do location cabeçalho que você recebeu na etapa anterior. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que você está chamando. O valor referenciado aqui é para a última versão lançada. Consulte Ciclo de vida do modelo para saber mais sobre outras versões de API disponíveis. 2022-05-01

Cabeçalhos

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

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Organismo de resposta

Depois de enviar o pedido, obterá a seguinte resposta. Continue pesquisando este ponto de extremidade até que o parâmetro de status mude para "bem-sucedido". Você deve obter um 200 código para indicar o sucesso da solicitação.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Extrair entidades personalizadas

Depois que o modelo for implantado, você poderá começar a usá-lo para extrair entidades do texto usando a API de previsão. No conjunto de dados de exemplo que você baixou anteriormente, você pode encontrar alguns documentos de teste que você pode usar nesta etapa.

Enviar uma tarefa personalizada do NER

Use esta solicitação POST para iniciar uma tarefa de classificação de texto.

{ENDPOINT}/language/analyze-text/jobs?api-version={API-VERSION}
Marcador de Posição valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION} A versão da API que você está chamando. O valor referenciado aqui é para a última versão lançada. Consulte Ciclo de vida do modelo para saber mais sobre outras versões de API disponíveis. 2022-05-01

Cabeçalhos

Key valor
Ocp-Apim-Subscription-Key A sua chave que fornece acesso a esta API.

Corpo

{
  "displayName": "Extracting entities",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomEntityRecognition",
      "taskName": "Entity Recognition",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}
Key Marcador de Posição valor Exemplo
displayName {JOB-NAME} O nome do seu trabalho. MyJobName
documents [{},{}] Lista de documentos para executar tarefas. [{},{}]
id {DOC-ID} Nome ou ID do documento. doc1
language {LANGUAGE-CODE} Uma cadeia de caracteres especificando o código de idioma para o documento. Se essa chave não for especificada, o serviço assumirá o idioma padrão do projeto que foi selecionado durante a criação do projeto. Consulte Suporte a idiomas para obter uma lista de códigos de idiomas suportados. en-us
text {DOC-TEXT} Documentar a tarefa na qual executar as tarefas. Lorem ipsum dolor sit amet
tasks Lista de tarefas que queremos realizar. []
taskName CustomEntityRecognition O nome da tarefa CustomEntityRecognition
parameters Lista de parâmetros a serem passados para a tarefa.
project-name {PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
deployment-name {DEPLOYMENT-NAME} O nome da sua implantação. Esse valor diferencia maiúsculas de minúsculas. prod

Response

Você receberá uma resposta 202 indicando que sua tarefa foi enviada com sucesso. Nos cabeçalhos de resposta, extraia operation-location. operation-location está formatado assim:

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

Você pode usar essa URL para consultar o status de conclusão da tarefa e obter os resultados quando a tarefa for concluída.

Obter resultados de tarefas

Use a seguinte solicitação GET para consultar o status/resultados da tarefa de reconhecimento de entidade personalizada.

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}
Marcador de Posição valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION} A versão da API que você está chamando. O valor referenciado aqui é para a última versão lançada. Consulte Ciclo de vida do modelo para saber mais sobre outras versões de API disponíveis. 2022-05-01

Cabeçalhos

Key valor
Ocp-Apim-Subscription-Key A sua chave que fornece acesso a esta API.

Organismo de resposta

A resposta será um documento JSON com os seguintes parâmetros

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxx-xxxxx-xxxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "EntityRecognitionLROResults",
        "taskName": "Recognize Entities",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "entities": [
                {
                  "category": "Event",
                  "confidenceScore": 0.61,
                  "length": 4,
                  "offset": 18,
                  "text": "trip"
                },
                {
                  "category": "Location",
                  "confidenceScore": 0.82,
                  "length": 7,
                  "offset": 26,
                  "subcategory": "GPE",
                  "text": "Seattle"
                },
                {
                  "category": "DateTime",
                  "confidenceScore": 0.8,
                  "length": 9,
                  "offset": 34,
                  "subcategory": "DateRange",
                  "text": "last week"
                }
              ],
              "id": "1",
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

Clean up resources (Limpar recursos)

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 por seus próprios valores.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}
Marcador de Posição valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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 última versão lançada. Consulte Ciclo de vida do modelo para saber mais sobre outras versões de API disponíveis. 2022-05-01

Cabeçalhos

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

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

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

Próximos passos

Depois de criar o modelo de extração de entidade, você pode:

Quando você começar a criar seus próprios projetos NER personalizados, use os artigos de instruções para saber mais sobre marcação, treinamento e consumo de seu modelo com mais detalhes: