Fundamentação com a sua API de pesquisa

Pode associar o Gemini às suas origens de dados externas fundamentando-o com a sua 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 seu 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 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 Search

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 da API ou clique no nome da chave.

    7. Na secção Restrições de 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 respetiva 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 funções do Google Cloud ou API de pesquisa. Se a sua API apresentar erros ou exceder o tempo limite com frequência, afeta negativamente a capacidade do Gemini de gerar respostas fundamentadas.

O que se segue?