Receber respostas e acompanhamentos

Esta página apresenta a pesquisa com respostas e acompanhamentos da Vertex AI para Pesquisa e mostra como implementar esse recurso em apps de pesquisa personalizados usando chamadas de método.

A pesquisa com respostas e acompanhamentos é baseada no método de resposta. O método answer substitui os recursos de resumo do método search mais antigo e todos os recursos do método converse descontinuado. O método de resposta também tem alguns recursos adicionais importantes, como a capacidade de processar consultas complexas.

Recursos do método de resposta

Confira os principais recursos do método de resposta:

  • A capacidade de gerar respostas para consultas complexas. Por exemplo, o método de resposta pode dividir consultas compostas, como a seguinte, em várias consultas menores para retornar resultados melhores que são usados para gerar respostas melhores:

    • "Qual é a receita do Google Cloud e do Google Ads em 2024?"
    • "Quantos anos depois da fundação, o Google atingiu US$ 1 bilhão de receita?"

  • A capacidade de combinar pesquisa e geração de respostas em uma conversa de várias rodadas chamando o método de resposta em cada rodada.

  • A capacidade de parear com o método de pesquisa para reduzir a latência. Você pode chamar os métodos de pesquisa e resposta separadamente e renderizar os resultados da pesquisa e as respostas em iframes diferentes em momentos diferentes. Isso significa que você pode mostrar aos usuários resultados da pesquisa (os 10 links azuis) em milissegundos. Não é necessário esperar que as respostas sejam geradas para mostrar os resultados da pesquisa.

Os recursos de resposta e acompanhamento podem ser divididos em três fases da consulta, pesquisa e resposta:

Quando usar resposta e quando usar pesquisa

A Vertex AI para Pesquisa tem dois métodos usados para consultar apps. Elas têm recursos diferentes, mas que se sobrepõem.

Use o método answer quando:

  • Você quer uma resposta (ou um resumo) gerada com IA dos resultados da pesquisa.

  • Você quer fazer pesquisas com várias interações, ou seja, que mantêm o contexto para permitir perguntas complementares.

Use o método search nos seguintes casos:

  • Você só precisa de resultados da pesquisa, não de uma resposta gerada.

  • Você tem qualquer uma das seguintes opções:

    • Dados de mídia ou de saúde
    • Seus próprios embeddings
    • Controles de sinônimos ou redirecionamento
    • Atributos
    • Códigos de países dos usuários

  • É preciso navegar pelos dados no seu repositório de dados genérico.

Use os métodos de resposta e pesquisa juntos quando:

  • Você quer retornar mais de dez resultados da pesquisa e quer uma resposta gerada.

  • Você tem problemas de latência e quer retornar e mostrar resultados da pesquisa rapidamente antes que a resposta gerada seja retornada.

Recursos da fase de consulta

O recurso de respostas e acompanhamentos é compatível com o processamento de consultas em linguagem natural.

Esta seção descreve e ilustra as várias opções de reformulação e classificação de consultas.

Reformulação de consultas

A reformulação de consultas fica ativada por padrão. Esse recurso escolhe a melhor maneira de reformular consultas automaticamente para melhorar os resultados da pesquisa. Esse recurso também pode processar consultas que não precisam ser reformuladas.

  • Divida consultas complexas em várias consultas e faça subconsultas síncronas.

    Por exemplo, uma consulta complexa é dividida em quatro consultas menores e mais simples.

    Entrada do usuário Subconsultas criadas com base na consulta complexa
    Quais empregos e hobbies Andie Ram e Arnaud Clément têm em comum?
    • Ocupação de Andie Ram
    • Ocupação de Arnaud Clément
    • Hobby de Andie Ram
    • Hobby de Arnaud Clément

  • Sintetizar consultas multiturno para fazer perguntas complementares contextuais e com estado.

    Por exemplo, as consultas sintetizadas da entrada do usuário em cada turno podem ser assim:

    Entrada do usuário Consulta sintetizada
    Turno 1: laptops para escolas laptops para escolas
    Turn 2: not mac laptops para escola que não sejam mac
    Turn 3: bigger screen and i also need wireless keyboard and mouse laptops com tela maior para escola sem mac com teclado e mouse sem fio
    Turn 4: and a backpack for it notebooks com tela maior para escola, não mac, com teclado e mouse sem fio e uma mochila para ele

  • Simplifique consultas longas para melhorar a recuperação (requer recursos avançados de LLM).

    Por exemplo, uma consulta longa é abreviada para uma consulta típica.

    Entrada do usuário Consulta simplificada
    Estou tentando descobrir por que o botão "Adicionar ao carrinho" no nosso site não está funcionando corretamente. Parece que, quando um usuário clica no botão, o item não é adicionado ao carrinho e ele recebe uma mensagem de erro. Verifiquei o código e parece estar correto, então não sei qual pode ser o problema. Você pode me ajudar a resolver esse problema? O botão "Adicionar ao carrinho" não está funcionando no site.

  • Realizar raciocínio em várias etapas

    O raciocínio em várias etapas se baseia no paradigma ReAct (raciocínio + ação), que permite que os LLMs resolvam tarefas complexas usando o raciocínio em linguagem natural. Por padrão, o número máximo de etapas é cinco.

    Exemplo:

    Entrada do usuário Duas etapas para gerar a resposta
    Quantos anos depois da fundação o Google atingiu US$ 1 bilhão de receita? Etapa 1:
    [Pensamento]: preciso saber quando o Google foi fundado para consultar a receita desde então.
    [Ação] Pesquisa: quando o Google foi fundado?[Observar resultados da pesquisa]: "1998"

    Etapa 2:
    [Pensamento]: agora preciso saber a receita anual do Google desde 1998 e descobrir quando ela ultrapassou 1 bilhão pela primeira vez.
    [Act] Pesquisa: receita do Google desde 1998
    [Observe Search Results] Receita do Google em 1998, receita do Google em 1999…
    [Resposta]: O Google atingiu mais de US$ 1 bilhão de receita em 2003 [1], 5 anos após sua fundação em 1998 [2].

    O raciocínio em várias etapas exige recursos avançados de LLM.

Classificação de consultas

As opções de classificação de consultas são para identificar consultas adversárias e que não buscam respostas. Por padrão, as opções de classificação de consultas estão desativadas.

Para mais informações sobre consultas adversárias e que não buscam respostas, consulte Ignorar consultas adversárias e Ignorar consultas que não buscam resumos.

Recursos da fase de pesquisa

Para pesquisar, o método de resposta tem as mesmas opções que o método de pesquisa. Exemplo:

Recursos da fase de resposta

Durante a fase de resposta, quando as respostas são geradas com base nos resultados da pesquisa, você pode ativar os mesmos recursos do método de pesquisa. Exemplo:

Outros recursos da fase de resposta que não estão disponíveis no método de pesquisa são:

  • Receber uma pontuação de suporte para cada declaração (frase na resposta gerada). Uma pontuação de suporte é um valor de ponto flutuante no intervalo [0,1] que indica o quanto a declaração é fundamentada nos dados do repositório de dados. Para mais informações, consulte Retornar pontuações de suporte de embasamento.

  • Receber uma pontuação de suporte agregada para a resposta. A pontuação de suporte indica o nível de embasamento da resposta nos dados do repositório de dados. Para mais informações, consulte Retornar pontuações de suporte de embasamento.

  • Retorne apenas respostas bem fundamentadas. Você pode optar por retornar apenas as respostas que atendem a um determinado limite de pontuação de suporte. Para mais informações, consulte Mostrar apenas respostas bem fundamentadas.

  • Escolha retornar perguntas relacionadas. As perguntas relacionadas são sugestões que seus usuários podem escolher em vez de inserir as próprias perguntas.

  • Adicione informações de personalização às consultas para que as respostas possam ser personalizadas para usuários individuais. Para mais informações, consulte Personalizar respostas.

Para receber respostas multimodais que incluem gráficos ou imagens além de texto, as seguintes opções estão disponíveis:

  • Receber respostas que incluem gráficos com os dados contidos nas respostas. Para mais informações, consulte Gerar gráficos para respostas.

  • Recuperando imagens do repositório de dados. Se o repositório de dados tiver imagens, o método de resposta poderá retornar uma imagem na resposta. As imagens do repositório de dados também podem ser retornadas em referências se citações forem solicitadas. Para mais informações, consulte Recuperar imagens atuais do repositório de dados.

Antes de começar

Dependendo do tipo de app, siga estas instruções:

  • Se você tiver um app de pesquisa de sites estruturada, não estruturada ou de sites, ative as seguintes opções:

    • Recursos da edição Enterprise: você tem acesso aos principais recursos de respostas generativas. Isso inclui todos os recursos de geração de respostas, exceto os recursos avançados de respostas generativas, como perguntas relacionadas, simplificação de consultas, consultas de várias rodadas e respostas multimodais que retornam imagens e gráficos.
    • Recursos avançados de LLM: isso dá acesso aos recursos de respostas generativas avançadas que exigem raciocínio em várias etapas, simplificação de consultas, consultas em vários turnos, perguntas relacionadas e respostas multimodais que retornam imagens e gráficos.

  • Além disso, se você tiver um repositório de dados de pesquisa no site, ative a indexação avançada de sites.

Pesquisar e responder (básico)

O comando a seguir mostra como chamar o método answer e retornar uma resposta gerada e uma lista de resultados da pesquisa, com links para as fontes.

Esse comando mostra apenas a entrada necessária. As opções são deixadas com os valores padrão.

REST

Para pesquisar e receber resultados com uma resposta gerada, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"}
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "Comparar os bancos de dados do BigQuery e do Spanner?".

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Comandos da fase de consulta

Esta seção mostra como especificar opções para a fase de consulta da chamada do método answer.

Pesquisar e responder (reformulação desativada)

O comando a seguir mostra como chamar o método answer e retornar uma resposta gerada e uma lista de resultados da pesquisa. A resposta pode ser diferente da anterior porque a opção de reformulação está desativada.

REST

Para pesquisar e receber resultados com uma resposta gerada sem aplicar a reformulação de consulta, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "queryUnderstandingSpec": {
           "queryRephraserSpec": {
              "disable": true
        }
    }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app Vertex AI para Pesquisa.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "Comparar os bancos de dados do BigQuery e do Spanner?".

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Pesquisar e responder (especifique o número máximo de etapas)

O comando a seguir mostra como chamar o método answer e retornar uma resposta gerada e uma lista de resultados da pesquisa. A resposta é diferente das anteriores porque o número de etapas de reformulação foi aumentado.

REST

Para pesquisar e receber resultados com uma resposta gerada, permitindo até cinco etapas de reformulação, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "queryUnderstandingSpec": {
            "queryRephraserSpec": {
                "maxRephraseSteps": MAX_REPHRASE
             }
         }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "Comparar os bancos de dados do BigQuery e do Spanner?".
    • MAX_REPHRASE: o número máximo de etapas de reformulação. O maior valor permitido é 5. Se não for definido ou se for definido como um valor menor que 1, o valor será o padrão, 1.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Pesquisar e responder com classificação de consulta

O comando a seguir mostra como chamar o método answer para perguntar se uma consulta é adversária, não busca respostas ou nenhuma das opções.

A resposta inclui o tipo de classificação da consulta, mas a resposta em si não é afetada pela classificação. Se quiser mudar o comportamento da resposta de acordo com o tipo de consulta, faça isso na fase de resposta. Consulte Ignorar consultas adversárias e Ignorar consultas que não buscam resumos.

REST

Para determinar se uma consulta é adversária ou não busca respostas, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "queryUnderstandingSpec": {
            "queryClassificationSpec": {
                "types": ["QUERY_CLASSIFICATION_TYPE"]
             }
         }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "olá".
    • QUERY_CLASSIFICATION_TYPE: os tipos de consulta que você quer identificar: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY ou ambos.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Comandos da fase de pesquisa: pesquisar e responder com opções de resultados da pesquisa

Esta seção mostra como especificar opções para a parte da fase de pesquisa da chamada do método answer, como definir o número máximo de documentos retornados, aumentar e filtrar, e como receber uma resposta quando você fornece seus próprios resultados de pesquisa.

O comando a seguir mostra como chamar o método answer e especificar várias opções de como o resultado da pesquisa é retornado. (Os resultados da pesquisa são independentes da resposta.)

REST

Para definir várias opções relacionadas a quais e como os resultados da pesquisa são retornados, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
          "searchSpec": {
          "searchParams": {
            "maxReturnResults": MAX_RETURN_RESULTS,
            "filter": "FILTER",
            "boostSpec": BOOST_SPEC,
            "orderBy": "ORDER_BY",
            "searchResultMode": SEARCH_RESULT_MODE
           }
         }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "Comparar os bancos de dados do BigQuery e do Spanner?"
    • MAX_RETURN_RESULTS: o número de resultados da pesquisa a serem retornados. O valor padrão é 10. O valor máximo é 25.
    • FILTER: o filtro especifica quais documentos são consultados. Se os metadados de um documento atenderem à especificação do filtro, o documento será consultado. Para mais informações, incluindo a sintaxe de filtro, consulte Filtrar a pesquisa personalizada para dados estruturados ou não estruturados.
    • BOOST_SPEC: a especificação de otimização permite otimizar determinados documentos nos resultados da pesquisa, o que pode afetar a resposta. Para mais informações, incluindo a sintaxe da especificação de reforço, consulte Reforçar resultados da pesquisa.
    • ORDER_BY: a ordem em que os documentos são retornados. Os documentos podem ser ordenados por um campo em um objeto Document. A expressão orderBy diferencia maiúsculas de minúsculas. Se esse campo não for reconhecido, um INVALID_ARGUMENT será retornado.
    • SEARCH_RESULT_MODE: especifica o modo de resultado da pesquisa: DOCUMENTS ou CHUNKS. Para mais informações, consulte Analisar e dividir documentos em partes e ContentSearchSpec. Esse campo está disponível apenas na versão v1alpha da API.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Comandos da fase de resposta

Esta seção mostra como personalizar a chamada de método answer. É possível combinar as seguintes opções conforme necessário.

Ignorar consultas adversárias e que não buscam respostas

O comando a seguir mostra como evitar responder a consultas adversárias e consultas que não buscam respostas ao chamar o método answer.

REST

Para pular respostas a consultas adversárias ou que não buscam respostas, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "ignoreAdversarialQuery": true,
           "ignoreNonAnswerSeekingQuery": true
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Mostrar apenas respostas relevantes

A Vertex AI para Pesquisa pode avaliar a relevância dos resultados para uma consulta. Se nenhum resultado for considerado relevante o suficiente, em vez de gerar uma resposta com base em resultados não relevantes ou minimamente relevantes, você pode escolher retornar uma resposta alternativa: We do not have a summary for your query.

O comando a seguir mostra como retornar a resposta alternativa em caso de resultados irrelevantes ao chamar o método answer.

REST

Para retornar uma resposta de fallback se nenhum resultado relevante for encontrado, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "ignoreLowRelevantContent": true
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Retornar pontuações de suporte de embasamento

O comando a seguir mostra como retornar pontuações de suporte de embasamento para respostas e declarações.

Para informações gerais sobre o embasamento na Vertex AI, consulte Verificar o embasamento com RAG. O método groundingConfigs.check é chamado pelo método answer.

REST

Para retornar uma pontuação de suporte para cada declaração (frase na resposta) e uma pontuação de suporte agregada para a resposta, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "groundingSpec": {
           "includeGroundingSupports": true,
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.

Mostrar apenas respostas bem fundamentadas

O comando a seguir mostra como retornar apenas as respostas consideradas bem embasadas no corpus, as informações no repositório de dados. Respostas mal fundamentadas são filtradas.

Você escolhe um limite baixo ou alto para a pontuação de suporte de embasamento. A resposta só será retornada se atender ou exceder esse nível. Teste os dois limites de filtro e sem limite para determinar qual nível de filtro provavelmente vai oferecer os melhores resultados para seus usuários.

Para informações gerais sobre o embasamento na Vertex AI, consulte Verificar o embasamento com RAG. O método groundingConfigs.check é chamado pelo método answer.

REST

Para retornar uma resposta somente se ela atender a um limite de pontuação de suporte, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "groundingSpec": {
           "filteringLevel": "FILTER_LEVEL"
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • FILTER_LEVEL: uma enumeração para filtrar respostas com base na pontuação de suporte de embasamento. As opções são: FILTERING_LEVEL_LOW e FILTERING_LEVEL_HIGH. Se filteringLevel não for incluído, nenhum filtro de pontuação de suporte será aplicado à resposta.

Especificar o modelo de resposta

O comando a seguir mostra como mudar a versão do modelo usada para gerar respostas.

Para informações sobre os modelos aceitos, consulte Versões e ciclo de vida do modelo de geração de respostas.

REST

Para gerar uma resposta usando um modelo diferente do padrão, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "modelSpec": {
              "modelVersion": "MODEL_VERSION",
           }
         }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • MODEL_VERSION: a versão do modelo que você quer usar para gerar a resposta. Para mais informações, consulte Versões e ciclo de vida do modelo de geração de respostas.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Especificar um preâmbulo personalizado

O comando a seguir mostra como definir um preâmbulo para a resposta gerada. Um preâmbulo contém instruções em linguagem natural para personalizar a resposta. Você pode pedir personalizações como extensão, nível de detalhes, estilo de saída (como "simples"), idioma da saída, foco da resposta e formato (como tabelas, marcadores e XML). Por exemplo, um preâmbulo pode ser "Explique como se você fosse uma criança de dez anos".

O preâmbulo pode afetar significativamente a qualidade da resposta gerada. Para informações sobre o que escrever em preâmbulos e exemplos de bons preâmbulos, consulte Sobre preâmbulos personalizados.

REST

Para gerar uma resposta usando um modelo diferente do padrão, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "promptSpec": {
               "preamble": "PREAMBLE",
           }
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • PREAMBLE: uma instrução em linguagem natural para personalizar a resposta. Por exemplo, tente show the answer format in an ordered list ou give a very detailed answer.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

O método de resposta pode sugerir perguntas relacionadas, que os usuários podem escolher em vez de inserir as próprias perguntas. Por exemplo, quando você pergunta "Qual é a melhor época do ano para passar férias no México?", além de responder à sua pergunta, o método de resposta pode sugerir outras perguntas que você pode fazer, como "Qual é o mês mais barato para passar férias no México?" e "Quais são os meses de alta temporada no México?".

Para receber perguntas relacionadas, especifique a inclusão delas em cada consulta. Elas são retornadas como uma matriz de strings na resposta.

Antes de começar

Confira se você ativou os recursos avançados de LLM para o app.

Procedimento

O comando a seguir mostra como pedir que perguntas relacionadas sejam incluídas na resposta.

REST

Para receber perguntas relacionadas com uma resposta gerada:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "relatedQuestionsSpec": { "enable": true }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "Quais tipos de dados posso importar para a Vertex AI Search?".

Incluir citações

O comando a seguir mostra como pedir que as citações sejam incluídas na resposta.

REST

Para gerar uma resposta usando um modelo diferente do padrão, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "includeCitations": INCLUDE_CITATIONS
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • INCLUDE_CITATIONS: especifica se os metadados de citação devem ser incluídos na resposta. O valor padrão é false.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Definir o código do idioma da resposta

O comando a seguir mostra como definir o código de idioma para respostas.

REST

Para gerar uma resposta usando um modelo diferente do padrão, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "answerLanguageCode": "ANSWER_LANGUAGE_CODE"
           }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • ANSWER_LANGUAGE_CODE: um código de idioma para a resposta. Use tags de idioma definidas pelo BCP47: Tags para identificar idiomas (em inglês).

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

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"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  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
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-2.0-flash-001/answer_gen/v1",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Personalizar respostas

Se houver informações específicas sobre o usuário disponíveis, por exemplo, dados em um perfil, especifique essas informações no objeto endUserMetadata para que os resultados da consulta possam ser personalizados para o usuário.

Por exemplo, se um usuário conectado estiver pesquisando informações sobre como fazer upgrade de um smartphone, as informações do perfil dele, como o modelo atual do smartphone e o plano de celular, podem personalizar a resposta gerada.

Para adicionar informações pessoais sobre o usuário que está fazendo uma consulta e gerar uma resposta que leve em consideração essas informações, faça o seguinte:

  1. Execute o seguinte comando curl:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
-d '{
    "query": { "text": "QUERY"},
    "endUserSpec": {
       "endUserMetadata": [
         {
           "chunkInfo": {
              "content": "PERSONALIZED_INFO",
              "documentMetadata":  { "title": "INFO_DESCRIPTION"}
           }
         }
       ]
    }
  }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • PERSONALIZATION_INFO: uma string que contém informações específicas do usuário que está fazendo a consulta. Por exemplo, This customer has a Pixel 6 Pro purchased over a period of 24-months starting 2023-01-15. This customer is on the Business Plus International plan. No payment is due at this time. O limite de comprimento dessa string é de 8.000 caracteres.
    • INFO_DESCRIPTION: uma string que descreve brevemente as informações de personalização. Por exemplo, Customer profile data, including model, plan, and billing status.. O modelo usa essa descrição e as informações de personalização ao gerar uma resposta personalizada para a consulta.

Gerar gráficos para respostas

O método answer pode gerar gráficos e retorná-los como parte da resposta a uma consulta.

Você pode pedir especificamente que uma resposta inclua um gráfico, por exemplo, "Mostre a taxa de crescimento anual dos pagamentos de pequenas empresas ao longo dos anos com dados disponíveis". Se o sistema determinar que há dados suficientes, um gráfico será retornado. Normalmente, um texto de resposta é retornado junto com o gráfico.

Além disso, se houver dados suficientes para criar um gráfico, o método de resposta poderá retornar um gráfico mesmo que a consulta não tenha solicitado explicitamente um. Por exemplo, "Qual foi a melhoria nos indicadores de IDH associada a mais acesso à água potável na década entre 2010 e 2020?"

Apenas um gráfico é gerado por resposta. No entanto, o gráfico pode ser composto, contendo outros gráficos menores. Exemplo de um gráfico composto:

O gráfico composto contém quatro gráficos menores

Limitação

As consultas precisam estar em inglês.

Cenários comuns de falha

Nem sempre uma imagem é retornada com sua resposta. Se não houver dados suficientes, não será possível gerar uma figura.

Outros cenários de falha incluem erros de execução de código e tempos limite. Se isso acontecer, reformule a consulta e tente de novo.

Antes de começar

Antes de executar uma consulta que pede gráficos gerados, faça o seguinte:

Procedimento

REST

Chame o método answer da seguinte maneira para retornar uma resposta que pode incluir um gráfico gerado com base nos dados do repositório de dados:

  1. Execute o seguinte comando curl:

    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:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
          "model_spec": {
             "model_version": "MODEL_VERSION"
         },
          "multimodalSpec": {
             "imageSource": "IMAGE_SOURCE"
             }
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre em inglês que contém a pergunta ou consulta de pesquisa.
    • MODEL_VERSION: versão do modelo gemini-2.0-flash-001/answer_gen/v1 ou mais recente. Para mais informações, consulte Versões e ciclo de vida do modelo de geração de respostas.
    • IMAGE_SOURCE: uma enumeração para solicitar que a resposta inclua um gráfico gerado, FIGURE_GENERATION_ONLY, ou que a resposta possa incluir um gráfico gerado ou uma imagem existente dos repositórios de dados, ALL_AVAILABLE_SOURCES.

Recuperar imagens atuais do repositório de dados

Você pode escolher que as imagens do repositório de dados sejam retornadas com a resposta e em referências de citação. O repositório de dados precisa ser não estruturado e ter o analisador de layout ativado.

Para receber gráficos nas respostas, ative os recursos avançados do LLM.

Quando imageSource é CORPUS_IMAGE_ONLY ou ALL_AVAILABLE_SOURCES, o método answer pode recuperar imagens do repositório de dados conforme apropriado. No entanto, ativar essa opção não significa que as imagens serão sempre retornadas.

Você recebe uma imagem (no máximo) por resposta. As citações podem conter várias imagens.

Limitações

  • O app que você está usando precisa estar conectado a um repositório de dados não estruturados. As imagens não podem ser retornadas de sites ou repositórios de dados estruturados.

  • As consultas precisam estar em inglês.

  • A anotação de imagem pelo analisador de layout precisa ser aplicada ao repositório de dados. Para informações sobre o analisador de layout, consulte Analisar e dividir documentos em partes.

Procedimento

REST

Chame o método answer da seguinte maneira para retornar uma resposta que pode incluir uma imagem do repositório de dados:

  1. Execute o seguinte comando curl:

    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:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
          "model_spec": {
             "model_version": "MODEL_VERSION"
          },
          includeCitations: true,
          "multimodalSpec": {
             "imageSource": "IMAGE_SOURCE"
             }
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app da Vertex AI para Pesquisa que você quer consultar.
    • QUERY: uma string de texto livre em inglês que contém a pergunta ou consulta de pesquisa.
    • MODEL_VERSION: versão do modelo gemini-2.0-flash-001/answer_gen/v1 ou mais recente. Para mais informações, consulte Versões e ciclo de vida do modelo de geração de respostas.
    • IMAGE_SOURCE: uma enumeração para solicitar que a resposta inclua uma imagem do repositório de dados, CORPUS_IMAGE_ONLY, ou que a resposta possa incluir uma imagem do repositório de dados ou um gráfico gerado, ALL_AVAILABLE_SOURCES.

Comandos para perguntas complementares

As perguntas complementares são consultas com vários turnos. Depois da primeira consulta em uma sessão de acompanhamento, os "turnos" subsequentes consideram as interações anteriores. Com os complementos, o método de resposta também pode sugerir perguntas relacionadas, que os usuários podem escolher em vez de inserir as próprias perguntas complementares. Para receber sugestões de perguntas relacionadas, ative os recursos avançados de LLM.

Todos os recursos de resposta e acompanhamento descritos nas seções anteriores, como citações, filtros, SafeSearch, ignorar determinados tipos de consultas e usar um preâmbulo para personalizar respostas, podem ser aplicados com os acompanhamentos.

Exemplo de uma sessão de acompanhamento

Confira a seguir um exemplo de sessão com acompanhamentos. Suponha que você queira saber sobre férias no México:

  • Turno 1:

    • Você:Qual é a melhor época do ano para passar as férias no México?

    • Resposta com acompanhamento:a melhor época para passar férias no México é durante a estação seca, que vai de novembro a abril.

  • Turno 2:

    • Você:Qual é a taxa de câmbio?

    • Resposta com acompanhamento:US$ 1 equivale a aproximadamente 17,65 pesos mexicanos.

  • Turno 3:

    • Você:Qual é a temperatura média em dezembro?

    • Resposta com acompanhamento:a temperatura média varia de 21 a 26 °C. A média de Cancún é de aproximadamente 25 °C.

Sem acompanhamentos, a pergunta "Qual é a taxa de câmbio?" não teria resposta porque a pesquisa normal não saberia que você queria a taxa de câmbio mexicana. Da mesma forma, sem acompanhamentos, não haveria o contexto necessário para fornecer temperaturas específicas para o México.

Sobre sessões

Para entender como os acompanhamentos funcionam na Vertex AI Search, você precisa saber sobre sessões.

Uma sessão é composta por consultas de texto fornecidas por um usuário e respostas da Vertex AI para Pesquisa.

Esses pares de consulta e resposta às vezes são chamados de turnos. No exemplo anterior, o segundo turno é composto por "Qual é a taxa de câmbio?" e "US$ 1 é igual a aproximadamente 17,65 pesos mexicanos".

As sessões são armazenadas com o app. No app, uma sessão é representada pelo recurso session.

Além de conter as mensagens de consulta e resposta, o recurso de sessão tem:

  • Um nome exclusivo (o ID da sessão).

  • 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. Quando mapeado para o ID pseudônimo do usuário nos eventos de usuário do seu app, o modelo pode ajudar você a veicular resultados personalizados para o usuário.

  • Um horário de início e um de término.

  • Um turno, que é um par de pergunta e resposta.

Antes de começar

Antes de executar uma consulta que pede perguntas de acompanhamento, verifique se você ativou os recursos avançados de LLM no app.

Armazenar informações da sessão e receber respostas

Você pode usar a linha de comando para gerar respostas e respostas de pesquisa e armazená-las, junto com cada consulta, em uma sessão.

REST

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

  1. Especifique o app em que você quer armazenar a sessão:

    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/engines/APP_ID/sessions" \
  -d '{
        "userPseudoId": "USER_PSEUDO_ID"
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.

    • APP_ID: o ID do app Vertex AI para Pesquisa.

    • USER_PSEUDO_ID: uma string codificada em UTF-8 que funciona como um identificador pseudônimo exclusivo que rastreia os usuários. Ele pode ter um tamanho máximo de 128 caracteres. O Google recomenda usar esse campo porque ele melhora a performance do modelo e a qualidade da personalização. Você pode usar um cookie HTTP para esse campo, que identifica um visitante em um único dispositivo. Algumas considerações importantes:

      • Esse identificador não muda quando o visitante faz login ou logout de um site.
      • Esse campo não pode ser definido com o mesmo identificador para vários usuários. Caso contrário, o mesmo ID de usuário pode combinar históricos de eventos de usuários diferentes e prejudicar a qualidade do modelo.
      • Esse campo não pode incluir informações de identificação pessoal (PII).
      • Para uma determinada solicitação de pesquisa ou navegação, esse campo precisa ser mapeado para o campo userPseudoId correspondente nos eventos do usuário.

      Para ver mais informações, consulte userPseudoId.

    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/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/sessions"
-d '{
"userPseudoId": "test_user"
}'

    
{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943",
  "state": "IN_PROGRESS",
  "userPseudoId": "test_user",
  "startTime": "2024-09-13T18:47:10.465311Z",
  "endTime": "2024-09-13T18:47:10.465311Z"
}

  2. Anote o ID da sessão, os números no final do campo name: na resposta JSON. No exemplo de resultado, o ID é 5386462384953257772. Você vai precisar desse ID na próxima etapa.

  3. Gere uma resposta e adicione-a a uma sessão no seu app:

    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/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "session": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID",
          "searchSpec":{ "searchParams": {"filter": "FILTER"} }
}'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app Vertex AI para Pesquisa.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • SESSION_ID: o ID da sessão que você criou na etapa 1. Esses são os dígitos no final do campo name:, anotados na etapa 2. Para uma sessão, use o mesmo ID em todos os turnos.
    • FILTER: um campo de texto para filtrar a pesquisa usando uma expressão de filtro. O valor padrão é uma string vazia. A forma de criar o filtro varia dependendo se você tem dados não estruturados com metadados, dados estruturados ou dados do site. Para mais informações, consulte Filtrar a pesquisa personalizada para dados estruturados ou não estruturados e Filtrar a pesquisa de sites.

    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/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/default_search:answer"
-d '{
"query": { "text": "Compare bigquery with spanner database?"},
"session":  "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943",
}'
    
    
{
  "answer": {
    "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943/answers/4861507376861383072",
    "state": "SUCCEEDED",
    "answerText": "BigQuery and Spanner are both powerful tools that can be used together to handle transactional and analytical workloads. Spanner is a fully managed relational database optimized for transactional workloads, while BigQuery is a serverless data warehouse designed for business agility. Spanner provides seamless replication across regions in Google Cloud and processes over 1 billion requests per second at peak. BigQuery analyzes over 110 terabytes of data per second. Users can leverage federated queries to read data from Spanner and write to a native BigQuery table. \n",
    "steps": [
      {
        "state": "SUCCEEDED",
        "description": "Rephrase the query and search.",
        "actions": [
          {
            "searchAction": {
              "query": "Compare bigquery with spanner database?"
            },
            "observation": {
              "searchResults": [
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/ecc0e7547253f4ca3ff3328ce89995af",
                  "uri": "https://cloud.google.com/blog/topics/developers-practitioners/how-spanner-and-bigquery-work-together-handle-transactional-and-analytical-workloads",
                  "title": "How Spanner and BigQuery work together to handle transactional and analytical workloads | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "Using Cloud \u003cb\u003eSpanner\u003c/b\u003e and \u003cb\u003eBigQuery\u003c/b\u003e also allows customers to build their \u003cb\u003edata\u003c/b\u003e clouds using Google Cloud, a unified, open approach to \u003cb\u003edata\u003c/b\u003e-driven transformation ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                },
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/d7e238f73608a860e00b752ef80e2941",
                  "uri": "https://cloud.google.com/blog/products/databases/cloud-spanner-gets-stronger-with-bigquery-federated-queries",
                  "title": "Cloud Spanner gets stronger with BigQuery-federated queries | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "As enterprises compete for market share, their need for real-time insights has given rise to increased demand for transactional \u003cb\u003edatabases\u003c/b\u003e to support \u003cb\u003edata\u003c/b\u003e ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                },
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/e10a5a3c267dc61579e7c00fefe656eb",
                  "uri": "https://cloud.google.com/blog/topics/developers-practitioners/replicating-cloud-spanner-bigquery-scale",
                  "title": "Replicating from Cloud Spanner to BigQuery at scale | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "... \u003cb\u003eSpanner data\u003c/b\u003e into \u003cb\u003eBigQuery\u003c/b\u003e for analytics. In this post, you will learn how to efficiently use this feature to replicate large tables with high throughput ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                },
                ...
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/8100ad36e1cac149eb9fc180a41d8f25",
                  "uri": "https://cloud.google.com/blog/products/gcp/from-nosql-to-new-sql-how-spanner-became-a-global-mission-critical-database",
                  "title": "How Spanner became a global, mission-critical database | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "... SQL \u003cb\u003evs\u003c/b\u003e. NoSQL dichotomy may no longer be relevant." The \u003cb\u003eSpanner\u003c/b\u003e SQL query processor, while recognizable as a standard implementation, has unique ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    ]
  },
  "session": {
    "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943",
    "state": "IN_PROGRESS",
    "userPseudoId": "test_user",
    "turns": [
      {
        "query": {
          "queryId": "projects/123456/locations/global/questions/741830",
          "text": "Compare bigquery with spanner database?"
        },
        "answer": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943/answers/4861507376861383072"
      }
    ],
    "startTime": "2024-09-13T18:47:10.465311Z",
    "endTime": "2024-09-13T18:47:10.465311Z"
  },
  "answerQueryToken": "NMwKDAjFkpK3BhDU24uZAhIkNjZlNDIyZWYtMDAwMC0yMjVmLWIxMmQtZjQwMzA0M2FkYmNj"
}

  4. Repita a etapa 3 para cada nova consulta na sessão.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

from google.cloud import discoveryengine_v1 as discoveryengine


def create_session(
    project_id: str,
    location: str,
    engine_id: str,
    user_pseudo_id: str,
) -> discoveryengine.Session:
    """Creates a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        user_pseudo_id: A unique identifier for tracking visitors. For example, this
          could be implemented with an HTTP cookie, which should be able to
          uniquely identify a visitor on a single device.
    Returns:
        discoveryengine.Session: The newly created Session.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    session = client.create_session(
        # The full resource name of the engine
        parent=f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}",
        session=discoveryengine.Session(user_pseudo_id=user_pseudo_id),
    )

    # Send Session name in `answer_query()`
    print(f"Session: {session.name}")
    return session

Receber uma sessão do repositório de dados

O comando a seguir mostra como chamar o método get e receber uma sessão do repositório de dados.

REST

Para receber uma sessão de um repositório de dados, faça o seguinte:

  1. 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/engines/APP_ID/sessions/SESSION_ID"

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app Vertex AI para Pesquisa.
    • SESSION_ID: o ID da sessão que você quer receber.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

from google.cloud import discoveryengine_v1 as discoveryengine


def get_session(
    project_id: str,
    location: str,
    engine_id: str,
    session_id: str,
) -> discoveryengine.Session:
    """Retrieves a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        session_id: The ID of the session.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the session
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/sessions/{session_id}"

    session = client.get_session(name=name)

    print(f"Session details: {session}")
    return session

Excluir uma sessão do app

O comando a seguir mostra como chamar o método delete e excluir uma sessão do repositório de dados.

Por padrão, as sessões com mais de 60 dias são excluídas automaticamente. No entanto, se você quiser excluir uma sessão específica, por exemplo, se ela contiver conteúdo sensível, use esta chamada de API para excluir.

REST

Para excluir uma sessão de um app, faça o seguinte:

  1. 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/engines/APP_ID/sessions/SESSION_ID"

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app Vertex AI para Pesquisa.
    • SESSION_ID: o ID da sessão que você quer excluir.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

from google.cloud import discoveryengine_v1 as discoveryengine


def delete_session(
    project_id: str,
    location: str,
    engine_id: str,
    session_id: str,
) -> None:
    """Deletes a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        session_id: The ID of the session.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the session
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/sessions/{session_id}"

    client.delete_session(name=name)

    print(f"Session {name} deleted.")

Atualizar uma sessão

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

  • Marcar uma sessão como concluída
  • Mesclar as mensagens de uma sessão em outra
  • Mudar o pseudo ID de um usuário

O comando a seguir mostra como chamar o método patch e atualizar uma sessão no repositório de dados.

REST

Para atualizar uma sessão de um app, faça o seguinte:

  1. 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/engines/APP_ID/sessions/SESSION_ID?updateMask=state" \
  -d '{
        "state": "NEW_STATE"
      }'

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app Vertex AI para Pesquisa.
    • SESSION_ID: o ID da sessão que você quer atualizar.
    • NEW_STATE: o novo valor do estado, por exemplo, IN_PROGRESS.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

from google.cloud import discoveryengine_v1 as discoveryengine
from google.protobuf import field_mask_pb2


def update_session(
    project_id: str,
    location: str,
    engine_id: str,
    session_id: str,
) -> discoveryengine.Session:
    """Updates a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        session_id: The ID of the session.
    Returns:
        discoveryengine.Session: The updated Session.
    """
    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the session
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/sessions/{session_id}"

    session = discoveryengine.Session(
        name=name,
        state=discoveryengine.Session.State.IN_PROGRESS,  # Options: IN_PROGRESS, STATE_UNSPECIFIED
    )

    # Fields to Update
    update_mask = field_mask_pb2.FieldMask(paths=["state"])

    session = client.update_session(session=session, update_mask=update_mask)
    print(f"Updated session: {session.name}")
    return session

Listar todas as sessões

O comando a seguir mostra como chamar o método list e listar as sessões no repositório de dados.

REST

Para listar as sessões de um app, faça o seguinte:

  1. 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/engines/APP_ID/sessions"

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app Vertex AI para Pesquisa.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

from google.cloud import discoveryengine_v1 as discoveryengine


def list_sessions(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ListSessionsResponse:
    """Lists all sessions associated with a data store.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
    Returns:
        discoveryengine.ListSessionsResponse: The list of sessions.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the engine
    parent = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}"

    response = client.list_sessions(
        request=discoveryengine.ListSessionsRequest(
            parent=parent,
            filter='state="IN_PROGRESS"',  # Optional: Filter requests by userPseudoId or state
            order_by="update_time",  # Optional: Sort results
        )
    )

    print("Sessions:")
    for session in response.sessions:
        print(session)

    return response

Listar sessões de um usuário

O comando a seguir mostra como chamar o método list para listar as sessões associadas a um usuário ou visitante.

REST

Para listar as sessões associadas a um usuário ou visitante, faça o seguinte:

  1. 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/engines/APP_ID/sessions?filter=userPseudoId=USER_PSEUDO_ID"

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app Vertex AI para Pesquisa.
    • USER_PSEUDO_ID: o ID pseudônimo do usuário cujas sessões você quer listar.

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

from google.cloud import discoveryengine_v1 as discoveryengine


def list_sessions(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ListSessionsResponse:
    """Lists all sessions associated with a data store.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
    Returns:
        discoveryengine.ListSessionsResponse: The list of sessions.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the engine
    parent = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}"

    response = client.list_sessions(
        request=discoveryengine.ListSessionsRequest(
            parent=parent,
            filter='state="IN_PROGRESS"',  # Optional: Filter requests by userPseudoId or state
            order_by="update_time",  # Optional: Sort results
        )
    )

    print("Sessions:")
    for session in response.sessions:
        print(session)

    return response

Listar sessões para um usuário e um estado

O comando a seguir mostra como chamar o método list para listar sessões em um determinado estado para um usuário específico.

REST

Para listar as sessões abertas ou fechadas de um usuário ou visitante específico, faça o seguinte:

  1. 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/engines/APP_ID/sessions?filter=userPseudoId=USER_PSEUDO_ID%20AND%20state=STATE"

    Substitua:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • APP_ID: o ID do app Vertex AI para Pesquisa.
    • USER_PSEUDO_ID: o ID pseudônimo do usuário cujas sessões você quer listar.
    • STATE: o estado da sessão: STATE_UNSPECIFIED (fechada ou desconhecida) ou IN_PROGRESS (aberta).

Python

Para mais informações, consulte a documentação de referência da API Python de aplicativos de IA.

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

from google.cloud import discoveryengine_v1 as discoveryengine


def list_sessions(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ListSessionsResponse:
    """Lists all sessions associated with a data store.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
    Returns:
        discoveryengine.ListSessionsResponse: The list of sessions.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the engine
    parent = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}"

    response = client.list_sessions(
        request=discoveryengine.ListSessionsRequest(
            parent=parent,
            filter='state="IN_PROGRESS"',  # Optional: Filter requests by userPseudoId or state
            order_by="update_time",  # Optional: Sort results
        )
    )

    print("Sessions:")
    for session in response.sessions:
        print(session)

    return response