URL context

Инструмент контекста URL позволяет предоставить моделям дополнительный контекст в виде URL-адресов. Включив URL-адреса в запрос, модель будет получать доступ к контенту этих страниц (если тип URL не указан в разделе ограничений ), чтобы информировать и улучшать свой ответ.

Инструмент контекста URL полезен для таких задач, как:

  • Извлечение данных : извлечение определенной информации, например цен, имен или основных результатов, из нескольких URL-адресов.
  • Сравнение документов : анализируйте несколько отчетов, статей или PDF-файлов, чтобы выявить различия и отслеживать тенденции.
  • Синтезируйте и создавайте контент : объединяйте информацию из нескольких исходных URL-адресов для создания точных сводок, сообщений в блогах или отчетов.
  • Анализ кода и документации : укажите ссылку на репозиторий GitHub или техническую документацию, чтобы пояснить код, создать инструкции по настройке или ответить на вопросы.

В следующем примере показано, как сравнить два рецепта с разных сайтов.

Питон 

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();

ОТДЫХ 

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 Context использует двухэтапный процесс извлечения, чтобы обеспечить баланс скорости, стоимости и доступа к актуальным данным. При указании URL-адреса инструмент сначала пытается извлечь контент из внутреннего кэша индекса. Это позволяет использовать высокооптимизированный кэш. Если URL-адрес отсутствует в индексе (например, если это совсем новая страница), инструмент автоматически переходит к динамическому извлечению. При этом осуществляется прямой доступ к URL-адресу для извлечения его контента в режиме реального времени.

Вы можете объединить инструмент контекста URL с другими инструментами для создания более эффективных рабочих процессов.

При включении контекста URL и функции Grounding with Google Search модель может использовать свои возможности поиска для поиска релевантной информации в Интернете, а затем использовать инструмент контекста URL для более глубокого анализа найденных страниц. Этот подход эффективен для запросов, требующих как широкого поиска, так и глубокого анализа конкретных страниц.

Питон 

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();

ОТДЫХ 

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

Полную информацию об этом объекте см. в справочнике API UrlContextMetadata .

Проверки безопасности

Система проверяет URL-адрес на соответствие стандартам безопасности. Если предоставленный вами URL-адрес не пройдёт проверку, вы получите статус url_retrieval_status URL_RETRIEVAL_STATUS_UNSAFE .

Количество токенов

Содержимое, полученное с 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-адрес, включая протокол (например, https://www.google.com вместо просто google.com).

Ограничения

  • Цены : Контент, полученный с URL-адресов, учитывается как входные токены. Ограничение скорости и цены зависят от используемой модели. Подробнее см. на страницах с ограничениями скорости и ценами .
  • Лимит запросов : инструмент может обрабатывать до 20 URL-адресов за один запрос.
  • Размер содержимого URL : максимальный размер содержимого, полученного с одного URL, составляет 34 МБ.

Поддерживаемые и неподдерживаемые типы контента

Инструмент может извлекать контент из URL-адресов со следующими типами контента:

  • Текст (текст/html, приложение/json, текст/plain, текст/xml, текст/css, текст/javascript, текст/csv, текст/rtf)
  • Изображение (изображение/png, изображение/jpeg, изображение/bmp, изображение/webp)
  • PDF (заявка/pdf)

Следующие типы контента не поддерживаются:

  • Платный контент
  • Видеоролики YouTube (см. раздел «Понимание видео» , чтобы узнать, как обрабатывать URL-адреса YouTube)
  • Файлы рабочего пространства Google, такие как документы Google или электронные таблицы
  • Видео и аудио файлы

Что дальше?