Gemini Search Grounding

Используйте Google Search Grounding и связывайте фрагменты ответа с веб-источниками.

Gemini Search Grounding позволяет поддерживающим его моделям Gemini получать актуальную информацию через Google Search и связывать фрагменты ответа с веб-источниками через groundingMetadata.

Grounding — не просто включение поиска. Клиентская программа должна читать связи между запросами, источниками и фрагментами текста, чтобы показывать проверяемые ссылки.

Поддержка протокола не равнозначна поддержке модели

Generate Content может описывать инструмент Google Search, но доступность зависит от текущей модели и учётной записи. Сначала проверьте модель в каталоге моделей, затем руководствуйтесь Gemini Generate Content Reference.

Запрос Grounding

Нативный путь Gemini добавляет /v1beta к Origin сайта. Нельзя добавлять /v1beta к Base URL, уже содержащему /v1:

curl --request POST \
  'https://api.agtcloud.cn/v1beta/models/MODEL_ID:generateContent' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Какие новости об искусственном интеллекте сегодня заслуживают внимания? Укажите источники."
          }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

Модель определяет необходимость поиска и может сформировать один или несколько поисковых запросов. Не предполагайте, что включение инструмента всегда создаёт Grounding Metadata.

Обработка Grounding

1. Отправьте вопрос и поисковый инструмент

Поместите вопрос в contents[].parts и включите Google Search в tools.

2. Прочитайте текст ответа

Читайте текст модели из content.parts кандидатов. Не предполагайте, что кандидат или Part всегда только один.

3. Прочитайте Grounding Metadata

Сохраните поисковые запросы, веб-источники и связи фрагментов ответа с индексами источников.

4. Покажите кликабельные ссылки

Добавьте маркеры ссылок по позициям конца фрагментов или покажите карточки источников рядом с ответом, чтобы пользователь мог проверить исходные страницы.

Структура `groundingMetadata`

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "Согласно недавним публикациям, основные изменения включают…"}
        ]
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "искусственный интеллект новости сегодня"
        ],
        "groundingChunks": [
          {
            "web": {
              "uri": "https://example.com/article",
              "title": "Название источника"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 12,
              "text": "Согласно недавним публикациям"
            },
            "groundingChunkIndices": [0]
          }
        ]
      }
    }
  ]
}

Поле	Назначение в клиенте
`webSearchQueries`	Запись фактических запросов модели для диагностики и объяснения области поиска
`groundingChunks`	Сохранение URI, заголовков и других сведений об источниках
`groundingSupports`	Связь фрагментов ответа с одним или несколькими индексами источников

Некоторые поля могут отсутствовать: используйте безопасный доступ к необязательным полям и пустые массивы по умолчанию.

Вставка ссылок в текст

Вставляйте ссылки в порядке убывания segment.endIndex, чтобы предыдущая вставка не сместила следующие позиции:

function addCitations(text, supports = [], chunks = []) {
  const sorted = [...supports].sort(
    (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
  );

  for (const support of sorted) {
    const endIndex = support.segment?.endIndex;
    if (endIndex == null) continue;

    const links = (support.groundingChunkIndices ?? [])
      .map((index) => {
        const source = chunks[index]?.web;
        return source?.uri ? `[${index + 1}](${source.uri})` : null;
      })
      .filter(Boolean);

    if (links.length > 0) {
      text = `${text.slice(0, endIndex)}${links.join('')}${text.slice(endIndex)}`;
    }
  }

  return text;
}

В браузере безопасно обрабатывайте Markdown или HTML, возвращённый моделью, и добавляйте внешним ссылкам безопасные атрибуты новой вкладки.

Ошибки и резервное поведение

Ситуация	Действие
Нет `groundingMetadata`	Покажите ответ и укажите, что источники Grounding в этом ответе отсутствуют
Индекс источника вне границ	Пропустите неверную связь и сохраните обезличенный ответ; не вставляйте ошибочную ссылку
Позиции текста не совпадают	Покажите список источников в конце, не вставляя ссылки в неверные позиции
Поиск завершился ошибкой	По ошибке ответа выберите ограниченный повтор или ответ без поиска
Источники противоречат друг другу	Покажите разные источники и даты, оставив решение пользователю и не скрывая важных расхождений

Проверка перед запуском

Текущая модель поддерживает Google Search Grounding.
Gemini Endpoint использует Origin сайта, без /v1/v1beta.
Текст ответа, запросы, источники и связи фрагментов сохраняются отдельно.
Неверные индексы ссылок не приводят к сбою страницы.
Внешние веб-страницы не считаются доверенными бизнес-инструкциями.
При отсутствии источников не создаются вымышленные Citation.

Если приложение использует Chat, а не нативную структуру Gemini, используйте явно поддерживаемые моделью поисковые поля Chat; не переносите парсер groundingMetadata напрямую.

На этой странице