Esta página foi traduzida pela API Cloud Translation.

Pesquisar com acompanhamentos

Esta página apresenta a pesquisa com acompanhamentos para a Pesquisa da Vertex AI e mostra como implementá-la usando chamadas de API.

Se você quiser adicionar pesquisa com acompanhamentos ao widget de pesquisa, consulte Configurar resultados para o widget de pesquisa.

A pesquisa com acompanhamentos se aplica a aplicativos de pesquisa com dados não estruturados dados e sites.

A pesquisa com acompanhamentos não se aplica aos apps de agentes da Vertex AI. Agentes da Vertex AI usam um agente que pode conversar sobre o conteúdo com seus usuários finais. Para mais informações sobre os agentes da Vertex AI, consulte Introdução aos agentes da Vertex AI.

Sobre a Pesquisa com acompanhamentos

A pesquisa com acompanhamento é baseada em modelos de IA generativa. Pesquisar com acompanhamentos é diferente dos dados não estruturados regulares pesquisa, porque pesquisar com acompanhamentos consideram as consultas anteriores na mesma sessão de pesquisa.

A pesquisa com acompanhamentos oferece suporte para:

Processamento de consultas em linguagem natural:processa e entende o comportamento humano. entrada de idioma, identifica a intenção por trás de uma consulta e retorna informações resultados.
Reconhecimento do contexto:entende o contexto das interações anteriores e fornece respostas baseadas no contexto.
Vários turnos: permite que os usuários façam perguntas de acompanhamento e recebam respostas relevantes.

Exemplo de pesquisa com acompanhamentos

Veja a seguir um exemplo de pesquisa com acompanhamentos. Suponha que você queira saber sobre férias no México:

Você: Qual é a melhor época do ano para passar as férias no México?
Pesquisa com acompanhamento: o melhor período para passar férias no México é durante a estação seca, que vai de novembro a abril.
Você: Qual é a taxa de câmbio?
Pesquisa com acompanhamento: 1 USD é igual a aproximadamente 17,65 pesos mexicanos.
Você: Qual é a temperatura média em dezembro?
Pesquisa com acompanhamento: a temperatura média varia de 21 a 25 °C. A média de Cancún é de cerca de 25 °C.

Com a pesquisa normal, sua pergunta "Qual é a taxa de câmbio?" não seria respondida, porque a pesquisa normal não saberia que você queria a taxa de câmbio mexicana. Da mesma forma, uma pesquisa regular não manteria o contexto para dar as temperaturas no México.

Sobre conversas

Na pesquisa com acompanhamentos, uma conversa é composta de consultas de texto fornecidas por um usuário e respostas fornecidas pela Vertex AI para Pesquisa.

Esses pares de consulta e resposta às vezes são chamados de mensagens. Na exemplo anterior, a segunda mensagem é composta por "Qual é a taxa de câmbio?" e "1 USD é igual a aproximadamente 17,65 pesos mexicanos".

As conversas são armazenadas no mesmo repositório de dados em que os dados não estruturados é mantida. No repositório de dados, uma conversa é representada pelo objeto Conversation recurso. Além de conter as mensagens de consulta e resposta, o recurso de conversa tem:

Um nome exclusivo (o ID da conversa).
Um estado (em andamento ou concluído).
Um pseudoID do usuário, que é um ID de visitante que rastreia o usuário. Ele pode ser atribuído de forma programática.
Um horário de início e um de término.

Antes de começar

Verifique se você atende aos seguintes pré-requisitos. Os requisitos variam de acordo com o tipo de app que você tem.

Se você tiver um app de pesquisa não estruturado, verifique se os seguintes recursos estão ativados: Recursos avançados do LLM
Se você tiver um app de pesquisa em sites, verifique se as seguintes opções estão ativadas:

Armazenar conversas e receber respostas

Você pode usar a linha de comando ou bibliotecas de cliente para gerar respostas de pesquisa e armazenar a conversa de pesquisa com acompanhamento.

REST

Para usar a linha de comando para criar uma conversa e gerar respostas com base na entrada do usuário, siga estas etapas:

Especifique o repositório de dados em que você quer armazenar o histórico de conversas:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations" \
-d '{
  "user_pseudo_id": "USER_PSEUDO_ID"
}'

PROJECT_ID: o número ou ID do projeto do Google Cloud
DATA_STORE_ID: o ID do repositório de dados associado ao app.
USER_PSEUDO_ID: é um identificador exclusivo para acompanhar um visitante da pesquisa. Por exemplo, é possível implementar isso com um cookie HTTP, que identifica exclusivamente um visitante em um único dispositivo.

Clique para conferir um exemplo de resposta do comando POST.

{
  "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/conversations/11078281986791420687",
  "state": "IN_PROGRESS",
  "userPseudoId": "test_id",
  "startTime": "2023-08-15T20:08:12.094639Z"
}

Gere uma resposta de pesquisa e adicione a uma conversa nova ou existente no repositório de dados:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID:converse" \
-d '{
  "query": { "input": "FREE_TEXT"},
  "filter": "FILTER"
}'

PROJECT_ID: o número ou ID do projeto do Google Cloud
DATA_STORE_ID: o ID do repositório de dados associado com seu app.
CONVERSATION_ID: um ID exclusivo para a conversa, por exemplo, 123456. Para uma conversa de pesquisa com acompanhamento, usar o mesmo ID de conversa todas as vezes.
FREE_TEXT: uma string de texto livre que contém o pergunta, por exemplo, what is bigquery?
FILTER: um campo de texto para filtrar a pesquisa usando um filtro expressão. O valor padrão é uma string vazia. A maneira como você constrói seu filtro varia dependendo se você tem dados do site ou dados não estruturados com metadados. Para mais informações, consulte Filtrar pesquisar com acompanhamentos.

Clique para ver um exemplo de resposta POST.

{
"reply": {
"summary": {
  "summaryText": "BigQuery is a cloud-based data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that provides a simple and cost-effective way to store and analyze large amounts of data."
}
},
"conversation": {
"name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/conversations/11078281986791420687",
"state": "IN_PROGRESS",
"userPseudoId": "test_id",
"messages": [
  {
    "userInput": {
      "input": "what is bigquery?"
    }
  },
  {
    "reply": {
      "summary": {
        "summaryText": "BigQuery is a cloud-based data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that provides a simple and cost-effective way to store and analyze large amounts of data."
      }
    }
  }
],
"startTime": "2023-08-15T20:08:12.094639Z"
},
"searchResults": [
{
  "id": "c86f19582746b56f71c9bb6929893835",
  "document": {
    "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/branches/0/documents/c86f19582746b56f71c9bb6929893835",
    "id": "c86f19582746b56f71c9bb6929893835",
    "derivedStructData": {
      "link": "gs://aquamuse-data-ucs-eval-dev/documents/94627ee0249dfdfda25b1b158c717bca.txt",
      "snippets": [
        {
          "snippet_status": "SUCCESS",
          "snippet": "For larger websites, talk to the IT team and/or utilize a big data solution such as Google \u003cb\u003eBigQuery\u003c/b\u003e to extract all URLs. It may also be necessary to ask the ..."
        }
      ],
      "extractive_answers": [
        {
          "content": "Alternatively, load the Server Log Files into Google BigQuery and use the Google BigQuery interface or the 360 Data Studio to analyze the data. To monitor the indexation numbers of the HTTP and the HTTPS version, keep an eye on all submitted XML Sitemaps."
        }
      ]
    }
  }
},
{
  "id": "774bd7ce2a3509ab4bbd1fc876f39dc2",
  "document": {
    "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/branches/0/documents/774bd7ce2a3509ab4bbd1fc876f39dc2",
    "id": "774bd7ce2a3509ab4bbd1fc876f39dc2",
    "derivedStructData": {
      "snippets": [
        {
          "snippet": "No snippet is available for this page.",
          "snippet_status": "NO_SNIPPET_AVAILABLE"
        }
      ],
      "extractive_answers": [
        {
          "content": "This consists of a collection of virtual tables. A virtual table exists for every queryable object type (content type if you prefer) in the repository. Each row in these virtual tables correspond to an instance of the corresponding object type (or of one of its subtypes)."
        }
      ],
      "link": "gs://aquamuse-data-ucs-eval-dev/documents/28841ef8590a105e9415f1390648a811.txt"
    }
  }
},
{
  "id": "3e1d306e49aefd9e23f2d5f7a66e6c76",
  "document": {
    "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/branches/0/documents/3e1d306e49aefd9e23f2d5f7a66e6c76",
    "id": "3e1d306e49aefd9e23f2d5f7a66e6c76",
    "derivedStructData": {
      "snippets": [
        {
          "snippet": "No snippet is available for this page.",
          "snippet_status": "NO_SNIPPET_AVAILABLE"
        }
      ],
      "extractive_answers": [
        {
          "content": "Other logo switches are based on search terms. For instance, if the term "ASCII art" is searched, an ASCII art version of the Google logo will appear next to the search box."
        }
      ],
      "link": "gs://aquamuse-data-ucs-eval-dev/documents/98008df3eef5d3ee1661c52f23189190.txt"
    }
  }
},
{
  "id": "cf94e24aacd47cd2c2f5effcbdeda832",
  "document": {
    "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/branches/0/documents/cf94e24aacd47cd2c2f5effcbdeda832",
    "id": "cf94e24aacd47cd2c2f5effcbdeda832",
    "derivedStructData": {
      "extractive_answers": [
        {
          "content": "The company is listed on the NASDAQ stock exchange under the ticker symbols GOOGL and GOOG, and on the Frankfurt Stock Exchange under the ticker symbol GGQ1. These ticker symbols now refer to Alphabet Inc., Google's holding company, since the fourth quarter of 2015."
        }
      ],
      "snippets": [
        {
          "snippet": "No snippet is available for this page.",
          "snippet_status": "NO_SNIPPET_AVAILABLE"
        }
      ],
      "link": "gs://aquamuse-data-ucs-eval-dev/documents/d80204083ef1096799fa4b7257548b33.txt"
    }
  }
},
{
  "id": "05bc6497a4e7e6ca36b2e495b354b764",
  "document": {
    "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/branches/0/documents/05bc6497a4e7e6ca36b2e495b354b764",
    "id": "05bc6497a4e7e6ca36b2e495b354b764",
    "derivedStructData": {
      "extractive_answers": [
        {
          "content": "SQL injection countermeasures are designed to utilize secure programming methods. By changing the variables used by the application code, weaknesses in applications can be greatly minimized. This report will detail how to perform a SQL injection and explore the best countermeasures to prevent the attack."
        }
      ],
      "link": "gs://aquamuse-data-ucs-eval-dev/documents/7cba75d646f5774a21d96801bec68bb3.txt",
      "snippets": [
        {
          "snippet_status": "NO_SNIPPET_AVAILABLE",
          "snippet": "No snippet is available for this page."
        }
      ]
    }
  }
}
]
}

Repita a etapa 2 para cada nova pergunta na conversa.

Python

Para mais informações, consulte a API Vertex AI Agent Builder Python documentação de referência.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

from typing import List

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# data_store_id = "YOUR_DATA_STORE_ID"
# search_queries = ["YOUR_FIRST_SEARCH_QUERY", "YOUR_SECOND_SEARCH_QUERY"]


def multi_turn_search_sample(
    project_id: str,
    location: str,
    data_store_id: str,
    search_queries: List[str],
) -> List[discoveryengine.ConverseConversationResponse]:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # Initialize Multi-Turn Session
    conversation = client.create_conversation(
        # The full resource name of the data store
        # e.g. projects/{project_id}/locations/{location}/dataStores/{data_store_id}
        parent=client.data_store_path(
            project=project_id, location=location, data_store=data_store_id
        ),
        conversation=discoveryengine.Conversation(),
    )


    for search_query in search_queries:
        # Add new message to session
        request = discoveryengine.ConverseConversationRequest(
            name=conversation.name,
            query=discoveryengine.TextInput(input=search_query),
            serving_config=client.serving_config_path(
                project=project_id,
                location=location,
                data_store=data_store_id,
                serving_config="default_config",
            ),
            # Options for the returned summary
            summary_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec(
                # Number of results to include in summary
                summary_result_count=3,
                include_citations=True,
            ),
        )
        response = client.converse_conversation(request)

        print(f"Reply: {response.reply.summary.summary_text}\n")

        for i, result in enumerate(response.search_results, 1):
            result_data = result.document.derived_struct_data
            print(f"[{i}]")
            print(f"Link: {result_data['link']}")
            print(f"First Snippet: {result_data['snippets'][0]['snippet']}")
            print(
                "First Extractive Answer: \n"
                f"\tPage: {result_data['extractive_answers'][0]['pageNumber']}\n"
                f"\tContent: {result_data['extractive_answers'][0]['content']}\n\n"
            )
        print("\n\n")

Filtrar a pesquisa com acompanhamentos

Ao fazer uma consulta com pesquisa com acompanhamentos, você pode incluir o filter para restringir o conjunto de documentos do qual uma resposta é derivada. Você constrói seu filtro usando expressões de filtro. As expressões de filtro que você usa variam dependendo se você tem dados do site ou dados não estruturados com metadados.

Expressões de filtro para dados do site

Se você tiver um repositório de dados com dados do site, poderá filtrar sua pesquisa com a consulta de acompanhamento usando as expressões de filtro em Expressões de filtro com indexação avançada de sites. Depois de criar a expressão do filtro, use-a para o valor do campo filter na etapa 2 de Armazenar conversas e receber respostas.

Filtrar expressões para dados não estruturados com metadados

Se você tem um repositório de dados com dados não estruturados com metadados, é possível filtrar sua pesquisa com consulta de acompanhamento para que retorne documentos com base na metadados que os documentos contêm. Consulte Filtrar a pesquisa de dados estruturados ou não estruturados para entender como usar metadados para filtrar a pesquisa comum (sem acompanhamentos). Você pode usar esses mesmos princípios para usar metadados para filtrar a pesquisa com acompanhamentos. Depois de criar a expressão de filtro, use-a para o valor do campo filter na etapa 2 de Armazenar conversas e receber respostas.

Configurar o resumo

A mensagem de resposta da pesquisa com acompanhamentos é um resumo gerado retornado em summaryText. Há várias maneiras de configurar o resumo gerado. Eles são descritos nas seções a seguir:

Receber citações com os resultados da pesquisa
Ignorar consultas adversárias
Ignorar consultas que não buscam resumos
Definir o número de resultados que serão usados no resumo
Receber resumos personalizados
Aplicar o SafeSearch às respostas do chat

Receber citações com os resultados da pesquisa

As citações, quando especificadas, são números colocados inline em um resumo de pesquisa. Esses números indicam de quais resultados da pesquisa frases específicas em resumo estão prontos.

Para receber citações:

Siga o procedimento anterior de armazenar conversas e receber respostas de chat, exceto na etapa 2. Execute este comando que inclui o campo summarySpec que define includeCitations como verdadeiro.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID:converse" \
-d '{
  "query": { "input": "FREE_TEXT"},
  "summarySpec": { "include_citations": true }
}'

Clique para ver parte da resposta de um exemplo kubectl.

{
"reply": {
"summary": {
}
"reply": {
"summary": {
  "summaryText": "BigQuery is a cloud-based data warehouse that enables businesses to analyze all their data very quickly [1]. It is a fully managed service that provides a simple and cost-effective way to store and analyze large amounts of data [2, 3].",
  "safetyAttributes": {
    "categories": [
      "Finance",
      "Legal"
    ]
…

Os números de citação são incluídos no texto do resumo. Os números das citações se referem os resultados de pesquisa retornados e são indexados em 1. Por exemplo, [1] significa que o frase é atribuída ao primeiro resultado da pesquisa. [2, 3] significa que a frase é atribuída ao segundo e ao terceiro resultados da pesquisa.

Ignorar consultas de adversários

As consultas de adversários incluem comentários negativos ou são projetadas para gerar resultados não seguros e que violam a política. É possível especificar que nenhum resumo de pesquisa será retornado para consultas adversas. Quando uma consulta adversária é ignorada, a A propriedade summaryText contém texto padrão indicando que nenhuma pesquisa um sumário for retornado. Os documentos de pesquisa são retornados para consultas adversas, mesmo que os resumos de pesquisa não sejam.

Para especificar que nenhum resumo de pesquisa deve ser retornado para consultas adversas:

Siga as conversas da loja e converse por chat de resposta, exceto na etapa 2, execute este comando que inclui o campo summarySpec que define ignoreAdversarialQuery como verdadeiro.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID:converse" \
-d '{
  "query": { "input": "FREE_TEXT"},
  "summarySpec": { "ignoreAdversarialQuery": true }
}'

Clique para conferir parte da resposta de uma consulta maliciosa.

"reply": {
"summary": {
  "summaryText": "A summary could not be generated for your search query. Here are some search results.",
  "summarySkippedReasons": [
    "ADVERSARIAL_QUERY_IGNORED"
  ]
…

Ignorar consultas de busca que não sejam de resumo

Consultas que não buscam resumo retornam resultados que não são adequados para resumo. Por exemplo, "por que o céu é azul?" e "Quem é o melhor futebol jogador de futebol do mundo?" são consultas em busca de resumo, mas "aeroporto de SFO" e "mundo xícara 2026" não são. Elas são, muito provavelmente, consultas de navegação. É possível especificar que nenhum resumo de pesquisa deve ser retornado para consultas de busca que não sejam de resumo. Os documentos de pesquisa são retornados para consultas que não são de resumo, mesmo que as os resumos não são.

Para especificar que nenhum resumo de pesquisa deve ser retornado em buscas não resumidas consultas:

Siga o procedimento anterior de armazenar conversas e receber respostas de chat, exceto na etapa 2. Execute este comando que inclui o campo summarySpec que define ignoreNonSummarySeekingQuery como verdadeiro.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID:converse" \
-d '{
  "query": { "input": "FREE_TEXT"},
  "summarySpec": { "ignore_non_summary_seeking_query": true }
}'

Clique para conferir parte da resposta de uma consulta maliciosa.

 "reply": {
"summary": {
  "summaryText": "A summary could not be generated for your search query. Here are some search results.",
  "summarySkippedReasons": [
    "NON_SUMMARY_SEEKING_QUERY_IGNORED"
  ]
…

Definir o número de resultados a serem usados no resumo

É possível especificar o número de resultados a serem usados na geração do resumo. De Por padrão, se o campo summaryResultCount não estiver definido, todos os resultados serão retornados são usadas para gerar o resumo.

Para definir o número de principais resultados a serem usados no resumo:

Siga as conversas da loja e converse por chat de resposta, exceto na etapa 2, execute este comando que inclui o campo summarySpec que define summaryResultCount.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID:converse" \
-d '{
  "query": { "input": "FREE_TEXT"},
  "summarySpec": { "summary_result_count": NUMBER_OF_RESULTS }
}'

NUMBER_OF_RESULTS: o número de resultados principais para gerar o resumo da pesquisa. Se o número de resultados retornados for menor que summaryResultCount, o resumo será gerado com base em todos os resultados. O valor máximo é 5.

Receber resumos personalizados

Você pode receber resumos personalizados fornecendo instruções em linguagem natural no campo modelPromptSpec.preamble ao solicitar um resumo.

Você pode solicitar personalizações como comprimento e nível de detalhes, estilo de saída (como "simples"), idioma de saída, foco da resposta e formato (como como tabelas, marcadores e XML).

Por exemplo, para a consulta "Quais são os benefícios do BigQuery?", você pode inserir instruções de personalização como estes exemplos:

Exemplo de instrução: "please show the answer format in an ordered list"

Exemplo de resposta:

The benefits of BigQuery are:

1. Increased business productivity
2. IT staff productivity
3. Reduced infrastructure costs
4. Loading and exporting data are free

Exemplo de instrução: give a very detailed answer

Exemplo de resposta:

BigQuery is a serverless, highly scalable, and cost-effective cloud data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that takes care of provisioning, scaling, and managing the underlying infrastructure, so you can focus on analyzing your data. BigQuery is also integrated with other Google Cloud services, such as Google Kubernetes Engine, Cloud Data Fusion, and Cloud Dataproc, making it easy to build and deploy data pipelines.

Here are some of the benefits of using BigQuery:

* **Fast and scalable:** BigQuery can process petabytes of data very quickly, and it can scale to handle even the most demanding workloads. * **Cost-effective:** BigQuery is a very cost-effective way to store and analyze data. You only pay for the data that you use, and there are no upfront costs or commitments. * **Secure:** BigQuery is a secure platform that meets the needs of even the most security-conscious organizations. * **Easy to use:** BigQuery is easy to use, even for non-technical users. It has a simple and intuitive user interface, and it supports a variety of data sources. * **Integrated with other Google Cloud services:** BigQuery is integrated with other Google Cloud services, making it easy to build and deploy data pipelines.

If you are looking for a fast, scalable, and cost-effective way to analyze your data, then BigQuery is a great option.

Para receber um resumo personalizado:

Siga o procedimento anterior de armazenar conversas e receber respostas de chat, exceto na etapa 2. Execute este comando que inclui o campo summarySpec, que especifica a instrução de personalização em modelPromptSpec.preamble.

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID:converse" \
  -d '{
    "query": { "input": "FREE_TEXT"},
    "summarySpec": {
      "modelPromptSpec": {
        "preamble": "CUSTOMIZATION_INSTRUCTIONS"
      }
    }
  }'

CUSTOMIZATION_INSTRUCTIONS: a instrução para personalização, como uma string.

Aplicar o SafeSearch às respostas do chat

O SafeSearch pode ser usado para filtrar conteúdo explícito, não seguro e que viola a política das respostas resumidas. Para mais informações sobre o SafeSearch, consulte Configurações de segurança para a Vertex AI para Pesquisa.

Para aplicar a pesquisa segura a uma resposta do chat:

Siga o procedimento anterior de armazenar conversas e receber respostas de chat, exceto na etapa 2, na consulta, e especifique safe_search.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID:converse" \
-d '{
  "query": { "input": "FREE_TEXT"},
  "safe_search": true
}'

Acessar e modificar conversas armazenadas

É possível usar a linha de comando para recuperar, excluir, atualizar e listar conversas.

Extrair uma conversa do repositório de dados

Para conferir todos os detalhes de uma conversa específica em um repositório de dados:

Execute o seguinte comando curl:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID"

PROJECT_ID: o número ou ID do projeto do Google Cloud
DATA_STORE_ID:o ID do repositório de dados associado com seu app.
CONVERSATION_ID: o ID da conversa

Clique para conferir um exemplo de resposta do comando GET.

{
"name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/conversations/2040473575290303058",
"state": "IN_PROGRESS",
"userPseudoId": "2040473575290303058",
"messages": [
{
  "userInput": {
    "input": "what is bigquery?"
  }
},
{
  "reply": {
    "summary": {
      "summaryText": "BigQuery is a cloud-based data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that provides a simple and cost-effective way to store and analyze large amounts of data."
    }
  }
}
],
"startTime": "2023-08-15T20:11:24.046735Z"
}

Excluir uma conversa do repositório de dados

Por padrão, as conversas anteriores a 60 dias atrás são excluídas automaticamente. No entanto, se você quiser excluir uma conversa específica, por exemplo, se ela acidentalmente tinha conteúdo confidencial, use essa chamada de API para excluí-lo.

Para excluir uma conversa de um repositório de dados:

Execute o seguinte comando curl:

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID"

PROJECT_ID: o número ou ID do seu projeto do Google Cloud
DATA_STORE_ID: o ID do repositório de dados associado ao app.
CONVERSATION_ID: o ID da conversa

A resposta do comando DELETE é assim:

{}

Atualizar uma conversa

Há vários motivos para atualizar uma conversa. Por exemplo, para fazer uma das seguintes ações:

Marcar uma conversa como "Concluída"
Mesclar as mensagens de uma conversa em outra
Mudar o user_pseudo_id

Para atualizar o state em uma conversa:

Execute o seguinte comando curl:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID?updateMask=state" \
-d '{
  "state": "NEW_STATE"
}'

PROJECT_ID: o número ou ID do seu projeto do Google Cloud
DATA_STORE_ID: o ID do repositório de dados associado com seu app.
CONVERSATION_ID: o ID da conversa que você quer atualizar
NEW_STATE: o novo valor do estado, por exemplo, COMPLETED

Clique para ver um exemplo de resposta PATCH.

{
"name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/conversations/11078281986791420687",
"state": "COMPLETED",
"userPseudoId": "test_id1",
"messages": [
{
  "userInput": {
    "input": "what is bigquery?"
  }
},
{
  "reply": {
    "summary": {
      "summaryText": "BigQuery is a cloud-based data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that provides a simple and cost-effective way to store and analyze large amounts of data."
    }
  }
}
],
"startTime": "2023-08-15T20:08:12.094639Z"
}

Para atualizar o user_pseudo_id em uma conversa:

Execute o seguinte comando curl:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations/CONVERSATION_ID?updateMask=user_pseudo_id" \
-d '{
  "user_pseudo_id": "NEW_USER_PSEUDO_ID"
}'

PROJECT_ID: o número ou ID do seu projeto do Google Cloud
DATA_STORE_ID: o ID do repositório de dados associado com seu app.
CONVERSATION_ID: o ID da conversa que você quer atualizar
NEW_USER_PSEUDO_ID: o novo valor do pseudoID do usuário.

Clique para ver um exemplo de resposta PATCH.

{
"name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/conversations/11078281986791420687",
"state": "IN_PROGRESS",
"userPseudoId": "test_id1",
"messages": [
{
  "userInput": {
    "input": "what is bigquery?"
  }
},
{
  "reply": {
    "summary": {
      "summaryText": "BigQuery is a cloud-based data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that provides a simple and cost-effective way to store and analyze large amounts of data."
    }
  }
}
],
"startTime": "2023-08-15T20:08:12.094639Z"
}

O comando anterior mostra como mudar o user_pseudo_id.. No entanto, você pode atualizar outros campos na conversa substituindo user_pseudo_id com outros campos na tabela Conversation recurso.

Listar todas as conversas

Para listar todas as conversas em um repositório de dados:

Execute o seguinte comando curl:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations"

PROJECT_ID: o número ou ID do seu projeto do Google Cloud
DATA_STORE_ID: o ID do repositório de dados associado com seu app.

Clique para conferir um exemplo de resposta do comando GET.

{
"conversations": [
{
  "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/conversations/11078281986791420687",
  "state": "IN_PROGRESS",
  "userPseudoId": "test_id",
  "messages": [
    {
      "userInput": {
        "input": "what is bigquery?"
      }
    },
    {
      "reply": {
        "summary": {
          "summaryText": "BigQuery is a cloud-based data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that provides a simple and cost-effective way to store and analyze large amounts of data."
        }
      }
    }
  ],
  "startTime": "2023-08-15T20:08:12.094639Z"
},
{
  "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/conversations/2040473575290303058",
  "state": "IN_PROGRESS",
  "userPseudoId": "2040473575290303058",
  "messages": [
    {
      "userInput": {
        "input": "what is bigquery?"
      }
    },
    {
      "reply": {
        "summary": {
          "summaryText": "BigQuery is a cloud-based data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that provides a simple and cost-effective way to store and analyze large amounts of data."
        }
      }
    }
  ]
}
]
}

A resposta contém uma lista de conversas e o next_page_token. Em caso negativo next_page_token foi retornado. Não há mais conversas para listar.

O tamanho padrão da página é 50.

Listar conversas por filtro

Em vez de listar todas as conversas em um repositório de dados, você pode listar todas as conversas abertas ou todas as conversas associadas a um usuário específico.

Por exemplo, você pode apresentar ao usuário as pesquisas fechadas dele com uma opção para reabrir um deles.

Para isso, liste as conversas que correspondem a um determinado filtro: user_pseudo_id ou state (IN_PROGRESS ou COMPLETED).

Listar conversas de um usuário

Para listar as conversas associadas a um usuário ou visitante:

Execute o seguinte comando curl:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations?filter=user_pseudo_id=USER_PSEUDO_ID"

PROJECT_ID: o número ou ID do seu projeto do Google Cloud
DATA_STORE_ID: o ID do repositório de dados associado com seu app.
USER_PSEUDO_ID: o pseudo-ID do usuário cujas conversas você quer listar.

A resposta do comando GET é semelhante a esta:

Clique para conferir um exemplo de resposta do comando GET.

{
"conversations": [
{
  "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/conversations/11078281986791420687",
  "state": "IN_PROGRESS",
  "userPseudoId": "test_id",
  "messages": [
    {
      "userInput": {
        "input": "what is bigquery?"
      }
    },
    {
      "reply": {
        "summary": {
          "summaryText": "BigQuery is a cloud-based data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that provides a simple and cost-effective way to store and analyze large amounts of data."
        }
      }
    }
  ],
  "startTime": "2023-08-15T20:08:12.094639Z"
}
]
}

Listar conversas de um usuário e um estado

Para listar conversas em um estado específico (aberta ou fechada) e que estão associadas a um usuário ou visitante:

Execute o seguinte comando curl:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/conversations?filter=user_pseudo_id=USER_PSEUDO_ID%20AND%20state=STATE"

PROJECT_ID: o número ou ID do seu projeto do Google Cloud
DATA_STORE_ID: o ID do repositório de dados associado com seu app.
USER_PSEUDO_ID: o pseudo-ID do usuário cujas conversas você quer listar.
STATE: se a conversa é aberta ou fechada. (IN_PROGRESS ou COMPLETED)

A resposta do comando GET é semelhante a esta:

Clique para ver um exemplo de resposta GET.

{
"conversations": [
{
  "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/conversations/11078281986791420687",
  "state": "IN_PROGRESS",
  "userPseudoId": "test_id",
  "messages": [
    {
      "userInput": {
        "input": "what is bigquery?"
      }
    },
    {
      "reply": {
        "summary": {
          "summaryText": "BigQuery is a cloud-based data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that provides a simple and cost-effective way to store and analyze large amounts of data."
        }
      }
    }
  ],
  "startTime": "2023-08-15T20:08:12.094639Z"
}
]
}

Para informações gerais sobre a sintaxe de filtragem, consulte Filtragem AIP-160.

Perguntas relacionadas

As perguntas relacionadas são um recurso de prévia com lista de permissões que pode retornar perguntas relacionadas, além de resultados de pesquisa.

Por exemplo, quando você pergunta "Qual é a melhor época do ano para passar as férias no México?", além de responder à sua pergunta, a pesquisa sugere outras perguntas que você pode fazer, como "Qual é o mês mais barato para passar as férias no México?" e "Quais são os meses de turismo no México?".

Se você quiser que o app de pesquisa retorne perguntas relacionadas, entre em contato com a equipe de conta do Google e informe quais projetos e apps você quer que as perguntas relacionadas sejam ativadas. Se você não estiver usando a configuração de veiculação padrão, será preciso forneça também o nome da configuração de veiculação.

Depois que o recurso de perguntas relacionadas é ativado, as perguntas são retornadas como strings no ConverseConversationResponse.

Mais informações

Para mais informações sobre os campos summaryResultCount, includeCitations, ignoreAdversarialQuery e ignoreNonSummarySeekingQuery, consulte SummarySpec na documentação da API Vertex AI Agent Builder.
Para mais exemplos de como receber resumos de pesquisa, consulte Receber resumos.