URL context

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

Инструмент «Контекст URL» полезен для решения следующих задач:

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

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

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

ОТДЫХ 

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

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

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

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

ОТДЫХ 

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, привязка к поиску Google и т. д.) при вызове функций в настоящее время не поддерживается.
  • Ограничение на количество запросов: инструмент может обрабатывать до 20 URL-адресов за один запрос.
  • Размер содержимого URL-адреса: максимальный размер содержимого, загружаемого с одного URL-адреса, составляет 34 МБ.

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

Инструмент может извлекать контент из 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, такие как документы Google или электронные таблицы Google.
  • Видео- и аудиофайлы

Что дальше?