URL-контекст

Инструмент "Контекст 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-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

Принцип работы

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

Использование в сочетании с другими инструментами

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

Модели Gemini 3 поддерживают сочетание встроенных инструментов (например, контекста URL) со специальными инструментами (вызовом функций). Подробнее о сочетаниях инструментов…

Обоснование с помощью поиска

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

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

Как понять ответ

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

Ограничения

• Ограничение на количество запросов. Инструмент может обработать до 20 URL за один запрос.
• Размер контента по URL. Максимальный размер контента, полученного по одному URL, составляет 34 МБ.
• Общедоступность. URL должны быть общедоступными. Адреса localhost (например, localhost, 127.0.0.1), частные сети и сервисы туннелирования (например, ngrok, pinggy) не поддерживаются.

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

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

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

Не поддерживаются:

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

Дальнейшие действия

• Другие примеры можно найти в справочнике по контексту URL.