이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Search API로 그라운딩

검색 API로 그라운딩하여 Gemini를 외부 데이터 소스에 연결할 수 있습니다. 이렇게 하면 Gemini의 그라운딩 소스로 모든 검색 서비스를 사용할 수 있으므로 시스템의 최신 정보와 가장 관련성 높은 정보를 기반으로 대답할 수 있습니다. 이는 공개적으로 제공되지 않는 엔터프라이즈 전용 데이터에 특히 유용합니다.

이 페이지에서는 Gemini를 사용하여 검색 API로 그라운딩을 구성하고 사용하는 방법을 설명합니다.

검색 API의 그라운딩 작동 방식

검색 API로 그라운딩하면 Gemini에서 제공한 외부 API 엔드포인트를 쿼리할 수 있습니다. 이렇게 하면 Gemini가 대답을 개선하는 도구로 맞춤 검색 기능을 활용할 수 있습니다. 모델이 필요할 때 지정된 데이터 소스에서 정보를 찾을 수 있으므로 더욱 동적이고 맥락을 인식하는 상호작용이 가능합니다.

생성 요청 중에 Gemini는 검색 쿼리를 사용하여 외부 API 엔드포인트를 호출할 수 있습니다. 그러면 API가 관련 데이터 스니펫을 반환해야 합니다. Gemini는 이러한 스니펫을 신뢰할 수 있는 정보 소스로 사용하여 더 정확하고 그라운딩된 대답을 생성합니다.

검색 API를 사용한 그라운딩을 Google 검색과 같은 다른 그라운딩 소스와 결합할 수 있습니다. 생성 요청은 최대 10개의 그라운딩 소스와 Gemini가 다양한 정보 소스를 활용하여 최적의 답변을 생성할 수 있는 다중 도구 쿼리를 지원합니다.

지원되는 모델

다음 모델은 API를 통한 그라운딩을 지원합니다.

자세한 내용은 Gemini 모델을 참고하세요.

시작하기 전에

검색 API에서 그라운딩 기능을 사용하려면 다음 단계를 따르세요.

Google Cloud프로젝트에서 Vertex AI API가 사용 설정되어 있는지 확인합니다.
상세 설정 가이드에 따라 새로운 검색 API 엔드포인트를 만들 계획이라면 Google Cloud CLI가 설치되고 초기화되어 있는지 확인하세요.

검색 API 요구사항

Gemini에서 기존 검색 인프라를 사용하려면 API 엔드포인트가 다음 요구사항을 충족해야 합니다.

API 스키마

HTTP 메서드: POST

요청 본문(Gemini에서 API로):

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

응답 본문(API에서 Gemini로): 객체의 JSON 배열. 각 객체는 검색 결과를 나타내며 스니펫 및 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"
  }
]

결과가 없으면 API 엔드포인트는 빈 배열을 반환해야 합니다.

인증

검색 API로 그라운딩하면 API 키를 사용할 수 있어 API 엔드포인트를 보호할 수 있습니다. Gemini는 이 API 키를 key라는 쿼리 파라미터로 전송합니다.

호환되는 엔드포인트로 검색 API에서 그라운딩 사용

스키마 및 인증 요구사항을 충족하는 API 엔드포인트가 이미 있는 경우 Gemini API 호출에서 직접 구성할 수 있습니다.

`externalApi` 도구 구성

Gemini API에 요청할 때는 externalApi에 구성된 검색 도구와 함께 tools 파라미터를 포함하세요. 주요 필드는 다음과 같습니다.

api_spec: "SIMPLE_SEARCH": Gemini가 사전 정의된 입력 및 출력 스키마를 사용하도록 지시합니다.
endpoint: API 게이트웨이 엔드포인트의 전체 URL입니다(예: https://YOUR_GATEWAY_HOSTNAME/v0/search).
apiAuth.apiKeyConfig.apiKeyString: Gemini가 API와 인증하는 데 사용하는 API 키입니다. Gemini는 이 키를 ?key=<YOUR_API_KEY>로 엔드포인트 URL에 추가합니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION: 요청을 처리할 리전입니다(예: us-central1).
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
MODEL_ID: 호환되는 Gemini 모델의 모델 ID입니다(예: gemini-2.0-flash-001).
USER_PROMPT: 프롬프트에 포함할 텍스트 요청 사항입니다.
EXTERNAL_API_ENDPOINT: Gemini가 호출하는 보안 API 게이트웨이 엔드포인트의 전체 URL입니다(예: https://YOUR_GATEWAY_HOSTNAME/v0/search). 이 엔드포인트는 지정된 API 스키마를 준수해야 합니다.
EXTERNAL_API_KEY: API 게이트웨이에 대해 생성하고 구성한 API 키입니다. Gemini는 이 키를 사용하여 엔드포인트에서 인증합니다.

HTTP 메서드 및 URL:

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

JSON 요청 본문:

  {
  "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

다음 명령어는 gcloud init 또는 gcloud auth login을 사용하거나 gcloud CLI에 자동으로 로그인되는 Cloud Shell을 사용하여 해당 사용자 계정으로 gcloud CLI에 로그인되었다고 가정합니다. gcloud CLI auth list를 실행하여 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

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

다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud CLI auth list를 실행하여 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$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

다음과 비슷한 JSON 응답이 표시됩니다.

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

검색 API 엔드포인트 설정

요구사항을 충족하는 기존 API 엔드포인트가 없는 경우 이 섹션에서는 Cloud Functions 및 API Gateway를 사용하여 엔드포인트를 설정하는 방법을 안내합니다.

Cloud Functions로 외부 API 래퍼 만들기

Cloud 함수는 Gemini로부터 쿼리를 수신하고, 데이터베이스, 내부 검색 엔진, 벡터 검색과 같은 기존 검색 인프라에 적절한 쿼리를 실행한 다음, Gemini가 이해하는 스키마로 결과를 포맷하는 중개자 역할을 할 수 있습니다.

자세한 내용은 Cloud Run Functions 문서를 참고하세요.

Cloud 함수 설정 예시(Python)

이 예시에서는 시연을 위해 하드코딩된 제품 목록을 사용합니다. 데이터 가져오기 로직을 실제 검색 시스템 호출로 대체해야 합니다.

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)

requirements.py

functions-framework>=3.0.0
Flask>=2.0.0

배포: main.py 및 requirements.txt이 포함된 디렉터리로 이동하여 다음을 실행합니다.
```
gcloud functions deploy custom_search_wrapper \
  --runtime python311 \
  --trigger-http \
  --entry-point custom_search_wrapper \
  --region YOUR_REGION \
  --allow-unauthenticated \
  --gen2
```
- YOUR_REGION을 선택한 Google Cloud 리전(예: us-central1)으로 바꿉니다.
- API 게이트웨이에서 인증을 처리하므로 --allow-unauthenticated가 지정됩니다.
중요: 배포 후 트리거 URL의 형식은 https://....run.app입니다. 다음 단계에서 API 게이트웨이 구성에 이 형식을 사용하세요.

API 게이트웨이 및 API 키로 Cloud Functions 보안

API 게이트웨이는 Cloud Functions에 대한 안전한 관리형 진입점을 제공하며 API 키 인증을 시행할 수 있습니다.

자세한 내용은 API Gateway 문서를 참고하세요.

OpenAPI 사양(openapi-spec.yaml) 만들기: 이 파일은 API 게이트웨이가 Cloud Functions를 노출하는 방식을 정의합니다. 게이트웨이가 /v0/search 경로에 대한 POST 요청을 예상하고 key라는 쿼리 파라미터로 전송된 API 키가 필요하다고 지정합니다.

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

API Gateway 배포: 다음 변수를 바꾼 후 gcloud CLI 명령어를 실행합니다.
- YOUR_PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- YOUR_REGION: Cloud Functions에 사용한 리전입니다(예: 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
```
배포 후 호스트 이름(게이트웨이 URL)의 형식은 다음과 같습니다.

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

호스트 이름을 사용하여 Gemini의 전체 엔드포인트 URL을 구성할 수 있습니다. 예를 들면 다음과 같습니다.

https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search
API 키 만들기 및 제한: Gemini가 API 게이트웨이 엔드포인트에 액세스하는 데 사용하는 API 키를 만들어야 합니다. 자세한 내용은 API 키 관리를 참고하세요.

API 키를 만들고 제한하려면 다음 단계를 따르세요.
1. Google Cloud 콘솔에서 API 게이트웨이 / API 사용 설정 페이지로 이동합니다.
  API Gateway API / Enable APIs로 이동
2. API Gateway API가 사용 설정되어 있지 않으면 실행을 클릭하고 사용 설정을 클릭합니다.
3. 사용자 인증 정보를 선택합니다.
4. 사용자 인증 정보 만들기를 클릭한 후 API 키를 선택합니다.
5. 키 표시를 클릭하고 생성된 API 키를 복사합니다. 키를 안전한 위치에 저장합니다. 이 키는 Gemini에서 사용합니다.
6. API 키 수정을 클릭하거나 키 이름을 클릭합니다.
7. API 제한사항 섹션에서 다음을 수행합니다.
  1. 키 제한 옵션을 선택합니다.
  2. API 게이트웨이 관리 서비스를 선택합니다. API 이름(예: Custom Search API for Gemini Grounding API)을 따라 이름을 지정해야 합니다.
  3. 키가 포함되어 있지 않거나 이 키를 사용하여 API로 게이트웨이를 관리하려는 경우 API Gateway API(apigateway.googleapis.com)가 선택되어 있어야 합니다. 그라운딩하려면 키가 API 게이트웨이에서 호스팅하는 특정 API 서비스에 액세스해야 합니다.
  참고: 일반적으로 관리에는 별도의 키 또는 서비스 계정이 사용됩니다.
8. 저장을 클릭합니다. API 게이트웨이 엔드포인트는 보호되며 API 게이트웨이 엔드포인트를 사용할 때는 API 키를 쿼리 파라미터로 전달해야 합니다. 예를 들면 다음과 같습니다.
  
  https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY

검색 API 고려사항

다음 고려사항을 검토하여 검색 API를 선택하세요.

스니펫 품질: API에서 반환되는 스니펫 텍스트가 중요합니다. Gemini가 대답의 사실적 근거로 사용할 수 있을 만큼 간결하면서도 유익해야 합니다.
지연 시간: 검색 API는 빠르게 응답해야 합니다. API의 지연 시간이 길면 Gemini의 전체 응답 시간이 길어집니다.
오류 처리: Cloud Functions 또는 검색 API에 강력한 오류 처리를 구현합니다. API에 오류가 자주 발생하거나 시간 초과가 되면 그라운딩된 대답을 생성하는 Gemini의 기능에 부정적인 영향을 미칩니다.

다음 단계

Google 검색을 사용한 그라운딩.