Melhorar os resultados da pesquisa com o ajuste de pesquisa

Um modelo de pesquisa ajustado pode oferecer resultados de melhor qualidade do que o modelo de pesquisa de base.

O ajuste de pesquisa é particularmente valioso se você tiver consultas específicas do setor ou da empresa que não são bem resolvidas por LLMs gerais. Ele pode ser usado para treinar o modelo de pesquisa.

Limitações

O ajuste de pesquisa só pode ser aplicado a repositórios de dados não estruturados.

Sobre os dados de treinamento

Para ajustar um modelo de pesquisa, comece reunindo dados de treinamento.

Os dados de treinamento precisam conter consultas que você espera que os usuários finais façam e snippets de texto com 250 a 500 palavras, que contenham informações relevantes necessárias para responder às consultas. Uma consulta pode ser associada a vários snippets, desde que cada um deles tenha informações que respondam à consulta.

Os dados de treinamento também precisam conter trechos de texto que não são associados a consultas, mas são semelhantes às respostas em estilo e comprimento. Esses snippets sem consultas associadas fornecem negativos aleatórios para ajustar o modelo. O Google recomenda que você forneça pelo menos 10.000 desses trechos.

Confira alguns termos para descrever os dados de treinamento que você vai precisar fornecer:

• Consultas de treinamento:consultas que você espera que os usuários finais façam. Concentre-se em consultas com terminologia específica do domínio ou da empresa.

  Informe pelo menos 100.

• Segmentos extrativos:os snippets (geralmente vários parágrafos) precisam ser extraídos literalmente dos documentos no repositório de dados. Todos os documentos juntos no repositório de dados são chamados de "corpus".

  Você precisa fornecer dois tipos de segmentos extrativos:

  • Segmentos que contêm informações relevantes necessárias para responder às consultas de treinamento. São segmentos que têm correspondência positiva com consultas.

  • Segmentos não associados a consultas de treinamento. Esses segmentos são usados como negativos aleatórios no ajuste do modelo.

  Uma ou duas frases não são longas o suficiente para serem um segmento de extração. O segmento precisa conter contexto suficiente para o treinamento. Por exemplo, em resposta a uma consulta como "quem fundou o Google", um extrato curto como "Larry Page" é insuficiente. Para exemplos de segmentos suficientemente longos, consulte a tabela de exemplos a seguir.

  Forneça pelo menos um segmento de extração por consulta e pelo menos 10.000 segmentos de extração adicionais.

• Pontuações de relevância:são números inteiros não negativos que estimam a relevância do segmento de extração para a consulta. Você fornece um valor de pontuação para cada par de consulta e segmento de extração. Uma pontuação de 0 significa que o segmento de extração não é relevante para a consulta. Uma pontuação maior que zero indica alguma relevância. Para uma pontuação simples, o Google recomenda 1 para todos os segmentos relevantes e 0 para os não relevantes. Como alternativa, se você quiser classificar a relevância, atribua pontuações de 0 a 10 (por exemplo), sendo 10 para os segmentos mais relevantes e 0 para os que não são relevantes.

  Forneça pelo menos 100 notas relevantes e, se quiser, outras notas não relevantes.

Exemplos de pares de consultas e segmentos extrativos

A tabela a seguir mostra alguns exemplos de pares de consulta e segmento extrativo. Esses exemplos gerais foram retirados da Wikipedia. No entanto, para uma otimização útil, forneça documentos de conjuntos de dados proprietários que contenham informações específicas da sua empresa e que sejam menos fáceis de encontrar na Web.

O último par nesta tabela é um exemplo de um par com pontuação zero, em que a resposta não é relevante para a consulta.

Consulta de treinamento	Segmento extrativo	Pontuação
quem fundou o Google?	O Google foi fundado em 4 de setembro de 1998 por cientistas da computação americanos, Larry Page e Sergey Brin, quando eles eram estudantes de doutorado na Universidade de Stanford na Califórnia.Juntos, eles são proprietários de cerca de 14% das ações listadas publicamente e controlam 56% do poder de voto dos acionistas por meio de ações com supervoto. A empresa abriu o capital em 2004 com uma oferta pública inicial (IPO). Em 2015, o Google foi reorganizado como uma subsidiária integral da Alphabet Inc. O Google é a maior subsidiária da Alphabet e é uma holding das propriedades e interesses da Alphabet na Internet. Sundar Pichai foi nomeado CEO do Google em 24 de outubro de 2015, substituindo Larry Page, que se tornou CEO da Alphabet. Em 3 de dezembro de 2019, Pichai também se tornou o CEO da Alphabet. [...] Na lista das marcas mais valiosas, o Google está em segundo lugar na Forbes e em quarto lugar na Interbrand.	1
Para onde o sangue é bombeado depois de sair do ventrículo direito?	O sangue oxigenado sai dos pulmões pelas veias pulmonares, que o devolvem à parte esquerda do coração, completando o ciclo pulmonar. Esse sangue então entra no átrio esquerdo, que o bombeia pela válvula mitral para o ventrículo esquerdo. Do ventrículo esquerdo, o sangue passa pela válvula aórtica para a aorta. O sangue é distribuído para o corpo pela circulação sistêmica antes de retornar à circulação pulmonar. Artérias Principal artigo: artéria pulmonar Do ventrículo direito, o sangue é bombeado pela válvula pulmonar semilunar para a artéria pulmonar principal esquerda e direita (uma para cada pulmão), que se ramificam em artérias pulmonares menores que se espalham pelos pulmões. [...] O desvio cardíaco é uma conexão não natural entre partes do coração que leva ao fluxo sanguíneo que contorna os pulmões.	1
Onde fica o Hall da Fama do Boliche?	O World Bowling Writers ( WBW ) International Bowling Hall of Fame foi criado em 1993 e está localizado no International Bowling Museum and Hall of Fame , no International Bowling Campus em Arlington, Texas. História O International Bowling Museum and Hall of Fame ficava em 11 Stadium Plaza, St. Louis, Missouri, EUA, e dividia o mesmo edifício com o St. Louis Cardinals Hall of Fame Museum, até 8 de novembro de 2008. Ele se mudou para Arlington e reabriu no início de 2010. Em 2012, a WBW foi incorporada à International Bowling Media Association. Após a fusão, os membros do WBW Hall of Fame passaram a fazer parte do IBMA Luby Hall of Fame. oficiais da World Bowling Writers, que formaram o Hall's Board.][...] O homem e a mulher que recebem mais votos são eleitos.	1
por que o céu é azul?	Um programa "Hello, World!" geralmente é um programa de computador simples que exibe na tela (geralmente no console) uma mensagem semelhante a "Hello, World!", ignorando qualquer entrada do usuário. Um pequeno trecho de código na maioria das linguagens de programação de uso geral, esse programa é usado para ilustrar a sintaxe básica de uma linguagem. Um programa "Hello, World!" geralmente é o primeiro escrito por um estudante de uma nova linguagem de programação, mas esse programa também pode ser usado como uma verificação para garantir que o software do computador destinado a compilar ou executar o código-fonte esteja instalado corretamente e que o operador entenda como usá-lo. [...] A versão da linguagem C foi precedida pelo próprio Tutorial de Introdução à Linguagem B de Kernighan, de 1972, em que a primeira versão conhecida do programa é encontrada em um exemplo usado para ilustrar variáveis externas.	0

Sobre os testes

Após o treinamento, a pesquisa ajustada é testada para determinar se o ajuste melhorou os resultados. Você pode fornecer explicitamente as consultas que quer testar. Se você não fornecer consultas de teste, a Pesquisa da Vertex AI vai usar 20% das consultas de treinamento como consultas de teste.

Arquivos de treinamento

Os dados de treinamento precisam ser enviados em três (ou quatro) arquivos específicos:

• Um arquivo de corpus que contém os segmentos extraídos

• Um arquivo de consulta que contém apenas as consultas

• Um arquivo de rótulos de treinamento que conecta consultas a segmentos e contém as pontuações de relevância

• Opcional: um arquivo de rótulos de teste semelhante aos arquivos de rótulos de treinamento, mas usado para avaliar o modelo ajustado em vez de treiná-lo.

Os três arquivos de treinamento (arquivo de corpus, arquivo de consulta e arquivo de rótulos de treinamento) e o arquivo de rótulos de teste (opcional) precisam estar no Cloud Storage. Os caminhos dos arquivos são definidos por campos na chamada trainCustomMethod.

Arquivo do corpus

O arquivo de corpus contém segmentos extrativos: segmentos que contêm informações para responder às consultas no arquivo de consulta e muitos outros segmentos para serem usados como negativos aleatórios ao ajustar o modelo. Você precisa ter pelo menos 100 segmentos que contenham respostas de consulta. As consultas podem ser respondidas por vários segmentos. Você também precisa ter pelo menos 10.000 segmentos aleatórios.

Se os documentos no repositório de dados tiverem menos de 500 palavras, você poderá usar documentos inteiros como segmentos. Caso contrário, crie segmentos aleatórios de 250 a 500 palavras dos documentos no repositório de dados e os adicione ao arquivo de corpus.

O arquivo de corpus é um arquivo JSONL (linhas JSON), em que cada linha tem os campos _id e text com valores de string. Exemplo:

  {"_id": "doc1", "text": "Google was founded on September 4, 1998, by American computer scientists Larry Page and Sergey Brin while they were PhD students at Stanford University in California. Together they own about 14% of its publicly listed shares and control 56% of its stockholder voting power through super-voting stock. The company went public via an initial public offering (IPO) in 2004. In 2015, Google was reorganized as a wholly owned subsidiary of Alphabet Inc. Google is Alphabet's largest subsidiary and is a holding company for Alphabet's internet properties and interests. Sundar Pichai was appointed CEO of Google on October 24, 2015, replacing Larry Page, who became the CEO of Alphabet. On December 3, 2019, Pichai also became the CEO of Alphabet. [...] On the list of most valuable brands, Google is 105 ranked second by Forbes and fourth by Interbrand."}
  {"_id": "doc2", "text": "Oxygenated blood leaves the lungs through pulmonary veins, which return it to the left part of the heart, completing the pulmonary cycle. This blood then enters the left atrium, which pumps it through the mitral valve into the left ventricle. From the left ventricle, the blood passes through the aortic valve to the aorta. The blood is then distributed to the body through the systemic circulation before returning again to the pulmonary circulation. Arteries Main article: Pulmonary artery From the right ventricle, blood is pumped through the semilunar pulmonary valve into the left and right main pulmonary artery (one for each lung), which branch into smaller pulmonary arteries that spread throughout the lungs. [...] Cardiac shunt is an unnatural connection between parts of the heart that leads to blood flow that bypasses the lungs."}
  {"_id": "doc3", "text": "The World Bowling Writers ( WBW ) International Bowling Hall of Fame was established in 1993 and is located in the International Bowling Museum and Hall of Fame , on the International Bowling Campus in Arlington , Texas. History The International Bowling Museum and Hall of Fame was located at 11 Stadium Plaza, St. Louis, Missouri, USA, and shared the same building with the St. Louis Cardinals Hall of Fame Museum, until November 8, 2008. It moved to Arlington and reopened in early 2010. In 2012, the WBW was merged with the International Bowling Media Association. After the merger, the WBW Hall of Fame inductees became part of the IBMA Luby Hall of Fame.  officers of the World Bowling Writers, which formed the Hall's Board.][...] The man and woman who receive the most votes are elected."}
  {"_id": "doc4", "text": "A \"Hello, World!\" program is generally a simple computer program which outputs (or displays) to the screen (often the console) a message similar to "Hello, World!" while ignoring any user input. A small piece of code in most general-purpose programming languages, this program is used to illustrate a language's basic syntax. A "Hello, World!" program is often the first written by a student of a new programming language, but such a program can also be used as a check to ensure that the computer software intended to compile or run source code is correctly installed, and that its operator understands how to use it.  [...] The C-language version was preceded by Kernighan's own 1972 A Tutorial Introduction to the Language B, where the first known version of the program is found in an example used to illustrate external variables."}

O tamanho máximo do arquivo é de 500.000 linhas.

Arquivo de consulta

O arquivo de consulta contém os exemplos de consultas que serão usados para ajustar o modelo. Cada consulta precisa ter um ou mais segmentos extrativos correspondentes no arquivo do corpus. É necessário fornecer pelo menos 100 consultas de correspondência positiva. Você também pode fornecer consultas não relevantes, que correspondem a segmentos extrativos com uma pontuação de relevância de zero.

O arquivo de consulta está no formato JSONL e tem os mesmos campos que o arquivo de corpus.

Exemplo:

  {"_id": "query1", "text": "who founded Google?"}
  {"_id": "query2", "text": "where is blood pumped after it leaves the right ventricle?"}
  {"_id": "query3", "text": "where is the bowling hall of fame located?"}
  {"_id": "query4", "text": "why is the sky blue?"}

O número máximo de consultas permitidas no arquivo é 40.000.

Rótulos de treinamento

O arquivo de rótulos de treinamento conecta as consultas aos segmentos de extração e classifica cada par de consulta e segmento.

Se o arquivo de rótulos de teste não estiver presente, 20% das consultas no arquivo de rótulos de treinamento serão reservadas para avaliar o modelo ajustado após o treinamento.

O arquivo contém o ID de uma consulta e o ID do segmento de extração correspondente (ou não correspondente) e uma pontuação para a relevância do segmento para a consulta. É necessário ter pelo menos uma linha por consulta. Se uma consulta for respondida por dois segmentos, haverá duas linhas para essa consulta. Score é um valor inteiro não negativo. Qualquer pontuação maior que zero indica que o documento está relacionado à consulta. Números maiores indicam um nível maior de relevância. Se a pontuação for omitida, o valor padrão será 1.

O arquivo de rótulos de treinamento é um arquivo TSV (valores separados por tabulação) com um cabeçalho. O arquivo precisa ter as colunas query-id, corpus-id e score. O query-id é uma string que corresponde à chave _id do arquivo de consulta, e o corpus-id é uma string que corresponde a _id no arquivo de corpus.

Exemplo:

query-id    corpus-id   score
query1  doc1    1
query2  doc2    1
query3  doc3    1
query3  doc9    1
query4  doc4    0

Observação: verifique se os separadores no arquivo são caracteres de tabulação (\t). Alguns navegadores e editores de texto podem substituir guias por uma sequência de espaços.

O arquivo de rótulos de treinamento precisa incluir pelo menos 100 IDs de consulta exclusivos. O número de IDs de consulta no arquivo de rótulos de treinamento combinado com o número de consultas no arquivo de rótulos de teste precisa ser menor que 500.000.

Rótulos de teste

Assim como o arquivo de rótulos de treinamento, esse arquivo opcional contém os IDs da consulta e do segmento de extração e as pontuações de relevância. Ele contém menos consultas e diferentes do arquivo de rótulos de treinamento. Se presentes, os pares de consulta e segmento extrativo no arquivo são usados para avaliar o ajuste. Se o arquivo de rótulos de teste não estiver presente, os pares de segmentos de consulta e extração do arquivo de rótulos de treinamento serão usados para avaliação.

Esse arquivo tem o mesmo formato do arquivo de rótulos de treinamento.

Exemplo:

query-id    corpus-id   score
query200    doc200  1
query201    doc201  1
query202    doc202  1

Embora o arquivo de rótulos de teste seja opcional, se você o enviar, ele precisa conter pelo menos três IDs de consulta exclusivos.

Antes de começar

Ative os recursos da edição Enterprise no app.

Ajustar a pesquisa

Para ajustar um modelo de pesquisa com seus próprios dados de treinamento, siga estas etapas.

Observação: para repositórios de dados grandes, o ajuste da pesquisa pode levar alguns dias.

Console

Para usar o console do Google Cloud para ajustar um modelo, siga estas etapas:

1. Prepare os dados de treinamento e, opcionalmente, os arquivos de dados de teste. Use os formatos descritos em Arquivos de treinamento.

2. Faça upload dos arquivos para o Cloud Storage.

3. No Console do Google Cloud, acesse a página Criador de agentes.

   Agent Builder.

4. Na página Apps, clique no nome do app para o qual você quer um modelo treinado.

5. No menu de navegação, clique em Configurações.

6. Clique na guia Ajuste.

7. Clique em Ajustar o modelo base.

8. Especifique os arquivos de corpus, consulta, treinamento e, opcionalmente, de teste que você preparou nas etapas 1 e 2 anteriores.

9. Clique em Iniciar ajuste.

10. Atualize a página para conferir o status na tabela Atividade de ajuste recente na guia Ajuste.

REST

Para usar o método trainCustomModel para ajustar um repositório de dados, siga estas etapas:

1. Prepare os arquivos de dados de treinamento (e, opcionalmente, de teste). Use os formatos descritos em Arquivos de treinamento.

2. Coloque os arquivos em um bucket do Cloud Storage.

3. Faça o upload dos arquivos do bucket do Cloud Storage para a Vertex AI Search executando o comando curl a seguir:

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID:trainCustomModel" \
   -d '{
   "gcsTrainingInput": {
    "corpusDataPath": "CORPUS_JSONL_GCS_PATH",
    "queryDataPath": "QUERY_JSONL_GCS_PATH",
    "trainDataPath": "TRAIN_TSV_GCS_PATH",
    "testDataPath": "TEST_TSV_GCS_PATH"
   },
   "modelType": "search-tuning"
   }'
   

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.

   • DATA_STORE_ID: o ID do repositório de dados que você quer ajustar.

   • CORPUS_JSONL_GCS_PATH: o caminho do arquivo JSONL do corpus no Cloud Storage, por exemplo, gs://my-bucket/corpus.jsonl.

   • QUERY_JSONL_GCS_PATH: o caminho do arquivo JSONL de consulta no Cloud Storage, por exemplo, gs://my-bucket/query.jsonl.

   • TRAIN_TSV_GCS_PATH: o caminho do arquivo TSV de rótulos de treinamento no Cloud Storage, por exemplo, gs://my-bucket/train.tsv.

   • TEST_TSV_GCS_PATH: um campo opcional para especificar o caminho do Cloud Storage para o arquivo TSV de rótulos de teste, por exemplo, gs://my-bucket/test.tsv. Se você não tiver um arquivo de rótulos de teste, remova o campo testDataPath ou deixe-o em branco.

   Para informações gerais sobre esse método, consulte trainCustomModel.

   O ajuste começa automaticamente após o upload dos arquivos de dados.

   Clique para conferir um exemplo de comando e resposta do curl.

   curl -X POST
   -H "Authorization: Bearer $(gcloud auth print-access-token)"
   -H "Content-Type: application/json"
   "https://discoveryengine.googleapis.com/v1/projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321:trainCustomModel"
   -d '{
   "dataStore":
   "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321",
   "gcsTrainingInput": {
   "corpusDataPath": "gs://my-bucket/corpus.jsonl",
   "queryDataPath": "gs://my-bucket/query.jsonl",
   "trainDataPath": "gs://my-bucket/train.tsv"
   },
   "modelType": "search-tuning"
   }

   {
     "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-data-store_4321/operations/train-custom-model-6071430366161939774",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.TrainCustomModelMetadata"
     },
     "response": {
       "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.TrainCustomModelResponse",
       "modelStatus": "in-progress"
     }
   }

4. Anote o valor name retornado pelo método trainCustomModel e siga as instruções em Conferir detalhes sobre uma operação de longa duração para saber quando a operação de ajuste de pesquisa for concluída.

Python

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

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

from google.api_core.client_options import ClientOptions
from google.api_core.operation import Operation
from google.cloud import discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION" # Values: "global"
# data_store_id = "YOUR_DATA_STORE_ID"
# corpus_data_path = "gs://my-bucket/corpus.jsonl"
# query_data_path = "gs://my-bucket/query.jsonl"
# train_data_path = "gs://my-bucket/train.tsv"
# test_data_path = "gs://my-bucket/test.tsv"


def train_custom_model_sample(
    project_id: str,
    location: str,
    data_store_id: str,
    corpus_data_path: str,
    query_data_path: str,
    train_data_path: str,
    test_data_path: str,
) -> Operation:
    #  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.SearchTuningServiceClient(client_options=client_options)

    # The full resource name of the data store
    data_store = f"projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{data_store_id}"

    # Make the request
    operation = client.train_custom_model(
        request=discoveryengine.TrainCustomModelRequest(
            gcs_training_input=discoveryengine.TrainCustomModelRequest.GcsTrainingInput(
                corpus_data_path=corpus_data_path,
                query_data_path=query_data_path,
                train_data_path=train_data_path,
                test_data_path=test_data_path,
            ),
            data_store=data_store,
            model_type="search-tuning",
        )
    )

    # Optional: Wait for training to complete
    # print(f"Waiting for operation to complete: {operation.operation.name}")
    # response = operation.result()

    # After the operation is complete,
    # get information from operation metadata
    # metadata = discoveryengine.TrainCustomModelMetadata(operation.metadata)

    # Handle the response
    # print(response)
    # print(metadata)
    print(operation)

    return operation

Testar a pesquisa otimizada e usá-la para consultas de pesquisa individuais

Depois que o ajuste for concluído, você poderá testá-lo comparando os resultados das consultas com o modelo ajustado e os resultados das mesmas consultas com o modelo de base.

Console

Para usar o console do Google Cloud e conferir o comportamento de um modelo ajustado, siga estas etapas:

1. Acesse a guia Ajuste:

   1. No Console do Google Cloud, acesse a página Criador de agentes.

      Agent Builder.

   2. Clique no nome do app que você quer visualizar.

   3. Clique em Configurations.

   4. Clique na guia Ajuste.

2. Clique em Modelo ajustado e use o painel de visualização à direita para fazer consultas que usem o modelo ajustado.

3. Clique em Modelo base e use o painel de visualização à direita para fazer consultas usando o modelo original.

4. Compare a qualidade dos resultados.

REST

Para avaliar o efeito do ajuste, faça consultas com o campo enableSearchAdaptor definido como true e false e compare os resultados. Definir o campo enableSearchAdaptor como true indica que a versão ajustada da pesquisa é usada para essa consulta.

Para fazer consultas de pesquisa que usam o modelo ajustado:

1. Na chamada do método de consulta, defina o campo enableSearchAdaptor no campo customFineTuningSpec como true.

   Exemplo:

   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:search" \
   -d '{
   "query": "QUERY",
   "customFineTuningSpec": { "enableSearchAdaptor": true }
   }'
   

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • APP_ID: o ID do app que você quer consultar.

Para informações detalhadas sobre consultas de pesquisa, consulte Receber resultados de pesquisa e o método servingConfigs.search.

Python

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

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

from 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"
# search_query = "YOUR_SEARCH_QUERY"


def search_sample(
    project_id: str,
    location: str,
    engine_id: str,
    search_query: str,
) -> discoveryengine.services.search_service.pagers.SearchPager:
    #  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.SearchServiceClient(client_options=client_options)

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

    # Optional - only supported for unstructured data: Configuration options for search.
    # Refer to the `ContentSearchSpec` reference for all supported fields:
    # https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest.ContentSearchSpec
    content_search_spec = discoveryengine.SearchRequest.ContentSearchSpec(
        # For information about snippets, refer to:
        # https://cloud.google.com/generative-ai-app-builder/docs/snippets
        snippet_spec=discoveryengine.SearchRequest.ContentSearchSpec.SnippetSpec(
            return_snippet=True
        ),
        # For information about search summaries, refer to:
        # https://cloud.google.com/generative-ai-app-builder/docs/get-search-summaries
        summary_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec(
            summary_result_count=5,
            include_citations=True,
            ignore_adversarial_query=True,
            ignore_non_summary_seeking_query=True,
            model_prompt_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec.ModelPromptSpec(
                preamble="YOUR_CUSTOM_PROMPT"
            ),
            model_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec.ModelSpec(
                version="stable",
            ),
        ),
    )

    # Refer to the `SearchRequest` reference for all supported fields:
    # https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest
    request = discoveryengine.SearchRequest(
        serving_config=serving_config,
        query=search_query,
        page_size=10,
        content_search_spec=content_search_spec,
        query_expansion_spec=discoveryengine.SearchRequest.QueryExpansionSpec(
            condition=discoveryengine.SearchRequest.QueryExpansionSpec.Condition.AUTO,
        ),
        spell_correction_spec=discoveryengine.SearchRequest.SpellCorrectionSpec(
            mode=discoveryengine.SearchRequest.SpellCorrectionSpec.Mode.AUTO
        ),
        # Optional: Use fine-tuned model for this request
        # custom_fine_tuning_spec=discoveryengine.CustomFineTuningSpec(
        #     enable_search_adaptor=True
        # ),
    )

    page_result = client.search(request)

    # Handle the response
    for response in page_result:
        print(response)

    return page_result

Ativar a pesquisa personalizada

Depois de testar a pesquisa ajustada e decidir que você quer usá-la em todas as consultas de pesquisa, é possível torná-la o modelo de pesquisa padrão.

Console

Para tornar o modelo ajustado o padrão e aplicá-lo à página de visualização principal, ao widget e às chamadas de API, siga estas etapas:

1. Acesse a guia Ajuste:

   1. No Console do Google Cloud, acesse a página Criador de agentes.

      Agent Builder.

   2. Clique no nome do app.

   3. Clique em Configurations.

   4. Clique na guia Ajuste.

2. Clique em Modelo ajustado.

3. Clique em Publicar.

REST

Ao definir o modelo ajustado como padrão, não é necessário especificar o campo customFineTuningSpec na consulta de pesquisa, como no procedimento anterior.

Para usar a versão ajustada da pesquisa por padrão em todas as consultas de pesquisa, siga estas etapas:

1. Para definir a pesquisa ajustada como o modelo padrão, execute o seguinte comando curl:

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?updateMask=customFineTuningSpec.enableSearchAdaptor" \
   -d '{
   "customFineTuningSpec": {
    "enableSearchAdaptor": true
   }
   }'
   

   Para informações gerais sobre esse método, consulte servingConfigs.patch.

Python

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

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

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

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION" # Values: "global"
# engine_id = "YOUR_DATA_STORE_ID"


def update_serving_config_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ServingConfig:
    #  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.ServingConfigServiceClient(client_options=client_options)

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

    update_mask = "customFineTuningSpec.enableSearchAdaptor"

    serving_config = client.update_serving_config(
        request=discoveryengine.UpdateServingConfigRequest(
            serving_config=discoveryengine.ServingConfig(
                name=serving_config_name,
                custom_fine_tuning_spec=discoveryengine.CustomFineTuningSpec(
                    enable_search_adaptor=True  # Switch to `False` to disable tuned model
                ),
            ),
            update_mask=update_mask,
        )
    )

    # Handle the response
    print(serving_config)

    return serving_config

Desativar a pesquisa personalizada

Se você não quiser mais usar a versão ajustada da pesquisa, por exemplo, se os resultados não forem melhores ou piores do que antes da otimização, você pode desativar a pesquisa ajustada.

Console

Para reverter para o modelo base como padrão, siga estas etapas:

1. Acesse a guia Ajuste:

   1. No Console do Google Cloud, acesse a página Criador de agentes.

      Agent Builder.

   2. Clique no nome do app.

   3. Clique em Configurations.

   4. Clique na guia Ajuste.

2. Clique em Modelo base.

3. Clique em Publicar.

REST

Para parar de usar o modelo ajustado, execute uma chamada curl semelhante à anterior, mas defina enableSearchAdaptor como false:

1. Execute o seguinte comando curl:

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?updateMask=customFineTuningSpec.enableSearchAdaptor" \
   -d '{
   "customFineTuningSpec": {
    "enableSearchAdaptor": false
   }
   }'
   

   Para informações gerais sobre esse método, consulte servingConfigs.patch.

Python

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

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

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

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION" # Values: "global"
# engine_id = "YOUR_DATA_STORE_ID"


def update_serving_config_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ServingConfig:
    #  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.ServingConfigServiceClient(client_options=client_options)

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

    update_mask = "customFineTuningSpec.enableSearchAdaptor"

    serving_config = client.update_serving_config(
        request=discoveryengine.UpdateServingConfigRequest(
            serving_config=discoveryengine.ServingConfig(
                name=serving_config_name,
                custom_fine_tuning_spec=discoveryengine.CustomFineTuningSpec(
                    enable_search_adaptor=True  # Switch to `False` to disable tuned model
                ),
            ),
            update_mask=update_mask,
        )
    )

    # Handle the response
    print(serving_config)

    return serving_config

A seguir

• Para entender o impacto do ajuste de pesquisa na qualidade da pesquisa, avalie a qualidade da pesquisa. Para mais informações, consulte Avaliar a qualidade da pesquisa.