Filtrar com compreensão de linguagem natural

Observação: este recurso é uma oferta de pré-lançamento, sujeita aos "Termos das Ofertas de pré-GA" dos Termos específicos de serviço do GCP. Os produtos e recursos pré-GA podem ter suporte limitado, e as mudanças neles podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições da fase de lançamento. Além disso, ao usar esse recurso, você concorda com os Termos e Condições da Prévia da IA generativa ("Termos de visualização"). Para esse recurso, é possível processar dados pessoais conforme descrito no Adendo sobre processamento de dados do Cloud, sujeito às restrições e obrigações aplicáveis no Contrato (conforme definido nos Termos de Pré-lançamento).

Esta página explica como aplicar o processamento de linguagem natural para criar filtros automaticamente para consultas de pesquisa e, portanto, melhorar a qualidade dos resultados retornados.

Você pode usar esse recurso com apps de pesquisa conectados a repositórios de dados estruturados.

Sobre a compreensão de consultas de linguagem natural

Se você tiver um app de pesquisa genérico com dados estruturados, as consultas de linguagem natural dos usuários poderão ser reformadas como consultas filtradas. Isso pode levar a resultados de pesquisa de melhor qualidade do que a pesquisa de palavras na string de consulta.

Usar a compreensão de consultas em linguagem natural é mais fácil e flexível do que escrever suas próprias expressões de filtro. Para informações sobre como escrever expressões de filtro, consulte Filtrar a pesquisa genérica para dados estruturados ou não estruturados.

Esse recurso é melhor explicado com exemplos:

• Exemplo: extração de campo de consultas mostra os filtros de campo extraídos da consulta.

• Exemplo: com um filtro de geolocalização inclui o caso especial do filtro de geolocalização.

Exemplo: extração de campos de consultas

Esse recurso de compreensão de consultas de linguagem natural é explicado pelo exemplo de pesquisa de um hotel.

Considere a seguinte consulta feita a um repositório de dados estruturados de um site de hotel: "Encontre um hotel para famílias com pelo menos quatro estrelas que custe menos de 300 por noite, permita que eu leve meu cachorro e tenha Wi-Fi gratuito".

Sem o entendimento da consulta de linguagem natural, o app de pesquisa procura documentos que contenham as palavras na consulta.

Com a compreensão de consultas de linguagem natural e dados estruturados de maneira adequada, a pesquisa fica mais eficaz ao substituir parte da linguagem natural na consulta por filtros. Se os dados estruturados tiverem campos para star_rating (números), price (números) e amenities (strings), a consulta poderá ser reescrita como os filtros a seguir, além de uma consulta residual:

• Filtros extraídos da consulta em linguagem natural:

  {
      "star_rating": ≥4,
      "price": ≤300,
      "amenities": "Wifi", "Pets Allowed"
  }
  

• Consulta residual, reformulada após a extração dos filtros:

  family-friendly

Exemplo: com um filtro de geolocalização

Esse exemplo é semelhante ao anterior, mas inclui um filtro de geolocalização, que é um tipo especial de filtro extraído. A Vertex AI Search consegue reconhecer locais em uma consulta e criar filtros de proximidade para eles.

Considere a seguinte consulta feita a um site de negócios em todo o estado: "Encontre um hotel elegante e sofisticado com pelo menos 4 estrelas em São Francisco."

Com o entendimento de consultas de linguagem natural e o filtro de geolocalização, a pesquisa é reformulada como filtros e uma consulta residual:

• Filtros extraídos da consulta em linguagem natural, com classificação mínima de 4 estrelas e raio de 10 km de São Francisco:

  {
      "star_rating": ≥4,
      "location": GEO_DISTANCE(\"San Francisco, CA\", 10000)
  }
  

  Neste exemplo, GEO_DISTANCE é um endereço, mas em outras consultas, ele pode ser escrito como uma latitude e uma longitude, mesmo que a consulta original tenha um endereço.

• Consulta residual, reformulada após a extração dos filtros:

  chic and stylish in San Francisco

  Embora o filtro de geolocalização seja feito, o nome do lugar permanece na consulta residual. Isso é diferente dos outros filtros, como o star_rating.

Limitações

As limitações a seguir se aplicam à compreensão de consultas em linguagem natural:

• A compreensão de consultas de linguagem natural não pode ser aplicada a apps de pesquisa combinada. Você recebe um erro se tentar usar a compreensão de consultas em linguagem natural com um app de pesquisa combinada.

• A compreensão de consultas de linguagem natural funciona apenas para apps de pesquisa genérica que usam repositórios de dados estruturados.

• O uso da compreensão de consultas em linguagem natural aumenta a latência. Portanto, você pode optar por não usá-la se a latência for um problema.

• Para a geolocalização, o local precisa ser descrito explicitamente. Não é possível usar locais como "perto de mim" ou "casa".

• O raio para geolocalização é de 10 km e não pode ser configurado.

Antes de começar

Antes de começar a usar a compreensão de consultas em linguagem natural, ative-a para os repositórios de dados estruturados conectados aos apps que você planeja usar.

Para ativar a compreensão de consultas em linguagem natural, siga estas etapas:

REST

1. Encontre o ID do repositório de dados. Se você já tiver o ID do repositório de dados, pule para a próxima etapa.

   1. No console do Google Cloud, acesse a página Criador de agentes e, no menu de navegação, clique em Repositórios de dados.

      Acesse a página "Repositórios de dados"

   2. Clique no nome do seu repositório de dados.

   3. Na página Dados do seu repositório de dados, encontre o ID do repositório.

2. Execute o seguinte comando curl:

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID?update_mask=natural_language_query_understanding_config.mode" \
   -d '{
         "naturalLanguageQueryUnderstandingConfig": {
           "mode": "ENABLED"
         }
       }'
   

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • DATA_STORE_ID: o ID do repositório de dados da Vertex AI para Pesquisa.
   Observação: se você quiser desativar a compreensão de consultas de linguagem natural para um repositório de dados, execute o comando acima, substituindo ENABLED por DISABLED.

   Exemplo de comando e resposta

   curl -X PATCH
   -H "Authorization: Bearer $(gcloud auth print-access-token)"
   -H "Content-Type: application/json"
   -H "X-Goog-User-Project: my-project-123"
   "https://discoveryengine.googleapis.com/v1beta/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store?update_mask=natural_language_query_understanding_config.mode"
   -d '{
          "naturalLanguageQueryUnderstandingConfig": {
            "mode": "ENABLED"
          }
       }'
   
   {
   "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store",
   "displayName": "test_data_store",
   "industryVertical": "GENERIC",
   "createTime": "2024-07-10T18:50:01.673414Z",
   "solutionTypes": [
   "SOLUTION_TYPE_SEARCH"
   ],
   "defaultSchemaId": "default_schema",
   "documentProcessingConfig": {
   "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/documentProcessingConfig",
   "defaultParsingConfig": {
     "digitalParsingConfig": {}
   }
   },
   "servingConfigDataStore": {},
   "naturalLanguageQueryUnderstandingConfig": {
   "mode": "ENABLED"
   }
   }
   

3. Repita as etapas 1 e 2 para cada repositório de dados.

4. Aguarde aproximadamente 24 horas.

   Se você tentar usar a compreensão de consultas de linguagem natural antes que o repositório de dados esteja pronto, a resposta será a mesma que se filterExtractionCondition fosse definido como DISABLED.

Pesquisa, convertendo consultas de linguagem natural em filtros

Para pesquisar em uma consulta em linguagem natural e receber resultados otimizados para consultas em linguagem natural, faça o seguinte:

REST

1. Execute o comando curl a seguir, que chama o método search:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
     -d '{
           "query": "QUERY",
           "naturalLanguageQueryUnderstandingSpec": {
             "filterExtractionCondition": "ENABLED"
           }
         }'
   

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar. O app precisa estar conectado a um repositório de dados estruturados. O app não pode ser um app de pesquisa combinada.
   • QUERY: a consulta está escrita em uma linguagem natural.

   Exemplo de comando e resultado

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"
   -H "Content-Type: application/json"
   "https://discoveryengine.googleapis.com/v1beta/projects/123456
   /locations/global/collections/default_collection/engines/my-app/servingConfigs/default_search:search"
   -d '{
   "query": "Find me a family-friendly hotel with at least four stars that costs less than 300 a night, lets me bring my dog, and has free Wi-Fi.",
   "naturalLanguageQueryUnderstandingSpec": {
     "filterExtractionCondition": "ENABLED"}
   }'
   
   {
   "results": [
   {
     "id": "b2617d862",
     "document": {
       "name": "projects/123456/locations/us/collections/default_collection/dataStores/my-data-store/branches/0/documents/b2617d862",
       ...
     }
   },
   {
     "id": "a51841841",
     "document": {
       "name": "projects/123456/locations/us/collections/default_collection/dataStores/my-data-store/branches/0/documents/a51841841",
       ...
     }
   }
   ],
   "naturalLanguageQueryUnderstandingInfo": {
   "extractedFilters": "(amenities: ANY(\"Pets Allowed\") AND amenities: ANY(\"Wifi\") AND star_rating: >= 4 AND price: < 300)",
   "rewrittenQuery": "family-friendly",
   "extractedFilterStructured": {
     "expression": {
       "andExpr": {
         "expressions": [
           {
             "numberConstraint": {
               "fieldName": "star_rating",
               "value": 4,
               "comparison": "GREATER_THAN_EQUALS",
             }
           },
           {
             "numberConstraint": {
               "fieldName": "price",
               "value": 300,
               "comparison": "LESS_THAN",
             }
           },
           {
             "stringConstraint": {
               "fieldName": "amenities",
               "any": ["Pets Allowed"]
             }
           },
           {
             "stringConstraint": {
               "fieldName": "amenities",
               "any": ["Wifi"]
             }
           },
         ]
       }
   

Pesquisar, convertendo locais em consultas em filtros de geolocalização

Para pesquisar em uma consulta em linguagem natural e receber resultados otimizados para consultas de linguagem natural, incluindo a proximidade de locais, faça o seguinte:

REST

1. Execute o comando curl a seguir, que chama o método search:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
     -d '{
           "query": "QUERY",
           "naturalLanguageQueryUnderstandingSpec": {
             "filterExtractionCondition": "ENABLED",
             "geoSearchQueryDetectionFieldNames": ["GEO_FIELD_NAME_1", "GEO_FIELD_NAME_N"]"
           }
         }'
   

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar. O app precisa estar conectado a um repositório de dados estruturados. O app não pode ser um app de pesquisa combinada.
   • QUERY: a consulta está escrita em uma linguagem natural.
   • GEO_FIELD_NAME_1, GEO_FIELD_NAME_N: uma lista de valores do tipo geolocation. Se o tipo de valor não for geolocation, esse campo será ignorado.

   Exemplo de comando e resultado

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"
   -H "Content-Type: application/json"
   "https://discoveryengine.googleapis.com/v1beta/projects/123456
   /locations/global/collections/default_collection/engines/my-app/servingConfigs/default_search:search"
   -d '{
   "query": "Find me a chic and stylish hotel with at least 4 stars that is in San Francisco.",
   "naturalLanguageQueryUnderstandingSpec": {
     "filterExtractionCondition": "ENABLED",
     "geoSearchQueryDetectionFieldNames": ["location"]}
   }'
   
   {
   "results": [
   {
   "id": "b2617d862",
   "document": {
   "name": "projects/123456/locations/us/collections/default_collection/dataStores/my-data-store/branches/0/documents/b2617d862",
   ...
   }
   },
   {
   "id": "a51841841",
   "document": {
   "name": "projects/123456/locations/us/collections/default_collection/dataStores/my-data-store/branches/0/documents/a51841841",
   ...
   }
   }
   ],
   "naturalLanguageQueryUnderstandingInfo": {
   "extractedFilters": "(star_rating: >= 4 AND GEO_DISTANCE("location", "San Francisco", 10000))",
   "rewrittenQuery": "chic and stylish",
   "extractedFilterStructured": {
   "expression": {
   "andExpr": {
     "expressions": [
       {
         "numberConstraint": {
           "fieldName": "star_rating",
           "value": 4,
           "comparison": "GREATER_THAN_EQUALS",
         }
       },
       {
         "geolocationConstraint": {
           "fieldName": "location",
           "address": "San Francisco",
           "radius_in_meters": 10000,
         }
       },
     ]
   }