URL context  |  Gemini API  |  Google AI for Developers (original) (raw)

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

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

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

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에서 콘텐츠를 추출할 수 있습니다.

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

다음 단계