URL bağlamı

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:

• Verileri ayıklama: Birden fazla URL'den fiyat, ad veya önemli bulgular gibi belirli bilgileri alın.
• 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 birden fazla kaynak URL'deki bilgileri birleştirin.
• Kod ve Doküman Analizi: Kodları açıklamak, kurulum talimatları oluşturmak veya soruları yanıtlamak için bir GitHub deposunu ya da teknik dokümanları referans gösterin.

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

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

client = genai.Client()
model_id = "gemini-3.8-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)

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.8-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();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-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 güncel verilere erişimi dengelemek için iki adımlı bir alma süreci kullanır. Bir URL sağladığınızda araç, öncelikle 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 (örneğin, çok yeni bir sayfaysa) araç otomatik olarak canlı getirme işlemine geri döner. Bu araç, içeriğini gerçek zamanlı olarak almak için URL'ye doğrudan erişir.

Diğer araçlarla birleştirme

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

Gemini 3 modelleri, yerleşik araçların (ör. URL Bağlamı) özel araçlarla (işlev çağrısı) birleştirilmesini destekler. Araç kombinasyonları sayfasından daha fazla bilgi edinebilirsiniz.

Arama ile temellendirme

Hem URL bağlamı hem de Google Arama ile temellendirme etkinleştirildiğinde model, arama özelliklerini kullanarak internette alakalı bilgiler bulabilir ve ardından bulduğu sayfalar hakkında daha ayrıntılı bilgi edinmek 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 çok etkilidir.

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

client = genai.Client()
model_id = "gemini-3.8-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)

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.8-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();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-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 yer alır. Bu nesne, modelin içerik aldığı URL'leri ve her alma denemesinin durumunu listeler. Bu, doğrulama ve hata ayıklama için kullanışlıdır.

Aşağıda, yanıtın bu bölümüne 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ına bakın.

Güvenlik kontrolleri

Sistem, URL'nin güvenlik standartlarını karşıladığını doğrulamak için URL'de içerik denetimi yapar. Sağladığınız URL bu kontrolü 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ının bir parçası olarak sayılır. İsteminiz ve araç kullanımınız için birim sayısı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ılı bilgi için fiyatlandırma sayfasına bakın.

Desteklenen modeller

En İyi Uygulamalar

• Belirli URL'ler sağlama: En iyi sonuçları elde etmek için modelin analiz etmesini istediğiniz içeriğe doğrudan giden URL'ler 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ş yapmayı gerektiren veya ödeme duvarının arkasında olan sayfalara yönlendirmediğini doğrulayın.
• Tam URL'yi kullanın: Protokol dahil olmak üzere tam URL'yi girin (ör. yalnızca google.com yerine https://www.google.com).

Sınırlamalar

• İ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.
• Herkese açık erişilebilirlik: URL'ler web'de herkesin erişimine açık olmalıdır. Localhost adresleri (ör. localhost, 127.0.0.1), özel ağlar ve tünel oluşturma hizmetleri (ör. ngrok, pinggy) desteklenmez.

Desteklenen ve desteklenmeyen içerik türleri

Araç, aşağıdaki içerik türlerini içeren 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 videoları 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?

• Daha fazla örnek için URL bağlamı kılavuzunu inceleyin.