Получение генеративного ответа

Сервис Yandex Search API позволяет получать генеративный ответ на текстовый поисковый запрос. Генеративный ответ формируется с помощью генеративных моделей Яндекса на основе релевантных результатов текстового поиска по указанным сайтам.

Чтобы воспользоваться примером, вам понадобится идентификатор каталога, сервисный аккаунт с ролью search-api.webSearch.user и API-ключ с областью действия yc.search-api.execute. API-ключ, который вы можете создать в AI Studio, имеет такие разрешения. Пример того, как настроить рабочее окружение, можно найти в разделе Начало работы.

Также вместо API-ключа вы можете использовать IAM-токен как более безопасный способ. Подробнее об аутентификации в Yandex Search API.

#!/usr/bin/env python3
        
        from __future__ import annotations
        
        import pprint
        
        from yandex_ai_studio_sdk import AIStudio
        
        
        def main() -> None:
        
            sdk = AIStudio(
                folder_id="<идентификатор_каталога>",
                auth="<API-ключ>",
            )
            sdk.setup_default_logging()
        
            search = sdk.search_api.generative(
                # Можно использовать только один из параметров: site, host или url
                site=["yandex.cloud", "yandex.ru"],
                # host=['yandex.cloud/', 'yandex.ru/'],
                # url=['https://yandex.cloud/ru/docs/serverless-containers/concepts/container', 'https://yandex.cloud/ru/docs/container-registry/concepts/docker-image'],
                fix_misspell=True,
                enable_nrfm_docs=True,
                search_filters=[
                    {"date": ">20250101"},
                    {"lang": "ru"},
                    {"format": "pdf"},
                ],
            )
        
            # Можно передать строку в качестве запроса
            search_result = search.run("Yandex Cloud generative Search API params")
        
            # Изучите структуру search_result с помощью pprint
            # чтобы понять, как с ней работать:
            pprint.pprint(search_result)
            print()
        
            queries = [
                # Можно также передать словарь {'text', 'role'}, как в моделях завершения
                {"text": "Gen search api params", "role": "user"},
                "With examples",
            ]
        
            # И можно передать массив любых допустимых типов
            search_result = search.run(queries)  # type: ignore[arg-type]
            print(search_result.text)
            print()
        
            # Также результат поиска можно использовать как один из запросов для лучшего контекста
            queries.append(search_result)  # type: ignore[arg-type]
            queries.append("Get me more examples of how to use Generative Search API with gprc")
        
            search_result = search.run(queries)  # type: ignore[arg-type]
            print(search_result.text)
            print()
        
        
        if __name__ == "__main__":
            main()

Где:

  • YANDEX_FOLDER_ID — идентификатор каталога сервисного аккаунта.
  • YANDEX_API_KEY — API-ключ для работы в AI Studio.

Текст поискового запроса задается в методе .run, а параметры поиска — в свойствах соответствующего объекта класса search_api.generative:

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

В примере используются утилиты cURL и jq для отправки запроса и обработки результата.

Чтобы отправить запрос через API, используйте метод search для генеративного поиска GenSearch.

curl https://searchapi.api.cloud.yandex.net/v2/gen/search \
          --request POST \
          --header "Authorization: Api-Key <API-ключ>" \
          --data '{
            "messages": [
              {
                "content": "Что такое контейнеризация и как она реализована в Yandex Cloud?",
                "role": "ROLE_USER"
              }
            ],
            "url": {
              "url": [
                  "https://ru.wikipedia.org/wiki/Контейнеризация",
                  "https://yandex.cloud/ru/docs/serverless-containers/",
                  "https://yandex.cloud/ru/docs/container-registry/"
              ]
            },
            "folderId": "<идентификатор_каталога>",
            "fixMisspell": "true",
            "enableNrfmDocs": "false",
            "getPartialResults": false,
            "searchFilters": [
              {
                "date": ">20250101"
              }
            ]
          }' | jq

Где:

  • <API-ключ> — API-ключ для работы в AI Studio. Если для аутентификации вы используете IAM-токен, замените заголовок Authorization на Authorization: Bearer <IAM-токен>.
  • folderId — идентификатор рабочего каталога пользователя или каталога сервисного аккаунта.
  • messages — массив сообщений с запросом пользователя. Каждое сообщение содержит поля:
    • content — текст сообщения.
    • role — роль отправителя: ROLE_USER (пользователь) или ROLE_ASSISTANT (ответ сервиса, используется для передачи контекста предыдущего ответа).
  • fixMisspell — исправлять ли опечатки в запросе. Необязательный параметр. Возможные значения: true или false.
  • enableNrfmDocs — включать ли в поиск документы, недоступные при прямом переходе с главной страницы. Параметр работает только в том случае, если область поиска задана параметром site. Возможные значения: true или false. По умолчанию false.
  • getPartialResults — возвращать ли промежуточные результаты по мере генерации. Возможные значения: true или false. По умолчанию false.

В примере используются утилиты gRPCurl и jq для отправки запроса и обработки результата.

Чтобы отправить запрос, используйте вызов GenSearchService/Search:

grpcurl searchapi.api.cloud.yandex.net:443 yandex.cloud.searchapi.v2.GenSearchService/Search \
          -rpc-header "Authorization: Api-Key <API-ключ>" \
          -d '{
            "messages": [
              {
                "content": "Что такое контейнеризация и как она реализована в Yandex Cloud?",
                "role": "ROLE_USER"
              }
            ],
            "url": {
              "url": [
                  "https://ru.wikipedia.org/wiki/Контейнеризация",
                  "https://yandex.cloud/ru/docs/serverless-containers/",
                  "https://yandex.cloud/ru/docs/container-registry/"
              ]
            },
            "folder_id": "aoevhr118rhc********",
            "fix_misspell": "true",
            "enable_nrfm_docs": "true",
            "get_partial_results": false,
            "search_filters": [
              {
                "date": ">20250101"
              }
            ]
          }' | jq

Где:

  • <API-ключ> — API-ключ для работы в AI Studio. Если для аутентификации вы используете IAM-токен, замените заголовок Authorization на Authorization: Bearer <IAM-токен>.
  • folder_id — идентификатор рабочего каталога пользователя или каталога сервисного аккаунта.
  • messages — массив сообщений с запросом пользователя. Каждое сообщение содержит поля:
    • content — текст сообщения.
    • role — роль отправителя: ROLE_USER (пользователь) или ROLE_ASSISTANT (ответ сервиса, используется для передачи контекста предыдущего ответа).
  • fix_misspell — исправлять ли опечатки в запросе. Необязательный параметр. Возможные значения: true или false.
  • enable_nrfm_docs — включать ли в поиск документы, недоступные при прямом переходе с главной страницы. Параметр работает только в том случае, если область поиска задана параметром site. Возможные значения: true или false. По умолчанию false.
  • get_partial_results — возвращать ли промежуточные результаты по мере генерации. Возможные значения: true или false. По умолчанию false.
Пример ответа
[
          {
            "message": {
              "content": "**Контейнеризация** (виртуализация на уровне операционной системы) — **метод 
              виртуализации**, при котором ядро операционной системы поддерживает несколько изолированных 
              экземпляров пространства пользователя вместо одного. [1] Эти экземпляры (контейнеры или зоны) с точки 
              зрения выполняемых в них процессов идентичны отдельному экземпляру операционной системы. [1] Ядро 
              обеспечивает полную изолированность контейнеров, поэтому программы из разных контейнеров не могут 
              воздействовать друг на друга. [1]\n\n**В Yandex Cloud контейнеризация реализована с помощью сервиса 
              Yandex Serverless Containers**. [5][6] Контейнер позволяет запустить в Yandex Cloud приложение, 
              которое содержится в Docker-образе. [6] \n\n**Некоторые особенности реализации контейнеризации в 
              Yandex Cloud:**\n\n* **Создание ревизии контейнера**. [6] Ревизию контейнера можно создать только из 
              Docker-образа, который загружен в реестр Yandex Container Registry. [6] Другие реестры не 
              поддерживаются. [6] Ревизия содержит всю информацию, необходимую для запуска контейнера. [6]\n* 
              **Вызов контейнера**. [6] После создания ревизии контейнера его можно вызвать через HTTPS, с помощью 
              триггера или с помощью расширения Yandex API Gateway. [6]\n* **Масштабирование контейнера**. [6] Если 
              контейнер вызывается быстрее, чем экземпляр успевает обработать запрос, сервис масштабирует контейнер 
              — запускает его дополнительные экземпляры. [6] Таким образом обеспечивается параллельная обработка 
              запросов. [6]\n* **Подготовленные экземпляры**. [6] Подготовленный экземпляр — это экземпляр 
              контейнера, при запуске которого гарантированно нет холодного старта. [6]",
              "role": "ROLE_ASSISTANT"
            },
            "sources": [
              {
                "used": false,
                "url": "https://ru.wikipedia.org/wiki/%D0%9A%D0%BE%D0%BD%D1%82%D0%B5%D0%B9%D0%BD%D0%B5%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F",
                "title": "Контейнеризация — Википедия"
              },
              {
                "used": true,
                "url": "https://yandex.cloud/ru/docs/serverless-containers/tutorials/functions-framework-to-container",
                "title": "Разработка функций в Functions Framework и их развертывание в Yandex Serverless Containers | Yandex Cloud - Документация"
              },
              {
                "used": false,
                "url": "https://yandex.cloud/ru/docs/container-registry/",
                "title": "Yandex Container Registry | Yandex Cloud - Документация"
              },
              {
                "used": false,
                "url": "https://yandex.cloud/ru/docs/container-registry/concepts/docker-image",
                "title": "Docker-образ. Что это и как работает? | Yandex Cloud - Документация"
              },
              {
                "used": false,
                "url": "https://yandex.cloud/ru/docs/serverless-containers/operations/",
                "title": "Инструкции по работе с Yandex Serverless Containers | Yandex Cloud - Документация"
              },
              {
                "used": true,
                "url": "https://yandex.cloud/ru/docs/serverless-containers/concepts/container",
                "title": "Контейнер в Yandex Serverless Containers | Yandex Cloud - Документация"
              },
              {
                "used": true,
                "url": "https://yandex.cloud/ru/docs/container-registry/operations/docker-image/docker-image-push",
                "title": "Загрузить Docker-образ в реестр Container Registry | Yandex Cloud - Документация"
              },
              {
                "used": false,
                "url": "https://yandex.cloud/ru/docs/serverless-containers/tutorials/deploy-app-container",
                "title": "Запуск контейнерного приложения в Yandex Serverless Containers | Yandex Cloud - Документация"
              },
              {
                "used": false,
                "url": "https://yandex.cloud/ru/docs/container-registry/tutorials/fault-tolerance",
                "title": "Настройка отказоустойчивой архитектуры в Yandex Cloud | Yandex Cloud - Документация"
              },
              {
                "used": false,
                "url": "https://yandex.cloud/ru/docs/serverless-containers/tf-ref",
                "title": "Справочник Terraform для Yandex Serverless Containers | Yandex Cloud - Документация"
              }
            ],
            "searchQueries": [
              {
                "text": "что такое контейнеризация и как она реализована в yandex cloud date 2025 01 01 date 2025 01 01 date 2025 01 01",
                "reqId": "1742492744075717-6834712924673670818-e23cqdex********-BAL"
              },
              {
                "text": "как контейнеризация реализована в yandex cloud date 2025 01 01 date 2025 01 01 date 2025 01 01",
                "reqId": "1742492744352285-5531077099747983300-hhsihxn5********-BAL"
              },
              {
                "text": "что такое контейнеризация date 2025 01 01 date 2025 01 01 date 2025 01 01",
                "reqId": "1742492744351443-10540017330195862709-gai4ndrg********-BAL"
              }
            ],
            "isAnswerRejected": false,
            "isBulletAnswer": false,
            "fixedMisspellQuery": "Что такое контейнеризация и как она реализована в Yandex Cloud?"
          }
        ]

Полезные ссылки

Каталог — пространство, в котором содержатся ресурсы Yandex Cloud. Для аутентификации в AI Studio необходим идентификатор каталога. Чтобы его получить, в интерфейсе AI Studio наведите указатель на название каталога, расположенное в верхней части экрана, и нажмите image. Идентификатор будет скопирован в буфер обмена.

image

Предыдущая
Текстовый поиск в отложенном режиме
Следующая
Поиск изображений по текстовому описанию