Entender os recursos para compilar um modelo de compreensão da linguagem coloquial

9 minutos

Para usar o serviço de reconhecimento vocal para desenvolver uma solução NLP, você precisará criar um recurso de linguagem no Azure. Esse recurso será usado para criar seu modelo e processar solicitações de previsão de aplicativos cliente.

Dica

O laboratório deste módulo aborda a compilação de um modelo para a compreensão da linguagem coloquial. Para obter módulos mais focados na classificação de texto personalizado e no reconhecimento personalizado de entidade nomeada, confira os módulos de solução personalizados no roteiro de aprendizagem Desenvolver soluções de linguagem natural.

Criar seu modelo

Para recursos que exigem um modelo para previsão, você precisará compilar, treinar e implantar esse modelo antes de usá-lo para fazer uma previsão. Esta construção e treinamento ensinarão ao serviço de Linguagem de IA do Azure o que procurar.

Primeiro, você precisará criar seu recurso de Linguagem de IA do Azure no portal do Azure. Em seguida:

Pesquise serviços de IA do Azure.
Localize e selecione o serviço de linguagem.
Selecione Criar no Serviço de Linguagem.
Preencha os detalhes necessários, escolhendo a região mais próxima geograficamente (para melhor desempenho) e dando a ela um nome exclusivo.

Depois que esse recurso tiver sido criado, você precisará de uma chave e do ponto de extremidade. Eles podem ser encontrados no lado esquerdo em Chaves e Ponto de Extremidade da página de visão geral do recurso.

Usar o Language Studio

Para obter um método mais visual de compilação, treinamento e implantação do modelo, você pode usar o Language Studio para obter cada uma dessas etapas. Na página principal, você pode optar por criar um projeto de compreensão da linguagem coloquial. Depois que o projeto for criado, passe pelo mesmo processo que o mostrado acima para compilar, treinar e implantar seu modelo.

O laboratório neste módulo usará o Language Studio para compilar seu modelo. Para saber mais, confira o início rápido do Language Studio

Usar a API REST

Uma forma de compilar seu modelo é por meio da API REST. O padrão seria criar seu projeto, importar dados, treinar, implantar e, em seguida, usar seu modelo.

Essas tarefas são executadas de maneira assíncrona; você precisará enviar uma solicitação para o URI apropriado para cada etapa e, em seguida, enviar outra solicitação para obter o status desse trabalho.

Por exemplo, se você quiser implantar um modelo para um projeto de compreensão da linguagem coloquial, envie o trabalho de implantação e verifique o status do trabalho de implantação.

Autenticação

Para cada chamada para seu recurso de Linguagem de IA do Azure, você autentica a solicitação fornecendo o cabeçalho a seguir.

Key	Valor
`Ocp-Apim-Subscription-Key`	A chave para o recurso

Solicitar implantação

Envie uma solicitação POST para o ponto de extremidade a seguir.

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

Espaço reservado	Valor	Exemplo
`{ENDPOINT}`	O ponto de extremidade do recurso de Linguagem de IA do Azure	`https://<your-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 implantação. Esse valor diferencia maiúsculas de minúsculas	`staging`
`{API-VERSION}`	A versão da API que você está chamando	`2022-05-01`

Inclua o seguinte body na solicitação.

{
  "trainedModelLabel": "{MODEL-NAME}",
}

Espaço reservado	Valor
`{MODEL-NAME}`	O nome do modelo que será atribuído à implantação. Esse valor diferencia maiúsculas de minúsculas.

O envio bem-sucedido da solicitação receberá uma resposta 202 com um cabeçalho de resposta de operation-location. Esse cabeçalho terá uma URL com a qual solicitar o status, formatado da seguinte maneira:

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

Obter status da implantação

Envie uma solicitação GET para a URL do cabeçalho de resposta acima. Os valores já estarão preenchidos com base na solicitação de implantação inicial.

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

Espaço reservado	Valor
`{ENDPOINT}`	O ponto de extremidade para autenticação de sua solicitação de API
`{PROJECT-NAME}`	O nome do projeto (com diferenciação de maiúsculas de minúsculas)
`{DEPLOYMENT-NAME}`	O nome da implantação (com diferenciação de maiúsculas de minúsculas)
`{JOB-ID}`	A ID para localizar o status de treinamento do modelo, encontrada no valor de cabeçalho detalhado acima na solicitação de implantação
`{API-VERSION}`	A versão da API que você está chamando

O corpo da resposta fornecerá os detalhes do status da implantação. O campo status terá o valor de êxito quando a implantação for concluída.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"String",
    "lastUpdatedDateTime":"String",
    "expirationDateTime":"String",
    "status":"running"
}

Para obter um passo a passo completo de cada etapa com solicitações de exemplo, consulte o início rápido de reconhecimento de conversa.

Consultar seu modelo

Para consultar seu modelo para uma previsão, você pode usar SDKs em C# ou Python ou usar a API REST.

Consultar usando SDKs

Para consultar seu modelo usando um SDK, primeiro você precisa criar seu cliente. Depois de ter seu cliente, você o usará para chamar o ponto de extremidade apropriado.

var languageClient = new TextAnalyticsClient(endpoint, credentials);
var response = languageClient.ExtractKeyPhrases(document);

language_client = TextAnalyticsClient(
            endpoint=endpoint, 
            credential=credentials)
response = language_client.extract_key_phrases(documents = documents)[0]

Outros recursos de linguagem, como compreensão da linguagem coloquial, exigem que a solicitação seja criada e enviada de forma diferente.

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = userText,
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,
        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};
Response response = await client.AnalyzeConversationAsync(RequestContent.Create(data));

result = client.analyze_conversation(
    task={
        "kind": "Conversation",
        "analysisInput": {
            "conversationItem": {
                "participantId": "1",
                "id": "1",
                "modality": "text",
                "language": "en",
                "text": query
            },
            "isLoggingEnabled": False
        },
        "parameters": {
            "projectName": cls_project,
            "deploymentName": deployment_slot,
            "verbose": True
        }
    }
)

Consultar usando a API REST

Para consultar seu modelo usando REST, crie uma solicitação POST para a URL apropriada com o corpo apropriado especificado. Para recursos internos, como detecção de idioma ou análise de sentimento, você consultará o ponto de extremidade analyze-text.

Dica

Lembre-se de que cada pedido precisa de ser autenticado com a sua chave de recurso da Linguagem de IA do Azure no cabeçalho Ocp-Apim-Subscription-Key

{ENDPOINT}/language/:analyze-text?api-version={API-VERSION}

Espaço reservado	Valor
`{ENDPOINT}`	O ponto de extremidade para autenticação de sua solicitação de API
`{API-VERSION}`	A versão da API que você está chamando

Dentro do corpo dessa solicitação, você deve especificar o parâmetro kind, que informa ao serviço qual tipo de reconhecimento vocal você está solicitando.

Se você quiser detectar o idioma, por exemplo, o corpo JSON seria semelhante ao seguinte.

{
    "kind": "LanguageDetection",
    "parameters": {
        "modelVersion": "latest"
    },
    "analysisInput":{
        "documents":[
            {
                "id":"1",
                "text": "This is a document written in English."
            }
        ]
    }
}

Outros recursos de linguagem, como compreensão da linguagem coloquial, exigem que a solicitação seja roteada para um ponto de extremidade diferente. Por exemplo, a solicitação de compreensão da linguagem coloquial seria enviada para o seguinte.

{ENDPOINT}/language/:analyze-conversations?api-version={API-VERSION}

Espaço reservado	Valor
`{ENDPOINT}`	O ponto de extremidade para autenticação de sua solicitação de API
`{API-VERSION}`	A versão da API que você está chamando

Essa solicitação incluiria um corpo JSON semelhante ao seguinte.

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Sample text"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}

Espaço reservado	Valor
`{PROJECT-NAME}`	O nome do projeto no qual você compilou seu modelo
`{DEPLOYMENT-NAME}`	O nome da sua implantação

Resposta de amostra

A resposta de consulta de um SDK será retornada no objeto, que varia dependendo do recurso (como em response.key_phrases ou response.Value). A API REST retornará JSON que seria semelhante ao seguinte.

{
    "kind": "KeyPhraseExtractionResults",
    "results": {
        "documents": [{
            "id": "1",
            "keyPhrases": ["modern medical office", "Dr. Smith", "great staff"],
            "warnings": []
        }],
        "errors": [],
        "modelVersion": "{VERSION}"
    }
}

Para outros modelos, como compreensão da linguagem coloquial, uma resposta de exemplo à consulta seria semelhante à seguinte.

{
  "kind": "ConversationResult",
  "result": {
    "query": "String",
    "prediction": {
      "topIntent": "intent1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text",
          "offset": 7,
          "length": 4,
          "confidenceScore": 1
        }
      ]
    }
  }
}

Os SDKs para Python e C# retornam JSON que é muito semelhante à resposta REST.

Para obter documentação completa sobre recursos, incluindo exemplos e guias de instruções, confira as páginas de documentação da Linguagem de IA do Azure.