Quickstart: Reconhecimento de entidades com nome personalizado

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

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

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

Pré-requisitos

Criar um novo recurso Azure Language e conta de armazenamento Azure

Antes de poder utilizar o NER personalizado, terá de criar um recurso Azure Language, que lhe dará as credenciais de que precisa para criar um projeto e começar a treinar um modelo. Também vai precisar de uma conta de armazenamento Azure, onde pode fazer o upload do seu conjunto de dados que será usado para construir o seu modelo.

Importante

Para começar rapidamente, recomendamos a criação de um novo recurso Azure Language utilizando os passos fornecidos neste artigo. A utilização dos passos neste artigo permitir-lhe-á criar a conta de recursos e armazenamento idiomas ao mesmo tempo, o que é mais fácil do que fazê-lo mais tarde.

Se tiver um recurso pré-existente que gostaria de utilizar, terá de conectá-lo à conta de armazenamento. Consulte a orientação para utilizar um recurso pré-existente para obter informações.

Criar um novo recurso a partir do portal do Azure

  1. Vá ao portal do Azure para criar um novo recurso Azure Language.

  2. Na janela que aparece, selecione o reconhecimento personalizado de classificação & de texto personalizado denominado entidade a partir das funcionalidades personalizadas. Clique Em Continuar a criar o seu recurso na parte inferior do ecrã.

    Uma imagem mostrando a classificação & personalizada de texto personalizado reconhecimento de entidade no portal do Azure.

  3. Crie um recurso 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á o seu recurso. Pode usar um existente, ou criar um novo.
    Region A região para o seu recurso linguístico. Por exemplo, "West US 2".
    Name Um nome para o seu recurso.
    Escalão de preço O nível de preços para o seu recurso Language. Pode utilizar o nível 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 no grupo de recursos antes de poder criar um recurso Language. Contacte o seu proprietário de subscrição Azure para obter assistência.

  4. Na secção de reconhecimento de entidade personalizada de classificação & de texto personalizado , selecione uma conta de armazenamento existente ou selecione Nova conta de armazenamento. Estes valores são para ajudá-lo a começar, e não necessariamente os valores da conta de armazenamento que você vai querer usar em ambientes de produção. Para evitar a latência durante a construção do seu projeto, ligue-se a contas de armazenamento na mesma região que o seu recurso Language.

    Valor da conta de armazenamento Valor recomendado
    Nome da conta de armazenamento Qualquer nome
    Tipo de conta de armazenamento LRs padrão
  5. Certifique-se de que o Aviso de IA Responsável é verificado. Selecione 'Rever + criar na parte inferior da página' e, em seguida, selecione Criar.

Faça o upload dos dados da amostra para o recipiente blob

Depois de ter criado uma conta de armazenamento Azure e a ter ligado ao seu recurso Language, terá de enviar os documentos do conjunto de dados da amostra para o diretório de raiz do seu recipiente. Estes documentos serão posteriormente utilizados para treinar o seu modelo.

  1. Descarregue o conjunto de dados da amostra do GitHub.

  2. Abra o ficheiro .zip e extrate a pasta que contém os documentos.

  3. Na portal do Azure, navegue para a conta de armazenamento que criou e selecione-a.

  4. Na sua conta de armazenamento, selecione Recipientes do menu esquerdo, localizado abaixo do armazenamento de Dados. No ecrã que aparece, selecione + Recipiente. Dê ao recipiente o nome de exemplo-dados e deixe o nível de acesso público predefinido.

    Uma imagem mostrando a página principal para uma conta de armazenamento.

  5. Depois de o seu recipiente ter sido criado, selecione-o. Em seguida, clique no botão Upload para selecionar os .txt ficheiros que .json descarregou anteriormente.

    Uma imagem mostrando o botão para o upload de ficheiros para a conta de armazenamento.

O conjunto de dados da amostra fornecido contém 20 contratos de empréstimo. Cada acordo inclui duas partes: um credor e um mutuário. Pode utilizar o ficheiro de amostra fornecido para extrair informações relevantes para: ambas as partes, uma data do acordo, um montante de empréstimo e uma taxa de juro.

Criar um projeto de reconhecimento de entidades com nome personalizado

Uma vez configurada a sua conta de recursos e armazenamento, crie um novo projeto NER personalizado. Um projeto é uma área de trabalho para construir os seus modelos ML personalizados com base nos seus dados. O seu projeto só pode ser acedido por si e por outros que tenham acesso ao recurso idioma que está a ser utilizado.

  1. Inscreva-se no Estúdio de Línguas. Uma janela parece permitir-lhe selecionar a sua subscrição e recurso de idioma. Selecione o recurso Language que criou no passo acima.

  2. Sob a secção de informações extrato do Language Studio, selecione o reconhecimento de entidade com nome personalizado.

    Uma imagem mostrando a localização do NER personalizado na página de aterragem do Language Studio.

  3. Selecione Criar novo projeto a partir do menu superior na página dos seus projetos. A criação de um projeto permitirá marcar dados, treinar, avaliar, melhorar e implementar os seus modelos.

    Uma imagem da página de criação do projeto.

  4. Depois de clicar, Criar um novo projeto, uma janela parece permitir-lhe ligar a sua conta de armazenamento. Se já ligou uma conta de armazenamento, verá o armazenamento contado ligado. Caso contrário, escolha a sua conta de armazenamento a partir do dropdown que aparece e clique na conta de armazenamento Connect; isto definirá as funções necessárias para a sua conta de armazenamento. Este passo possivelmente devolverá um erro se não for designado como proprietário na conta de armazenamento.

    Nota

    • Só precisa de fazer este passo uma vez para cada novo recurso que utilizar.
    • Este processo é irreversível, se ligar uma conta de armazenamento ao seu recurso idioma não poderá desligá-la mais tarde.
    • Só pode ligar o seu recurso Language a uma conta de armazenamento.

    Uma imagem mostrando o ecrã de ligação de armazenamento.

  5. Insira as informações do projeto, incluindo um nome, descrição e a linguagem dos ficheiros no seu projeto. Se estiver a utilizar o conjunto de dados de exemplo, selecione Inglês. Não poderá mudar o nome do seu projeto mais tarde. Clique em seguida

    Dica

    O seu conjunto de dados não tem de estar inteiramente na mesma língua. Pode ter vários documentos, cada um com diferentes línguas apoiadas. Se o seu conjunto de dados contiver documentos de diferentes idiomas ou se espera texto de diferentes idiomas durante o tempo de funcionamento, selecione ative a opção de conjunto de dados multilingue quando introduzir as informações básicas para o seu projeto. Esta opção pode ser ativada mais tarde a partir da página de definições do Projeto .

  6. Selecione o recipiente onde fez o upload do conjunto de dados. Se já tiver dados rotulados certifique-se de que segue o formato suportado e clique em Sim, os meus ficheiros já estão rotulados e eu formatei o ficheiro de etiquetas JSON e selecionei o ficheiro de etiquetas do menu suspenso. Clique em Seguinte.

  7. Reveja os dados introduzidos e selecione Create Project.

Preparar o seu modelo

Normalmente, depois de criar um projeto, vá em frente e comece a marcar os documentos que tem no recipiente ligado ao seu projeto. Para este arranque rápido, importou um conjunto de dados marcado por amostras e iniciou o seu projeto com o ficheiro de etiquetas JSON da amostra.

Para começar a treinar o seu modelo dentro do Estúdio de Línguas:

  1. Selecione trabalhos de formação do menu do lado esquerdo.

  2. Selecione Iniciar um trabalho de formação a partir do menu superior.

  3. Selecione Train um novo modelo e escreva o nome modelo na caixa de texto. Também pode substituir um modelo existente selecionando esta opção e escolhendo o modelo deseja substituir do menu suspenso. A sobreposição de um modelo treinado é irreversível, mas não afetará os seus modelos implantados até que implemente o novo modelo.

    Criar um novo trabalho de formação

  4. Selecione método de divisão de dados. Pode escolher dividir automaticamente o conjunto de testes a partir de dados de treino onde o sistema irá dividir os seus dados rotulados entre os conjuntos de treino e teste, de acordo com as percentagens especificadas. Ou pode utilizar uma divisão manual de dados de treino e teste, esta opção só está ativada se tiver adicionado documentos ao seu conjunto de testes durante a rotulagem dos dados. Veja como treinar um modelo para obter informações sobre a divisão de dados.

  5. Clique no botão Comboio .

  6. Se clicar no ID de Trabalho de Formação da lista, aparecerá um painel lateral onde poderá verificar o progresso da Formação, o estado do trabalho e outros detalhes para este trabalho.

    Nota

    • Só trabalhos de formação concluídos com sucesso gerarão modelos.
    • O treino pode demorar algum tempo entre alguns minutos e várias horas com base no tamanho dos seus 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.

Desdobre o seu modelo

Geralmente, após o treino de um modelo, você iria rever os seus detalhes de avaliação e fazer melhorias se necessário. Neste arranque rápido, basta implementar o seu modelo e disponibilizá-lo para que experimente em estúdio language, ou pode chamar a API de previsão.

Para implementar o seu modelo a partir do Estúdio de Línguas:

  1. Selecione Implementar uma modelo do menu do lado esquerdo.

  2. Clique em Adicionar implementação para iniciar um novo trabalho de implantação.

    Uma imagem mostrando o botão de implantação

  3. Selecione Criar uma nova implementação para criar uma nova implementação e atribuir uma modelo treinada a partir do dropdown abaixo. Também pode substituir uma implementação existente selecionando esta opção e selecionar o modelo treinado que pretende atribuir a ela a partir do dropdown abaixo.

    Nota

    A sobreescrita de uma implementação existente não requer alterações na sua chamada de API de previsão, mas os resultados que obtém serão baseados na modelo recentemente atribuída.

    Uma imagem mostrando o ecrã de implementação

  4. Clique em Implementar para iniciar o trabalho de implantação.

  5. Após o sucesso da implementação, aparecerá uma data de validade ao lado. A expiração da implementação é quando o seu modelo implantado não estará disponível para ser usado para previsão, o que normalmente acontece doze meses após o termo de uma configuração de treino.

Testar o seu modelo

Após a implementação do seu modelo, pode começar a usá-lo para extrair entidades do seu texto através da API de Previsão. Para este arranque rápido, você usará o Language Studio para submeter a tarefa de reconhecimento de entidade personalizada e visualizar os resultados. No conjunto de dados da amostra que descarregou anteriormente, pode encontrar alguns documentos de teste que pode utilizar neste passo.

Para testar os seus modelos implantados a partir do Estúdio de Línguas:

  1. Selecione implementações de teste a partir do menu do lado esquerdo.

  2. Selecione a implementação que pretende testar. Só é possível testar modelos que sejam atribuídos a implementações.

  3. Para projetos multilingues, a partir da queda do idioma, selecione a linguagem do texto que está a testar.

  4. Selecione a implementação desejada para consultar/testar a partir do dropdown.

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

  6. Clique em Executar o teste a partir do menu superior.

  7. No separador Resultados , pode ver as entidades extraídas do seu texto e dos seus tipos. Também pode ver a resposta JSON no separador JSON .

    Ver os resultados dos testes

Limpar os recursos

Quando já não precisa do seu projeto, pode eliminar o seu projeto usando o Language Studio. Selecione o reconhecimento de entidade nomeada por personalizado (NER) a partir do topo, selecione o projeto que pretende eliminar e clique em Apagar a partir do menu superior.

Pré-requisitos

Criar um novo recurso Azure Language e conta de armazenamento Azure

Antes de poder utilizar o NER personalizado, terá de criar um recurso Azure Language, que lhe dará as credenciais de que precisa para criar um projeto e começar a treinar um modelo. Também vai precisar de uma conta de armazenamento Azure, onde poderá fazer o upload do seu conjunto de dados que será utilizado na construção do seu modelo.

Importante

Para começar rapidamente, recomendamos a criação de um novo recurso Azure Language utilizando os passos fornecidos neste artigo, que lhe permitirão criar o recurso Language, e criar e/ou ligar uma conta de armazenamento ao mesmo tempo, o que é mais fácil do que fazê-lo mais tarde.

Se tiver um recurso pré-existente que gostaria de utilizar, terá de conectá-lo à conta de armazenamento. Consulte o projeto de criação para obter informações.

Criar um novo recurso a partir do portal do Azure

  1. Vá ao portal do Azure para criar um novo recurso Azure Language.

  2. Na janela que aparece, selecione o reconhecimento personalizado de classificação & de texto personalizado denominado entidade a partir das funcionalidades personalizadas. Clique Em Continuar a criar o seu recurso na parte inferior do ecrã.

    Uma imagem mostrando a classificação & personalizada de texto personalizado reconhecimento de entidade no portal do Azure.

  3. Crie um recurso 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á o seu recurso. Pode usar um existente, ou criar um novo.
    Region A região para o seu recurso linguístico. Por exemplo, "West US 2".
    Name Um nome para o seu recurso.
    Escalão de preço O nível de preços para o seu recurso Language. Pode utilizar o nível 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 no grupo de recursos antes de poder criar um recurso Language. Contacte o seu proprietário de subscrição Azure para obter assistência.

  4. Na secção de reconhecimento de entidade personalizada de classificação & de texto personalizado , selecione uma conta de armazenamento existente ou selecione Nova conta de armazenamento. Estes valores são para ajudá-lo a começar, e não necessariamente os valores da conta de armazenamento que você vai querer usar em ambientes de produção. Para evitar a latência durante a construção do seu projeto, ligue-se a contas de armazenamento na mesma região que o seu recurso Language.

    Valor da conta de armazenamento Valor recomendado
    Nome da conta de armazenamento Qualquer nome
    Tipo de conta de armazenamento LRs padrão
  5. Certifique-se de que o Aviso de IA Responsável é verificado. Selecione 'Rever + criar na parte inferior da página' e, em seguida, selecione Criar.

Faça o upload dos dados da amostra para o recipiente blob

Depois de ter criado uma conta de armazenamento Azure e a ter ligado ao seu recurso Language, terá de enviar os documentos do conjunto de dados da amostra para o diretório de raiz do seu recipiente. Estes documentos serão posteriormente utilizados para treinar o seu modelo.

  1. Descarregue o conjunto de dados da amostra do GitHub.

  2. Abra o ficheiro .zip e extrate a pasta que contém os documentos.

  3. Na portal do Azure, navegue para a conta de armazenamento que criou e selecione-a.

  4. Na sua conta de armazenamento, selecione Recipientes do menu esquerdo, localizado abaixo do armazenamento de Dados. No ecrã que aparece, selecione + Recipiente. Dê ao recipiente o nome de exemplo-dados e deixe o nível de acesso público predefinido.

    Uma imagem mostrando a página principal para uma conta de armazenamento.

  5. Depois de o seu recipiente ter sido criado, selecione-o. Em seguida, clique no botão Upload para selecionar os .txt ficheiros que .json descarregou anteriormente.

    Uma imagem mostrando o botão para o upload de ficheiros para a conta de armazenamento.

O conjunto de dados da amostra fornecido contém 20 contratos de empréstimo. Cada acordo inclui duas partes: um credor e um mutuário. Pode utilizar o ficheiro de amostra fornecido para extrair informações relevantes para: ambas as partes, uma data do acordo, um montante de empréstimo e uma taxa de juro.

Obtenha as suas chaves de recursos e ponto final

  1. Vá à página geral do seu recurso na portal do Azure

  2. A partir do menu do lado esquerdo, selecione Keys e Endpoint. Você usará o ponto final e a chave para os pedidos da API

    Uma imagem mostrando a página da chave e ponto final na portal do Azure

Criar um projeto NER personalizado

Uma vez configurada a sua conta de recursos e armazenamento, crie um novo projeto NER personalizado. Um projeto é uma área de trabalho para construir os seus modelos ML personalizados com base nos seus dados. O seu projeto só pode ser acedido por si e por outros que tenham acesso ao recurso idioma que está a ser utilizado.

Utilize o ficheiro tags que descarregou a partir dos dados da amostra no passo anterior e adicione-o ao corpo do seguinte pedido.

Desencadear trabalho de projeto de importação

Envie um pedido DE POST utilizando o seguinte URL, cabeçalhos e corpo JSON para importar o seu ficheiro de etiquetas. Certifique-se de que o ficheiro das suas etiquetas segue o formato aceite.

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

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}
Marcador de posição Valor Exemplo
{ENDPOINT} O ponto final para autenticar o seu pedido de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome para o seu projeto. Este valor é sensível a casos. myProject
{API-VERSION} A versão da API que está a ligar. O valor aqui referenciado é para a versão mais recente lançada. Consulte o ciclo de vida do Modelo para saber mais sobre outras versões API disponíveis. 2022-05-01

Cabeçalhos

Utilize o seguinte cabeçalho para autenticar o seu pedido.

Chave Valor
Ocp-Apim-Subscription-Key A chave do seu recurso. Utilizado para autenticar os seus pedidos de API.

Corpo

Utilize o seguinte JSON no seu pedido. 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
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
Chave Marcador de posição Valor Exemplo
api-version {API-VERSION} A versão da API que está a ligar. A versão aqui utilizada deve ser a mesma versão API no URL. Saiba mais sobre outras versões API disponíveis 2022-03-01-preview
projectName {PROJECT-NAME} O nome do seu projeto. Este valor é sensível a casos. myProject
projectKind CustomEntityRecognition O seu tipo de projeto. CustomEntityRecognition
language {LANGUAGE-CODE} Uma cadeia especificando o código de linguagem para os documentos utilizados no seu projeto. Se o seu projeto for um projeto multilíngue, escolha o código linguístico da maioria dos documentos. en-us
multilingual true Um valor booleano que lhe permite ter documentos em vários idiomas no seu conjunto de dados e quando o seu modelo é implementado pode consultar o modelo em qualquer idioma suportado (não necessariamente incluído nos seus documentos de formação. Consulte o suporte linguístico para obter informações sobre suporte multilíngue. true
storageInputContainerName {NOME DE CONTENTOR} O nome do seu recipiente de armazenamento Azure onde carregou os seus documentos. myContainer
entities Matriz que contém todos os tipos de entidades que você tem no projeto. Estes são os tipos de entidades que serão extraídos dos seus documentos.
documents Matriz que contém todos os documentos do seu projeto e lista das entidades rotuladas dentro de cada documento. []
location {DOCUMENT-NAME} A localização dos documentos no contentor de armazenamento. Uma vez que todos os documentos estão na raiz do recipiente, este deve ser o nome do documento. doc1.txt
dataset {DATASET} O conjunto de testes ao qual este ficheiro irá quando se separar antes do treino. Veja como treinar um modelo para obter mais informações sobre a forma como os seus dados são divididos. Os valores possíveis para este campo são Train e Test. Train

Assim que enviar o seu pedido de API, receberá uma 202 resposta indicando que o trabalho foi submetido corretamente. Nos cabeçalhos de resposta, extraia o operation-location valor. Será formatado assim:

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

{JOB-ID} é usado para identificar o seu pedido, uma vez que esta operação é assíncronea. Você vai usar este URL para obter o estatuto de trabalho importado.

Possíveis cenários de erro para este pedido:

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

Obtenha o estatuto de emprego de importação

Utilize o seguinte pedido GET para obter o estado da sua importação do seu 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 final para autenticar o seu pedido de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Este valor é sensível a casos. myProject
{JOB-ID} A identificação para localizar o estado de treino do seu modelo. Este valor está no valor do location cabeçalho que recebeu no passo anterior. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que está a ligar. O valor aqui referenciado é para a versão mais recente lançada. Consulte o ciclo de vida do Modelo para saber mais sobre outras versões API disponíveis. 2022-05-01

Cabeçalhos

Utilize o seguinte cabeçalho para autenticar o seu pedido.

Chave Valor
Ocp-Apim-Subscription-Key A chave do seu recurso. Utilizado para autenticar os seus pedidos de API.

Preparar o seu modelo

Normalmente, depois de criar um projeto, vá em frente e comece a marcar os documentos que tem no recipiente ligado ao seu projeto. Para este arranque rápido, importou um conjunto de dados marcado por amostras e iniciou o seu projeto com o ficheiro de etiquetas JSON da amostra.

Iniciar o trabalho de formação

Depois de o seu projeto ter sido importado, pode começar a treinar o seu modelo.

Submeta um pedido de CORREIO utilizando o seguinte URL, cabeçalhos e corpo JSON para submeter um trabalho de formação. 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 final para autenticar o seu pedido de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Este valor é sensível a casos. myProject
{API-VERSION} A versão da API que está a ligar. O valor aqui referenciado é para a versão mais recente lançada. Consulte o ciclo de vida do Modelo para saber mais sobre outras versões API disponíveis. 2022-05-01

Cabeçalhos

Utilize o seguinte cabeçalho para autenticar o seu pedido.

Chave Valor
Ocp-Apim-Subscription-Key A chave do seu recurso. Utilizado para autenticar os seus pedidos de API.

Corpo do pedido

Utilize o seguinte JSON no seu corpo de pedido. O modelo será dado assim que o {MODEL-NAME} treino estiver completo. Só trabalhos de formação bem sucedidos produzirão modelos.

{
	"modelLabel": "{MODEL-NAME}",
	"trainingConfigVersion": "{CONFIG-VERSION}",
	"evaluationOptions": {
		"kind": "percentage",
		"trainingSplitPercentage": 80,
		"testingSplitPercentage": 20
	}
}
Chave Marcador de posição Valor Exemplo
modeloLabel {MODEL-NAME} O nome modelo que será atribuído ao seu modelo uma vez treinado com sucesso. myModel
formaçãoConfigVersão {CONFIG-VERSION} Esta é a versão modelo que será usada para treinar o modelo. 2022-05-01
avaliaçõesOpções Opção de dividir os seus dados através de conjuntos de treino e teste. {}
tipo percentage Métodos divididos. Os valores possíveis são percentage ou manual. Veja como treinar um modelo para mais informações. percentage
formaçãoSplitPercentage 80 Percentagem dos seus dados marcados para serem incluídos no conjunto de treino. O valor recomendado é 80. 80
testesSplitPercentage 20 Percentagem dos seus dados marcados para serem incluídos no conjunto de testes. O valor recomendado é 20. 20

Nota

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

Assim que enviar o seu pedido de API, receberá uma 202 resposta indicando que o trabalho foi submetido corretamente. Nos cabeçalhos de resposta, extraia o location valor. Será formatado assim:

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

{JOB-ID} é usado para identificar o seu pedido, uma vez que esta operação é assíncronea. Você pode usar este URL para obter o estado de treino.

Obter estatuto de emprego de formação

O treino pode demorar entre 10 e 30 minutos para este conjunto de dados da amostra. Pode utilizar o seguinte pedido para manter a votação do estado do trabalho de formação até que esteja concluído com sucesso.

Use o seguinte pedido GET para obter o estado do progresso de formação 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 final para autenticar o seu pedido de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Este valor é sensível a casos. myProject
{JOB-ID} A identificação para localizar o estado de treino do seu modelo. Este valor está no valor do location cabeçalho que recebeu no passo anterior. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que está a ligar. O valor aqui referenciado é para a versão mais recente lançada. Consulte o ciclo de vida do Modelo para saber mais sobre outras versões API disponíveis. 2022-05-01

Cabeçalhos

Utilize o seguinte cabeçalho para autenticar o seu pedido.

Chave Valor
Ocp-Apim-Subscription-Key A chave do seu recurso. Utilizado para autenticar os seus pedidos de API.

Corpo de Resposta

Assim que enviar o pedido, terá 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"
}

Desdobre o seu modelo

Geralmente, depois de treinar um modelo, você iria rever os seus detalhes de avaliação e fazer melhorias se necessário. Neste arranque rápido, basta implementar o seu modelo e disponibilizá-lo para que experimente em Language Studio, ou pode chamar a API de previsão.

Iniciar o trabalho de implantação

Submeta um pedido DEMS utilizando o seguinte URL, cabeçalhos e corpo JSON para submeter 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 final para autenticar o seu pedido de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Este valor é sensível a casos. myProject
{DEPLOYMENT-NAME} O nome da sua implantação. Este valor é sensível a casos. staging
{API-VERSION} A versão da API que está a ligar. O valor aqui referenciado é para a versão mais recente lançada. Consulte o ciclo de vida do Modelo para saber mais sobre outras versões API disponíveis. 2022-05-01

Cabeçalhos

Utilize o seguinte cabeçalho para autenticar o seu pedido.

Chave Valor
Ocp-Apim-Subscription-Key A chave do seu recurso. Utilizado para autenticar os seus pedidos de API.

Corpo do pedido

Utilize o seguinte JSON no corpo do seu pedido. Use o nome do modelo que designa para a implantação.

{
  "trainedModelLabel": "{MODEL-NAME}"
}
Chave Marcador de posição Valor Exemplo
treinadoModelLabel {MODEL-NAME} O modelo nome que será atribuído à sua implantação. Só é possível atribuir modelos treinados com sucesso. Este valor é sensível a casos. myModel

Assim que enviar o seu pedido de API, receberá uma 202 resposta indicando que o trabalho foi submetido corretamente. Nos cabeçalhos de resposta, extraia o operation-location valor. Será formatado assim:

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

{JOB-ID} é usado para identificar o seu pedido, uma vez que esta operação é assíncronea. Pode utilizar este URL para obter o estado de implantação.

Obter estatuto de emprego de implantação

Utilize o seguinte pedido GET para consultar o estado do trabalho de implantação. Pode utilizar o URL que recebeu do passo anterior ou substituir os valores de espaços reservados abaixo pelos 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 final para autenticar o seu pedido de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Este valor é sensível a casos. myProject
{DEPLOYMENT-NAME} O nome da sua implantação. Este valor é sensível a casos. staging
{JOB-ID} A identificação para localizar o estado de treino do seu modelo. Isto está no valor do location cabeçalho que recebeu no passo anterior. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que está a ligar. O valor aqui referenciado é para a versão mais recente lançada. Consulte o ciclo de vida do Modelo para saber mais sobre outras versões API disponíveis. 2022-05-01

Cabeçalhos

Utilize o seguinte cabeçalho para autenticar o seu pedido.

Chave Valor
Ocp-Apim-Subscription-Key A chave do seu recurso. Utilizado para autenticar os seus pedidos de API.

Corpo de Resposta

Assim que enviar o pedido, receberá a seguinte resposta. Continue a sondar este ponto final até que o parâmetro de estado mude para "ter sucesso". Deve obter um 200 código que indique o sucesso do pedido.

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

Extrair entidades personalizadas

Após a implementação do seu modelo, pode começar a usá-lo para extrair entidades do seu texto utilizando a API de previsão. No conjunto de dados da amostra que descarregou anteriormente, pode encontrar alguns documentos de teste que pode utilizar neste passo.

Envie uma tarefa NER personalizada

Utilize este pedido 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 final para autenticar o seu pedido de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION} A versão da API que está a ligar. O valor aqui referenciado é para a versão mais recente lançada. Consulte o ciclo de vida do Modelo para saber mais sobre outras versões API disponíveis. 2022-05-01

Cabeçalhos

Chave Valor
Ocp-Apim-Subscription-Key A sua chave que dá 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}"
      }
    }
  ]
}
Chave Marcador de posição Valor Exemplo
displayName {JOB-NAME} Seu nome de trabalho. MyJobName
documents [{},{}] Lista de documentos para executar tarefas. [{},{}]
id {DOC-ID} Nome do documento ou identificação. doc1
language {LANGUAGE-CODE} Uma cadeia especificando o código de linguagem para o documento. Se esta chave não for especificada, o serviço assumirá a linguagem padrão do projeto que foi selecionado durante a criação do projeto. Consulte o suporte linguístico para obter uma lista de códigos linguísticos suportados. en-us
text {DOC-TEXT} Documente a tarefa de executar as tarefas. Lorem ipsum dolor sit amet
tasks Lista de tarefas que queremos realizar. []
taskName CustomEntityRecognition O nome da tarefa Reconhecimento de Entidades Personalizadas
parameters Lista de parâmetros para passar para a tarefa.
project-name {PROJECT-NAME} O nome para o seu projeto. Este valor é sensível a casos. myProject
deployment-name {DEPLOYMENT-NAME} O nome da sua implantação. Este valor é sensível a casos. prod

Resposta

Receberá uma resposta de 202 indicando que a sua tarefa foi submetida com sucesso. Nos cabeçalhos de resposta, extrato operation-location. operation-location é formatado assim:

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

Pode utilizar este URL para consultar o estado de conclusão da tarefa e obter os resultados quando a tarefa estiver concluída.

Obtenha resultados de tarefas

Utilize o seguinte pedido GET para consultar o estado/resultados da tarefa de reconhecimento da entidade personalizada.

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}
Marcador de posição Valor Exemplo
{ENDPOINT} O ponto final para autenticar o seu pedido de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION} A versão da API que está a ligar. O valor aqui referenciado é para a versão mais recente lançada. Consulte o ciclo de vida do Modelo para saber mais sobre outras versões API disponíveis. 2022-05-01

Cabeçalhos

Chave Valor
Ocp-Apim-Subscription-Key A sua chave que dá acesso a esta API.

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

Limpar os recursos

Quando já não precisar do seu projeto, pode eliminá-lo com o seguinte pedido DELETE . Substitua os valores do espaço reservado pelos seus próprios valores.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}
Marcador de posição Valor Exemplo
{ENDPOINT} O ponto final para autenticar o seu pedido de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome para o seu projeto. Este valor é sensível a casos. myProject
{API-VERSION} A versão da API que está a ligar. O valor aqui referenciado é para a versão mais recente lançada. Consulte o ciclo de vida do Modelo para saber mais sobre outras versões API disponíveis. 2022-05-01

Cabeçalhos

Utilize o seguinte cabeçalho para autenticar o seu pedido.

Chave Valor
Ocp-Apim-Subscription-Key A chave do seu recurso. Utilizado para autenticar os seus pedidos de API.

Assim que enviar o seu pedido de API, receberá uma 202 resposta indicando sucesso, o que significa que o seu projeto foi eliminado. Uma chamada bem sucedida resulta com um cabeçalho Operation-Location usado para verificar o estado do trabalho.

Passos seguintes

Depois de criar a modelo de extração de entidades, pode:

Quando começar a criar os seus próprios projetos NER personalizados, use os artigos de como fazer para saber mais sobre a marcação, formação e consumo do seu modelo com maior detalhe: