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 próprios campos gerais. Para entender onde encontrá-los nos dados baixados, consulte a documentação do método de download escolhido.

Rótulos

Um comentário pode ter zero, um ou vários rótulos previstos. O exemplo a seguir mostra dois rótulos previstos, Order e Order > Ausente, juntamente com suas pontuações de confiança. A maioria das rotas de API usa esse formato. Uma exceção é a rota Exportação de conjunto de dados , 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, que atualmente são Rotas de previsão, retornarão opcionalmente uma lista de nomes de limites, como "high_recall", "balanced", "high_precision" que a pontuação de confiança do rótulo atende. Essa é uma alternativa útil para a escolha manual de limites, especialmente para taxonomias muito grandes. Em seu aplicativo, você decide se está interessado em resultados "high_recall", "balanced" ou "high_precision", 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:

Name	Tipo	Description
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	number	Pontuação de confiabilidade. Um número entre 0,0 e 1,0.
sentiment	number	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.

Os nomes dos rótulos devem:

• Comece com qualquer caractere de palavra unicode, por exemplo, caracteres não específicos ou pontuação.
• Conter qualquer combinação de caracteres de palavra, espaços ou qualquer um dos caracteres especiais listados na tabela a seguir.

Por exemplo, Hello World! é válido, mas !Hello World não é.

Caractere especial	Name
~	UiPath
!	Ponto de exclamação
@	No sinal
#	Assinatura de hash
$	Sinal de dólar
R$	Sinal do Euro
%	Sinal de porcentagem
^	Sinal de inserção
&	Ampersand
*	Asterisk
(	Parêntese esquerdo
)	Parêntese direito
_	Sublinhado
+	Sinal de mais
-	Hífen
=	sinal de igual
[	Colchete esquerdo
]	Colchete direito
{	Chave à esquerda
}	Chave chave direita
;	Ponto e vírgula
'	Apóstrofos
\	Barra invertida
:	Colon
"	Quotation mark
|	Barra vertical
,	Vírgula
.	Período
/	Barra para frente
<	Less than sign
?	Question mark

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% do tempo, 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 Seleção de limites de confiança do rótulo.

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.

Perguntas frequentes sobre rótulos

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

A: os seguintes métodos de download fornecem rótulos: Communications Mining, downloads de CSV e ferramenta de linha de comando do Communications Mining . Confira a página Download de dados para uma visão geral dos métodos de download disponíveis, e o seguinte item de perguntas frequentes para uma comparação detalhada.

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

R: As tabelas a seguir explicam as diferenças entre os métodos de download. Uma descrição dos 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 , Download de CSV, a ferramenta de linha de comando do Communications Mining e o ponto de extremidade da API Exportar fornecem as previsões mais recentes disponíveis.

Observação: após o treinamento de uma nova versão do modelo, mas antes de todas as previsões serem recalculadas, você notará uma mistura de previsões das versões mais recente e anterior do modelo. Esses métodos estão cientes dos 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

Em contraste com os métodos não determinísticos anteriores, as rotas Stream API e Predict API retornarão previsões de uma versão de modelo específica. Dessa forma, essas rotas de API se comportam como se você baixasse um comentário da plataforma e o enviasse para previsão em 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).

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 seguinte exemplo mostra uma entidade order_number prevista.

Observação: ao contrário 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 intervalo representa os limites da entidade no comentário correspondente. O formatted_value normalmente corresponde ao texto coberto por esse intervalo, exceto em algumas instâncias específicas que descrevemos nas seções a seguir.

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 métodos de download a seguir fornecem os campos gerais: Communications Mining e ferramenta de linha de comando do Communications Mining . Dê uma olhada na Visão geral do download de dados para entender qual método é adequado para seu caso de uso. 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 de Predict API 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 plataforma os usuários podem 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.