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)

자바스크립트

# 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 컨텍스트와 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)

자바스크립트

# 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 컨텍스트가 있는 엔터프라이즈용 웹 그라운딩

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

Enterprise용 웹 그라운딩에 대한 자세한 내용은 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">
            },
          ]
        }
    }
  ]
}

제한사항

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