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:

Também há duas 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 ES. Acesse a documentação e abra o Console (em inglês). As instruções abaixo referem-se ao uso do Console. Para acessar os dados de opções da entidade:

  1. Acesse o Console do Dialogflow ES.
  2. Selecione um agente.
  3. Selecione Entities no menu da barra lateral à esquerda.
  4. Selecione a guia Custom para entidades personalizadas definidas para seu agente ou a guia System para entidades do sistema usadas pelo seu agente.
  5. Veja as opções de caixa de seleção a seguir para qualquer entidade atual:
    • Define synonyms
    • Regexp entity (somente para entidades personalizadas)
    • Allow automated expansion (somente para entidades personalizadas)
    • Fuzzy matching (somente para entidades personalizadas)

Se você estiver usando a API em vez do Console para criar um agente, consulte a referência de EntityTypes. 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.

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 do mapa de entidades tem um único valor de referência e uma lista de sinônimos. Por exemplo, cada uma das linhas a seguir são entradas de entidade para um tipo de entidade size:

Valor de referência Sinônimos
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 tiver correspondência com uma parte da expressão 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 associado.

Não há problema em omitir o valor de referência da lista de sinônimos. Isso significa apenas que ele não tem correspondência com nenhuma parte da expressão do usuário final, mas é usado como o valor extraído quando um dos sinônimos tem correspondência. 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:

  • Usando o Console, desmarque a opção Regexp entity e marque a opção Define synonyms.
  • 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 tiver correspondência com uma parte da expressão 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 Regexp entity e a opção Define synonyms.
  • 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 expressão de usuário final tiver uma parte "Nashville", o tipo de entidade place será correspondido. 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 tiver correspondência com uma expressão de usuário final que inclua "cinco passos para trás", a entidade move será correspondida. 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 expressões 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 RegExp entity.
  • Usando a API, defina o campo EntityType kind como KIND_REGEXP.

Expansão automatizada

É 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 uma expressão do usuário final for "Preciso comprar cenoura", "cenoura" corresponderá a esse tipo de entidade, mesmo que esse valor não tenha sido fornecido. 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 Allow automated expansion.
  • 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.