Kontekst adresu URL

Narzędzie kontekstu adresu URL umożliwia przekazywanie modelom dodatkowego kontekstu w postaci adresów URL. Jeśli uwzględnisz adresy URL w żądaniu, model uzyska dostęp do treści z tych stron (o ile nie jest to typ adresu URL wymieniony w sekcji ograniczeń), aby informować i ulepszać swoją odpowiedź.

Narzędzie kontekstu adresu URL jest przydatne w przypadku takich zadań jak:

• Pozyskiwanie danych: pobieranie konkretnych informacji, takich jak ceny, nazwy lub kluczowe ustalenia, z wielu adresów URL.
• Porównywanie dokumentów: analizowanie wielu raportów, artykułów lub plików PDF w celu identyfikowania różnic i śledzenia trendów.
• Synteza i tworzenie treści: łączenie informacji z kilku źródłowych adresów URL w celu generowania dokładnych podsumowań, postów na blogu lub raportów.
• Analizowanie kodu i dokumentów: wskazywanie repozytorium GitHub lub dokumentacji technicznej w celu wyjaśnienia kodu, wygenerowania instrukcji konfiguracji lub udzielenia odpowiedzi na pytania.

Z przykładu poniżej dowiesz się, jak porównać 2 przepisy z różnych witryn.

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

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

Jak to działa

Narzędzie kontekstu adresu URL korzysta z 2-etapowego procesu pobierania, aby zachować równowagę między szybkością, kosztem i dostępem do aktualnych danych. Gdy podasz adres URL, narzędzie najpierw spróbuje pobrać treść z wewnętrznej pamięci podręcznej indeksu. Działa ona jak wysoce zoptymalizowana pamięć podręczna. Jeśli adres URL nie jest dostępny w indeksie (np. jeśli jest to bardzo nowa strona), narzędzie automatycznie przełączy się na pobieranie na żywo. Dzięki temu uzyskuje bezpośredni dostęp do adresu URL, aby pobrać jego zawartość w czasie rzeczywistym.

Łączenie z innymi narzędziami

Aby tworzyć bardziej zaawansowane przepływy pracy, możesz połączyć narzędzie kontekstu adresu URL z innymi narzędziami.

Modele Gemini 3 obsługują łączenie wbudowanych narzędzi (takich jak kontekst adresu URL) z narzędziami niestandardowymi (wywołanie funkcji). Więcej informacji znajdziesz na stronie dotyczącej kombinacji narzędzi.

Powiązanie ze źródłem informacji przy użyciu wyszukiwarki

Gdy włączone są zarówno kontekst adresu URL, jak i powiązanie ze źródłem informacji przy użyciu wyszukiwarki Google, model może korzystać z funkcji wyszukiwania, aby znajdować odpowiednie informacje w internecie, a następnie używać narzędzia kontekstu adresu URL, aby lepiej zrozumieć znalezione strony. To podejście jest skuteczne w przypadku promptów, które wymagają zarówno szerokiego wyszukiwania, jak i dogłębnej analizy konkretnych stron.

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

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

Opis odpowiedzi

Gdy model używa narzędzia kontekstu adresu URL, odpowiedź zawiera obiekt url_context_metadata. Ten obiekt zawiera listę adresów URL, z których model pobrał treści, oraz stan każdej próby pobrania, co jest przydatne do weryfikacji i debugowania.

Oto przykład tej części odpowiedzi (dla zwięzłości pominięto niektóre części):

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

Szczegółowe informacje o tym obiekcie znajdziesz w UrlContextMetadata dokumentacji API.

Testy zabezpieczeń

System sprawdza adres URL pod kątem moderacji treści, aby potwierdzić, że spełnia on standardy bezpieczeństwa. Jeśli podany adres URL nie przejdzie tego testu, otrzymasz url_retrieval_status o wartości URL_RETRIEVAL_STATUS_UNSAFE.

Liczba tokenów

Treści pobrane z adresów URL podanych w prompcie są liczone jako część tokenów wejściowych. Liczbę tokenów w prompcie i użycie narzędzi możesz sprawdzić w usage_metadata obiekcie w danych wyjściowych modelu. Oto przykład danych wyjściowych:

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

Cena za token zależy od używanego modelu. Więcej informacji znajdziesz na stronie cennika.

Obsługiwane modele

Sprawdzone metody

• Podawaj konkretne adresy URL: aby uzyskać najlepsze wyniki, podaj bezpośrednie adresy URL do treści, które mają być analizowane przez model. Model będzie pobierać treści tylko z podanych adresów URL, a nie z linków zagnieżdżonych.
• Sprawdź dostępność: upewnij się, że podane adresy URL nie prowadzą do stron, które wymagają logowania lub są płatne.
• Używaj pełnego adresu URL: podaj pełny adres URL, w tym protokół (np. https://www.google.com zamiast google.com).

Ograniczenia

• Wywołanie funkcji: używanie narzędzi (kontekst adresu URL, powiązanie ze źródłem informacji przy użyciu wyszukiwarki Google itp.) z wywołaniem funkcji nie jest obecnie obsługiwane.
• Limit żądań: narzędzie może przetwarzać maksymalnie 20 adresów URL na żądanie.
• Rozmiar treści adresu URL: maksymalny rozmiar treści pobranych z jednego adresu URL to 34 MB.
• Dostępność publiczna: adresy URL muszą być publicznie dostępne w internecie. Adresy localhost (np. localhost, 127.0.0.1), sieci prywatne i usługi tunelowania (np. ngrok, pinggy) nie są obsługiwane.

Obsługiwane i nieobsługiwane typy treści

Narzędzie może wyodrębniać treści z adresów URL o tych typach:

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

Te typy treści nie są obsługiwane:

• Treści płatne
• Filmy z YouTube (informacje o przetwarzaniu adresów URL z YouTube znajdziesz w artykule o rozumieniu filmów)
• Pliki Google Workspace, takie jak dokumenty i arkusze Google
• Pliki audio i wideo

Co dalej?

• Więcej przykładów znajdziesz w przewodniku po kontekście adresu URL.