URL context

URL 컨텍스트 도구를 사용하면 URL 형식으로 모델에 추가 컨텍스트를 제공할 수 있습니다. 요청에 URL을 포함하면 모델이 해당 페이지의 콘텐츠에 액세스하여 (제한사항 섹션에 나열된 URL 유형이 아닌 경우) 대답을 알리고 개선합니다.

URL 컨텍스트 도구는 다음과 같은 작업에 유용합니다.

  • 데이터 추출: 여러 URL에서 가격, 이름, 주요 결과와 같은 특정 정보를 가져옵니다.
  • 문서 비교: 여러 보고서, 기사 또는 PDF를 분석하여 차이점을 파악하고 추세를 추적합니다.
  • 콘텐츠 합성 및 생성: 여러 소스 URL의 정보를 결합하여 정확한 요약, 블로그 게시물 또는 보고서를 생성합니다.
  • 코드 및 문서 분석: GitHub 저장소 또는 기술 문서를 가리켜 코드를 설명하거나, 설정 안내를 생성하거나, 질문에 답변합니다.

다음 예에서는 서로 다른 웹사이트의 두 레시피를 비교하는 방법을 보여줍니다.

Python

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

client = genai.Client()
model_id = "gemini-2.5-flash"

tools = [
  {"url_context": {}},
]

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

response = client.models.generate_content(
    model=model_id,
    contents=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)

# For verification, you can inspect the metadata to see which URLs the model retrieved
print(response.candidates[0].url_context_metadata)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);

  // For verification, you can inspect the metadata to see which URLs the model retrieved
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

작동 방식

URL 컨텍스트 도구는 2단계 검색 프로세스를 사용하여 속도, 비용, 최신 데이터 액세스의 균형을 맞춥니다. URL을 제공하면 도구에서 먼저 내부 색인 캐시에서 콘텐츠를 가져오려고 시도합니다. 이는 고도로 최적화된 캐시 역할을 합니다. URL이 색인에서 사용할 수 없는 경우 (예: 매우 새로운 페이지인 경우) 도구는 자동으로 실제 가져오기로 대체됩니다. 이렇게 하면 URL에 직접 액세스하여 콘텐츠를 실시간으로 가져옵니다.

URL 컨텍스트 도구를 다른 도구와 결합하여 더 강력한 워크플로를 만들 수 있습니다.

URL 컨텍스트와 Google 검색으로 그라운딩이 모두 사용 설정된 경우 모델은 검색 기능을 사용하여 온라인에서 관련 정보를 찾은 다음 URL 컨텍스트 도구를 사용하여 찾은 페이지를 더 자세히 이해할 수 있습니다. 이 접근 방식은 광범위한 검색과 특정 페이지의 심층 분석이 모두 필요한 프롬프트에 유용합니다.

Python

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

client = genai.Client()
model_id = "gemini-2.5-flash"

tools = [
      {"url_context": {}},
      {"google_search": {}}
  ]

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,
    )
)

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

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    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: {
      tools: [
        {urlContext: {}},
        {googleSearch: {}}
        ],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Give me three day events 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

대답 이해하기

모델이 URL 컨텍스트 도구를 사용하면 응답에 url_context_metadata 객체가 포함됩니다. 이 객체는 모델이 콘텐츠를 가져온 URL과 각 가져오기 시도의 상태를 나열하므로 확인 및 디버깅에 유용합니다.

다음은 응답의 해당 부분의 예입니다(간결성을 위해 응답의 일부는 생략됨).

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata": {
        "url_metadata": [
          {
            "retrieved_url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          },
          {
            "retrieved_url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          }
        ]
      }
    }
}

이 객체에 관한 자세한 내용은 UrlContextMetadata API 참조를 확인하세요.

안전 확인

시스템은 URL에 대한 콘텐츠 검토를 실행하여 안전 표준을 충족하는지 확인합니다. 제공한 URL이 이 검사를 통과하지 못하면 URL_RETRIEVAL_STATUS_UNSAFE의 url_retrieval_status가 표시됩니다.

토큰 수

프롬프트에 지정한 URL에서 가져온 콘텐츠는 입력 토큰의 일부로 계산됩니다. 프롬프트 및 도구 사용량의 토큰 수는 모델 출력의 usage_metadata 객체에서 확인할 수 있습니다. 다음은 출력 예시입니다.

'usage_metadata': {
  'candidates_token_count': 45,
  'prompt_token_count': 27,
  'prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 27}],
  'thoughts_token_count': 31,
  'tool_use_prompt_token_count': 10309,
  'tool_use_prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 10309}],
  'total_token_count': 10412
  }

토큰당 가격은 사용된 모델에 따라 다릅니다. 자세한 내용은 가격 책정 페이지를 참고하세요.

지원되는 모델

권장사항

  • 구체적인 URL 제공: 최상의 결과를 얻으려면 모델이 분석할 콘텐츠의 직접 URL을 제공하세요. 모델은 중첩된 링크의 콘텐츠가 아닌 사용자가 제공한 URL의 콘텐츠만 가져옵니다.
  • 접근성 확인: 제공한 URL이 로그인해야 하거나 페이월 뒤에 있는 페이지로 연결되지 않는지 확인합니다.
  • 전체 URL 사용: 프로토콜을 포함한 전체 URL을 제공합니다(예: google.com 대신 https://www.google.com).

제한사항

  • 가격: URL에서 가져온 콘텐츠는 입력 토큰으로 계산됩니다. 비율 제한 및 가격은 사용된 모델을 기반으로 합니다. 자세한 내용은 요청률 한도 및 가격 책정 페이지를 참고하세요.
  • 요청 한도: 이 도구는 요청당 최대 20개의 URL을 처리할 수 있습니다.
  • URL 콘텐츠 크기: 단일 URL에서 가져온 콘텐츠의 최대 크기는 34MB입니다.

지원되는 콘텐츠 유형과 지원되지 않는 콘텐츠 유형

이 도구는 다음 콘텐츠 유형의 URL에서 콘텐츠를 추출할 수 있습니다.

  • 텍스트 (text/html, application/json, text/plain, text/xml, text/css, text/javascript , text/csv, text/rtf)
  • 이미지 (image/png, image/jpeg, image/bmp, image/webp)
  • PDF (application/pdf)

다음 콘텐츠 유형은 지원되지 않습니다.

  • 페이월 콘텐츠
  • YouTube 동영상 (YouTube URL 처리 방법을 알아보려면 동영상 이해 참고)
  • Google Docs 또는 스프레드시트와 같은 Google Workspace 파일
  • 동영상 및 오디오 파일

다음 단계