Поиск изображений по заданному изображению

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

Улучшена

Обновлена 12 ноября 2025 г.

Перед началом работы
- Подготовьте облако к работе
Выполните поисковый запрос

Сервис Yandex Search API позволяет искать изображения по заданному изображению в индексе Яндекс Картинок и получать результат поиска в формате JSON. Выполнять запросы можно с помощью Yandex Cloud ML SDK, REST API и gRPC API. Поисковая выдача зависит от заданных в запросе параметров.

Перед началом работы

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

Подготовьте облако к работе

Чтобы воспользоваться примерами:

SDK

REST API

gRPC API

Создайте сервисный аккаунт и назначьте ему роль search-api.webSearch.user.
Получите и сохраните API-ключ сервисного аккаунта, указав для него область действия yc.search-api.execute.

В примерах используется аутентификация с помощью API-ключа. Yandex Cloud ML SDK также поддерживает аутентификацию с помощью IAM-токена и OAuth-токена. Подробнее см. в разделе Аутентификация в Yandex Cloud ML SDK.

Примечание

Если вы используете ОС Windows, рекомендуем предварительно установить оболочку WSL и выполнять дальнейшие действия в этой оболочке.
Установите Python версии 3.10 или выше.
Установите библиотеку Python venv для создания изолированных виртуальных окружений в Python.
Создайте и войдите в новое виртуальное окружение Python:
```
python3 -m venv new-env
source new-env/bin/activate
```
С помощью менеджера пакетов pip установите библиотеку ML SDK:
```
pip install yandex-cloud-ml-sdk
```

Создайте сервисный аккаунт, от имени которого будут выполняться запросы. Вы также можете использовать аккаунт на Яндексе или федеративный аккаунт, но для автоматизации предпочтительнее использовать сервисный аккаунт.
Назначьте аккаунту, от имени которого будут выполняться запросы, роль search-api.webSearch.user.
Получите IAM-токен, необходимый для аутентификации.

В приведенных примерах используется аутентификация с помощью IAM-токена. Чтобы использовать для аутентификации API-ключ сервисного аккаунта, измените в примерах запросов заголовок Authorization. Подробнее см. в разделе Аутентификация в API.

Чтобы воспользоваться примерами, также установите утилиты cURL и jq.

Создайте сервисный аккаунт, от имени которого будут выполняться запросы. Вы также можете использовать аккаунт на Яндексе или федеративный аккаунт, но для автоматизации предпочтительнее использовать сервисный аккаунт.
Назначьте аккаунту, от имени которого будут выполняться запросы, роль search-api.webSearch.user.
Получите IAM-токен, необходимый для аутентификации.

В приведенных примерах используется аутентификация с помощью IAM-токена. Чтобы использовать для аутентификации API-ключ сервисного аккаунта, измените в примерах запросов заголовок Authorization. Подробнее см. в разделе Аутентификация в API.

Чтобы воспользоваться примерами, также установите утилиты gRPCurl и jq.

Выполните поисковый запрос

Чтобы выполнить поисковый запрос:

SDK

REST API

gRPC API

Создайте файл pic-search-by-pic.py и добавьте в него следующий код:

#!/usr/bin/env python3

from __future__ import annotations

import pathlib

from yandex_cloud_ml_sdk import YCloudML
from yandex_cloud_ml_sdk.search_api import FamilyMode

EXAMPLE_FILE = pathlib.Path(__file__).parent / "image.jpg"


def main() -> None:
    sdk = YCloudML(
        folder_id="<идентификатор_каталога>",
        auth="<API-ключ>",
    )
    sdk.setup_default_logging()

    # You can pass initial configuration here:
    search = sdk.search_api.by_image(
        family_mode="moderate",
        site="ya.ru",
    )
    # Or configure the Search object later:
    search = search.configure(
        # family mode may be passed as a string or as a special enum value
        family_mode=FamilyMode.NONE,
    )

    # You can reset any config property back to its default value by passing None:
    search = search.configure(site=None)

    search_type = input(
        "Select a search type:\n1 — using a remote image URL (default)\n2 — using bytes data from './image.jpeg'\n\n"
    )
    if not search_type.strip():
        search_type = "1"

    if int(search_type) == 2:

        # The first search option is to search using bytes data:
        image_data = pathlib.Path(EXAMPLE_FILE).read_bytes()
        search_result = search.run(image_data)

    else:

        # The second search option is to search using a remote image url:
        # e.g. Photo of Leo Tolstoy
        url = "https://upload.wikimedia.org/wikipedia/commons/b/be/Leo_Tolstoy_1908_Portrait_%283x4_cropped%29.jpg"
        search_result = search.run_from_url(url)

    # You can examine the search_result structure via pprint
    # to get to know how to work with it:
    # pprint.pprint(search_result)
    # Search results can also be used in boolean context:
    if search_result:
        print(f"{len(search_result)} documents found")
    else:
        print("Nothing found")

    # The third search option is to search using the image's CBIR ID:
    # using CBIR ID is way faster than any other option,
    # but it requires to make at least one "heavy" request to get this ID.

    cbid_id = search_result.cbir_id
    search_result = search.run_from_id(cbid_id, page=1)

    while search_result:
        print(f"Page {search_result.page}:")
        output_filename = (
            str(pathlib.Path(__file__).parent)
            + "/"
            + "results_page_"
            + str(search_result.page)
            + ".txt"
        )
        file = open(output_filename, "a")
        for document in search_result:
            file.write(str(document) + "\n\n")
        print(f"Page {search_result.page} saved to file {output_filename}")
        file.close()

        # search_result.next_page() is a shortcut for
        # `.run_from_id(search_query.cbir_id, page=page + 1)`
        # with search configuration saved from the initial run;
        # last page + 1 will return an "empty" search_result;
        search_result = search_result.next_page()


if __name__ == "__main__":
    main()

Где:

<идентификатор_каталога> — идентификатор каталога, в котором создан сервисный аккаунт.
<API-ключ> — API-ключ сервисного аккаунта, полученный ранее и необходимый для аутентификации в API.

В примерах используется аутентификация с помощью API-ключа. Yandex Cloud ML SDK также поддерживает аутентификацию с помощью IAM-токена и OAuth-токена. Подробнее см. в разделе Аутентификация в Yandex Cloud ML SDK.

Параметры поиска вы можете задать в свойствах соответствующего объекта класса search_api.by_image или в свойствах метода .configure:

family_mode — фильтрация результатов. Необязательный параметр. Возможные значения:
- moderate — умеренный фильтр (значение по умолчанию). Из выдачи исключаются документы, относящиеся к категории «для взрослых», если запрос явно не направлен на поиск подобных ресурсов.
- none — фильтрация отключена. В выдачу включаются любые документы, вне зависимости от содержимого.
- strict — семейный фильтр. Вне зависимости от поискового запроса из выдачи исключаются документы, относящиеся к категории «для взрослых», а также содержащие ненормативную лексику.

Выполните созданный файл:
```
python3 pic-search-by-pic.py
```
В процессе выполнения код запросит у вас выбрать вариант поиска:
1. По изображению, опубликованному в интернете. URL этого изображения задан в переменной url.
2. По изображению с локального компьютера. Локальный путь к изображению задан в переменной EXAMPLE_FILE.
На завершающем этапе код выполнит поиск изображений по идентификатору CBIR, после чего постранично сохранит результаты поиска в текущей директории в текстовые файлы:
```
Page 1 saved to file /Users/MyUser/Desktop/results_page_1.txt
...
Page 134 saved to file /Users/MyUser/Desktop/results_page_134.txt
```

Создайте файл с телом запроса (например, body.json):

body.json
```
{
  "site": "<доменное_имя_сайта>",
  "folderId": "<идентификатор_каталога>",
  "url": "<URL_исходного_изображения>",
  "data": "<тело_изображения>",
  "id": "<идентификатор_CBIR>",
  "page": "<номер_страницы>"
}
```
Описание полей
- site — поиск изображений только на указанном сайте. Например: yandex.cloud. Необязательный параметр. Если параметр не задан, поиск выполняется по всем сайтам поисковой базы.
- folderId — идентификатор каталога пользователя или сервисного аккаунта, от имени которого вы будете выполнять запросы.
- url — URL, по которому доступно исходное изображение.
- data — тело исходного изображения в кодировке Base64.
- id — идентификатор CBIR исходного изображения. Указывайте идентификатор, полученный в ответе, чтобы быстрее получить следующую страницу поисковой выдачи.
  
  Примечание
  
  В запросе можно передать только один из параметров: url, id или data.
- page — номер запрашиваемой страницы. Необязательный параметр. По умолчанию возвращается первая страница поисковой выдачи. Нумерация страниц начинается с нуля (первой странице соответствует значение 0).
Пример тела запроса
body.json
```
{
  "folderId": "b1gt6g8ht345********",
  "data": "<закодированное_в_base64_изображение>",
  "page": "1"
}
```
Выполните HTTP-запрос, указав полученный ранее IAM-токен и путь к файлу с телом запроса:
```
curl \
  --request POST \
  --header "Authorization: Bearer <IAM-токен>" \
  --data "@body.json" \
  "https://searchapi.api.yandexcloud.kz/v2/image/search_by_image" \
  > result.json
```
В файл result.json будут сохранены результаты поиска в формате JSON.

Создайте файл с телом запроса (например, body.json):

body.json
```
{
  "site": "<доменное_имя_сайта>",
  "folder_id": "<идентификатор_каталога>",
  "url": "<URL_исходного_изображения>",
  "data": "<тело_изображения>",
  "id": "<идентификатор_CBIR>",
  "page": "<номер_страницы>"
}
```
Описание полей
- site — поиск изображений только на указанном сайте. Например: yandex.cloud. Необязательный параметр. Если параметр не задан, поиск выполняется по всем сайтам поисковой базы.
- folder_id — идентификатор каталога пользователя или сервисного аккаунта, от имени которого вы будете выполнять запросы.
- url — URL, по которому доступно исходное изображение.
- data — тело исходного изображения в кодировке Base64.
- id — идентификатор CBIR исходного изображения. Указывайте идентификатор, полученный в ответе, чтобы быстрее получить следующую страницу поисковой выдачи.
  
  Примечание
  
  В запросе можно передать только один из параметров: url, id или data.
- page — номер запрашиваемой страницы. Необязательный параметр. По умолчанию возвращается первая страница поисковой выдачи. Нумерация страниц начинается с нуля, первой странице соответствует значение 0.
Пример тела запроса
body.json
```
{
  "folder_id": "b1gt6g8ht345********",
  "data": "<закодированное_в_base64_изображение>",
  "page": "1"
}
```
Выполните gRPC-вызов, указав полученный ранее IAM-токен и путь к файлу с телом запроса:
```
grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d @ < body.json \
  searchapi.api.yandexcloud.kz:443 yandex.cloud.searchapi.v2.ImageSearchService/SearchByImage \
  > result.json
```
В файл result.json будут сохранены результаты поиска в формате JSON.

Поиск изображений по заданному изображению

Перед началом работы

Подготовьте облако к работе

Выполните поисковый запрос

См. также

Была ли статья полезна?

Поиск изображений по заданному изображению

Перед началом работыПеред началом работы

Подготовьте облако к работеПодготовьте облако к работе

Выполните поисковый запросВыполните поисковый запрос

См. такжеСм. также

Была ли статья полезна?

Перед началом работы

Подготовьте облако к работе

Выполните поисковый запрос

См. также