Início Rápido: Compreensão da linguagem de conversação

  • Artigo

Utilize este artigo para começar a utilizar o Language Understanding de Conversação com o Language Studio e a API REST. Siga estes passos para experimentar um exemplo.

Pré-requisitos

Iniciar sessão no Language Studio

  1. Aceda ao Language Studio e inicie sessão com a sua conta do Azure.

  2. Na janela Escolher um recurso de idioma que é apresentada, localize a sua subscrição do Azure e selecione o recurso Idioma. Se não tiver um recurso, pode criar um novo.

    Detalhes da instância Valor obrigatório
    Subscrição do Azure A sua subscrição do Azure.
    Grupo de recursos do Azure O nome do grupo de recursos do Azure.
    Nome do recurso do Azure O nome do recurso do Azure.
    Localização Uma das regiões suportadas para o recurso de Idioma. Por exemplo, "E.U.A. Oeste 2".
    Escalão de preço Um dos escalões de preço válidos para o recurso de Idioma. Pode utilizar o escalão Gratuito (F0) para experimentar o serviço.

    Captura de ecrã a mostrar o ecrã de seleção de recursos no Language Studio.

Criar um projeto de compreensão de linguagem de conversação

Assim que tiver um recurso de Idioma selecionado, crie um projeto de compreensão de linguagem de conversação. Um projeto é uma área de trabalho para criar os seus modelos de ML personalizados com base nos seus dados. O seu projeto só pode ser acedido por si e por outras pessoas que tenham acesso ao recurso Idioma que está a ser utilizado.

Para este início rápido, pode transferir este ficheiro de projeto de exemplo e importá-lo. Este projeto pode prever os comandos pretendidos da entrada do utilizador, tais como: ler e-mails, eliminar e-mails e anexar um documento a um e-mail.

  1. Na secção Compreender as perguntas e o idioma de conversação do Language Studio, selecione Compreensão de idiomas conversacionais.

    Uma captura de ecrã a mostrar a localização da Language Understanding Personalizada na página de destino do Language Studio.

  2. Isto irá levá-lo para a página Projetos de compreensão de linguagem de conversação . Junto ao botão Criar novo projeto , selecione Importar.

    Captura de ecrã a mostrar a página do projeto de conversação no Language Studio.

  3. Na janela apresentada, carregue o ficheiro JSON que pretende importar. Certifique-se de que o seu ficheiro segue o formato JSON suportado.

Assim que o carregamento estiver concluído, irá aceder à página Definição de esquema . Neste início rápido, o esquema já foi criado e as expressões já estão etiquetadas com intenções e entidades.

Preparar o seu modelo

Normalmente, depois de criar um projeto, deve criar um esquema e etiquetar expressões. Neste início rápido, já importámos um projeto pronto com esquema incorporado e expressões etiquetadas.

Para preparar um modelo, tem de iniciar uma tarefa de preparação. O resultado de uma tarefa de preparação bem-sucedida é o modelo preparado.

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

  1. Selecione Preparar modelo no menu esquerdo.

  2. Selecione Iniciar uma tarefa de preparação no menu superior.

  3. Selecione Preparar um novo modelo e introduza um novo nome de modelo na caixa de texto. Caso contrário, para substituir um modelo existente por um modelo preparado para os novos dados, selecione Substituir um modelo existente e, em seguida, selecione um modelo existente. A substituição de um modelo preparado é irreversível, mas não afetará os modelos implementados até implementar o novo modelo.

  4. Selecione o modo de preparação. Pode escolher Formação Padrão para uma preparação mais rápida, mas só está disponível para inglês. Em alternativa, pode escolher Formação avançada que é suportada para outros idiomas e projetos multilingues, mas envolve tempos de preparação mais longos. Saiba mais sobre os modos de preparação.

  5. Selecione um método de divisão de dados . Pode escolher Dividir automaticamente o conjunto de testes a partir dos dados de preparação em que o sistema irá dividir as expressões entre os conjuntos de preparação e teste, de acordo com as percentagens especificadas. Em alternativa, pode Utilizar uma divisão manual dos dados de preparação e teste. Esta opção só é ativada se tiver adicionado expressões ao seu conjunto de testes quando tiver etiquetado as expressões.

  6. Selecione o botão Preparar .

    Captura de ecrã a mostrar a página de preparação no Language Studio.

  7. Selecione o ID da tarefa de preparação na lista. Será apresentado um painel onde pode verificar o progresso da preparação, o estado da tarefa e outros detalhes para esta tarefa.

    Nota

    • Apenas as tarefas de preparação concluídas com êxito irão gerar modelos.
    • A preparação pode demorar entre alguns minutos e algumas horas com base na contagem de expressões.
    • Só pode ter um trabalho de preparação em execução de cada vez. Não pode iniciar outras tarefas de preparação no mesmo projeto até que a tarefa em execução esteja concluída.
    • A aprendizagem automática utilizada para preparar modelos é atualizada regularmente. Para preparar numa versão de configuração anterior, selecione Clique aqui para alterar a partir da página Iniciar uma tarefa de preparação e escolha uma versão anterior.

Implementar o modelo

Geralmente, após a preparação de um modelo, iria rever os respetivos detalhes de avaliação. Neste início rápido, irá implementar o modelo e disponibilizá-lo para experimentar no Language Studio ou pode chamar a API de predição.

Para implementar o modelo a partir do Language Studio:

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

  2. Selecione Adicionar implementação para iniciar o assistente Adicionar implementação .

    Captura de ecrã a mostrar o botão de implementação do modelo no Language Studio.

  3. Selecione Criar um novo nome de implementação para criar uma nova implementação e atribuir um modelo preparado na lista pendente abaixo. Caso contrário, pode selecionar Substituir um nome de implementação existente para substituir eficazmente o modelo utilizado por uma implementação existente.

    Nota

    A substituição de uma implementação existente não requer alterações à chamada à API de Predição , mas os resultados obtidos serão baseados no modelo recentemente atribuído.

    Uma captura de ecrã a mostrar o ecrã para adicionar uma nova implementação no Language Studio.

  4. Selecione um modelo preparado na lista pendente Modelo .

  5. Selecione Implementar para iniciar a tarefa de implementação.

  6. Após a implementação ser bem-sucedida, será apresentada uma data de expiração junto à mesma. A expiração da implementação é quando o modelo implementado não estará disponível para ser utilizado para predição, o que normalmente ocorre doze meses após a expiração de uma configuração de preparação.

Testar o modelo implementado

Para testar os modelos implementados a partir do Language Studio:

  1. Selecione Testar implementações no menu esquerdo.

  2. Para projetos multilingues, na lista pendente Selecionar idioma de texto , selecione o idioma da expressão que está a testar.

  3. Na lista pendente Nome da implementação , selecione o nome da implementação correspondente ao modelo que pretende testar. Só pode testar modelos atribuídos a implementações.

  4. Na caixa de texto, introduza uma expressão para testar. Por exemplo, se tiver criado uma aplicação para expressões relacionadas com o e-mail, pode introduzir Eliminar este e-mail.

  5. Na parte superior da página, selecione Executar o teste.

  6. Depois de executar o teste, deverá ver a resposta do modelo no resultado. Pode ver os resultados na vista de cartões de entidades ou vê-lo no formato JSON.

Limpar os recursos

Quando já não precisar do seu projeto, pode eliminar o seu projeto com o Language Studio. Selecione Projetos no menu de navegação esquerdo, selecione o projeto que pretende eliminar e, em seguida, selecione Eliminar no menu superior.

Pré-requisitos

Criar um novo recurso a partir do portal do Azure

  1. Aceda ao portal do Azure para criar um novo recurso de Linguagem do Azure.

  2. Clique em Criar um novo recurso

  3. Na janela apresentada, procure Serviço de idiomas

  4. Clique em Criar

  5. Crie um recurso de Idioma com os seguintes detalhes.

    Detalhes da instância Valor obrigatório
    Região Uma das regiões suportadas para o recurso de Idioma.
    Name Nome necessário para o recurso de Idioma
    Escalão de preço Um dos escalões de preço suportados para o recurso de Idioma.

Obter as chaves de recursos e o ponto final

  1. Aceda à página de descrição geral do recurso na portal do Azure.

  2. No menu do lado esquerdo, selecione Chaves e Ponto Final. Irá utilizar o ponto final e a chave para os pedidos da API

    Uma captura de ecrã a mostrar a chave e a página de ponto final no portal do Azure

Importar um novo projeto de exemplo CLU

Depois de criar um recurso de Linguagem, crie um projeto de compreensão de linguagem de conversação. Um projeto é uma área de trabalho para criar os seus modelos de ML personalizados com base nos seus dados. O seu projeto só pode ser acedido por si e por outras pessoas que tenham acesso ao recurso Idioma que está a ser utilizado.

Neste início rápido, pode transferir este projeto de exemplo e importá-lo. Este projeto pode prever os comandos pretendidos da entrada do utilizador, tais como: ler e-mails, eliminar e-mails e anexar um documento a um e-mail.

Acionar a tarefa de importação do projeto

Submeta um pedido POST com o seguinte URL, cabeçalhos e corpo JSON para importar o projeto.

URL do Pedido

Utilize o seguinte URL ao criar o pedido da API. Substitua os valores dos marcadores de posição pelos seus próprios valores.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:import?api-version={API-VERSION}
Marcador de posição Valor Exemplo
{ENDPOINT} O ponto final para autenticar o pedido da API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Este valor é sensível a maiúsculas e minúsculas e tem de corresponder ao nome do projeto no ficheiro JSON que está a importar. EmailAppDemo
{API-VERSION} A versão da API que está a chamar. O valor aqui referenciado destina-se à versão mais recente do modelo lançado. 2022-05-01

Cabeçalhos

Utilize o cabeçalho seguinte para autenticar o pedido.

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

Corpo

O corpo JSON que envia é semelhante ao exemplo seguinte. Veja a documentação de referência para obter mais detalhes sobre o objeto JSON.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Conversation",
    "settings": {
      "confidenceThreshold": 0.7
    },
    "projectName": "{PROJECT-NAME}",
    "multilingual": true,
    "description": "Trying out CLU",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Conversation",
    "intents": [
      {
        "category": "intent1"
      },
      {
        "category": "intent2"
      }
    ],
    "entities": [
      {
        "category": "entity1"
      }
    ],
    "utterances": [
      {
        "text": "text1",
        "dataset": "{DATASET}",
        "intent": "intent1",
        "entities": [
          {
            "category": "entity1",
            "offset": 5,
            "length": 5
          }
        ]
      },
      {
        "text": "text2",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "intent": "intent2",
        "entities": []
      }
    ]
  }
}
Chave Marcador de posição Valor Exemplo
api-version {API-VERSION} A versão da API que está a chamar. A versão utilizada aqui tem de ser a mesma versão do modelo de API no URL. Veja o artigo da versão do modelo para saber mais. 2022-05-01
projectName {PROJECT-NAME} O nome do seu projeto. Este valor é sensível às maiúsculas e minúsculas. EmailAppDemo
language {LANGUAGE-CODE} Uma cadeia que especifica o código de idioma para as expressões utilizadas no projeto. Se o seu projeto for um projeto multilingue, escolha o código de idioma da maioria das expressões. en-us
multilingual true Um valor booleano que lhe permite ter documentos em vários idiomas no seu conjunto de dados. Quando o modelo é implementado, pode consultar o modelo em qualquer idioma suportado, incluindo idiomas que não estão incluídos nos seus documentos de preparação. true
dataset {DATASET} Veja como preparar um modelo para obter informações sobre como dividir os seus dados entre um conjunto de teste e preparação. Os valores possíveis para este campo são Train e Test. Train

Após um pedido bem-sucedido, a resposta da API conterá um operation-location cabeçalho com um URL que pode utilizar para verificar o estado da tarefa de importação. Está formatado da seguinte forma:

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

Obter o estado da tarefa de importação

Quando envia um pedido de importação de projeto com êxito, o URL de pedido completo para verificar o estado da tarefa de importação (incluindo o ponto final, o nome do projeto e o ID da tarefa) está contido no cabeçalho da operation-location resposta.

Utilize o seguinte pedido GET para consultar o estado da tarefa de importação. Pode utilizar o URL que recebeu do passo anterior ou substituir os valores dos marcadores de posição pelos seus próprios valores.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
Marcador de posição Valor Exemplo
{ENDPOINT} O ponto final para autenticar o pedido da API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Este valor é sensível às maiúsculas e minúsculas. myProject
{JOB-ID} O ID para localizar o estado da tarefa de importação. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que está a chamar. O valor aqui referenciado destina-se à versão mais recente do modelo lançado. 2022-05-01

Cabeçalhos

Utilize o cabeçalho seguinte para autenticar o pedido.

Chave Descrição Valor
Ocp-Apim-Subscription-Key A chave do recurso. Utilizado para autenticar os seus pedidos de API. {YOUR-PRIMARY-RESOURCE-KEY}

Corpo da resposta

Depois de enviar o pedido, obterá a seguinte resposta. Continue a consultar este ponto final até que o parâmetro de estado mude para "com êxito".

{
  "jobId": "xxxxx-xxxxx-xxxx-xxxxx",
  "createdDateTime": "2022-04-18T15:17:20Z",
  "lastUpdatedDateTime": "2022-04-18T15:17:22Z",
  "expirationDateTime": "2022-04-25T15:17:20Z",
  "status": "succeeded"
}

Começar a preparar o modelo

Normalmente, depois de criar um projeto, deve criar expressões de esquema e etiqueta. Neste início rápido, já importámos um projeto pronto com esquema incorporado e expressões etiquetadas.

Crie um pedido POST com o seguinte URL, cabeçalhos e corpo JSON para submeter uma tarefa de preparação.

URL do Pedido

Utilize o seguinte URL ao criar o pedido da API. Substitua os valores dos marcadores de posição pelos seus próprios valores.

{ENDPOINT}/language/authoring/analyze-conversations/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 projeto. Este valor é sensível às maiúsculas e minúsculas. EmailApp
{API-VERSION} A versão da API que está a chamar. O valor aqui referenciado destina-se à versão do modelo lançada mais recente. 2022-05-01

Cabeçalhos

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

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

Corpo do pedido

Utilize o seguinte objeto no seu pedido. O modelo terá o nome do valor que utiliza para o parâmetro assim que a modelLabel preparação estiver concluída.

{
  "modelLabel": "{MODEL-NAME}",
  "trainingMode": "{TRAINING-MODE}",
  "trainingConfigVersion": "{CONFIG-VERSION}",
  "evaluationOptions": {
    "kind": "percentage",
    "testingSplitPercentage": 20,
    "trainingSplitPercentage": 80
  }
}
Chave Marcador de posição Valor Exemplo
modelLabel {MODEL-NAME} O nome do modelo. Model1
trainingConfigVersion {CONFIG-VERSION} A versão do modelo de configuração de preparação. Por predefinição, é utilizada a versão mais recente do modelo. 2022-05-01
trainingMode {TRAINING-MODE} O modo de preparação a utilizar para preparação. Os modos suportados são formação Standard, formação mais rápida, mas apenas disponíveis para formação em inglês e avançada suportada para outros idiomas e projetos multilingues, mas envolve tempos de preparação mais longos. Saiba mais sobre os modos de preparação. standard
kind percentage Dividir métodos. Os Valores Possíveis são percentage ou manual. Veja como preparar um modelo para obter mais informações. percentage
trainingSplitPercentage 80 Percentagem dos dados marcados a incluir no conjunto de preparação. O valor recomendado é 80. 80
testingSplitPercentage 20 Percentagem dos dados marcados a incluir no conjunto de testes. O valor recomendado é 20. 20

Nota

As trainingSplitPercentage e testingSplitPercentage só são necessárias se Kind estiver definida como percentage e a soma de ambas as percentagens deve ser igual a 100.

Depois de enviar o seu pedido de API, receberá uma 202 resposta que indica êxito. Nos cabeçalhos de resposta, extraia o operation-location valor. Será formatado da seguinte forma:

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

Pode utilizar este URL para obter o estado da tarefa de preparação.

Obter o estado da tarefa de preparação

A preparação pode demorar algum tempo a concluir - por vezes entre 10 e 30 minutos. Pode utilizar o seguinte pedido para continuar a consultar o estado da tarefa de formação até que seja concluída com êxito.

Quando envia um pedido de preparação bem-sucedido, o URL de pedido completo para verificar o estado da tarefa (incluindo o ponto final, o nome do projeto e o ID da tarefa) está contido no cabeçalho da operation-location resposta.

Utilize o seguinte pedido GET para obter o estado do progresso da preparação do modelo. Substitua os valores de marcador de posição abaixo pelos seus próprios valores.

URL do Pedido

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
Marcador de posição Valor Exemplo
{YOUR-ENDPOINT} O ponto final para autenticar o seu pedido de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do projeto. Este valor é sensível às maiúsculas e minúsculas. EmailApp
{JOB-ID} O ID para localizar o estado de preparação do modelo. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que está a chamar. O valor aqui referenciado destina-se à versão mais recente lançada. Saiba mais sobre outras versões de API disponíveis 2022-05-01

Cabeçalhos

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

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

Corpo da Resposta

Assim que enviar o pedido, obterá a seguinte resposta. Continue a consultar este ponto final até que o parâmetro de estado mude para "com êxito".

{
  "result": {
    "modelLabel": "{MODEL-LABEL}",
    "trainingConfigVersion": "{TRAINING-CONFIG-VERSION}",
    "trainingMode": "{TRAINING-MODE}",
    "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": "xxxxx-xxxxx-xxxx-xxxxx-xxxx",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}
Chave Valor Exemplo
modelLabel O nome do modelo Model1
trainingConfigVersion A versão de configuração de preparação. Por predefinição, é utilizada a versão mais recente . 2022-05-01
trainingMode O modo de preparação selecionado. standard
startDateTime A hora de preparação iniciada 2022-04-14T10:23:04.2598544Z
status O estado da tarefa de preparação running
estimatedEndDateTime Tempo estimado para a conclusão da tarefa de preparação 2022-04-14T10:29:38.2598544Z
jobId O ID da tarefa de preparação xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
createdDateTime Data e hora de criação de tarefas de formação 2022-04-14T10:22:42Z
lastUpdatedDateTime Última data e hora da tarefa de preparação 2022-04-14T10:23:45Z
expirationDateTime Data e hora de expiração da tarefa de preparação 2022-04-14T10:22:42Z

Implementar o modelo

Geralmente, após a preparação de um modelo, iria rever os respetivos detalhes de avaliação. Neste início rápido, irá apenas implementar o modelo e chamar a API de predição para consultar os resultados.

Submeter tarefa de implementação

Crie um pedido PUT com o seguinte URL, cabeçalhos e corpo JSON para começar a implementar um modelo de compreensão de linguagem de conversação.

URL do Pedido

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?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 projeto. Este valor é sensível às maiúsculas e minúsculas. myProject
{DEPLOYMENT-NAME} O nome da sua implementação. Este valor é sensível às maiúsculas e minúsculas. staging
{API-VERSION} A versão da API que está a chamar. O valor aqui referenciado destina-se à versão mais recente do modelo lançado. 2022-05-01

Cabeçalhos

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

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

Corpo do Pedido

{
  "trainedModelLabel": "{MODEL-NAME}",
}
Chave Marcador de posição Valor Exemplo
trainedModelLabel {MODEL-NAME} O nome do modelo que será atribuído à sua implementação. Só pode atribuir modelos preparados com êxito. Este valor é sensível às maiúsculas e minúsculas. myModel

Depois de enviar o seu pedido de API, receberá uma 202 resposta que indica êxito. Nos cabeçalhos de resposta, extraia o operation-location valor. Será formatado da seguinte forma:

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

Pode utilizar este URL para obter o estado da tarefa de implementação.

Obter o estado da tarefa de implementação

Quando envia um pedido de implementação bem-sucedido, o URL de pedido completo para verificar o estado da tarefa (incluindo o ponto final, o nome do projeto e o ID da tarefa) está contido no cabeçalho da operation-location resposta.

Utilize o seguinte pedido GET para obter o estado da sua tarefa de implementação. Substitua os valores do marcador de posição pelos seus próprios valores.

URL do Pedido

{ENDPOINT}/language/authoring/analyze-conversations/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 projeto. Este valor é sensível às maiúsculas e minúsculas. myProject
{DEPLOYMENT-NAME} O nome da sua implementação. Este valor é sensível às maiúsculas e minúsculas. staging
{JOB-ID} O ID para localizar o estado de preparação do modelo. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que está a chamar. O valor aqui referenciado destina-se à versão mais recente do modelo lançado. 2022-05-01

Cabeçalhos

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

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

Corpo da Resposta

Assim que enviar o pedido, obterá a seguinte resposta. Continue a consultar este ponto final até que o parâmetro de estado mude para "com êxito".

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

Modelo de consulta

Após a implementação do modelo, pode começar a utilizá-lo para fazer predições através da API de predição.

Assim que a implementação for concluída com êxito, pode começar a consultar o modelo implementado para obter predições.

Crie um pedido POST com o seguinte URL, cabeçalhos e corpo JSON para começar a testar um modelo de compreensão de linguagem de conversação.

URL do Pedido

{ENDPOINT}/language/:analyze-conversations?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 chamar. O valor aqui referenciado destina-se à versão mais recente do modelo lançado. 2022-05-01

Cabeçalhos

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

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

Corpo do pedido

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Text 1"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}
Chave Marcador de posição Valor Exemplo
participantId {JOB-NAME} "MyJobName
id {JOB-NAME} "MyJobName
text {TEST-UTTERANCE} A expressão da qual pretende prever a sua intenção e extrair entidades. "Read Matt's email
projectName {PROJECT-NAME} O nome do seu projeto. Este valor é sensível às maiúsculas e minúsculas. myProject
deploymentName {DEPLOYMENT-NAME} O nome da sua implementação. Este valor é sensível às maiúsculas e minúsculas. staging

Assim que enviar o pedido, obterá a seguinte resposta para a predição

Corpo da resposta

{
  "kind": "ConversationResult",
  "result": {
    "query": "Text1",
    "prediction": {
      "topIntent": "inten1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        },
        {
          "category": "intent3",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text1",
          "offset": 29,
          "length": 12,
          "confidenceScore": 1
        }
      ]
    }
  }
}
Chave Valor de Exemplo Description
query "Ler o e-mail do Matt" o texto que submeteu para consulta.
topIntent "Ler" A intenção prevista com a classificação de confiança mais alta.
intenções [] Uma lista de todas as intenções que foram previstas para o texto da consulta, cada uma com uma classificação de confiança.
entidades [] matriz que contém a lista de entidades extraídas do texto da consulta.

Resposta da API para um projeto de conversações

Num projeto de conversações, obterá predições para as suas intenções e entidades que estão presentes no seu projeto.

  • As intenções e entidades incluem uma classificação de confiança entre 0,0 e 1.0 associada ao quão confiante o modelo tem em prever um determinado elemento no seu projeto.
  • A intenção de classificação superior está contida no seu próprio parâmetro.
  • Apenas as entidades previstas serão apresentadas na sua resposta.
  • As entidades indicam:
    • O texto da entidade que foi extraída
    • A localização de início indicada por um valor de deslocamento
    • O comprimento do texto da entidade indicado por um valor de comprimento.

Limpar os recursos

Quando já não precisar do seu projeto, pode eliminar o projeto com as APIs.

Crie um pedido DELETE com o seguinte URL, cabeçalhos e corpo JSON para eliminar um projeto de compreensão de linguagem de conversação.

URL do Pedido

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?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 projeto. Este valor é sensível às maiúsculas e minúsculas. myProject
{API-VERSION} A versão da API que está a chamar. O valor aqui referenciado destina-se à versão mais recente do modelo lançado. 2022-05-01

Cabeçalhos

Utilize o cabeçalho seguinte para autenticar o pedido.

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

Depois de enviar o pedido da API, receberá uma 202 resposta a indicar êxito, o que significa que o projeto foi eliminado.

Passos seguintes