/yandex-search-api

Настройка Yandex Search API

Для работы скилла нужен сервисный аккаунт в Яндекс.Облаке. Доступны два способа входа:

• IAM через авторизованный JSON-ключ: шаги 1–6 ниже. Скрипты сами получают и обновляют IAM-токен.
• API-ключ сервисного аккаунта: раздел API-ключ. JSON-ключ и OpenSSL для этого режима не требуются; API-ключ автоматически не обновляется.

Настройка через IAM

Шаг 1: Создайте каталог в Яндекс.Облаке

1. Откройте https://console.yandex.cloud/
2. Если нет аккаунта — зарегистрируйтесь (нужен Яндекс ID)
3. Создайте каталог (folder) или используйте существующий
4. Скопируйте ID каталога — он понадобится дальше

ID каталога выглядит так: b1gabcdef12345678900 Найти его можно: Консоль → ваш каталог → кнопка "ID" справа от названия

Шаг 2: Создайте сервисный аккаунт

1. В консоли откройте ваш каталог
2. Слева выберите Сервисные аккаунты (раздел IAM)
3. Нажмите Создать сервисный аккаунт
4. Имя: search-api-sa (или любое другое)
5. Нажмите Создать

Шаг 3: Назначьте роль

Сервисному аккаунту нужна роль для доступа к Search API:

1. Откройте созданный сервисный аккаунт
2. Перейдите в раздел Роли (или назначьте через настройки каталога)
3. Нажмите Назначить роль
4. Найдите и выберите: search-api.webSearch.user
5. Сохраните

Шаг 4: Создайте ключ авторизации

1. Откройте сервисный аккаунт
2. Перейдите на вкладку Авторизованные ключи
3. Нажмите Создать авторизованный ключ
4. Скачайте JSON-файл ключа
5. Переименуйте его в service_account_key.json
6. Положите в папку config/ (рядом с этим README)

Этот файл секретный! Не добавляйте его в git (он уже в .gitignore).

Шаг 5: Создайте config.json

Скопируйте пример:

cp config/config.example.json config/config.json

Откройте config.json и замените "b1g..." на ваш ID каталога из Шага 1:

{
  "yandex_cloud_folder_id": "b1gabcdef12345678900",
  "auth": {
    "service_account_key_file": "config/service_account_key.json"
  }
}

Остальные поля можно не менять — значения по умолчанию подходят для большинства случаев.

Шаг 6: Проверьте

bash scripts/iam_token_get.sh

Если всё правильно — увидите "IAM token cached" и можно искать.

Для пользователей macOS в режиме IAM

На macOS вместо OpenSSL стоит LibreSSL, который не поддерживает нужный алгоритм подписи. Если при проверке видите ошибку про LibreSSL:

1. Установите OpenSSL:

   brew install openssl

2. Добавьте путь к OpenSSL в config.json:

   {
     "yandex_cloud_folder_id": "b1g...",
     "auth": {
       "service_account_key_file": "config/service_account_key.json",
       "openssl_bin": "/opt/homebrew/bin/openssl"
     }
   }

/opt/homebrew/bin/openssl — для Mac на Apple Silicon (M1/M2/M3/M4). Для Intel Mac путь: /usr/local/opt/openssl/bin/openssl. Узнать точный путь: brew --prefix openssl

Частые проблемы

"401 Unauthorized" / "Unknown api key"

• IAM: проверьте путь к авторизованному JSON-ключу, его действительность и доступность. IAM-токен обновляется автоматически; отозванный авторизованный ключ нужно заменить.
• API-ключ: проверьте YANDEX_AI_API_KEY, срок действия, отсутствие отзыва и область yc.search-api.execute. При истечении или отзыве создайте новый API-ключ. JSON-ключ и обновление IAM здесь не нужны.

"Error: LibreSSL detected"

macOS по умолчанию использует LibreSSL вместо OpenSSL. Это относится только к IAM; см. раздел выше для macOS.

"Error: 403 Forbidden"

• Не назначена роль search-api.webSearch.user → назначьте (Шаг 3)
• Неправильный ID каталога → проверьте yandex_cloud_folder_id

"Error: config.json not found"

Не создан файл конфигурации → выполните Шаг 5.

"Error: openssl not found"

В режиме IAM OpenSSL не установлен или не в PATH → установите через brew install openssl и укажите путь в конфиге.

Лимиты и цены

• Бесплатный тариф: есть (проверяйте актуальные лимиты)
• Подробнее: https://yandex.cloud/ru/docs/search-api/pricing

Настройки по умолчанию

Эти настройки можно менять в config.json, но для начала подойдут как есть:

Инфоконтексты (search.smart_snippets) — главная причина ставить этот скилл в агента: вместе со ссылкой приходит содержательный фрагмент страницы, по которому можно ответить и на который можно сослаться. Работают только в синхронном режиме и только с русской поисковой базой (SEARCH_TYPE_RU), и стоят заметно дороже обычного запроса: 1 500 ₽ против 488 ₽ за 1000 запросов. Выключаются флагом --no-snippets или "enabled": false в конфиге. Подробности: ../references/SMART_SNIPPETS.md.

Настройка IAM через CLI

Если у вас установлен yc (Yandex Cloud CLI), можно сделать всё через командную строку:

# Создать сервисный аккаунт
yc iam service-account create --name search-api-sa

# Назначить роль (замените <FOLDER_ID> и <SA_ID>)
yc resource-manager folder add-access-binding <FOLDER_ID> \
  --role search-api.webSearch.user \
  --subject serviceAccount:<SA_ID>

# Создать ключ
yc iam key create --service-account-name search-api-sa \
  --output config/service_account_key.json

Альтернатива: API-ключ сервисного аккаунта

Сервисный аккаунт и роль search-api.webSearch.user нужны и в этом режиме. JSON с авторизованным ключом, подпись JWT и получение IAM-токена не требуются.

1. Откройте консоль Yandex Cloud, выберите каталог → Identity and Access Management → Сервисные аккаунты → нужный аккаунт → API-ключи.

2. Создайте API-ключ с областью действия yc.search-api.execute. Укажите её явно, не полагайтесь на значения по умолчанию. Эквивалент через CLI:

   yc iam api-key create --service-account-name <имя> --scopes yc.search-api.execute

3. Скопируйте config/.env.example в config/.env и впишите ключ в YANDEX_AI_API_KEY. Задайте права chmod 600 config/.env. Этот файл секретный; не добавляйте его в Git.

4. В config/config.json сохраните yandex_cloud_folder_id, а auth задайте как {"mode": "api_key"}.

5. Запустите sh scripts/web_search_sync.sh --query "пример" --results 1 для проверки доступа (запрос тарифицируется).

auth.mode может быть iam или api_key. Поле можно не задавать: при наличии auth.service_account_key_file используется IAM, даже если задан YANDEX_AI_API_KEY. Без пути к авторизованному ключу, но с YANDEX_AI_API_KEY, выбирается API-ключ. Существующую IAM-конфигурацию менять не нужно.