Embasamento com a API de pesquisa

Você pode conectar o Gemini às suas fontes de dados externas usando a API Search. Assim, você pode usar qualquer serviço de pesquisa como fonte de embasamento para o Gemini, o que ajuda a garantir que as respostas sejam baseadas nas informações mais recentes e relevantes dos seus sistemas. Isso é especialmente útil para dados específicos da empresa que não estão disponíveis publicamente.

Nesta página, explicamos como configurar e usar o embasamento com qualquer API de pesquisa e o Gemini.

Como o embasamento com sua API Search funciona

Quando você faz o embasamento com sua API de pesquisa, o Gemini pode consultar um endpoint de API externa que você fornece. Assim, o Gemini pode usar sua funcionalidade de pesquisa personalizada como uma ferramenta para melhorar as respostas. Ele permite interações mais dinâmicas e contextualizadas, já que o modelo pode buscar informações nas fontes de dados especificadas quando necessário.

Durante uma solicitação de geração, o Gemini pode fazer uma chamada para o endpoint de API externa com uma consulta de pesquisa. Em seguida, sua API vai retornar snippets de dados relevantes. O Gemini usa esses snippets como uma fonte de verdade para gerar uma resposta mais precisa e embasada.

É possível combinar o embasamento usando sua API de pesquisa com outras fontes, como a Pesquisa Google. Uma solicitação de geração aceita até 10 fontes de embasamento e consultas com várias ferramentas em que o Gemini pode aproveitar diferentes fontes de informação para gerar a melhor resposta possível.

Modelos compatíveis

Os seguintes modelos são compatíveis com o embasamento usando sua API:

• Vertex AI Model Optimizer
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

Para mais informações, consulte Modelos do Gemini.

Antes de começar

Para usar o embasamento com a API Search, faça o seguinte:

1. Verifique se a API Vertex AI está ativada no seu projeto Google Cloud.
2. Se você planeja seguir o guia de configuração detalhado para criar um novo endpoint de API Search, verifique se a Google Cloud CLI está instalada e inicializada.

Requisitos da API Search

Para usar sua infraestrutura de pesquisa atual com o Gemini, o endpoint de API precisa atender aos seguintes requisitos:

Esquema da API

• Método HTTP: POST

• Corpo da solicitação (do Gemini para sua API):

  {
    "query": "the user's search query string"
  }
  

• Corpo da resposta (da sua API para o Gemini): uma matriz JSON de objetos. Cada objeto representa um resultado da pesquisa e precisa conter os campos "snippet" e "uri".

  [
    {
      "snippet": "A text snippet containing the answer or relevant information.",
      "uri": "A URI/URL linking to the source of the information, or a relevant identifier."
    },
    {
      "snippet": "Another piece of information.",
      "uri": "https://example.com/another-source"
    }
  ]
  

Se nenhum resultado for encontrado, o endpoint de API vai retornar uma matriz vazia.

Autenticação

O embasamento com sua API de pesquisa é compatível com o uso da chave de API, que protege o endpoint de API. O Gemini envia essa chave de API como um parâmetro de consulta chamado key.

Usar o embasamento com sua API de pesquisa e um endpoint compatível

Se você já tiver um endpoint de API que atenda aos requisitos de esquema e autenticação, poderá configurá-lo diretamente nas chamadas da API Gemini.

Configurar a ferramenta externalApi

Ao fazer uma solicitação para a API Gemini, inclua o parâmetro "tools" com uma ferramenta de recuperação configurada para o externalApi. Os campos principais incluem:

• api_spec: "SIMPLE_SEARCH": informa ao Gemini para usar o esquema de entrada e saída predefinido.
• endpoint: o URL completo do endpoint do API Gateway, como https://YOUR_GATEWAY_HOSTNAME/v0/search.

• apiAuth.apiKeyConfig.apiKeyString: a chave de API que o Gemini usa para autenticar com sua API. O Gemini anexa essa chave como ?key=<YOUR_API_KEY> ao URL do endpoint.

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

  {
  "contents": [{
      "role": "user",
      "parts": [{
          "text": "USER_PROMPT"
      }]
  }],
  "tools": [{
      "retrieval": {
        "externalApi": {
          "api_spec": "SIMPLE_SEARCH",
          "endpoint": "EXTERNAL_API_ENDPOINT",
          "apiAuth": {
            "apiKeyConfig": {
              "apiKeyString": "EXTERNAL_API_KEY"
            }
          }
        }
      }
  }]
}

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "You can make an appointment on the website https://dmv.gov/"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        "..."
      ],
      "groundingMetadata": {
        "retrievalQueries": [
          "How to make appointment to renew driving license?"
        ],
        "groundingChunks": [
          {
            "retrievedContext": {
              "uri": "https://...",
              "snippet": "Snippet text about driving license renewal"
            }
          }
        ],
        "groundingSupport": [
          {
            "segment": {
              "startIndex": 25,
              "endIndex": 147
            },
            "segment_text": "ipsum lorem ...",
            "supportChunkIndices": [1, 2],
            "confidenceScore": [0.9541752, 0.97726375]
          },
          {
            "segment": {
              "startIndex": 294,
              "endIndex": 439
            },
            "segment_text": "ipsum lorem ...",
            "supportChunkIndices": [1],
            "confidenceScore": [0.9541752, 0.9325467]
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "..."
  }
}

Configurar um endpoint de API de pesquisa

Se você não tiver um endpoint de API que atenda aos requisitos, esta seção vai orientar você na configuração de um usando o Cloud Functions e o API Gateway.

Criar seu wrapper de API externa com o Cloud Functions

Uma função do Cloud pode atuar como um intermediário que recebe consultas do Gemini, emite consultas adequadas para sua infraestrutura de pesquisa atual, como um banco de dados, um mecanismo de pesquisa interno ou uma pesquisa vetorial, e formata os resultados no esquema que o Gemini entende.

Para mais informações, consulte a documentação das funções do Cloud Run.

Exemplo de configuração de função do Cloud (Python)

Este exemplo usa uma lista de produtos codificada para demonstração. Você vai precisar substituir a lógica de recuperação de dados por chamadas ao seu sistema de pesquisa real.

1. main.py

   import functions_framework
   import json
   from flask import jsonify
   
   @functions_framework.http
   def custom_search_wrapper_minimal(request):
       """
       HTTP Cloud Function to provide a minimal, fixed response for Gemini grounding.
       """
       if request.method != 'POST':
           return 'Only POST requests are accepted', 405
   
       request_json = request.get_json(silent=True)
   
       if not request_json or 'query' not in request_json:
           return jsonify({"error": "Invalid request. JSON body with 'query' field is required."}), 400
   
       user_query = request_json['query']
       print(f"Received query: '{user_query}'. Responding with fixed data.")
   
       # --- FIXED RESPONSE ---
       # This is a hardcoded response. In a real scenario, you would
       # use the 'user_query' to fetch relevant data.
       fixed_results = [
           {
               "snippet": "This is a fixed snippet from your custom Search API. The original query was: " + user_query,
               "uri": "https://example.com/docs/fixed-test-data"
           },
           {
               "snippet": "Another piece of fixed information to demonstrate the list format.",
               "uri": "https://example.com/another-fixed-source"
           }
       ]
       # --- END OF FIXED RESPONSE ---
   
       return jsonify(fixed_results)
   

2. requirements.py

   functions-framework>=3.0.0
   Flask>=2.0.0
   

3. Implantação: navegue até o diretório que contém main.py e requirements.txt e execute:

   gcloud functions deploy custom_search_wrapper \
     --runtime python311 \
     --trigger-http \
     --entry-point custom_search_wrapper \
     --region YOUR_REGION \
     --allow-unauthenticated \
     --gen2
   

   • Substitua YOUR_REGION pela região Google Cloud escolhida, como us-central1.
   • --allow-unauthenticated é especificado porque o gateway de API processa a autenticação.

Proteger o Cloud Functions com o gateway de API e uma chave de API

O API Gateway oferece um ponto de entrada gerenciado e seguro para seus Cloud Functions e permite aplicar a autenticação de chave de API.

Para mais informações, consulte a documentação do API Gateway.

1. Crie uma especificação OpenAPI (openapi-spec.yaml): esse arquivo define como o gateway de API expõe suas Cloud Functions. Ele especifica que o gateway espera uma solicitação POST para o caminho /v0/search e exige uma chave de API enviada como um parâmetro de consulta chamado key.

   swagger: '2.0'
   info:
     title: Custom Search API for Gemini Grounding
     description: Wraps an internal search function, secured by API Key for Gemini.
     version: 1.0.0
   schemes:
     - https
   produces:
     - application/json
   consumes:
     - application/json
   paths:
     /v0/search: # TODO: This will be part of API endpoint URL change if necessary
       post:
         summary: Custom search endpoint for Gemini
         operationId: customSearchForGemini # TODO: Change if needed
         x-google-backend:
           address: YOUR_CLOUD_FUNCTION_TRIGGER_URL # TODO: Replace with your Cloud Function trigger URL
         parameters:
           - name: body
             in: body
             required: true
             schema:
               type: object
               properties:
                 query:
                   type: string
         security:
           - api_key_query: []
         responses:
           '200':
             description: Search results
             schema:
               type: array
               items:
                 type: object
                 properties:
                   snippet:
                     type: string
                   uri:
                     type: string
           '400':
             description: Invalid request
           '401':
             description: Unauthorized (Missing or invalid API key)
           '500':
             description: Internal server error
   securityDefinitions:
     api_key_query:
       type: apiKey
       name: key # Gemini will send its API key using this query parameter name
       in: query
   

2. Implante o API Gateway: depois de substituir as seguintes variáveis, execute os comandos da CLI gcloud:

   • YOUR_PROJECT_ID: o ID do projeto do Google Cloud .
   • YOUR_REGION: a região Google Cloud que você usou para o Cloud Functions, como us-central1.

   # 1. Create an API
   gcloud api-gateway apis create custom-search-gemini-api --project=YOUR_PROJECT_ID
   
   # 2. Create an API Config from your OpenAPI spec
   gcloud api-gateway api-configs create v1 \
     --api=custom-search-gemini-api \
     --openapi-spec=openapi-spec.yaml \
     --project=YOUR_PROJECT_ID \
     --display-name="Version 1"
   
   # 3. Create a Gateway
   gcloud api-gateway gateways create custom-search-gateway \
     --api=custom-search-gemini-api \
     --api-config=v1 \
     --location=YOUR_REGION \
     --project=YOUR_PROJECT_ID
   

   Após a implantação, o nome do host (URL do gateway) tem o seguinte formato:

   https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev

   Você pode usar o nome do host para criar o URL completo do endpoint do Gemini. Exemplo:

   https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search

3. Criar e restringir uma chave de API: você precisa criar uma chave de API que o Gemini usa para acessar seu endpoint do API Gateway. Para mais informações, consulte Gerenciar chaves de API.

   Para criar e restringir uma chave de API, faça o seguinte:

   1. No console Google Cloud , acesse a página Gateway de API / Ativar APIs.

      Acesse API do API Gateway / Ativar APIs

   2. Se a API API Gateway não estiver ativada, clique em Iniciar e em Ativar.

   3. Selecione Credenciais.

   4. Clique em Criar credenciais e selecione Chave de API.

   5. Clique em Mostrar chave e copie a chave de API gerada. Armazene a chave em um local seguro. Essa chave é usada pelo Gemini.

   6. Clique em Editar chave de API ou no nome da chave.

   7. Na seção Restrições de API, faça o seguinte:

      1. Selecione a opção Restringir chave.

      2. Selecione o serviço gerenciado do gateway de API. Ele precisa ter o nome da sua API, como Custom Search API for Gemini Grounding API.

      3. Se a chave não estiver incluída ou se você pretende gerenciar o gateway com a API usando essa chave, verifique se a API API Gateway (apigateway.googleapis.com) está selecionada. Para o embasamento, a chave precisa de acesso ao serviço de API específico hospedado pelo gateway de API.

   8. Clique em Salvar. O endpoint do gateway de API está protegido e, ao usá-lo, é necessário transmitir a chave de API como um parâmetro de consulta. Exemplo:

      https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY

Considerações sobre a API Search

Considere o seguinte para escolher a API de pesquisa:

• Qualidade do snippet: o texto do snippet retornado pela sua API é crucial. Ele precisa ser conciso, mas informativo o suficiente para o Gemini usar como base factual para a resposta.
• Latência: sua API de pesquisa precisa responder rapidamente. A alta latência na sua API aumenta o tempo de resposta geral do Gemini.
• Tratamento de erros: implemente um tratamento de erros robusto nas suas Cloud Functions ou na API Search. Se a API apresentar erros ou expirar com frequência, isso vai afetar negativamente a capacidade do Gemini de gerar respostas embasadas.

A seguir

• Embasamento com a Pesquisa.