URL 컨텍스트

URL 컨텍스트 도구를 사용하여 프롬프트에 대한 추가 컨텍스트로 Gemini에 URL을 제공할 수 있습니다. 그러면 모델이 URL에서 콘텐츠를 가져와 해당 콘텐츠를 사용하여 대답을 알리고 형성할 수 있습니다.

이 도구는 다음과 같은 작업에 유용합니다.

  • 기사에서 핵심 데이터 포인트 또는 요점 추출
  • 여러 링크의 정보 비교
  • 여러 소스의 데이터 종합
  • 특정 페이지의 콘텐츠를 기반으로 질문에 답변
  • 특정 목적 (예: 직무 설명 작성 또는 테스트 문제 만들기)을 위해 콘텐츠 분석

이 가이드에서는 Vertex AI의 Gemini API에서 URL 컨텍스트 도구를 사용하는 방법을 설명합니다.

지원되는 모델

다음 모델은 URL 컨텍스트를 지원합니다.

URL 컨텍스트 사용

URL 컨텍스트 도구는 단독으로 사용하거나 Google 검색으로 그라운딩과 함께 사용하는 두 가지 주요 방법이 있습니다.

URL 컨텍스트만

프롬프트에서 모델이 분석할 특정 URL을 직접 제공할 수 있습니다.

Summarize this document: YOUR_URLs

Extract the key features from the product description on this page: YOUR_URLs

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig, HttpOptions, UrlContext

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.5-flash"

url_context_tool = Tool(
    url_context = UrlContext
)

response = client.models.generate_content(
    model=model_id,
    contents="Compare recipes from YOUR_URL1 and YOUR_URL2",
    config=GenerateContentConfig(
        tools=[url_context_tool],
        response_modalities=["TEXT"],
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

Javascript

# 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

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "Compare recipes from YOUR_URL1 and YOUR_URL2",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-2.5-flash:generateContent \
  -d '{
      "contents": [
          {
              "role": "user",
              "parts": [
                  {"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

URL 컨텍스트를 사용한 Google 검색으로 그라운딩

URL이 포함된 프롬프트 또는 URL이 없는 프롬프트를 사용하여 URL 컨텍스트와 Google 검색으로 그라운딩을 모두 사용 설정할 수도 있습니다. 모델은 먼저 관련 정보를 검색한 다음 URL 컨텍스트 도구를 사용하여 검색 결과의 콘텐츠를 읽어 더 자세히 이해할 수 있습니다.

이 기능은 실험적이며 API 버전 v1beta1에서 사용할 수 있습니다.

프롬프트 예:

Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.

Recommend 3 books for beginners to read to learn more about the latest YOUR_SUBJECT.

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig, HttpOptions, UrlContext, GoogleSearch

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.5-flash"

tools = []
tools.append(Tool(url_context=UrlContext))
tools.append(Tool(google_search=GoogleSearch))

response = client.models.generate_content(
    model=model_id,
    contents="Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    config=GenerateContentConfig(
        tools=tools,
        response_modalities=["TEXT"],
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

Javascript

# 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

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1beta1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    ],
    config: {
      tools: [{urlContext: {}}, {googleSearch: {}}],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-2.5-flash:generateContent \
  -d '{
      "contents": [
          {
              "role": "user",
              "parts": [
                  {"text": "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          },
          {
              "google_search": {}
          }
      ]
  }' > result.json

cat result.json

Google 검색으로 그라운딩에 관한 자세한 내용은 개요 페이지를 참고하세요.

URL 컨텍스트가 있는 엔터프라이즈용 웹 그라운딩

특정 규제 준수 요구사항이 있거나 의료, 금융, 공공 부문과 같은 규제 업종에 종사하는 경우 Enterprise용 URL 컨텍스트와 웹 그라운딩을 모두 사용 설정할 수 있습니다. 엔터프라이즈용 웹 그라운딩에 사용되는 웹 색인은 Google 검색에서 사용할 수 있는 항목의 하위 집합을 사용하므로 표준 'Google 검색을 사용한 그라운딩' 색인보다 제한적입니다.

Web Grounding for Enterprise에 관한 자세한 내용은 Web Grounding for Enterprise 페이지를 참고하세요.

맥락 기반 대답

모델의 대답은 URL에서 가져온 콘텐츠를 기반으로 합니다. 모델이 URL에서 콘텐츠를 가져온 경우 대답에 url_context_metadata가 포함됩니다. 이러한 응답은 다���과 같�� ��������� 수 있습니다(간결성을 위해 응답의 일부가 생략됨).

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/code-execution",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-search",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
          ]
        }
    }
  ]
}

제한사항

  • 이 도구는 분석을 위해 요청당 최대 20개의 URL을 사용합니다.
  • 이 도구는 웹페이지의 실시간 버전을 가져오지 않으므로 최신 상태 또는 오래된 정보에 문제가 있을 수 있습니다.
  • 실험 단계에서 최상의 결과를 얻으려면 YouTube 동영상과 같은 멀티미디어 콘텐츠가 아닌 표준 웹페이지에서 도구를 사용하세요.