Configuração de pesquisa do repositório de dados

É possível influenciar os resultados da pesquisa recuperados das ferramentas de repositório de dados do Dialogflow CX configurando as especificações de otimização e filtro. Isso permite interações mais personalizadas e contextuais quando o agente usa um repositório de dados para encontrar informações.

Opcionalmente, você pode incluir expressões dinâmicas para ajustar os resultados com base no contexto da conversa. Por exemplo, seu agente capturou informações indicando que o usuário final tem um "smartphone". Você pode configurar a ferramenta de repositório de dados para otimizar documentos relacionados a smartphones ao responder a uma consulta geral mais tarde na conversa, como "Como faço para verificar minha caixa postal?".

É possível configurar os resultados da pesquisa do repositório de dados usando o console, API, ou a integração do Dialogflow CX Messenger.

Entradas de condição de pesquisa

Os resultados da pesquisa são configurados usando os especificação de otimização (BoostSpec) e especificação de filtro (FilterSpec) campos em um SearchConfig objeto. Essas configurações são aplicadas por repositório de dados na ferramenta, oferecendo controle refinado sobre o comportamento de cada repositório de dados conectado.

É possível configurar as condições de pesquisa de duas maneiras: usando o console, ou enviando uma chamada de API direta. Há distinções importantes entre as duas.

• Chamada de API: BoostSpec e FilterSpec são enviados em um SearchConfig usando uma chamada de API DetectIntent. Um objeto completo SearchConfig precisa ser fornecido na solicitação. Um SearchConfig enviado por chamada de API direta sempre substitui um SearchConfig enviado usando o console. Expressões dinâmicas e referências de parâmetros não são aceitas.

• Console: as configurações BoostSpec e FilterSpec são usadas para construir um objeto SearchConfig que é enviado com a solicitação de pesquisa. Opcionalmente, você pode incluir referências de parâmetros e expressões dinâmicas para adaptar os resultados aos dados de contexto gravados na conversa. Só é necessário fornecer objetos ConditionBoostSpec e uma lista de strings de filtro para construir FilterSpecs, em vez de um objeto SearchConfig completo.

As informações do usuário final são fornecidas como JSON. Não há um esquema esperado, então você pode definir as propriedades do objeto.

Especificações de otimização

As especificações de otimização permitem mudar a classificação dos resultados da pesquisa aplicando um valor de otimização a documentos específicos. É possível adicionar várias especificações de otimização a um único repositório de dados.

Cada especificação de otimização é inserida como uma string JSON. Essa string JSON precisa representar um único objeto ConditionBoostSpec.

Campos-chave:

• condition: (string) uma expressão que especifica quando a otimização deve ser aplicada. Ela usa a sintaxe de expressão de filtro padrão filter expression syntax. É possível usar expressões do Dialogflow CX para tornar os resultados dinâmicos, como $session.params.YOUR_PARAM_NAME ou $request.end-user-metadata.YOUR_KEY.
• boost: (número) um valor entre -1,0 e 1,0 que determina a intensidade da otimização.
  • Um valor positivo promove documentos correspondentes. Um valor de 1.0 oferece uma promoção forte.
  • Um valor negativo rebaixa documentos correspondentes. Um valor de -1.0 oferece uma rebaixamento forte.
  • Um valor de 0.0 não aplica nenhuma otimização e não é permitido.
• boostControlSpec: oferece mais controles para uma classificação personalizada do que a combinação básica de condição e otimização. Para mais informações sobre como configurar esse campo, consulte a documentação de referência.

Exemplo de entrada do console:

Se você estiver configurando o agente no console, será necessário fornecer uma lista de ConditionBoostSpecs no formato a seguir.

Neste exemplo, os documentos com um URI correspondente ao valor do parâmetro de sessão $session.params.doc_id serão otimizados com uma intensidade de 0,5. JSON desse formato

{
  "condition": "uri: ANY(\"http://www.example.com/docs/$session.params.doc_id\")",
  "boost": 0.5
}

Exemplo de entrada da API:

Se você estiver chamando a API diretamente, será necessário fornecer ConditionBoostSpecs em um objeto SearchConfig completo.A configuração de pesquisa a seguir descreve uma especificação de otimização:

"searchConfig": {
  "boostSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "spec": [
        {
          "conditionBoostSpecs": {
            "condition": "CONDITION",
            "boost": "1.0"
          }
        }
      ]
    }
  ]
}

Observação: DATASTORE_ID é o nome completo do repositório de dados: projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name,
CONDITION precisa seguir a sintaxe de expressão de filtro da Pesquisa do agente,
e o valor de otimização precisa estar entre -1,0 e 1,0.

Especificações de filtro

As especificações de filtro restringem os resultados da pesquisa para incluir apenas documentos que correspondam aos critérios definidos. É possível adicionar várias especificações de filtro a um único repositório de dados.

Cada especificação de filtro precisa ser inserida como uma expressão de string. A string precisa estar em conformidade com a sintaxe de expressão de filtro padrão. É possível usar expressões do Dialogflow CX nessa string para tornar os resultados dinâmicos, como $session.params.YOUR_PARAM_NAME ou $request.end-user-metadata.YOUR_KEY.

Exemplo de string de especificação de filtro do console:

Se você configurar o agente usando o console, será necessário fornecer uma lista de filter strings para formar um FilterSpec objeto.

Neste exemplo, o filtro retorna apenas documentos com numeric_field maior ou igual ao valor de $session.params.min_value E em que stock_availability é "IN_STOCK".

"numeric_field >= $session.params.min_value AND stock_availability: ANY(\"IN_STOCK\")"

Exemplo de configuração de filtro da API:

Se você estiver chamando a API diretamente, será necessário fornecer strings filter em um objeto SearchConfig completo:

"searchConfig": {
  "filterSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "filter": "CONDITION"
    }
  ]
}

Observação: DATASTORE_ID é o nome completo do repositório de dados: projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name,
e CONDITION precisa seguir a sintaxe de expressão de filtro da Pesquisa do agente.

Expressões dinâmicas do Dialogflow CX

**Observação** :as expressões dinâmicas estão disponíveis apenas para ferramentas de repositório de dados. Elas não estão disponíveis para processadores de repositório de dados.

As condições BoostSpec e as strings FilterSpec podem incorporar expressões do Dialogflow CX para torná-las dinâmicas. Isso permite adaptar o comportamento de pesquisa com base nos dados de contexto recuperados de uma conversa em andamento. As expressões dinâmicas não são aceitas em chamadas de API diretas e só podem ser usadas se você estiver configurando usando o console.

É possível acessar dados de contexto de conversa de duas maneiras:

• Parâmetros de sessão:valores coletados durante a conversa usando $session.params.YOUR_PARAMETER_ID.
• Metadados do usuário final:metadados sobre o usuário final transmitidos no DetectIntentRequest usando $request.end-user-metadata.YOUR_KEY. Para que essa opção esteja disponível, verifique se end_user_metadata está incluído nos QueryParameters das chamadas DetectIntent. Para mais informações, consulte endUserMetadata.

Para mais detalhes sobre as funções do sistema e a sintaxe de expressão disponíveis, consulte a referência de condições e funções do sistema.

Condições de pesquisa aplicadas no ambiente de execução

Quando a ferramenta de repositório de dados executa uma pesquisa:

1. As strings JSON fornecidas para as especificações de otimização são avaliadas. Cada string JSON válida é convertida em um objeto ConditionBoostSpec. Elas são agrupadas em um objeto BoostSpecs para a conexão de repositório de dados específica, que é adicionada ao SearchConfig geral.
2. As strings fornecidas para as especificações de filtro são avaliadas como expressões do Dialogflow CX. Cada string de filtro resultante é usada para criar um objeto FilterSpecs para o repositório de dados, que também é adicionado ao SearchConfig.
3. Esse SearchConfig construído dinamicamente é incluído nos QueryParameters da solicitação de pesquisa enviada ao repositório de dados.

Configurar condições de pesquisa

Antes de configurar as condições de pesquisa, verifique se você tem:

• Um agente do Dialogflow CX.
• Uma ferramenta de repositório de dados configurada para seu agente com um ou mais repositórios de dados ativados.

Configuração do console

1. Abra o console dos Agentes de conversação e escolha um Google Cloud projeto.
2. Selecione um agente no menu suspenso.
3. No menu à esquerda, clique em Ferramentas. Selecione a ferramenta de repositório de dados que você quer configurar.
4. Na página de edição da ferramenta, acesse a seção Repositórios de dados. Clique no ícone Configurações (⚙️) ao lado do repositório de dados que você quer modificar.
5. O menu Configurar repositório de dados aparece. Aqui, você pode adicionar especificações de otimização e especificações de filtro para modificar os resultados da pesquisa.
   • Para uma especificação de otimização, forneça um objeto JSON que defina um ConditionBoostSpec. Consulte Especificações de otimização para mais detalhes.
   • Para uma especificação de filtro, forneça uma string que defina os critérios de filtro. Consulte Especificações de filtro para mais detalhes.
6. Depois de adicionar e configurar as especificações, clique em Confirmar na parte de baixo do painel lateral.
7. Clique em Salvar na página de edição da ferramenta de repositório de dados para salvar as mudanças.

Configuração da API

É possível fornecer dados de configuração de pesquisa para o Dialogflow CX ao enviar solicitações de detecção de intent. Essas informações precisam ser fornecidas em todas as solicitações de detecção de intent, porque não são mantidas na sessão.

Forneça essas informações no campo queryParams.searchConfig no método Sessions.detectIntent.

Acessar a referência da API Session

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

Protocolo	V3	V3beta1
REST	Recurso da sessão	Recurso da sessão
RPC (remote procedure call)	Interface da sessão	Interface da sessão
C++	SessionsClient	Indisponível
C#	SessionsClient	Indisponível
Go	SessionsClient	Indisponível
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	Indisponível	Indisponível
Python	SessionsClient	SessionsClient
Ruby	Indisponível	Indisponível

Fechar

Configuração do Dialogflow CX Messenger

É possível fornecer dados de configuração de pesquisa para a integração do Dialogflow CX Messenger. Consulte o setContext método para mais informações.

Para aplicar uma especificação ou configuração de pesquisa, o snippet a seguir precisa ser adicionado ao código do Dialogflow CX Messenger ao incorporá-lo a um site:

<script>
  document.addEventListener('df-messenger-loaded', () => {
    const dfMessenger = document.querySelector('df-messenger');
    const searchConfig = { ... }
    dfMessenger.setQueryParameters(searchConfig);
  });
</script>

Consulte o setQueryParameters.

Solução de problemas

Esta seção descreve as soluções para alguns problemas comuns encontrados durante a configuração. Sempre teste suas configurações simulando conversas que acionam diferentes parâmetros de sessão e valores de metadados do usuário final.

Expressões inválidas

Se uma condição de especificação de otimização ou uma string de especificação de filtro contiver uma expressão inválida do Dialogflow CX (por exemplo, sintaxe incorreta ou referência a um parâmetro inexistente), a compilação da expressão vai falhar. Os erros relacionados à compilação de expressões normalmente são retornados no DetectIntentResponse no campo diagnostic_info como SystemFunctionResults.

JSON ConditionBoostSpec inválido

O console dos Agentes de conversação realiza algumas validações na string JSON ConditionBoostSpec ao salvá-la. Isso é para verificar se é um JSON válido e se a estrutura dele pode ser mapeada para um objeto ConditionBoostSpec. Se o JSON for válido, mas resultar em um SearchConfig inválido de acordo com o serviço de pesquisa subjacente (por exemplo, uma string de condição inválida após a substituição de parâmetros), o serviço de pesquisa vai retornar um erro.

Erros de substituição no ambiente de execução

Se uma string JSON ConditionBoostSpec for válida e analisável, mas ocorrer um erro durante a substituição no ambiente de execução de expressões do Dialogflow CX nos campos dela (como a string de condição), esses erros serão informados em diagnostic_info como SystemFunctionResults.

Analisar o SearchConfig compilado

O SearchConfig aplicado quando a consulta é executada está disponível em search_signals na resposta. A análise do SearchConfig pode fornecer insights sobre outros problemas não descritos aqui.

A seguir

• Para mais informações sobre a estrutura do SearchConfig e os componentes dele, consulte a search_config documentação.
• Para mais informações sobre a sintaxe de expressão, consulte a referência de condições e funções do sistema do Dialogflow CX.
• Para mais informações sobre a sintaxe de expressão de filtro para pesquisa, consulte Filtrar e ordenar resultados.