Opções de entidade

Há várias opções de entidades que alteram o comportamento da correspondência com entidades e da extração de dados. Essas opções são pré-configuradas para entidades do sistema, de modo que não é possível alterá-las para entidades desse tipo. No entanto, é possível alterá-las para suas entidades personalizadas. É possível criar diferentes tipos de entidades, dependendo das opções selecionadas:

Há outras opções que não determinam o tipo de entidade, mas afetam o comportamento da correspondência de entidade:

Neste documento, descrevemos cada uma dessas opções.

Onde encontrar esses dados

Ao criar um agente, o mais comum é usar o Console do Dialogflow CX (acesse a documentação, abra o Console). As instruções abaixo referem-se ao uso do Console. Para acessar os dados de opções da entidade:

  1. Abra o Console do Dialogflow CX.
  2. Escolha seu projeto do Google Cloud.
  3. Selecione seu agente.
  4. Selecione a guia Gerenciar.
  5. Clique em Tipos de entidade.
  6. Veja as opções a seguir para qualquer entidade atual. Alguns deles só estarão visíveis depois de abrir as Opções avançadas:
    • Somente entidades (sem sinônimos)
    • Entidades regexp
    • Adicionar entidades automaticamente
    • Correspondência difusa
    • Encobrir no registro
    • Exclusões de entidades

Se estiver criando um agente usando a API, em vez do console, consulte o tipo EntityType. Os nomes de campo da API são semelhantes aos nomes de campo do Console. As instruções abaixo destacam as diferenças importantes entre o Console e a API.

Selecione um protocolo e uma versão para a referência EntityType:

Protocolo V3 V3beta1
REST Recurso EntityType Recurso EntityType
RPC Interface de EntityType Interface de EntityType
C++ EntityTypesClient Indisponível
C# EntityTypesClient Indisponível
Go EntityTypesClient Indisponível
Java EntityTypesClient EntityTypesClient
Node.js EntityTypesClient EntityTypesClient
PHP Indisponível Indisponível
Python EntityTypesClient EntityTypesClient
Ruby Indisponível Indisponível

Entidade de mapeamento

Entidades de mapeamento fornecem um mapa dos valores de referência para os sinônimos para cada valor de referência. Cada entrada de entidade do mapa contém um único valor de referência e uma lista de sinônimos. Também é possível defina um padrão DTMF para cada entidade.

Por exemplo, cada uma das linhas a seguir são entradas de entidade para um tipo de entidade size:

Entity Sinônimos Padrão DTMF
S S, "small", pequeno, reduzido
M M, "medium", médio, mediano
L L, "large", grande, enorme

O valor de referência é incluído na lista de sinônimos para cada entrada de entidade acima. Para que um valor de referência seja correspondido, ele precisa ser incluído como sinônimo. Quando você insere um valor de referência com o Console, ele é automaticamente adicionado como sinônimo.

Se algum dos sinônimos corresponder a uma parte da entrada do usuário final, o valor de referência associado será extraído para a correspondência e usado para resolver o valor do parâmetro.

Não há problema em omitir o valor de referência da lista de sinônimos. Isso apenas significa que ele não corresponde a nenhuma parte da entrada do usuário final, mas é usado como valor extraído quando um dos sinônimos corresponde. Isso serve para quando você usa strings especiais para valores de referência que não são digitados nem falados pelos usuários finais.

Muitas entidades do sistema são entidades de mapeamento. Por exemplo, a entidade do sistema @sys.date corresponde a entradas de datas comuns, como "1º de janeiro de 2015" ou "Primeiro de janeiro de 2015". Essas duas entradas são mapeadas para um valor de referência no formato ISO-8601: "2015-01-01T12:00:00-03:00".

Para criar uma entidade de mapeamento:

  • Com o Console, desmarque a opção Entidades regexp e desmarque a opção Apenas entidades.
  • Usando a API, defina o campo EntityType.kind como KIND_MAP.

Entidade de lista

Entidades de lista fornecem uma lista de entradas de entidades de valor único. Elas não têm valores de referência nem sinônimos. Por exemplo, cada uma das linhas a seguir são entradas de entidade para um tipo de entidade material:

Valor
tecido
madeira
metal

Se algum valor corresponder a uma parte da entrada do usuário final, o valor será extraído para a correspondência e usado para resolver o valor do parâmetro associado.

Muitas entidades do sistema são entidades de lista. Por exemplo, a entidade do sistema @sys.color corresponde a entradas de cores comuns, como "vermelho" ou "azul". Quando uma cor tem correspondência, o valor extraído não é mapeado para nenhum valor de referência. Por exemplo, tons de vermelho, como "escarlate" ou "carmesim" não são mapeados para "vermelho". Em vez disso, eles são extraídos como valores originais, "escarlate" e "carmesim".

Para criar uma entidade de lista:

  • Usando o console, desmarque a opção Entidades regexp e marque a opção Apenas entidades.
  • Usando a API, defina o campo EntityType.kind como KIND_LIST.

Entidade composta

Uma entidade composta é um tipo especial de entidade de lista. Entradas de entidades de lista normalmente têm palavras ou frases simples, mas também podem ter outros tipos de entidades. Quando um tipo de entidade é referenciado em outro tipo de entidade, a referência é chamada de alias. Quando uma entidade de lista tem alias para outros tipos de entidade, ela é chamada de entidade composta.

Ao criar um alias, você precisa fornecer o nome do tipo de entidade referenciado e um nome exclusivo de sua escolha. Quando uma entidade composta tem correspondência no ambiente de execução, o valor extraído é retornado como um objeto JSON, com o nome exclusivo do alias usado como nomes de propriedade JSON. O formato para inserir um alias é:

@entity-name:property-name

Por exemplo, é possível criar um tipo de entidade place que corresponda a uma cidade ou estado com as entradas de entidade a seguir:

Valor
@sys.geo-city:city
@sys.geo-state:state

Se uma entrada de usuário final tiver uma parte "Nashville", o tipo de entidade place irá corresponder. O valor extraído é retornado como: {"city": "Nashville"}.

Também é possível usar vários alias em uma entrada de entidade. Considere o tipo de entidade personalizada move, que contém alias para um tipo de entidade direction e o tipo de entidade @sys.number do sistema:

Tipo personalizado de entidade de mapeamento relacionada a direções:

Valor de referência Sinônimos
frente frente, para frente
atrás atrás, para trás, voltar

Tipo de entidade da lista personalizado relacionado a movimentação:

Valor
@sys.number:steps steps @direction:direction

Se a entidade move corresponder a uma entrada de usuário final que contenha "cinco passos para trás", a entidade move irá corresponder. O valor extraído é retornado como: {"steps": 5, "direction": "back"}.

Muitas entidades do sistema são entidades compostas. Por exemplo, a entidade do sistema @sys.unit-currency é usada para valores corresponder valores monetários com o nome de uma moeda. Ela combina entradas do usuário final como "50 euros" ou "20 dólares e cinco centavos". O valor extraído é retornado como um objeto JSON: {"amount": 50, "currency": "EUR"}

Entidade regexp

Com entidades regexp, é possível fornecer expressões regulares para correspondência. Para mais informações, consulte Entidades regexp.

Para criar uma entidade regexp:

  • Usando o console, marque a opção Entidades regexp.
  • Usando a API, defina o campo EntityType.kind como KIND_REGEXP.

Expansão automatizada (adicionar entidades automaticamente)

É possível ativar a expansão automatizada para um tipo de entidade personalizada. Quando ativada, o agente pode reconhecer valores que não foram fornecidos explicitamente. Por exemplo, considere um tipo de entidade de lista de compras:

Valor
pão
manteiga
leite
maçã
sorvete

Se a entrada de um usuário final for "Preciso comprar cenoura", "cenoura" corresponderá a esse tipo de entidade, mesmo que não seja fornecida. O agente reconhece "cenoura" como sendo semelhante a outros valores em termos de contexto.

Siga estas práticas recomendadas quando for considerar a expansão automatizada:

  • Ativar a expansão automática não garante a extração de entidades. Para uma lista finita, forneça a lista completa em vez de fornecer uma lista parcial e ativar a expansão automatizada.
  • Ativar a expansão automatizada em mais de uma entidade pode gerar conflitos e resultados de classificação inesperados.
  • Para garantir melhor qualidade de extração de parâmetros, é essencial fornecer dados de treinamento diversos que cubram todos os casos de uso em que uma determinada entidade pode ser encontrada no tráfego do agente esperado. Sem exemplos suficientes, a expansão automática de entidades pode não funcionar como esperado.

Para ativar a expansão automatizada:

  • Usando o console, marque a opção Adicionar entidades automaticamente.
  • Usando a API, defina o campo EntityType.autoExpansionMode como AUTO_EXPANSION_MODE_DEFAULT.

Correspondência parcial

É possível ativar a correspondência parcial para uma entidade personalizada. Com a correspondência parcial ativada, a ordem das palavras em um valor ou sinônimo não importa. Para mais informações, consulte Correspondência parcial.

Para ativar a correspondência parcial:

  • Usando o Console, marque a opção Fuzzy matching.
  • Usando a API, defina o campo EntityType.enableFuzzyExtraction como true.

Editar no registro

Se você ativar a omissão de entidades, todos os valores de parâmetro extraídos no tempo de execução para o tipo de entidade serão omitidos no registro.

Como alternativa, você pode encobrir parâmetros individuais.

Exclusões de entidades

Você pode adicionar exclusões de entidades, que são frases que não devem ter correspondência. Por exemplo, se você tiver um tipo de entidade de tamanho com a entidade gigante (um adjetivo), adicione gigantes (um substantivo) como uma exclusão.