Rótulos e campos gerais

Esta página descreve como interpretar rótulos e campos gerais baixados da plataforma Communications Mining para uso em seu aplicativo. Esta página descreve os rótulos e os campos gerais em si. Para saber onde encontrá-los nos dados baixados, consulte a documentação referente ao método de download escolhido.

Rótulos

Um comentário pode ter zero, um ou vários rótulos previstos. O exemplo abaixo mostra dois rótulos previstos (Pedido e Pedido > Ausente) juntamente com suas pontuações de confiança. Esse formato é usado pela maioria das rotas de API. Uma exceção é a rota Dataset Exportt, que formata nomes de rótulos como strings em vez de listas (para ser consistente com a exportação de CSV no navegador).

Algumas rotas (atualmente Prever rotas) retornarão opcionalmente uma lista de nomes de limites ("alto_recall", "balanced", "alto_precision") aos quais a pontuação de confiança do rótulo atende. Essa é uma alternativa útil para a seleção manual de limites, especialmente para taxonomias muito grandes. No aplicativo, você decide se está interessado em resultados " High_recall ", " Balanced " ou " High_precision ", depois descarta todos os rótulos que não têm o limite automático escolhido e processa os rótulos restantes como antes.

• Todas as rotas, exceto Exportação de conjunto de dados

  {
    "labels": [
      {
        "name": ["Order"],
        "probability": 0.6598735451698303
      },
      {
        "name": ["Order", "Missing"],
        "probability": 0.6598735451698303
      }
    ]
  }

• Exportação de conjunto de dados

  {
    "labels": [
      {
        "name": "Order",
        "probability": 0.6598735451698303
      },
      {
        "name": "Order > Missing",
        "probability": 0.6598735451698303
      }
    ]
  }

• Prever (limiar automaticamente)

  {
    "labels": [
      {
        "name": ["Order"],
        "probability": 0.6598735451698303,
        "auto_thresholds": ["high_recall", "balanced", "sampled_2"]
      },
      {
        "name": ["Order", "Missing"],
        "probability": 0.6598735451698303,
        "auto_thresholds": ["high_recall", "sampled_2"]
      }
    ]
  }

O objeto Rótulo tem o seguinte formato:

Nome	Tipo	Descrição
name	array<string> ou string	Todas as rotas de API, exceto Exportação de conjunto de dados: o nome do rótulo previsto, formatado como uma lista de rótulos hierárquicos. Por exemplo, o rótulo Rótulo pai > Rótulo filho terá o formato ["Parent Label", "Child Label"]. Rota da API de exportação de conjunto de dados: o nome do rótulo previsto, formatado como uma string com " > " rótulos hierárquicos de separação.
probability	Número	Pontuação de confiabilidade. Um número entre 0,0 e 1,0.
sentiment	Número	Pontuação de opinião. Um número entre -1.0 e 1.0. Retorna apenas se os sentimentos estiverem habilitados no conjunto de dados.
auto_thresholds	array<string>	Uma lista de limites calculados automaticamente que a pontuação de confiança do rótulo atende. Os limites são retornados como nomes descritivos (em vez de valores entre 0,0 e 1) que podem ser usados para filtrar facilmente rótulos que não atendem aos níveis de confiança desejados. Os nomes de limites "alto_recall", "balanced" e "alta_precision" correspondem a três níveis de confiança crescentes. Os limites adicionais "sampled_0" ... "sampled_5" fornecem uma maneira mais avançada de executar agregações para aplicativos de ciência de dados e podem ser ignorados se você estiver processando comentários individualmente.

Perguntas frequentes sobre rótulos

P: como posso baixar rótulos da plataforma Communications Mining?

R: Os seguintes métodos de download fornecem rótulos: API do Communications Mining , downloads de CSV e ferramenta de linha de comando do Communications Mining. Dê uma olhada na página Baixando dados para ter uma visão geral dos métodos de download disponíveis, e o item de Perguntas frequentes abaixo para uma comparação detalhada.

P: Todos os métodos de download fornecem as mesmas informações?

R: As tabelas abaixo explicam as diferenças entre os métodos de download. Uma descrição de rótulos na página Explorar na UI da Web do Communications Mining é fornecida para comparação.

Métodos não deterministas

A página Explorar, o download de CSV, a ferramenta de linha de comando do Communications Mining e o endpoint da API de Exportação fornecem as previsões disponíveis mais recentes. Observe que após o treinamento de uma nova versão do modelo, porém antes que todas as previsões sejam recalculadas, você verá uma mistura de previsões da versão mais recente e anterior do modelo. Esses métodos estão cientes de rótulos atribuídos e os mostrarão como atribuídos ou com uma pontuação de confiança de 1.

Método	Rótulos Atribuídos	Rótulos Previstos
Explorar página	A página de Exploração diferencia visualmente rótulos atribuídos de rótulos previstos. Ele não relata pontuações de confiança para rótulos atribuídos.	A página Explorar foi projetada para oferecer suporte ao fluxo de trabalho de treinamento do modelo e, portanto, ela mostra rótulos previstos selecionados que o usuário pode querer fixar. Ela mostrará preferencialmente rótulos que atendem a um limite equilibrado (derivado da pontuação F para esse rótulo), mas também pode mostrar rótulos com menor probabilidade como uma sugestão, se for provável que o usuário queira fixá-los.
API de exportação	Retorna rótulos atribuídos.	Retorna todos os rótulos previstos (nenhum limite é aplicado).
Download de CSV	Retorna uma pontuação de confiança de 1 para rótulos atribuídos. Observe que os rótulos previstos também podem ter uma pontuação de 1 se o modelo for muito confiável.	Retorna todos os rótulos previstos (nenhum limite é aplicado).
CLI do Communications Mining	Se um comentário tiver rótulos atribuídos, retornará tanto os rótulos atribuídos quanto os previstos para esse comentário.	Retorna todos os rótulos previstos (nenhum limite é aplicado).

Métodos deterministas

Ao contrário dos métodos não deterministas acima, as rotas Stream API e Prever API retornarão previsões de uma versão específica do modelo. Dessa forma, essas rotas de API se comportam como se você baixasse um comentário da plataforma e o enviasse para previsão em relação a uma versão de modelo específica e não estivesse ciente dos rótulos atribuídos.

Método	Rótulos Atribuídos	Rótulos Previstos
API de stream e API de previsão	Não reconhece rótulos atribuídos.	Retornar rótulos previstos com pontuação de confiança acima dos limites de rótulo fornecidos (ou acima do valor padrão de 0,25 se nenhum limite for fornecido).

Uso de rótulos na automação

Ao projetar um aplicativo que toma decisões por mensagem, você desejará converter a pontuação de confiança de cada rótulo em uma resposta Sim ou Não. Você pode fazer isso determinando 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.

Importante:

Como escolher um limite de pontuação de confiança

Um equívoco comum é escolher o limite para igualar a precisão que você gostaria de obter ("Quero que os rótulos estejam corretos pelo menos 70% das vezes, então escolherei rótulos com pontuações de confiança acima de 0,70"). Para entender os limites e como selecioná-los, consulte a seção Limites de confiança do guia de integração.

Uso de rótulos na análise

Se você estiver exportando rótulos para uso em um aplicativo de análise, é importante decidir se vai expor as pontuações de confiança aos usuários. Para usuários de aplicativos de análise de negócios, você deve converter as pontuações de confiança na presença ou ausência do rótulo usando uma das abordagens descritas na seção Automação . Por outro lado, usuários de aplicativos de ciências de dados hábeis no trabalho com dados probabilísticas serão beneficiados com o acesso a pontuações de confiança brutas.

Uma consideração importante é garantir que todas as previsões em seu aplicativo de análise sejam da mesma versão do modelo. Se você estiver atualizando sua integração para buscar previsões de uma nova versão do modelo, todas as previsões precisarão ser reingeridas para que os dados permaneçam consistentes.

propriedades do rótulo

Se os rótulos de Qualidade do Serviço tiverem sido adicionados ao conjunto de dados, a resposta da previsão conterá uma pontuação da Qualidade do Serviço para cada comentário. Se o Tom tiver sido habilitado em um conjunto de dados, a resposta da previsão conterá uma pontuação do Tom para cada comentário. Ambas as pontuações podem ser encontradas na parte label_properties da resposta.

{
  "label_properties": [
    {
      "property_id": "0000000000000001",
      "property_name": "tone",
      "value": -1.8130283355712891
    },
    {
      "id": "0000000000000002",
      "name": "quality_of_service",
      "value": -3.006324252113699913
    }
  ]
}

O objeto de propriedade rótulo tem o seguinte formato:

Nome	Tipo	Descrição
name	String	Nome da propriedade do rótulo.
id	String	ID interno da propriedade do rótulo.
value	Número	Valor da propriedade do rótulo. Valor entre -10 e 10.

Campos gerais

Um comentário pode ter zero, um ou vários campos gerais previstos. O exemplo abaixo mostra uma entidade order_number prevista. Observe que, diferentemente dos rótulos, os campos gerais não têm pontuações de confiança associadas.

"entities": [
    {
        "id": "0abe5b728ee17811",
        "name": "order_number",
        "span": {
            "content_part": "body",
            "message_index": 0,
            "utf16_byte_start": 58,
            "utf16_byte_end": 76,
            "char_start": 29,
            "char_end": 38
        },
        "name": "order_number",
        "kind": "order_number", # deprecated
        "formatted_value": "ABC-123456",
        "capture_ids": []
    }
]

A API retorna entidades no seguinte formato:

Nome	Tipo	Descrição
id	String	ID da entidade.
name	String	Nome da entidade.
kind	String	(Obsoleto) Tipo de entidade.
formatted_value	String	Valor da entidade.
span	Span	Um objeto que contém a localização da entidade no comentário.
capture_ids	array<int>	Os IDs de captura dos grupos aos quais uma entidade pertence.

Formatting

Cada entidade tem um span e um formatted_value. O período representa os limites da entidade no comentário correspondente. O formatted_value normalmente corresponde ao texto coberto por esse período, exceto em alguns casos específicos que descrevemos abaixo.

Quantia Monetária

A entidade Monetary Quantity extrairá uma grande variedade de valores monetários e aplicará uma formatação comum. Por exemplo, "1M USD", "USD 1000000" e "1.000.000 usd" serão extraídos como 1,000,000.00 USD. Como o valor extraído é formatado de maneira consistente, você pode obter facilmente a moeda e o valor dividindo no espaço em branco.

No entanto, se a moeda for ambígua, o valor extraído manterá a moeda ambígua. Por exemplo, "$1M" e "$1.000.000" serão extraídos como $1,000,000.00 em vez de 1,000,000.00 USD, pois o sinal "$" pode se referir a um dólar canadiano ou australiano, bem como a um dólar americano.

Data

A entidade Date extrairá qualquer data que apareça em um comentário e as normalizará usando o formato padrão ISO 8601, seguido pela hora em UTC. Por exemplo, "Jan 25 2020", "25/01/2020" e "now" em um email enviado em 25 de janeiro de 2020 serão todos extraídos como "2020-01-25 00:00 UTC".

Essa formatação será aplicada a qualquer entidade que tenha um tipo correspondente a uma data, como datas de cancelamento, datas valor ou qualquer tipo de data que tenha sido treinada pelo usuário.

Se algumas partes da data estiverem ausentes, o carimbo de data/hora do comentário será usado como âncora; a data "às 16h do dia cinco do mês" em uma mensagem enviada em 1º de maio de 2020 será extraída como "2020-05-05 16:00 UTC". Se nenhum fuso horário for fornecido, o fuso horário do comentário será usado, mas a data extraída sempre será retornada no fuso horário UTC.

País

Os nomes de países são normalizados para um valor comum; por exemplo, tanto as strings "UK" quanto "Reino Unido" terão o valor formatado "Reino Unido".

IDs de captura

Se um comentário foi processado como rich text, contém uma tabela e uma entidade foi correspondida nessa tabela, a propriedade capture_ids dessa entidade conterá um ID de captura. Entidades correspondentes na mesma linha da tabela terão o mesmo ID de captura, permitindo que sejam agrupadas.

Por exemplo, um Order ID pode ser associado a um Order Date. Em um comentário em que vários pedidos são referidos, é possível distinguir os diferentes detalhes do pedido agrupando entidades por seus IDs de captura.

Hoje, as entidades correspondidas em uma tabela pertencem exatamente a um grupo, ou seja, sua propriedade capture_ids contém exatamente um ID. No futuro, a API poderá retornar vários IDs.

Em todos os outros casos, a propriedade capture_id será uma lista vazia.

Observação: as entidades agora serão preservadas ao fazer atualizações de texto por meio de upload de arquivo CSV ou API.

Perguntas frequentes sobre campos gerais

P: Como posso baixar campos gerais da plataforma Communications Mining?

R: Os seguintes métodos de download fornecem campos gerais: API do Communications Mining e ferramenta de linha de comando do Communications Mining . Dê uma olhada na Visão geral de download de dados para entender qual método é adequado para o seu caso de uso. Observe que os downloads de CSV não incluirão campos gerais.

Modelos

Tags de teste e ativas

Para facilitar o uso com integrações, uma versão de modelo pode ser marcada como staging ou live na interface gráfica do Communications Mining. Essa tag pode ser fornecida para solicitações da API Prever no lugar do número da versão do modelo. Isso permite que sua integração busque previsões de qualquer versão do modelo para a qual a tag Staging ou Live aponta, qual dos usuários da plataforma pode gerenciar facilmente a partir da interface gráfica do Communications Mining.

Detalhes da Versão do Modelo

Os detalhes sobre uma versão específica do modelo podem ser obtidos usando o ponto de extremidade da API de Validação.

Além disso, as respostas às solicitações de previsão contêm informações sobre o modelo que foi usado para fazer as previsões.

"model": {
    "version": 2,
    "time": "2021-02-17T12:56:13.444000Z"
}

Nome	Tipo	Descrição
time	Carimbo de data/hora	Quando a versão do modelo foi fixada.
version	Número	Versão do modelo.