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 especificações de otimização e filtro. Isso permite que você tenha interações mais personalizadas e contextuais quando o agente usa um repositório de dados para encontrar informações.

Se quiser, inclua 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". É possível configurar a ferramenta de repositório de dados para impulsionar documentos relacionados a smartphones ao responder a uma consulta geral mais adiante na conversa, como "Como faço para verificar meu correio de voz?".

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

Entradas de condição de pesquisa

Para configurar os resultados da pesquisa, use os campos especificação de otimização (BoostSpec) e especificação de filtro (FilterSpec) em um objeto SearchConfig. Essas configurações se aplicam a cada repositório de dados na ferramenta, permitindo que você controle como cada repositório de dados conectado se comporta.

É 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 os dois:

  • Chamada de API:você envia BoostSpec e FilterSpec em um SearchConfig usando uma chamada de API DetectIntent. É necessário fornecer um objeto SearchConfig completo 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 compatíveis.

  • Console:o console usa as configurações BoostSpec e FilterSpec para criar um objeto SearchConfig que é enviado com a solicitação de pesquisa. Se quiser, inclua referências de parâmetros e expressões dinâmicas para adaptar os resultados aos dados de contexto registrados na conversa. Você só precisa fornecer objetos ConditionBoostSpec e uma lista de strings de filtro para criar FilterSpecs em vez de um objeto SearchConfig completo.

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

Especificações de otimização (especificações de otimização)

As especificações de otimização permitem alterar 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.

Insira cada especificação de otimização como uma string JSON que representa um único objeto ConditionBoostSpec.

Campos-chave:

  • condition: (string) uma expressão que especifica quando o aumento deve ser aplicado. Isso usa a sintaxe de expressão de filtro padrão. É 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 força da otimização.
    • Um valor positivo promove os documentos correspondentes. Um valor de 1.0 oferece uma boa promoção.
    • Um valor negativo rebaixa os documentos correspondentes. Um valor de -1.0 resulta em um rebaixamento forte.
    • Um valor de 0.0 não aplica nenhum aumento 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ê configurar o agente no console, forneça uma lista de ConditionBoostSpecs no seguinte formato:

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

Exemplo de entrada da API:

Se você chamar a API diretamente, forneça 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"
          }
        }
      ]
    }
  ]
}

Especificações de filtro (especificações de filtro)

As especificações de filtro restringem os resultados da pesquisa para incluir apenas documentos que correspondem 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, forneça uma lista de strings filter para formar um objeto FilterSpec.

Neste exemplo, o filtro só retorna 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 de API:

Se você chamar a API diretamente, forneça strings filter em um objeto SearchConfig completo:

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

Expressões dinâmicas do Dialogflow CX

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

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

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

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

Condições de pesquisa aplicadas no momento da execução

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

  1. Avalie as strings JSON que você forneceu para as especificações de otimização. Cada string JSON válida é convertida em um objeto ConditionBoostSpec. Em seguida, eles são agrupados em um objeto BoostSpecs para a conexão específica do repositório de dados, que é adicionado ao SearchConfig geral.
  2. Avalie as strings fornecidas para as especificações de filtro 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. Inclua esse SearchConfig criado dinamicamente no QueryParameters da solicitação de pesquisa enviada ao repositório de dados.

Configurar condições de pesquisa

Para configurar as condições de pesquisa, verifique se você concluiu os seguintes pré-requisitos:

Configuração do console

  1. Abra o console dos Agentes de Conversação e escolha um projeto doGoogle Cloud .
  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 será exibido. Aqui, é possível adicionar especificações de otimização e 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 ao Dialogflow CX ao enviar solicitações de detecção de intent. É preciso fornecer essas informações em todas as solicitações de detecção de intent, porque elas não são mantidas na sessão.

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

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

Protocolo V3 V3beta1
REST Recurso de sessão Recurso de sessão
RPC (remote procedure call) Interface de sessão Interface de 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

Configuração do Dialogflow CX Messenger

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

Para aplicar uma especificação ou configuração de pesquisa, adicione o seguinte snippet 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>

Para mais informações, consulte o método setQueryParameters.

Solução de problemas

As soluções a seguir abordam alguns problemas comuns encontrados durante a configuração. 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 Boost Spec ou uma string de Filter Spec 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 de ConditionBoostSpec inválido

O console dos Agentes de Conversação realiza uma validação na string JSON ConditionBoostSpec ao salvá-la para verificar se ela é um JSON válido e se a estrutura dela pode ser mapeada para um objeto ConditionBoostSpec. Se o JSON for válido, mas resultar em um SearchConfig inválido de acordo com os serviços da Pesquisa subjacentes (por exemplo, uma string de condição inválida após a substituição de parâmetros), os serviços da Pesquisa vão retornar um erro.

Erros de substituição do 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 (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

Anterior
Agentes híbridos do repositório de dados
Avançar
Noções básicas sobre agentes baseados em fluxo