Receba respostas e seguimentos

Esta página apresenta a pesquisa com respostas e seguimentos para a Pesquisa do Vertex AI e mostra como a implementar para apps de pesquisa personalizadas através de chamadas de métodos.

A pesquisa com resposta e seguimentos baseia-se no método de resposta. O método de resposta substitui as funcionalidades de resumo do método search mais antigo e todas as funcionalidades do método converse descontinuado. O método de resposta também tem algumas funcionalidades adicionais importantes, como a capacidade de processar consultas complexas.

Funcionalidades do método de resposta

Seguem-se as principais funcionalidades do método de resposta:

  • A capacidade de gerar respostas a consultas complexas. Por exemplo, o método answer pode dividir consultas compostas, como as seguintes, em várias consultas mais pequenas para devolver melhores resultados que são usados para gerar melhores respostas:

    • "Qual é a receita respetiva do Google Cloud e do Google Ads em 2024?"
    • "Quantos anos após a sua fundação, a Google atingiu 1000 milhões de USD de receita?"

  • A capacidade de combinar a pesquisa e a geração de respostas numa conversa de várias interações chamando o método de resposta em cada interação.

  • A capacidade de sincronizar com o método de pesquisa para reduzir a latência de pesquisa. Pode chamar o método de pesquisa e o método de resposta separadamente e renderizar os resultados da pesquisa e as respostas em diferentes iFrames em momentos diferentes. Isto significa que pode apresentar aos seus utilizadores resultados da pesquisa (os 10 links azuis) em milissegundos. Não tem de esperar que as respostas sejam geradas antes de poder mostrar os resultados da pesquisa.

As funcionalidades de resposta e seguimentos podem ser divididas em três fases da consulta, pesquisa e resposta:

Quando usar a resposta e quando usar a pesquisa

O Vertex AI Search tem dois métodos que são usados para consultar apps. Têm funcionalidades diferentes, mas sobrepostas.

Use o método answer quando:

  • Quer uma resposta (ou um resumo) gerada pela IA dos resultados da pesquisa.

  • Quer pesquisas com várias interações, ou seja, pesquisas que mantêm o contexto para permitir perguntas de seguimento.

Use o método search nos seguintes casos:

  • Só precisa de resultados da pesquisa e não de uma resposta gerada.

  • Tem qualquer um dos seguintes elementos:

    • Dados de comunicação social ou de cuidados de saúde
    • As suas próprias incorporações
    • Controlos de sinónimos ou redirecionamentos
    • Atributos
    • Códigos dos países dos utilizadores

  • Tem de procurar os dados no seu repositório de dados genérico.

Use os métodos de resposta e pesquisa em conjunto quando:

  • Quer devolver mais de dez resultados da pesquisa e quer uma resposta gerada.

  • Tem problemas de latência e quer devolver e apresentar rapidamente os resultados da pesquisa antes de a resposta gerada ser devolvida.

Funcionalidades da fase de consulta

A funcionalidade de respostas e seguimentos suporta o processamento de consultas de linguagem natural.

Esta secçã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 está ativada por predefinição. Esta funcionalidade escolhe automaticamente a melhor forma de reformular as consultas para melhorar os resultados da pesquisa. Esta funcionalidade também pode processar consultas que não requerem reformulação.

  • Divida consultas complexas em várias consultas e execute subconsultas síncronas.

    Por exemplo: uma consulta complexa é dividida em quatro consultas mais pequenas e simples.

    Introdução do utilizador Subconsultas criadas a partir da consulta complexa
    Que empregos e hobbies têm Andie Ram e Arnaud Clément em comum?
    • Profissão de Andie Ram
    • Ocupação de Arnaud Clément
    • Andie Ram hobby
    • Passatempo de Arnaud Clément

  • Sintetizar consultas de várias interações para tornar as perguntas de seguimento sensíveis ao contexto e com estado.

    Por exemplo, as consultas sintetizadas a partir da introdução do utilizador em cada interação podem ter o seguinte aspeto:

    Introdução do utilizador Consulta sintetizada
    Turn 1: portáteis para a escola portáteis para a escola
    Turn 2: not mac portáteis para a escola que não sejam Mac
    Turn 3: bigger screen and i also need wireless keyboard and mouse portáteis com ecrã maior para a escola, que não sejam Mac, com teclado e rato sem fios
    Turn 4: and a backpack for it portáteis com ecrã maior para a escola, que não sejam Macs, com teclado e rato sem fios e uma mochila para o portátil

  • Simplificar consultas longas para melhorar a obtenção (requer funcionalidades avançadas de MDG).

    Por exemplo: uma consulta longa é reduzida a uma consulta típica.

    Introdução do utilizador Consulta simplificada
    Estou a tentar descobrir por que motivo o botão "Adicionar ao carrinho" no nosso Website não está a funcionar corretamente. Parece que, quando um utilizador clica no botão, o artigo não é adicionado ao carrinho e recebe uma mensagem de erro. Verifiquei o código e parece estar correto, por isso, não tenho a certeza de qual poderá ser o problema. Podes ajudar-me a resolver este problema? O botão "Adicionar ao carrinho" não funciona no Website.

  • Realizar raciocínio em vários passos

    O raciocínio em vários passos baseia-se no paradigma ReAct (reason + act), que permite aos MDLs resolver tarefas complexas através do raciocínio em linguagem natural. Por predefinição, o número máximo de passos é cinco.

    Por exemplo:

    Introdução do utilizador Dois passos para gerar a resposta
    Quantos anos após a sua fundação, a Google atingiu 1000 milhões de USD de receita? Passo 1:
    [Thought]: I need to know when Google was founded, then I can query it is revenue since then.
    [Act] Search: When was Google founded?[Observe Search Results]: "1998"

    Passo 2:
    [Thought]: Agora, preciso de saber a receita anual da Google desde 1998 e descobrir quando excedeu 1000 milhões pela primeira vez.
    [Act] Pesquisar: receita da Google desde 1998
    [Observe Search Results] Receita da Google em 1998, receita da Google em 1999…
    [Resposta]: A Google alcançou uma receita de mais de 1000 milhões de USD em 2003 [1], 5 anos após a sua fundação em 1998 [2].

    O raciocínio em vários passos requer funcionalidades avançadas de LLM.

Classificação de consultas

As opções de classificação de consultas destinam-se a identificar consultas adversariais e consultas que não procuram respostas. Por predefinição, as opções de classificação de consultas estão desativadas.

Para mais informações sobre consultas adversariais e que não procuram respostas, consulte os artigos Ignorar consultas adversariais e Ignorar consultas que não procuram resumos.

Funcionalidades da fase de pesquisa

Para a pesquisa, o método de resposta tem as mesmas opções que o método de pesquisa. Por exemplo:

Funcionalidades da fase de resposta

Durante a fase de resposta, quando as respostas são geradas a partir dos resultados da pesquisa, pode ativar as mesmas funcionalidades que no método de pesquisa. Por exemplo:

Funcionalidades adicionais da fase de resposta que não estão disponíveis no método de pesquisa:

  • Obter uma pontuação de apoio para cada afirmação (frase na resposta gerada). Uma pontuação de apoio é um valor de ponto flutuante no intervalo [0,1] que indica o quão fundamentada está a reivindicação nos dados na base de dados. Para mais informações, consulte o artigo Devolva classificações de apoio técnico de fundamentação.

  • Receber uma pontuação de apoio técnico agregada para a resposta. A pontuação de apoio técnico indica o quão bem a resposta se baseia nos dados do armazenamento de dados. Para mais informações, consulte a secção Devolver classificações de apoio de fundamentação.

  • Devolver apenas respostas bem fundamentadas. Pode optar por devolver apenas as respostas que atingem um determinado limite de pontuação de apoio técnico. Para mais informações, consulte o artigo Mostre apenas respostas bem fundamentadas.

  • Opte por devolver perguntas relacionadas. As perguntas relacionadas são sugestões que os seus utilizadores podem escolher em vez de introduzirem as suas próprias perguntas.

  • Adicionar informações de personalização às consultas para que as respostas possam ser personalizadas para utilizadores individuais. Para mais informações, consulte o artigo Personalize as respostas.

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

  • Receber respostas que incluem tabelas e gráficos que representam os dados contidos nas respostas. Para mais informações, consulte o artigo Gere gráficos para respostas.

  • A obter imagens do repositório de dados. Se o repositório de dados contiver imagens, o método de resposta pode devolver uma imagem na resposta. As imagens do armazenamento de dados também podem ser devolvidas em referências se forem pedidas citações. Para mais informações, consulte o artigo Recupere imagens existentes do arquivo de dados.

Antes de começar

Consoante o tipo de app que tiver, cumpra os seguintes requisitos:

  • Se tiver uma app de pesquisa estruturada, não estruturada ou de Website, ative as seguintes opções:

    • Funcionalidades da edição Enterprise: isto dá-lhe acesso às funcionalidades de respostas generativas essenciais. Isto inclui todas as funcionalidades de geração de respostas, exceto as funcionalidades de respostas generativas avançadas, como perguntas relacionadas, simplificação de consultas, consultas de várias interações e respostas multimodais que devolvem imagens e gráficos.
    • Funcionalidades avançadas de GML: isto dá-lhe acesso às funcionalidades de respostas generativas avançadas que requerem raciocínio de vários passos, simplificação de consultas, consultas multifacetadas, perguntas relacionadas e respostas multimodais que devolvem imagens e gráficos.

  • Além disso, se tiver um arquivo de dados de pesquisa no Website, ative a opção Indexação avançada de Websites.

Pesquisar e responder (básico)

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

Este comando mostra apenas a entrada necessária. As opções são mantidas como predefinições.

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 o seguinte:

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

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

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

    # Handle the response
    print(response)

    return response

Comandos da fase de consulta

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

Pesquise e responda (reformulação desativada)

O comando seguinte mostra como chamar o método answer e devolver uma resposta gerada e uma lista de resultados da pesquisa. A resposta pode ser diferente da resposta 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 da 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 o seguinte:

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

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

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

    # Handle the response
    print(response)

    return response

Pesquisar e responder (especificar o número máximo de passos)

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

REST

Para pesquisar e obter resultados com uma resposta gerada que permite até cinco passos 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search que quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou a consulta de pesquisa. Por exemplo, "Comparar as bases de dados do BigQuery e do Spanner?".
    • MAX_REPHRASE: o número máximo de passos de reformulação. O valor máximo permitido é 5. Se não for definido ou se for definido para um valor inferior a 1, o valor é o predefinido, 1.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

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

    # Handle the response
    print(response)

    return response

Pesquise e responda com a classificação de consultas

O comando seguinte mostra como chamar o método answer para saber se uma consulta é adversária, não procura 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 alterar o comportamento da resposta de acordo com o tipo de consulta, pode fazê-lo na fase de resposta. Consulte Ignorar consultas adversariais e Ignorar consultas que não procuram resumos.

REST

Para determinar se uma consulta é adversária ou não procura uma 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"},
        "queryUnderstandingSpec": {
            "queryClassificationSpec": {
                "types": ["QUERY_CLASSIFICATION_TYPE"]
             }
         }
      }'

    Substitua o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search que quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou a consulta de pesquisa. Por exemplo, "olá".
    • QUERY_CLASSIFICATION_TYPE: os tipos de consultas que 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 aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # 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 secçã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 devolvidos, o aumento e a filtragem, e como obter uma resposta quando fornece os seus próprios resultados da pesquisa.

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

REST

Para definir várias opções relacionadas com os resultados de pesquisa devolvidos e a forma como são devolvidos, 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search que quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou a consulta de pesquisa. Por exemplo, "Comparar as bases de dados do BigQuery e do Spanner?"
    • MAX_RETURN_RESULTS: o número de resultados da pesquisa a devolver. O valor predefinido é 10. O valor máximo é 25.
    • FILTER: o filtro especifica os documentos que são consultados. Se os metadados de um documento cumprirem a especificação do filtro, o documento é consultado. Para mais informações, incluindo a sintaxe dos filtros, consulte o artigo Filtre a pesquisa personalizada para dados estruturados ou não estruturados.
    • BOOST_SPEC: a especificação de aumento permite-lhe aumentar determinados documentos nos resultados da pesquisa, o que pode afetar a resposta. Para mais informações, incluindo a sintaxe da especificação de aumento, consulte o artigo Aumente os resultados da pesquisa.
    • ORDER_BY: a ordem em que os documentos são devolvidos. Os documentos podem ser ordenados por um campo num objeto Document. A expressão orderBy é sensível a maiúsculas e minúsculas. Se este campo for irreconhecível, é devolvido um INVALID_ARGUMENT.
    • SEARCH_RESULT_MODE: especifica o modo de resultado da pesquisa: DOCUMENTS ou CHUNKS. Para mais informações, consulte Analise e divida documentos em partes e ContentSearchSpec. Este campo só está disponível na versão v1alpha da API.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

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

    # Handle the response
    print(response)

    return response

Comandos da fase de resposta

Esta secção mostra como personalizar a chamada do método answer. Pode combinar as seguintes opções conforme necessário.

Ignore consultas adversariais e consultas que não procuram respostas

O comando seguinte mostra como evitar responder a consultas adversariais e consultas que não procuram respostas quando chama o método answer.

REST

Para ignorar respostas a consultas hostis ou que não procuram 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 o seguinte:

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

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

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

    # Handle the response
    print(response)

    return response

Mostrar apenas respostas relevantes

O Vertex AI Search pode avaliar a relevância dos resultados para uma consulta. Se não forem determinados resultados suficientemente relevantes, em vez de gerar uma resposta a partir de resultados não relevantes ou minimamente relevantes, pode optar por devolver uma resposta alternativa: "We do not have a summary for your query."

O comando seguinte mostra como devolver a resposta alternativa no caso de resultados irrelevantes quando chama o método answer.

REST

Para devolver uma resposta alternativa se não forem encontrados resultados relevantes, 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 o seguinte:

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

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

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

    # Handle the response
    print(response)

    return response

Devolva pontuações de apoio técnico de verificação

O comando seguinte mostra como devolver classificações de apoio de fundamentação para respostas e reivindicações.

Para obter informações gerais sobre a fundamentação no Vertex AI, consulte o artigo Verifique a fundamentação com a RAG. O método groundingConfigs.check é chamado pelo método answer.

REST

Para devolver uma pontuação de apoio para cada reivindicação (frase na resposta) e uma pontuação de apoio 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 o seguinte:

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

Mostrar apenas respostas bem fundamentadas

O comando seguinte mostra como devolver apenas as respostas consideradas bem fundamentadas no corpus, as informações no armazenamento de dados. As respostas com fundamentos fracos são filtradas.

Escolhe um limite de nível baixo ou elevado para a pontuação de apoio técnico de fundamentação. Em seguida, a resposta só é devolvida se atingir ou exceder esse nível. Pode fazer experiências com os dois limites dos filtros e sem limite para determinar que nível de filtro é provável que ofereça os melhores resultados aos seus utilizadores.

Para obter informações gerais sobre a fundamentação no Vertex AI, consulte o artigo Verifique a fundamentação com a RAG. O método groundingConfigs.check é chamado pelo método answer.

REST

Para devolver uma resposta apenas se esta atingir um limite de pontuação de apoio técnico, 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 o seguinte:

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

Especificar o modelo de resposta

O comando seguinte mostra como alterar a versão do modelo usada para gerar respostas.

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

REST

Para gerar uma resposta com um modelo diferente do modelo predefinido, 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 o seguinte:

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

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

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

    # Handle the response
    print(response)

    return response

Especifique um preâmbulo personalizado

O comando seguinte mostra como definir um preâmbulo para a resposta gerada. Um preâmbulo contém instruções de linguagem natural para personalizar a resposta. Pode pedir personalizações como a duração, o nível de detalhe, o estilo do resultado (como "simples"), o idioma do resultado, o foco da resposta e o formato (como tabelas, marcadores e XML). Por exemplo, um preâmbulo pode ser "Explica como se tivesses 10 anos".

O preâmbulo pode ter um efeito significativo na qualidade da resposta gerada. Para ver informações sobre o que escrever nos preâmbulos e exemplos de bons preâmbulos, consulte o artigo Acerca dos preâmbulos personalizados.

REST

Para gerar uma resposta com um modelo diferente do modelo predefinido, 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search que quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou a consulta de pesquisa.
    • PREAMBLE: uma instrução em linguagem natural para personalizar a resposta. Por exemplo, experimente 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 aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # 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 utilizadores podem escolher em vez de introduzirem as suas próprias perguntas. Por exemplo, quando pergunta "Qual é a melhor altura 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 pode fazer, como "Qual é o mês mais barato para passar férias no México?" e "Quais são os meses turísticos no México?".

Para receber perguntas relacionadas, tem de especificar a respetiva inclusão em cada consulta, e estas são devolvidas como uma matriz de strings na resposta.

Antes de começar

Certifique-se de que ativou as funcionalidades avançadas do MDG para a app.

Procedimento

O comando seguinte mostra como pedir que sejam incluídas perguntas relacionadas com a resposta.

REST

Para obter 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 o seguinte:

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

Inclua citações

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

REST

Para gerar uma resposta com um modelo diferente do modelo predefinido, 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search que quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou a consulta de pesquisa.
    • INCLUDE_CITATIONS: especifica se deve incluir metadados de citações na resposta. O valor predefinido é false.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

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

    # Handle the response
    print(response)

    return response

Defina o código do idioma de resposta

O comando seguinte mostra como definir o código do idioma para as respostas.

REST

Para gerar uma resposta com um modelo diferente do modelo predefinido, 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search que quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou a consulta de pesquisa.
    • ANSWER_LANGUAGE_CODE: um código de idioma para a resposta. Use etiquetas de idioma definidas pela norma BCP47: Etiquetas para identificar idiomas.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

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

    # Handle the response
    print(response)

    return response

Personalize respostas

Se existirem informações específicas sobre o utilizador disponíveis, por exemplo, dados num perfil, pode especificar essas informações no objeto endUserMetadata para que os resultados da consulta possam ser personalizados para o utilizador.

Por exemplo, se um utilizador com sessão iniciada estiver a pesquisar informações sobre a atualização de um telemóvel, as informações do respetivo perfil, como o modelo do telemóvel atual e o plano de rede móvel, fornecem informações que podem personalizar a resposta gerada.

Para adicionar informações pessoais sobre o utilizador que está a fazer uma consulta e gerar uma resposta que tenha em conta as informações pessoais, 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search que quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou a consulta de pesquisa.
    • PERSONALIZATION_INFO: uma string que contém informações específicas do utilizador que está a fazer 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 desta string é de 8000 carateres.
    • 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 esta descrição e as informações de personalização quando gera uma resposta personalizada à consulta.

Gere gráficos para respostas

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

Pode pedir especificamente que uma resposta inclua um gráfico, por exemplo, "Representa graficamente a taxa de crescimento anual dos pagamentos de pequenas empresas ao longo dos anos com dados disponíveis". Se o sistema determinar que existem dados suficientes, é devolvido um gráfico. Normalmente, é devolvido algum texto de resposta juntamente com o gráfico.

Além disso, se existirem dados suficientes para criar um gráfico, o método de resposta pode devolver um gráfico, mesmo que a consulta não tenha pedido explicitamente um gráfico. Por exemplo, "Qual foi a melhoria nas pontuações do IDH associada a um maior acesso a água potável limpa na década entre 2010 e 2020?"

Só é gerado um gráfico por resposta. No entanto, o gráfico pode ser um gráfico composto, que contém outros gráficos mais pequenos. Um exemplo de um gráfico composto:

O gráfico composto contém quatro gráficos mais pequenos

Limitação

As consultas têm de estar em inglês.

Cenários de falha comuns

Nem sempre recebe uma imagem com a resposta. Se não existirem dados suficientes, não é possível gerar uma figura.

Outros cenários de falha incluem falhas de execução de código e limites de tempo. Se ocorrer alguma destas situações, reformule a consulta e tente novamente.

Antes de começar

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

Procedimento

REST

Chame o método answer da seguinte forma para devolver uma resposta que pode incluir um gráfico gerado a partir dos dados no arquivo 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search que quer consultar.
    • QUERY: uma string de texto livre em inglês que contém a pergunta ou a consulta de pesquisa.
    • MODEL_VERSION: versão do modelo gemini-2.0-flash-001/answer_gen/v1 ou posterior. Para mais informações, consulte o artigo Ciclo de vida e versões do modelo de geração de respostas.
    • IMAGE_SOURCE: uma enumeração para pedir 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 das bases de dados, ALL_AVAILABLE_SOURCES.

Obtenha imagens existentes do repositório de dados

Pode optar por que as imagens do repositório de dados sejam devolvidas com a resposta e em referências de citação. O repositório de dados tem de ser um repositório de dados não estruturados com o analisador de esquemas ativado.

Para receber gráficos nas respostas devolvidas, tem de ativar as funcionalidades avançadas do MDG.

Quando imageSource é CORPUS_IMAGE_ONLY ou ALL_AVAILABLE_SOURCES, o método answer pode obter imagens do repositório de dados conforme adequado. No entanto, a ativação desta opção não significa que as imagens sejam sempre devolvidas.

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

Limitações

  • A app que está a usar tem de estar ligada a um repositório de dados não estruturados. Não é possível devolver imagens de Websites nem de armazenamentos de dados estruturados.

  • As consultas têm de estar em inglês.

  • A anotação de imagens através da análise sintática de esquemas tem de ser aplicada ao repositório de dados. Para obter informações sobre o analisador de esquemas, consulte o artigo Analise e divida documentos em partes.

Procedimento

REST

Chame o método answer da seguinte forma para devolver uma resposta que pode incluir uma imagem do arquivo de dados na resposta:

  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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search que quer consultar.
    • QUERY: uma string de texto livre em inglês que contém a pergunta ou a consulta de pesquisa.
    • MODEL_VERSION: versão do modelo gemini-2.0-flash-001/answer_gen/v1 ou posterior. Para mais informações, consulte o artigo Ciclo de vida e versões do modelo de geração de respostas.
    • IMAGE_SOURCE: uma enumeração para pedir 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 de seguimento

Os seguimentos são consultas de várias interações. Após a primeira consulta numa sessão de seguimento, as "interações" subsequentes têm em conta as interações anteriores. Com os seguimentos, o método de resposta também pode sugerir perguntas relacionadas, que os utilizadores podem escolher em vez de introduzir as suas próprias perguntas de seguimento. Para receber sugestões de perguntas relacionadas, tem de ativar as funcionalidades avançadas do MDG.

Todas as funcionalidades de resposta e seguimentos descritas nas secções anteriores, como citações, filtros, Pesquisa Segura, ignorar determinados tipos de consultas e usar um preâmbulo para personalizar as respostas, podem ser aplicadas juntamente com os seguimentos.

Exemplo de uma sessão de seguimento

Segue-se um exemplo de uma sessão com seguimentos. Suponhamos que quer saber mais sobre passar férias no México:

  • Turno 1:

    • Eu: qual é a melhor altura do ano para passar férias no México?

    • Responder com seguimentos: a melhor altura para passar férias no México é durante a estação seca, que decorre de novembro a abril.

  • Turn 2:

    • Eu: qual é a taxa de câmbio?

    • Responder com seguimentos: 1 USD é igual a aproximadamente 17,65 pesos mexicanos.

  • Turn 3:

    • Eu: qual é a temperatura média em dezembro?

    • Responder com seguimentos: a temperatura média varia entre 21 e 26 °C. A média de Cancún é de ~ 25 °C.

Sem seguimentos, a pergunta "Qual é a taxa de câmbio?" não teria resposta, porque a pesquisa normal não saberia que queria a taxa de câmbio mexicana. Da mesma forma, sem seguimentos, não haveria o contexto necessário para lhe dar temperaturas especificamente para o México.

Acerca das sessões

Para compreender como funcionam os seguimentos na Vertex AI Search, tem de saber mais sobre as sessões.

Uma sessão é composta por consultas de texto fornecidas por um utilizador e respostas fornecidas pelo Vertex AI Search.

Por vezes, estes pares de consultas e respostas são denominados interações. No exemplo anterior, a segunda interação é composta por "Qual é a taxa de câmbio?" e "1 USD é igual a aproximadamente 17,65 pesos mexicanos."

As sessões são armazenadas com a app. Na 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 curso ou concluído).

  • Um pseudo ID de utilizador, que é um ID de visitante que acompanha o utilizador. Pode ser atribuído de forma programática. Quando mapeado para o ID pseudonimizado do utilizador nos eventos do utilizador da sua app, o modelo pode ajudar a publicar resultados personalizados para o utilizador.

  • Uma hora de início e uma hora de fim.

  • Uma interação, que é um par de resposta a uma consulta.

Antes de começar

Antes de executar uma consulta que peça perguntas de seguimento, certifique-se de que ativou as funcionalidades avançadas de MDIs para a app.

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

Pode usar a linha de comandos para gerar respostas e respostas de pesquisa e armazená-las, juntamente com cada consulta numa sessão.

REST

Para usar a linha de comandos para criar uma sessão e gerar respostas a partir da entrada do utilizador, siga estes passos:

  1. Especifique a app onde 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .

    • APP_ID: o ID da app Vertex AI Search.

    • USER_PSEUDO_ID: uma string codificada em UTF-8 que funciona como um identificador pseudonimizado exclusivo que acompanha os utilizadores. Pode ter um comprimento máximo de 128 carateres. A Google recomenda vivamente a utilização deste campo porque melhora o desempenho do modelo e a qualidade da personalização. Pode usar um cookie HTTP para este campo, que identifica de forma exclusiva um visitante num único dispositivo. Seguem-se algumas considerações importantes:

      • Este identificador não se altera quando o visitante inicia ou termina sessão num Website.
      • Este campo não pode ser definido com o mesmo identificador para vários utilizadores. Caso contrário, o mesmo ID do utilizador pode combinar os históricos de eventos de diferentes utilizadores e degradar a qualidade do modelo.
      • Este campo não pode incluir informações de identificação pessoal (PII).
      • Para um determinado pedido de pesquisa ou navegação, este campo tem de ser mapeado para o campo userPseudoId correspondente nos eventos do utilizador.

      Para 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 resultado de exemplo, o ID é 5386462384953257772. Precisa deste ID no passo seguinte.

  3. Gerar uma resposta e adicioná-la a uma sessão na sua 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • QUERY: uma string de texto livre que contém a pergunta ou a consulta de pesquisa.
    • SESSION_ID: o ID da sessão que criou no passo 1. Estes são os dígitos no final do campo name:, indicados no passo 2. Para uma sessão, use o mesmo ID de sessão em cada interação.
    • FILTER: um campo de texto para filtrar a pesquisa através de uma expressão de filtro. O valor predefinido é uma string vazia. A forma como cria o filtro varia consoante tenha dados não estruturados com metadados, dados estruturados ou dados de Websites. Para mais informações, consulte Filtrar a pesquisa personalizada para dados estruturados ou não estruturados e Filtrar a pesquisa de Websites.

    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 o passo 3 para cada nova consulta na sessão.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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.SessionServiceClient()

    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

Obtenha uma sessão a partir do arquivo de dados

O comando seguinte mostra como chamar o método get e obter uma sessão da loja de dados.

REST

Para obter uma sessão de um arquivo 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • SESSION_ID: o ID da sessão que quer obter.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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.SessionServiceClient()

    # 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

Elimine uma sessão da app

O comando seguinte mostra como chamar o método delete e eliminar uma sessão da loja de dados.

Por predefinição, as sessões com mais de 60 dias são eliminadas automaticamente. No entanto, se quiser eliminar uma sessão específica, por exemplo, se contiver conteúdo sensível, use esta chamada API para a eliminar.

REST

Para eliminar uma sessão de uma 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • SESSION_ID: o ID da sessão que quer eliminar.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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.SessionServiceClient()

    # 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.")

Atualize uma sessão

Existem vários motivos pelos quais pode querer atualizar uma sessão. Por exemplo, para fazer uma das seguintes ações:

  • Marque uma sessão como concluída
  • Unir as mensagens de uma sessão noutra
  • Altere o ID pseudonimizado de um utilizador

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

REST

Para atualizar uma sessão a partir de uma 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • SESSION_ID: o ID da sessão que 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 aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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.SessionServiceClient()

    # 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

Apresentar todas as sessões

O comando seguinte mostra como chamar o método list e listar as sessões no arquivo de dados.

REST

Para listar as sessões de uma 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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.SessionServiceClient()

    # 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

Liste as sessões de um utilizador

O comando seguinte mostra como chamar o método list para listar as sessões associadas a um utilizador ou um visitante.

REST

Para listar as sessões associadas a um utilizador ou um 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • USER_PSEUDO_ID: o ID pseudonimizado do utilizador cujas sessões quer listar.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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.SessionServiceClient()

    # 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

Liste as sessões de um utilizador e um estado

O comando seguinte mostra como chamar o método list para listar sessões num determinado estado para um utilizador específico.

REST

Para listar as sessões de um utilizador que estão abertas ou fechadas e associadas a um determinado utilizador 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%20AND%20state=STATE"

    Substitua o seguinte:

    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • USER_PSEUDO_ID: o ID pseudonimizado do utilizador cujas sessões 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 aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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.SessionServiceClient()

    # 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