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 a pesquisa com acompanhamentos ao widget de pesquisa, consulte Configurar resultados para o widget de pesquisa.

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

A pesquisa com acompanhamentos não se aplica aos apps dos agentes da Vertex AI. Os apps da Vertex AI Agents 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. A pesquisa com acompanhamentos é diferente da pesquisa regular de dados não estruturados, porque considera consultas anteriores na mesma sessão de pesquisa.

A Pesquisa com acompanhamentos oferece suporte para:

Processamento de consultas de linguagem natural:processa e entende a entrada de linguagem humana, identifica a intenção por trás de uma consulta e retorna resultados relevantes.
Percepção de contexto:entende o contexto das interações anteriores e oferece respostas com base no contexto.
Vários turnos:permite que os usuários façam perguntas de acompanhamento e recebam respostas relevantes.

Exemplo de pesquisa com acompanhamentos

Confira 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 equivale 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 normal não mantém o contexto para mostrar as temperaturas do México.

Sobre conversas

Na pesquisa com acompanhamentos, uma conversa é composta por 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. No 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 são mantidos. No repositório de dados, uma conversa é representada pelo recurso de conversa. 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 estruturada, 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

É possível usar a linha de comando ou as bibliotecas de cliente para gerar respostas de pesquisa e armazenar a conversa de pesquisa com acompanhamentos.

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 seu 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 seu projeto do Google Cloud
DATA_STORE_ID: o ID do repositório de dados associado ao app.
CONVERSATION_ID: um ID exclusivo para a conversa, por exemplo, 123456. Para uma conversa de pesquisa com acompanhamentos, use o mesmo ID de conversa em cada turno.
FREE_TEXT: uma string de texto livre que contém a pergunta do usuário, por exemplo, what is bigquery?.
FILTER: um campo de texto para filtrar a pesquisa usando uma expressão de filtro. O valor padrão é uma string vazia. A maneira como você constrói o filtro varia dependendo se você tem dados do site ou dados não estruturados com metadados. Para mais informações, consulte Filtrar pesquisas com acompanhamentos.

Clique para conferir um exemplo de resposta do comando 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 documentação de referência da API Python do Vertex AI Agent Builder.

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, é possível incluir o campo filter para restringir o conjunto de documentos de onde uma resposta é derivada. Você constrói o 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.

Filtrar expressões 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ê tiver um repositório de dados com dados não estruturados e metadados, poderá filtrar sua pesquisa com a consulta de acompanhamento para que ela retorne documentos com base nos campos de metadados que eles 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 de adversários
Ignorar consultas que não buscam resumos
Definir o número de resultados a serem 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 de pesquisa as frases específicas do resumo são retiradas.

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 conferir parte da resposta de um comando de exemplo.

{
"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 de resumo. Os números de citação se referem aos resultados de pesquisa retornados e são indexados a partir de 1. Por exemplo, [1] significa que a 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 adversárias

As consultas adversas 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 maliciosa é ignorada, a propriedade summaryText contém um texto padrão indicando que nenhum resumo de pesquisa foi 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 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 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 que não buscam 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 jogador de futebol do mundo?" são consultas que buscam resumos, mas "aeroporto de SFO" e "copa do mundo 2026" não são. Elas provavelmente são consultas de navegação. É possível especificar que nenhum resumo de pesquisa será retornado para consultas de pesquisa que não sejam resumos. Os documentos de pesquisa são retornados para consultas que não são de resumo, mesmo que os resumos de pesquisa não sejam.

Para especificar que nenhum resumo de pesquisa será retornado para consultas que não buscam resumos:

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. Por padrão, se o campo summaryResultCount não estiver definido, todos os resultados retornados serão usados para gerar o resumo.

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

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 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 de linguagem natural no campo modelPromptSpec.preamble ao solicitar um resumo.

É possível solicitar personalizações, como duração e nível de detalhes, estilo de saída (como "simples"), idioma de saída, foco da resposta e formato (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 de 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 de respostas resumidas. Para mais informações sobre o SafeSearch, consulte Configurações de segurança da Vertex AI para Pesquisa.

Para aplicar a pesquisa segura a uma resposta de chat:

Siga o procedimento anterior de armazenar conversas e receber respostas de chat, exceto na etapa 2, na consulta, 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 receber, excluir, atualizar e listar conversas armazenadas.

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 seu projeto do Google Cloud
DATA_STORE_ID:o ID do repositório de dados associado ao 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 com mais de 60 dias são excluídas automaticamente. No entanto, se você quiser excluir uma conversa específica, por exemplo, se ela contiver conteúdo sensível, use essa chamada de API para excluir.

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 com outra
Mude 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 ao app.
CONVERSATION_ID: o ID da conversa que você quer atualizar.
NEW_STATE: o novo valor do estado, por exemplo, COMPLETED

Clique para conferir um exemplo de resposta do comando 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 ao app.
CONVERSATION_ID: o ID da conversa que você quer atualizar
NEW_USER_PSEUDO_ID: o novo valor do pseudo-ID do usuário

Clique para conferir um exemplo de resposta do comando 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, é possível atualizar outros campos na conversa substituindo user_pseudo_id por outros campos no recurso de conversa.

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 ao 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. Se nenhum next_page_token for 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 com uma opção para reabrir uma delas.

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 ao 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 ao app.
USER_PSEUDO_ID: o pseudo-ID do usuário cujas conversas você quer listar.
STATE: se a conversa está aberta ou fechada (IN_PROGRESS ou COMPLETED)

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"
}
]
}

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

Perguntas relacionadas

As perguntas relacionadas são um recurso de pré-lançamento com lista de permissões que pode retornar perguntas relacionadas além dos resultados da pesquisa.

Por exemplo, quando você pergunta "Qual é a melhor época do ano para tirar 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 tirar 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, também precisará informar o nome dela.

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.