Fundamentação com a sua API de pesquisa

Pode associar o Gemini às suas origens de dados externas através da fundamentação com a API de pesquisa. Isto permite-lhe usar qualquer serviço de pesquisa como fonte de base para o Gemini, o que ajuda a garantir que as respostas se baseiam nas informações mais recentes e relevantes dos seus sistemas. Isto é particularmente útil para dados específicos da empresa que não estão disponíveis publicamente.

Esta página explica como configurar e usar a fundamentação com qualquer API de pesquisa com o Gemini.

Como funciona a fundamentação com a sua API Search

Quando fundamenta com a sua API de pesquisa, o Gemini pode consultar um ponto final da API externa que fornece. Isto permite que o Gemini use a sua funcionalidade de pesquisa personalizada como uma ferramenta para melhorar as respetivas respostas. Permite interações mais dinâmicas e conscientes do contexto, uma vez que o modelo pode procurar informações nas origens de dados especificadas quando necessário.

Durante um pedido de geração, o Gemini pode fazer uma chamada ao ponto final da API externa com uma consulta de pesquisa. Em seguida, a API deve devolver fragmentos de dados relevantes. O Gemini usa estes fragmentos como fonte de verdade para gerar uma resposta mais precisa e fundamentada.

Pode combinar a fundamentação através da sua API de pesquisa com outras fontes de fundamentação, como a Pesquisa Google. Um pedido de geração suporta até 10 fontes de fundamentação e consultas com várias ferramentas em que o Gemini pode tirar partido de diferentes fontes de informações para gerar a melhor resposta possível.

Modelos suportados

Esta secção apresenta os modelos que suportam a fundamentação com a sua API de pesquisa.

Antes de começar

Para usar a fundamentação com a sua API de pesquisa, faça o seguinte:

  1. Certifique-se de que a API Vertex AI está ativada no seu Google Cloud projeto.
  2. Se planeia seguir o guia de configuração detalhado para criar um novo ponto final da API Google Search, certifique-se de que tem a CLI Google Cloud instalada e inicializada.

Requisitos da API Search

Para usar a sua infraestrutura de pesquisa existente com o Gemini, o ponto final da API tem de cumprir os seguintes requisitos:

Esquema da API

  • Método HTTP: POST

  • Corpo do pedido (do Gemini para a 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 tem de conter campos de fragmento 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 não forem encontrados resultados, o seu ponto final da API deve devolver uma matriz vazia.

Autenticação

A fundamentação com a sua API de pesquisa suporta a utilização da chave da API, que protege o seu ponto final da API. O Gemini envia esta chave da API como um parâmetro de consulta com o nome key.

Use a fundamentação com a sua API Search com um ponto final compatível

Se já tiver um ponto final da API que cumpra os requisitos de esquema e autenticação, pode configurá-lo diretamente nas chamadas da API Gemini.

Configure a ferramenta externalApi

Quando fizer um pedido à API Gemini, inclua o parâmetro tools com uma ferramenta de obtenção configurada para o externalApi. Os campos principais incluem o seguinte:

  • api_spec: "SIMPLE_SEARCH": isto indica ao Gemini para usar o esquema de entrada e saída predefinido.
  • endpoint: o URL completo do ponto final do API Gateway, como https://YOUR_GATEWAY_HOSTNAME/v0/search.
  • apiAuth.apiKeyConfig.apiKeyString: a chave da API que o Gemini usa para autenticar com a sua API. O Gemini anexa esta chave como ?key=<YOUR_API_KEY> ao URL do ponto final.

Python

Instalação

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 gen com o 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_VERTEXAI=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 qualquer um dos dados do pedido, faça as seguintes substituições:

  • LOCATION: a região para processar o pedido. Para usar o ponto final global, exclua a localização do nome do ponto final e configure a localização do recurso para global.
  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • MODEL_ID: O ID do modelo de um modelo Gemini compatível, como gemini-2.0-flash-001.
  • PROMPT: as instruções de texto a incluir no comando.
  • EXTERNAL_API_ENDPOINT: O URL completo do seu ponto final do API Gateway seguro que o Gemini chama, como https://YOUR_GATEWAY_HOSTNAME/v0/search. Este ponto final tem de estar em conformidade com o esquema da API especificado.

  • EXTERNAL_API_KEY: a chave da API que gerou e configurou para o seu API Gateway. O Gemini usa esta chave para fazer a autenticação com o seu ponto final.

    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 do pedido:

      {
  "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 o seu pedido, use uma destas opções:

    curl

    O comando seguinte pressupõe que iniciou sessão na CLI gcloud com a sua conta de utilizador executando gcloud CLI init ou gcloud CLI auth login , ou usando o Cloud Shell, que inicia sessão automaticamente na CLI gcloud. Pode verificar a conta ativa executando o comando gcloud CLI auth list.

    Guarde o corpo do pedido num ficheiro com o nome request.json e execute o seguinte comando:

    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 seguinte pressupõe que iniciou sessão na CLI gcloud com a sua conta de utilizador executando o comando gcloud CLI init ou gcloud CLI auth login. Pode verificar a conta ativa executando o comando gcloud CLI auth list.

    Guarde o corpo do pedido num ficheiro com o nome request.json e execute o seguinte comando:

    $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

    Deve receber uma resposta JSON semelhante à seguinte:

    {
  "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": {
    "..."
  }
}

Configure um ponto final da API de pesquisa

Se não tiver um ponto final da API existente que cumpra os requisitos, esta secção explica como configurar um através das Cloud Functions e do API Gateway.

Crie o wrapper da API externa com as Funções da nuvem

Uma Cloud Function pode atuar como intermediário que recebe consultas do Gemini, envia consultas adequadas à sua infraestrutura de pesquisa existente, como uma base de dados, um motor de pesquisa interno ou uma pesquisa vetorial, e, em seguida, formata os resultados no esquema que o Gemini compreende.

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

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

Este exemplo usa uma lista de produtos codificada para demonstração. Tem de substituir a lógica de obtençã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(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. Implementação: navegue para 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 Google Cloud região escolhida, como us-central1.
    • --allow-unauthenticated é especificado porque o gateway da API processa a autenticação.

Proteja as Cloud Functions com o API Gateway e uma chave da API

O API Gateway oferece um ponto de entrada gerido e seguro para as suas Cloud Functions e permite-lhe aplicar a autenticação de chaves da API.

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

  1. Crie uma especificação OpenAPI (openapi-spec.yaml): este ficheiro define como o API Gateway expõe as suas Cloud Functions. Especifica que o gateway espera um pedido POST para o caminho /v0/search e requer uma chave da API enviada como um parâmetro de consulta denominado 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. Implemente o API Gateway: depois de substituir as seguintes variáveis, execute os comandos da CLI gcloud:

    • YOUR_PROJECT_ID: o ID do seu projeto Google Cloud .
    • YOUR_REGION: a região que usou para as suas Cloud Functions, como us-central1. Google Cloud 
    # 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 implementação, o nome do anfitrião (URL do gateway) tem o seguinte formato:

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

    Pode usar o nome do anfitrião para criar o URL do ponto final completo para o Gemini. Por exemplo:

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

  3. Crie e restrinja uma chave da API: tem de criar uma chave da API que o Gemini usa para aceder ao seu ponto final da API Gateway. Para mais informações, consulte o artigo Faça a gestão das chaves da API.

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

    1. Na Google Cloud consola, aceda à página API Gateway / Enable APIs.

      Aceda a API do API Gateway / Ativar APIs

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

    3. Selecione Credenciais.

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

    5. Clique em Mostrar chave e copie a chave da API gerada. Armazene a chave num local seguro. Esta chave é usada pelo Gemini.

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

    7. Na secção Restrições da API, faça o seguinte:

      1. Selecione a opção Restringir chave.

      2. Selecione o serviço gerido do API Gateway. Tem de 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 pretender gerir a gateway com a API através desta chave, certifique-se de que a API API Gateway (apigateway.googleapis.com) está selecionada. Para a fundamentação, a chave precisa de acesso ao seu serviço de API específico alojado pelo API Gateway.

    8. Clique em Guardar. O ponto final do API Gateway está protegido e, quando usa o ponto final do API Gateway, tem de transmitir a chave da API como um parâmetro de consulta. Por exemplo:

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

Considerações para a sua API Search

Reveja as seguintes considerações para ajudar a escolher a sua API de pesquisa:

  • Qualidade do fragmento: o texto do fragmento devolvido pela sua API é crucial. Deve ser conciso, mas suficientemente informativo para o Gemini usar como base factual para a sua resposta.
  • Latência: a sua API de pesquisa deve responder rapidamente. A latência elevada na sua API aumenta o tempo de resposta geral do Gemini.
  • Processamento de erros: implemente um processamento de erros robusto nas suas Cloud Functions ou API de pesquisa. Se a sua API apresentar erros ou exceder o tempo limite com frequência, isso afeta negativamente a capacidade do Gemini de gerar respostas fundamentadas.

O que se segue?