Automação em tempo real

Neste tutorial prático, criaremos um aplicativo de classificação automatizado simples que usa o Communications Mining para categorizar e-mails recebidos em tempo real. Vamos criar um fluxo de trabalho de ponta a ponta que pode ser usado como ponto de partida para sua própria automação do Communications Mining e dar uma olhada detalhada em como usar a API do Stream em tempo real.

Pré-requisitos

Noções básicas de Communications Mining

Antes de iniciar este tutorial, certifique-se de que você está familiarizado com os conceitos e a terminologia do Communications Mining e com os conceitos básicos da API do Communications Mining.

Acesso ao Communications Mining

Você precisa das seguintes permissões para seguir o tutorial. Você pode verificar suas permissões atuais na sua página Gerenciar conta.

Projeto	Descrição	PERMISSIONS
reinfer-sandbox	Contém o conjunto de dados reinfer-sandbox/integration-tutorial pré-anotado usado neste tutorial.	"Exibir origens", "Exibir rótulos"
Seu projeto de desenvolvimento	Durante sua integração, você deve ter recebido acesso a um projeto que pode usar como seu ambiente de desenvolvimento.	"Administrador de stream", "Consumir streams", "Ver origens", "Ver rótulos"

Entre em contato com o suporte se não tiver certeza de qual projeto pode ser usado para o desenvolvimento ou se você precisa das permissões "Exibir origens" e "Exibir rótulos" em reinfer-sandbox.

Dados do tutorial

Neste tutorial, usaremos dados pré-anotados. Para fazer uma cópia do conjunto de dados reinfer-sandbox/integration-tutorial pré-anotado, crie um novo conjunto de dados em seu projeto de desenvolvimento usando a opção "Copiar uma taxonomia existente". Você pode encontrar instruções sobre como fazer isso aqui.

Como seu novo conjunto de dados contém dados anotados, o modelo começará o treinamento imediatamente. Você pode acompanhar o status de treinamento do modelo na barra de status do conjunto de dados. Depois de terminar, as métricas de desempenho para cada rótulo serão exibidas na página Validação, e uma nova versão do modelo será exibida na página Modelos.

Figura 1. Página Validação mostrando o desempenho do rótulo

Figura 2. Página de modelos mostrando a nova versão do modelo

Crie seu aplicativo

Agora que você está familiarizado com os pré- requisitos, vamos começar a criar nosso fluxo de trabalho de ponta a ponta. Nesta seção, discutiremos o projeto de um aplicativo de classificação automatizado simples e sua integração com o Communications Mining. Nas próximas seções, aprenderemos sobre a API Stream que direcionará nossa automação. Por fim, vamos construir nosso aplicativo com base no design aqui e testá-lo usando dados pré-anotados.

Visão geral do caso de uso

Vamos segmentar um caso de uso típico de suporte por email como o ponto de partida para nosso design:

• Uma caixa de correio de suporte do Outlook recebe um grande número de emails de clientes diariamente.
• Uma equipe de classificação transforma cada e-mail em um ticket de suporte. Isso requer o preenchimento dos campos de ticket com informações do e-mail (por exemplo, um ID do cliente). Cada ticket é então adicionado à fila do fluxo de trabalho apropriada.
• Os tickets nas filas do fluxo de trabalho são processados continuamente por uma equipe de suporte ao cliente.
  Figura 3. Um caso de uso de suporte por e-mail simples
  

  

  
  

Há duas oportunidades de automação aqui: a etapa de classificação e a etapa de processamento. Este tutorial demonstrará como automatizar a etapa de seleção usando o Communications Mining para extrair os campos necessários de um e-mail e atribuir o e-mail a uma fila de fluxo de trabalho.

Observação: embora a etapa de processamento não seja abordada neste tutorial, ela depende dos dados coletados durante a etapa de classificação, portanto, você tem a opção de adicioná-la após criar o aplicativo de amostra de amostra.

Design de ponta a ponta

Vamos dar uma olhada no diagrama abaixo, que esboça o design fim a fim que vamos criar:

Figura 4. Design de automação ponta a ponta

Devido à conexão ativa entre o servidor do Exchange e o Communications Mining, o Communications Mining pode servir como uma origem de dados para o seu aplicativo. Dessa forma, uma conexão separada entre seu aplicativo e o servidor do Exchange não é necessária. Seu aplicativo pesquisará continuamente o Communications Mining em relação a novos e-mails e os receberá junto com seus rótulos previstos e campos gerais. (Assumimos que nenhum usuário esteja trabalhando diretamente na caixa de entrada da caixa de correio ao mesmo tempo em que seu aplicativo estiver em execução; caso contrário, você precisará considerar os conflitos entre seu aplicativo e os usuários de caixa de correio).

Seu aplicativo consultará o Communications Mining e, para cada e-mail, verificará se os rótulos e campos gerais necessários estão presentes na resposta da API. Em caso afirmativo, será criado um ticket na fila do fluxo de trabalho apropriada. Caso contrário, ele fará uma segunda solicitação de API para o Communications Mining marcar o e-mail como uma exceção "sem previsão". Da mesma forma, deve haver uma maneira para os usuários que processam os tíquetes relatarem tíquetes categorizados incorretamente, para que os e-mails correspondentes possam ser marcados no Communications Mining como uma exceção de "previsão errada". (Ambos os tipos de exceção serão revisados e anotados pelo mantenedor do modelo para melhorar seu desempenho).

Partes do design (mostrada no diagrama com um contorno pontilhado) estarão fora do escopo para este tutorial. Em um cenário da vida real, é claro que essas etapas não devem ser ignoradas:

• Usaremos dados existentes na plataforma em vez de configurar uma conexão de EWS ao vivo.
• Os dados vêm pré-anotados, portanto, não precisamos treinar um modelo.
• Não vamos projetar um loop de feedback para exceções de "previsão errada", pois o design depende das capacidades do sistema em que os tickets são processados.

Ingestão de dados

A opção recomendada para obter dados de e-mail no Communications Mining é usar o conector EWS do Communications Mining, mas outras opções também estão disponíveis. Como estamos usando dados que já estão na plataforma, configurar a ingestão de dados não faz parte deste tutorial. Saiba mais sobre todas as opções de ingestão de dados disponíveis aqui.

Lógica de negócios

Gostaríamos de automatizar este processo:

Uma equipe de classificação transforma cada e-mail em um ticket de suporte. Isso requer o preenchimento dos campos de ticket com informações do e-mail (por exemplo, um ID do cliente). Cada ticket é então adicionado à fila do fluxo de trabalho apropriada.

Para este tutorial, vamos supor que nossas filas de fluxo de trabalho sejam "Renovação", "Cancelamento", "Administrador" e "Urgent". E-mails sobre renovação, cancelamento e tarefas administrativas (por exemplo, alterações de endereço) devem ir para as respectivas filas, enquanto todos os emails urgentes devem ir para a fila "Urgent", independentemente do tópico.

Vamos supor também que cada e-mail pode conter um ID do cliente (seja no assunto ou no corpo do e-mail). A ID do cliente precisa ser extraída para que possa ser usada ao criar um ticket a partir do e-mail. Mas como os clientes às vezes se esquecem de incluir a ID do cliente, queremos tornar esse campo opcional para que um tíquete possa ser criado mesmo que não haja nenhuma ID do cliente presente.

Figura 5. Comentário revisado com o rótulo "Cancelamento" atribuído e o campo geral "ID do cliente" extraído

Para poder categorizar e-mails nas quatro filas de fluxos de trabalho, o modelo foi treinado para prever os rótulos "Renovação", "Cancelamento", "Administrador" e "Urgent". Para extrair o ID do cliente, um campo geral de “ID do cliente” foi configurado. (O Communications Mining vem com muitos tipos de campos gerais pré-construídos; outros tipos de campos gerais podem ser adicionados com base nas necessidades de sua integração específica. Você pode ver uma lista de campos gerais disponíveis atualmente aqui e aprender como solicitar novos tipos de campos gerais aqui).

Agora, podemos elaborar um mapeamento entre o(s) rótulo(s) previsto(s) recebido(s) do Communications Mining e a fila de fluxo de trabalho na qual o e-mail deve ir:

IF number of labels == 0 THEN put email into "Uncategorised" queue
IF one of labels is "Urgent" THEN put email into "Urgent" queue
ELSE
    IF number of labels == 1 THEN put email into the respective queue
    ELSE put email into "Uncategorised" queue

Fizemos algumas escolhas por conta do tutorial:

• Além das quatro filas de fluxo de trabalho existentes, há uma fila especial "Sem categoria". Se o modelo não for capaz de fornecer uma previsão, colocaremos o e-mail lá para ser processado manualmente. Alternativamente, poderiamos ter escolhido uma fila existente que deveria lidar com todos os emails não categorizados, por exemplo, “Administrador”.
• Se um e-mail tiver mais de um rótulo do conjunto ["Renewal", "Cancellation", "Admin"], significa que ele contém várias solicitações. Optamos por colocar esses e-mails na fila "Sem categoria", talvez porque não esperemos receber muitos deles. Alternativamente, poderia ter criado uma fila de "Solicitações complexas".

Em um cenário da vida real, você deve basear tais decisões nos requisitos específicos do seu caso de uso.

Treinamento do modelo

Para consultar um modelo para previsões, é claro que você precisa ter um modelo treinado. Um modelo é treinado anotando alguns dos dados que você ingeriu. Como são necessárias várias horas de anotação para produzir um modelo com bom desempenho, usaremos dados pré-anotados neste tutorial para que você não precise treinar seu próprio modelo.

Em um cenário da vida real, um treinador de modelos deve ter um bom conhecimento do domínio dos dados. Por exemplo, o usuário de uma caixa de correio de suporte seria um bom treinador de modelo para rotular os dados provenientes dessa caixa de correio. O treinamento precisa ser feito com cuidado para produzir um modelo com um bom desempenho e não enviesado. Para esse fim, o Communications Mining fornece recursos de treinamento e oferece sessões de treinamento práticas.

Manuseio de exceção

Mesmo um modelo com bom desempenho fornecerá ocasionalmente resultados incorretos, seja por não prever um rótulo ou por prever o rótulo errado. Uma das melhores maneiras de melhorar o modelo é anotar os e-mails nos quais o modelo não tem um bom desempenho. Por isso, queremos ter um loop de feedback para esses e-mails:

Para cada e-mail, seu aplicativo verifica se os rótulos e campos gerais obrigatórios estão presentes. Se sim, ele cria um ticket na fila do fluxo de trabalho apropriada. Se não, ele faz uma segunda solicitação de API para o Communications Mining marcar o e-mail como uma exceção "sem previsão". Da mesma forma, deve haver uma maneira para os usuários que processam os tíquetes relatarem tíquetes categorizados incorretamente, para que os e-mails correspondentes possam ser marcados no Communications Mining como uma exceção de "previsão errada".

Nosso design mostra loops de feedback para ambos os tipos de exceção.

Sistemas a jusante

Nosso design mostra filas de fluxo de trabalho de forma abstrata. Na realidade, você pode enviar os e-mails diretamente para uma plataforma de CRM, usar um agente de mensagens como oKafka ou até mesmo simplesmente mover os e-mails da pasta caixa de entrada para uma subpasta. Para fins deste tutorial, vamos simular as filas, mas você é incentivado a desenvolver sua integração de teste de ponta a ponta.

Entender a API do stream

In order to fetch incoming emails together with predicted labels and extracted general fields, we will use the The Stream API allows you to define a stream of comments based on a dataset, pinned model version, and optional comment filters, and to iterate through them in a stateful way.

Cada resultado na resposta do Stream conterá um comentário, uma lista de rótulos previstos e uma lista de campos gerais. Isso é passado como uma estrutura JSON, conforme exibido abaixo:

{
"comment": {...},
"entities": [...],
"labels": [...],
    ...
}

A seção a seguir explica como interpretar corretamente os rótulos previstos em cada resposta de fluxo.

Pontuações de limites de confiança

Pontuações de confiabilidade

O ponto de extremidade do Stream retornará rótulos previstos junto com uma pontuação de confiança (um número entre 0 e 1). Por exemplo, o fragmento abaixo seria para previsões de "Cancelamento" e "Administrador" com confiança de cerca de 0,84 e 0,02 respectivamente:

"labels": [
{
"name": ["Cancellation"],
"probability": 0.8374786376953125
},
{
"name": ["Admin"],
"probability": 0.0164003014564514
}
]

Para interpretar corretamente esse resultado, você precisa determinar a pontuação mínima de confiança na qual você tratará a previsão como dizendo "sim, o rótulo se aplica". Chamamos esse número de limite de pontuação de confiança.

Precisão e recall

Para entender os limites de confiança, você deve estar familiarizado com os termos precisão e recall. Você pode encontrar uma explicação desses termos em nossas páginas de suporte. Resumindo, uma alta precisão está relacionada a uma baixa taxa de falsos positivos (ou seja, seus resultados têm mais chances de serem precisos), e um recall alto está relacionado a uma taxa baixa de falsos negativos (ou seja, é menos provável que você perca resultados relevantes).

Limite de confiança

O limite de confiança para um rótulo corresponde a uma contrapartida específica de precisão versus recall. A menos que seu modelo funcione perfeitamente, ter alta precisão abrirá tempo para o recall e, por outro lado, terá um pouco de recall. Essas contrapartidas são visualizadas como uma curva de recall de precisão para cada rótulo na página Validação.

Figura 6. Curva de recall de precisão de um rótulo

Usando o controle deslizante interativo, você pode encontrar rapidamente o limite desejado: mova o controle deslizante para a direita para otimizar a precisão ou para a esquerda para otimizar o recall, até encontrar a precisão e o recall que correspondam aos requisitos do seu aplicativo. O valor limite exibido será o limite desejado. Se você quiser saber mais sobre a funcionalidade da página de Validação, consulte as páginas de suporte.

Observação:

Se você conferir a página Validação, poderá notar que as formas das preciso-recall-curves são diferentes para cada rótulo. Isso dá uma dica de como escolheremos os limites: escolheremos um limite individual para cada rótulo. Isso é particularmente importante em aplicativos de automação, nos quais é preciso garantir o melhor desempenho.

Exemplo de Limites

Para nosso aplicativo de amostra, escolheremos um balanceamento de precisão versus recall para os rótulos "Renovação", "Cancelamento" e "Admin", e otimizaremos o recall para o rótulo "Urgent" (para que tenhamos menos probabilidade de perca emails urgentes). (Observe que, devido a melhorias contínuas no desempenho de ML subjacente, no momento em que você estiver fazendo este tutorial, os valores de precisão e recall no limite escolhido podem ser ligeiramente diferentes do que é mostrado aqui.)

Figura 7. Precisão e recall do rótulo de administrador

Figura 8. Precisão e recall do rótulo de cancelamento

Figura 9. Precisão e recall do rótulo de renovação

Figura 10. Precisão e recall de rótulos urgentes

Usaremos os seguintes valores limite para o resto do tutorial.

Admin: 0.898 (corresponds to 100% precision at 100% recall)
Cancellation: 0.619 (corresponds to 100% precision at 100% recall)
Renewal: 0.702 (corresponds to 100% precision at 100% recall)
Urgent: 0.179 (corresponds to 83% precision at 100% recall)

Agora, podemos aplicar os limites ao nosso exemplo. O rótulo "Cancelamento" se aplica desde 0.8374786376953125 > 0.619. O rótulo "Admin" não se aplica desde 0.0164003014564514 < 0.898.

"labels": [
{
"name": ["Cancellation"],
"probability": 0.8374786376953125
},
{
"name": ["Admin"],
"probability": 0.0164003014564514
}
]

Para facilitar esse processo, a API do Streams permite que você especifique os limites de seu rótulo na configuração do Stream. Se especificado, apenas rótulos com valores acima do limite serão retornados.

Em um cenário real, o desempenho alvo de recall de precisão será definido pela combinação de requisitos de negócios e desempenho do modelo histórico. Por exemplo, se um rótulo atingiu anteriormente 85% de precisão com 55% de recall, você pode decidir investir tempo adicional para treiná-lo até 90% de precisão com 55% de recall. Então, você irá fixar a nova versão do modelo, escolher novos limiares e atualizar a configuração do seu aplicativo.

Crie seu aplicativo

Depois de finalizar o design, estamos prontos para começar a criar o aplicativo.

Fixar seu modelo

Acesse a página Modelos e fixe o modelo clicando no botão de alternância "Salvar". Assim que o modelo estiver fixado, você poderá começar a acessá-lo por meio da API.

Observação:

Se você quiser seguir esta parte do tutorial usando um conjunto de dados anotado diferente, certifique-se de que esteja suficientemente anotado. Em particular, um conjunto de dados com apenas alguns exemplos anotados produzirá um modelo que não retornará previsões para a maioria dos comentários.

Figura 11. Fixe a versão do modelo clicando no botão de alternância "Salvar"

Configuração do stream

In most cases, it is enough to specify the Stream name, dataset name and model version, and the labels you are interested in. For a full list of options, see the reference.

Para cada rótulo, você deve especificar um limite. Consulte a seção anterior neste tutorial sobre como escolher os limites de rótulos.

curl -X PUT 'https://<my_api_endpoint>/api/v1/datasets/<my-project>/<my-dataset>/streams' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "stream": {
        "name": "<my-stream-name>",
        "model": {
          "version": <my-model-version>,
          "label_thresholds": [
            {
              "name": [
                "Parent Label",
                "Child Label"
              ],
              "threshold": <my-label-threshold>
            },
            {
              "name": [
                "Label Without Parent"
              ],
              "threshold": <my-label-threshold>
            }
          ]
        }
      }
    }'

Loop Buscar e Avançar

Agora você pode usar seu fluxo para buscar comentários do Communications Mining. Observe que tamanhos de lote muito baixos (como a busca em lotes de 1 comentário) afetarão a velocidade em que os comentários são buscados.

curl -X POST 'https://<my_api_endpoint>/api/v1/datasets/<my-project>/<my-dataset>/streams/<my-stream-name>/fetch' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "size": <my-stream-batch-size>
    }'

A posição inicial do fluxo é definida para seu tempo de criação. Para fins de desenvolvimento, geralmente é útil buscar comentários que foram criados antes do fluxo. Para fazê-lo, você pode definir o fluxo como um carimbo de data/hora específico.

curl -X POST 'https://<my_api_endpoint>/api/v1/datasets/<my-project>/<my-dataset>/streams/<my-stream-name>/reset' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "to_comment_created_at": "<YYYY-MM-DDTHH:MM:SS>"
    }'

Se você executar novamente a solicitação fetch agora, ela será buscada a partir da mesma posição. Para buscar o próximo lote de comentários, você precisa confirmar o lote anterior com uma solicitação advance . Na solicitação advance , você deve fornecer um sequence_id , que pode ser encontrado em sua resposta fetch .

O loop buscar-e-avançar garante que você não pule acidentalmente comentários se seu aplicativo falhar durante o processamento. Observe que seu aplicativo precisa ser capaz de lidar com um comentário várias vezes no caso de processar um comentário com sucesso, mas falhar na etapa de avançar.

curl -X POST 'https://<my_api_endpoint>/api/v1/datasets/<my-project>/<my-dataset>/streams/<my-stream-name>/advance' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "sequence_id": "<my-sequence-id>"
    }'

Observe que você deve fornecer o nome do conjunto de dados em todas as solicitações de API usando o fluxo - isso ocorre porque os fluxos têm escopo em conjuntos de dados.

Resultados do Processo

A resposta conterá comentários, rótulos previstos e campos gerais, conforme descrito nas páginas Comentários , Rótulos e campos gerais . Consulte estas páginas para entender como analisar a resposta.

Manuseio de exceção

Se seu aplicativo permitir que os usuários marquem itens que foram previstos incorretamente, você pode usar o ponto de extremidade de exceção para marcar o comentário correspondente como uma exceção na plataforma. O nome da exceção ficará disponível como um filtro no conjunto de dados, para que o treinador do modelo possa revisar e anotar exceções para melhorar o modelo.

curl -X PUT 'https://<my_api_endpoint>/api/v1/datasets/<my-project>/<my-dataset>/streams/<my-stream-name>/exceptions' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "exceptions": [
        {
          "metadata": {
            "type": "Wrong Prediction"
          },
          "uid": "<comment-uid>"
        },
        {
          "metadata": {
            "type": "Wrong Prediction"
          },
          "uid": "<comment-uid>"
        }
      ]
    }'

Pronto!

Parabéns, você concluiu o tutorial de automação do Communications Mining. É claro que seu próprio aplicativo de automação pode ser diferente daquele abordado aqui. Entre em contato com o suporte se tiver dúvidas.