Embasamento com sua API Search

Você pode conectar o Gemini às suas fontes de dados externas usando o embasamento com sua API de pesquisa. Isso permite usar qualquer serviço da 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 é útil principalmente 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 com o Gemini.

Como funciona o embasamento com a API Search

Quando você embasa com sua API de pesquisa, o Gemini pode consultar um endpoint de API externo que você fornece. Isso permite que o Gemini use sua funcionalidade de pesquisa personalizada como uma ferramenta para melhorar as respostas. Isso permite interações mais dinâmicas e que consideram o contexto, já que o modelo pode buscar informações das 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. A API deve retornar snippets de dados relevantes. O Gemini usa esses snippets como fonte de dados para gerar uma resposta mais precisa e fundamentada.

É possível combinar o embasamento usando sua API de pesquisa com outras fontes de embasamento, 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

Nesta seção, listamos os modelos que aceitam o embasamento com a API de pesquisa.

Clique para abrir os modelos compatíveis

Antes de começar

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

  1. Verifique se a API Agent Platform está ativada no seu projeto do Google Cloud.
  2. Se você planeja seguir o guia de configuração detalhado para criar um novo endpoint de API de pesquisa, 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 de 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 a API de pesquisa permite 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 a API de pesquisa com 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 à 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": instrui o Gemini a usar o esquema de entrada e saída predefinido.
  • endpoint: o URL completo do endpoint do gateway de API, 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.

Python

Instalar

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

  from google import genai
  from google.genai.types import (
      GenerateContentConfig,
      ExternalApi,
      Retrieval,
      Tool,
      HttpOptions,
  )

  client = genai.Client(http_options=HttpOptions(api_version="v1"))

  # Replace with your API details
  EXTERNAL_API_ENDPOINT = "YOUR_EXTERNAL_API_ENDPOINT"  # e.g., https://YOUR_GATEWAY_HOSTNAME/v0/search
  EXTERNAL_API_KEY = "YOUR_EXTERNAL_API_KEY"

  tool = Tool(
      retrieval=Retrieval(
          external_api=ExternalApi(
              api_spec="SIMPLE_SEARCH",
              endpoint=EXTERNAL_API_ENDPOINT,
              api_auth={
                  "apiKeyConfig": {
                      "apiKeyString": EXTERNAL_API_KEY
                  }
              }
          )
      )
  )

  response = client.models.generate_content(
      model="gemini-2.5-flash",  # Or another supported model
      contents="What can you tell me about product Y based on my API?", # Your query
      config=GenerateContentConfig(
          tools=[tool],
      ),
  )

  print(response.text)

REST

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • LOCATION: a região para processar a solicitação. Para usar o endpoint global, exclua o local do nome do endpoint e configure o local do recurso como global.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • MODEL_ID: o ID de um modelo do Gemini compatível, como gemini-2.5-flash.
  • PROMPT: as instruções de texto a serem incluídas no comando.
  • EXTERNAL_API_ENDPOINT: o URL completo do endpoint seguro do gateway de API que o Gemini chama, como https://YOUR_GATEWAY_HOSTNAME/v0/search. Esse endpoint precisa seguir o esquema de API especificado.

  • EXTERNAL_API_KEY: a chave de API que você gerou e configurou para o gateway de API. O Gemini usa essa chave para se autenticar com seu endpoint.

    Método HTTP e URL:

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

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, use uma destas opções:

    curl

    O comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando CLI gcloud init ou CLI gcloud auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa executando CLI gcloud auth list.

    Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

    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"

    Powershell

    O comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando CLI gcloud init ou CLI gcloud auth login. Para verificar a conta ativa, execute o comando CLI gcloud auth list.

    Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

    $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

    Você receberá uma resposta JSON semelhante a esta:

    {
  "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 gateway de API.

Criar o wrapper de API externa com o Cloud Functions

Uma função do Cloud pode atuar como intermediária que recebe consultas do Gemini, emite consultas apropriadas 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 do Cloud Run functions.

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

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

  1. main.py

    import functions_framework
import json
from flask import jsonify

@functions_framework.http
def custom_search_wrapper(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 do 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 gateway de API oferece um ponto de entrada seguro e gerenciado para as Cloud Functions Run e permite aplicar a autenticação de chave de API.

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

  1. Criar uma especificação OpenAPI (openapi-spec.yaml): esse arquivo define como o gateway de API expõe o Cloud Functions. Ele especifica que o gateway espera uma solicitação POST para o caminho /v0/search e requer 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. Implantar o gateway de API: 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 do 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

    Use 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: é preciso criar uma chave de API que o Gemini use para acessar o endpoint do gateway de API. Para mais informações, consulte Gerenciar chaves de API.

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

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

      Acesse API Gateway API / Ativar APIs

    2. Se o gateway de API não estiver ativado, 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 gateway de API (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 os seguintes pontos para escolher sua API de pesquisa:

  • Qualidade do snippet: o texto do snippet retornado pela API é crucial. Ele precisa ser conciso, mas informativo o suficiente para que o Gemini o use como base factual para a resposta.
  • Latência: sua API de pesquisa precisa responder rapidamente. A alta latência na API aumenta o tempo de resposta geral do Gemini.
  • Tratamento de erros: implemente um tratamento de erros robusto no 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