Генеративный ответ

Статья создана

Обновлена 14 марта 2025 г.

Поисковый запрос
Генеративный ответ
- Особенности ответа

Вы можете использовать текстовый поиск Yandex Search API в сочетании с генеративными возможностями YandexGPT, чтобы получить на поисковый запрос пользователя единый емкий и понятный генеративный ответ, при формировании которого нейросеть анализирует релевантные результаты текстового поиска Yandex Search API по сайтам вашей компании.

По умолчанию можно отправить не более одного синхронного запроса в секунду для получения генеративного ответа. Подробнее об ограничения Yandex Search API см. в разделе Квоты и лимиты в Yandex Search API.

Примечание

Функциональность находится на стадии Preview.

Важно

До 1 апреля 2025 года получить генеративный ответ можно только для запросов, выполненных через интерфейс API v1.

С 1 апреля 2025 года функциональность генеративного ответа будет доступна только в интерфейсе API v2. Подробнее о стоимости получения генеративных ответов на запросы см. Правила тарификации для Yandex Search API

Поисковый запрос

Запросы к сервису Yandex Search API на получение генеративного ответа отправляются методом POST на эндпоинт https://yandex.ru/search/xml/generative.

Для выполнения запросов необходим сервисный аккаунт с ролью search-api.executor и созданный для него API-ключ. Для успешной авторизации передавайте в каждом запросе идентификатор каталога и API-ключ сервисного аккаунта.

Формат запроса

Каждый запрос на получение генеративного ответа должен содержать тело запроса в формате JSON следующего вида:

{
  "messages": [
    {
      "content": "<текст_сообщения_1>",
      "role": "user"
    },
    {
      "content": "<ответ_модели_1>",
      "role": "assistant"
    },
    {
      "content": "<текст_сообщения_2>",
      "role": "user"
    },
    {
      "content": "<ответ_модели_3>",
      "role": "assistant"
    },
    ...
    {
      "content": "<текст_сообщения_n>",
      "role": "user"
    }
  ],
  "site": [
    "<адрес_сайта_1_для_поиска>",
    "<адрес_сайта_2_для_поиска>",
    ...
    "<адрес_сайта_n_для_поиска>"
  ],
  "host": [
    "<хост_1_для_поиска>",
    "<хост_2_для_поиска>",
    ...
    "<хост_n_для_поиска>"
  ],
  "url": [
    "<страница_1_для_поиска>",
    "<страница_2_для_поиска>",
    ...
    "<страница_n_для_поиска>"
  ],
  "search_additional_text": "<дополнительный_текст_для_поиска>",
  "fix_misspell": true|false,
  "enable_nrfm_docs": true|false
}

Параметры запроса

messages — одиночный поисковый запрос или поисковый запрос с контекстом в форме чата с моделью. Задается в виде массива объектов, в каждом из которых содержатся два элемента:
- content — текст запроса пользователя или ответа модели (в зависимости от значения элемента role).
- role — роль автора сообщения. Возможные значения:
  - user — означает, что автор сообщения — пользователь, а в поле content — запрос пользователя.
  - assistant — означает, что автор сообщения — модель, а в поле content — ответ модели.
Подробнее о режиме чата в YandexGPT см. в разделе Как реализовать чат с YandexGPT Lite или YandexGPT Pro.
site — ограничение области поиска релевантных документов по массиву сайтов.

Например, для сайта yandex.cloud поиск будет выполняться по всем документам вида *.yandex.cloud/*. То есть, в область поиска попадут документы со следующими адресами:
- yandex.cloud/
- subdomain.yandex.cloud/
- yandex.cloud/path/
- subdomain.yandex.cloud/path/
В поле site можно указать конкретный путь к области поиска, например https://yandex.cloud/ru/docs.
host — ограничение области поиска релевантных документов по массиву хостов.

Например, для хоста yandex.cloud/ поиск будет выполняться по всем документам вида yandex.cloud/*. То есть, в область поиска попадут документы со следующими адресами:
- yandex.cloud/
- yandex.cloud/path/
В отличие от ограничения области поиска в поле site, заданное в поле host ограничение не распространяется на поддомены. В поле host также нельзя указать конкретный путь к области поиска.
url — ограничение области поиска релевантных документов по массиву страниц. Например https://yandex.cloud/ru/docs/serverless-containers/concepts/container и https://yandex.cloud/ru/docs/container-registry/concepts/docker-image.

Примечание

Для ограничения области поиска достаточно указать в запросе одно из полей: site, host или url.

Приоритет поля host выше, чем у поля site, а url в приоритете над host. Если в запросе передаются все три поля, область поиска будет ограничена значением поля url, а значение полей host и site будет проигнорировано.
search_additional_text — дополнительный текст, который будет добавлен к каждому запросу. Используется для передачи поисковых операторов, таких как date:, mime: и lang:. Например, если указать "search_additional_text": "date:>2025-01-01", то в ответ на запрос будут получены только документы с датой обновления после 1 января 2025 года. Необязательный параметр.
fix_misspell — параметр отвечает за проверку текста запроса на опечатки. Если параметр задан, то перед отправкой текста запроса выполняется его проверка на наличие опечаток, а в ответе добавляется поле is_fixed_misspell, указывающее, были ли найдены опечатки. Если опечатки были найдены, в ответе также появляется поле fixed_misspell, содержащее исправленный текст запроса, который был отправлен в модель. Необязательный параметр. Возможные значения: true или false.
enable_nrfm_docs — параметр определяет, попадут ли в поиск документы, недоступные при прямом переходе с главной страницы. Параметр работает только в том случае, если область поиска задана параметром site. Например, если вы хотите добавить в поиск страницу, на которую нельзя перейти ни по одной из ссылок, ведущих с главной страницы сайта, то необходимо включить параметр enable_nrfm_docs. Необязательный параметр. Возможные значения: true или false.

Пример тела запроса:

{
  "messages": [
    {
      "content": "Что такое контейнеризация и как она реализована в Yandex Cloud?",
      "role": "user"
    }
  ],
  "site": [
    "https://ru.wikipedia.org/wiki/Контейнеризация",
    "https://yandex.cloud/ru/docs/serverless-containers/",
    "https://yandex.cloud/ru/docs/container-registry/"
  ],
  "search_additional_text": "date:>2025-01-01",
  "fix_misspell": "true",
  "enable_nrfm_docs": "true"
}

Отправка запроса

Чтобы отправить запрос, воспользуйтесь утилитой cURL или языком программирования Python. Перед отправкой запроса сохраните идентификатор каталога и API-ключ вашего сервисного аккаунта в переменные окружения:

export FOLDER_ID=<идентификатор_каталога>
export API_KEY=<API-ключ>

cURL

Python 3

curl \
  --request POST \
  --header "Authorization: Api-Key ${API_KEY}" \
  --data "@<путь_к_файлу_с_телом_запроса>" \
  "https://yandex.ru/search/xml/generative?folderid=${FOLDER_ID}"

import requests
import os

SEARCH_API_GENERATIVE = (
    f"https://ya.ru/search/xml/generative?folderid={os.getenv('FOLDER_ID')}"
)

def main():
    headers = {"Authorization": f"Api-Key {os.getenv('API_KEY')}"}
    data = {
        "messages": [
            {
                "content": "Что такое контейнеризация и как она реализована в Yandex Cloud?",
                "role": "user",
            }
        ],
        "site": [
            "https://ru.wikipedia.org/wiki/Контейнеризация",
            "https://yandex.cloud/ru/docs/serverless-containers/",
            "https://yandex.cloud/ru/docs/container-registry/",
        ],
        "search_additional_text": "date:>2025-01-01",
        "fix_misspell": "true",
        "enable_nrfm_docs": "true",
    }

    response = requests.post(SEARCH_API_GENERATIVE, headers=headers, json=data)

    if "application/json" in response.headers["Content-Type"]:
        print(response.json()["message"]["content"])
        for i, link in enumerate(response.json()["links"], start=1):
            print(f"[{i}]: {link}")
    elif "text/xml" in response.headers["Content-Type"]:
        print("Error:", response.text)
    else:
        print("Unexpected content type:", response.text)

if __name__ == "__main__":
    main()