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

É possível influenciar os resultados da pesquisa recuperados das ferramentas de repositório de dados dos agentes de conversa (Dialogflow CX) ao configurar especificações de reforço e filtro. Isso permite 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 refinar os resultados com base no contexto da conversa. Por exemplo, o agente capturou informações indicando que o usuário final tem um "smartphone". Você pode configurar a ferramenta de repositório de dados para impulsionar 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 no repositório de dados usando o console, a API ou a integração do Messenger do Dialogflow CX.

Entradas de condição de pesquisa

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

É possível configurar 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: BoostSpec e FilterSpec são enviados em um SearchConfig usando uma chamada de API DetectIntent. Um objeto SearchConfig completo precisa ser fornecido na solicitação. Um SearchConfig enviado por uma chamada direta de API 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: suas configurações de BoostSpec e FilterSpec são usadas para construir um objeto SearchConfig que é enviado com a solicitação de pesquisa. Como opção, inclua referências de parâmetros e expressões dinâmicas para personalizar os resultados de acordo com os dados de contexto gravados na conversa. Você só precisa 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.

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

Com as especificações de otimização, é possível 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 reforço a um único repositório de dados.

Cada especificação de reforç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 o reforço deve ser aplicado. Isso usa a sintaxe de expressão de filtro padrão. Você pode usar expressões do Dialogflow 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 diminui a classificação dos documentos correspondentes. Um valor de -1.0 resulta em uma redução significativa.
    • Um valor de 0.0 não aplica reforç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 reforç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, forneça uma lista de ConditionBoostSpecs no seguinte formato.

Neste exemplo, os documentos com um URI que corresponda ao valor do parâmetro de sessão $session.params.doc_id serão promovidos 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, forneça ConditionBoostSpecs em um objeto SearchConfig completo.A configuração de pesquisa a seguir descreve uma especificação de reforço:

"searchConfig": {
  "boostSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "spec": [
        {
          "conditionBoostSpecs": {
            "condition": "CONDITION",
            "boost": "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. Você pode usar expressões do Dialogflow 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 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 de API:

Se você estiver chamando 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

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

É possível acessar os dados de contexto da 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 no QueryParameters das suas chamadas DetectIntent. Para mais informações, consulte endUserMetadata.

Para mais detalhes sobre as funções do sistema disponíveis e a sintaxe de expressão, 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 reforço são avaliadas. 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. As strings fornecidas para especificações de filtro são avaliadas como expressões do Dialogflow. 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 no 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:

Configuração do console

  1. Abra o console dos Agentes de conversação e escolha um projeto do Google 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 vai aparecer. Aqui, você pode adicionar especificações de otimização e filtro para modificar os resultados da pesquisa.
    • Para uma especificação de reforço, forneça um objeto JSON que defina um ConditionBoostSpec. Consulte Especificações de impulso 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 aos agentes de conversação (Dialogflow CX) ao enviar solicitações de detecção de intenção. Essas informações precisam ser fornecidas em todas as solicitações de detecção de intenção, porque não são mantidas na sessão.

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

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

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 método setContext 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 em um site:

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

Consulte o método 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 reforço ou uma string de especificação de filtro contiver uma expressão inválida de agentes de conversa (Dialogflow CX), por exemplo, sintaxe incorreta ou referência a um parâmetro inexistente, a compilação da expressão vai falhar. Erros relacionados à compilação de expressões geralmente são retornados no DetectIntentResponse dentro do campo diagnostic_info como SystemFunctionResults.

JSON ConditionBoostSpec inválido

O console de agentes de conversa 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 de tempo de execução

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

Analise 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