URL context

URL bağlamı aracı, URL'ler şeklinde modellere ek bağlam sağlamanıza olanak tanır. İsteğinize URL'ler ekleyerek model, yanıtını bilgilendirmek ve geliştirmek için bu sayfalardaki içeriğe (sınırlamalar bölümünde listelenen bir URL türü olmadığı sürece) erişir.

URL bağlamı aracı, aşağıdaki gibi görevler için kullanışlıdır:

  • Veri Ayıklama: Fiyatlar, adlar veya temel bulgular gibi belirli bilgileri birden fazla URL'den çekin.
  • Belgeleri Karşılaştırma: Farklılıkları belirlemek ve trendleri takip etmek için birden fazla raporu, makaleyi veya PDF'yi analiz edin.
  • İçerik Sentezleme ve Oluşturma: Doğru özetler, blog yayınları veya raporlar oluşturmak için çeşitli kaynak URL'lerden gelen bilgileri birleştirin.
  • Kodu ve Dokümanları Analiz Etme: Kodu açıklamak, kurulum talimatları oluşturmak veya soruları yanıtlamak için bir GitHub deposunu ya da teknik dokümanı işaret edin.

Aşağıdaki örnekte, farklı web sitelerindeki iki tarifin nasıl karşılaştırılacağı gösterilmektedir.

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

İşleyiş şekli

URL Bağlamı aracı, hızı, maliyeti ve yeni verilere erişimi dengelemek için iki adımlı bir alma süreci kullanır. Bir URL sağladığınızda araç, önce içeriği dahili bir dizin önbelleğinden getirmeye çalışır. Bu, yüksek düzeyde optimize edilmiş bir önbellek görevi görür. Bir URL dizinde mevcut değilse (ör. çok yeni bir sayfa ise) araç otomatik olarak canlı getirme işlemine geri döner. Bu araç, içeriğini gerçek zamanlı olarak almak için doğrudan URL'ye erişir.

Daha güçlü iş akışları oluşturmak için URL bağlam aracını diğer araçlarla birleştirebilirsiniz.

Hem URL bağlamı hem de Google Arama ile temellendirme etkinleştirildiğinde model, internette alakalı bilgiler bulmak için arama özelliklerini kullanabilir ve ardından bulduğu sayfaları daha ayrıntılı bir şekilde anlamak için URL bağlamı aracını kullanabilir. Bu yaklaşım, hem geniş kapsamlı arama hem de belirli sayfaların ayrıntılı analizini gerektiren istemler için oldukça faydalıdır.

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

Yanıtı anlama

Model, URL bağlamı aracını kullandığında yanıtta bir url_context_metadata nesnesi bulunur. Bu nesne, modelin içerik aldığı URL'leri ve her bir alma denemesinin durumunu listeler. Bu bilgiler, doğrulama ve hata ayıklama için yararlıdır.

Aşağıda, yanıtın bu bölümüne ilişkin bir örnek verilmiştir (yanıtın bazı bölümleri, kısa olması için çıkarılmıştır):

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

Bu nesneyle ilgili tüm ayrıntılar için UrlContextMetadata API referansı bölümüne bakın.

Güvenlik kontrolleri

Sistem, URL'de içerik denetimi yaparak güvenlik standartlarına uygun olup olmadığını kontrol eder. Sağladığınız URL bu denetimi geçemezse url_retrieval_status URL_RETRIEVAL_STATUS_UNSAFE hatası alırsınız.

Jeton sayısı

İsteminizde belirttiğiniz URL'lerden alınan içerik, giriş jetonları kapsamında sayılır. İsteminizin jeton sayısını ve araç kullanımını model çıkışının usage_metadata nesnesinde görebilirsiniz. Aşağıda örnek bir çıkış verilmiştir:

'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
  }

Jeton başına fiyat, kullanılan modele bağlıdır. Ayrıntılar için fiyatlandırma sayfasına bakın.

Desteklenen modeller

En İyi Uygulamalar

  • Belirli URL'ler sağlama: En iyi sonuçlar için modele analiz etmesini istediğiniz içeriğin doğrudan URL'lerini sağlayın. Model yalnızca sağladığınız URL'lerden içerik alır, iç içe yerleştirilmiş bağlantılardaki içerikleri almaz.
  • Erişilebilirliği kontrol edin: Sağladığınız URL'lerin, giriş yapılması gereken veya ödeme duvarının arkasında olan sayfalara yönlendirmediğini doğrulayın.
  • Tam URL'yi kullanın: Protokolü de dahil ederek tam URL'yi girin (ör. yalnızca google.com yerine https://www.google.com).

Sınırlamalar

  • Fiyatlandırma: URL'lerden alınan içerikler, giriş jetonu olarak sayılır. Hız sınırı ve fiyatlandırma, kullanılan modele göre belirlenir. Ayrıntılar için hız sınırları ve fiyatlandırma sayfalarına bakın.
  • İstek sınırı: Araç, istek başına en fazla 20 URL işleyebilir.
  • URL içerik boyutu: Tek bir URL'den alınan içeriklerin maksimum boyutu 34 MB'tır.

Desteklenen ve desteklenmeyen içerik türleri

Araç, aşağıdaki içerik türlerine sahip URL'lerden içerik ayıklayabilir:

  • Metin (text/html, application/json, text/plain, text/xml, text/css, text/javascript , text/csv, text/rtf)
  • Resim (image/png, image/jpeg, image/bmp, image/webp)
  • PDF (application/pdf)

Aşağıdaki içerik türleri desteklenmez:

  • Ödeme duvarlı içerik
  • YouTube videoları (YouTube URL'lerinin nasıl işleneceğini öğrenmek için video anlama bölümüne bakın)
  • Google Dokümanları veya e-tablolar gibi Google Workspace dosyaları
  • Video ve ses dosyaları

Sırada ne var?