Начать

API Ultralytics Explorer

Примечание сообщества ⚠️

Начиная с версии ultralytics>=8.3.12, Ultralytics Explorer удалён. Чтобы использовать Explorer, установи pip install ultralytics==8.3.11. Аналогичные (и расширенные) возможности исследования наборов данных доступны на платформе Ultralytics.

Введение#

Explorer API — это API Python для изучения датасетов. Он поддерживает фильтрацию и поиск по датасету с помощью SQL-запросов, поиска по сходству векторов и семантического поиска.



Смотри: Обзор Explorer API Ultralytics

Установка#

Для некоторых функций Explorer нужны внешние библиотеки. Они устанавливаются автоматически при использовании Explorer. Чтобы установить эти зависимости вручную, выполни следующую команду:

pip install "ultralytics[explorer]==8.3.11"

Использование#

from ultralytics import Explorer

# Создать объект Explorer
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")

# Создать эмбеддинги для набора данных
explorer.create_embeddings_table()

# Найти изображения, похожие на заданное изображение или изображения
df = explorer.get_similar(img="path/to/image.jpg")

# Или найти изображения, похожие на заданный индекс или индексы
df = explorer.get_similar(idx=0)
Примечание

Таблица эмбеддингов для заданной пары набора данных и модели создаётся только один раз и используется повторно. В основе лежит LanceDB, которая хранит данные на диске и масштабируется, поэтому ты можешь создавать и повторно использовать эмбеддинги для больших наборов данных, например COCO, не опасаясь нехватки памяти.

Чтобы принудительно обновить таблицу эмбеддингов, передай force=True методу create_embeddings_table.

Ты можешь напрямую обращаться к объекту таблицы LanceDB для расширенного анализа. Подробнее см. в разделе Работа с таблицей эмбеддингов.

Поиск по сходству, также известный как векторный поиск, — это метод поиска изображений, похожих на заданное изображение. Он основан на том, что похожие изображения имеют похожие эмбеддинги. Когда таблица эмбеддингов будет создана, можно выполнять поиск по сходству любым из следующих способов:

  • По заданному индексу или списку индексов в наборе данных: exp.get_similar(idx=[1,10], limit=10)
  • По любому изображению или списку изображений, отсутствующих в наборе данных: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

Если задано несколько входных данных, используется совокупный эмбеддинг этих данных.

Ты получишь pandas DataFrame с limit наиболее похожими на входные данные объектами и расстоянием до них в пространстве эмбеддингов. Затем этот набор данных можно дополнительно фильтровать.

Семантический поиск
from ultralytics import Explorer

# создать объект Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

similar = exp.get_similar(img="https://ultralytics.com/images/bus.jpg", limit=10)
print(similar.head())

# Искать по нескольким изображениям
similar = exp.get_similar(
    img=["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/bus.jpg"],
    limit=10,
)
print(similar.head())

Построение графика похожих изображений#

Ты также можешь построить график похожих изображений с помощью метода plot_similar. Он принимает те же аргументы, что и get_similar, и отображает похожие изображения в виде сетки.

Построение графика похожих изображений
from ultralytics import Explorer

# создать объект Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

plt = exp.plot_similar(img="https://ultralytics.com/images/bus.jpg", limit=10)
plt.show()

2. Ask AI (запросы на естественном языке)#

Эта функция позволяет фильтровать датасет с помощью запросов на естественном языке, не составляя SQL-запросы. Генератор запросов на основе ИИ преобразует запрос в выборку и возвращает подходящие результаты. Например, можно спросить: «покажи 100 изображений ровно с одним человеком и двумя собаками. Другие объекты тоже могут присутствовать», — и он составит запрос и покажет результаты. Примечание: эта функция использует большие языковые модели (LLM), поэтому результаты вероятностные и могут быть неточными.

Ask AI
from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# создать объект Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

df = exp.ask_ai("show me 100 images with exactly one person and 2 dogs. There can be other objects too")
print(df.head())

# построить график результатов
plt = plot_query_result(df)
plt.show()

3. Выполнение SQL-запросов#

Ты можешь выполнять SQL-запросы к набору данных с помощью метода sql_query. Метод принимает SQL-запрос и возвращает pandas DataFrame с результатами.

SQL-запрос
from ultralytics import Explorer

# создать объект Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

df = exp.sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%'")
print(df.head())

Построение графика результатов SQL-запроса#

Ты также можешь построить график результатов SQL-запроса с помощью метода plot_sql_query. Он принимает те же аргументы, что и sql_query, и отображает результаты в виде сетки.

Построение графика результатов SQL-запроса
from ultralytics import Explorer

# создать объект Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# построить график SQL-запроса
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

4. Работа с таблицей эмбеддингов#

Ты также можешь работать с таблицей эмбеддингов напрямую. После создания таблицы к ней можно обратиться с помощью Explorer.table.

Совет

Внутри Explorer работает с таблицами LanceDB. Ты можешь обращаться к такой таблице напрямую через объект Explorer.table и выполнять необработанные запросы, применять фильтры до и после запроса и т. д.

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()
table = exp.table

Вот несколько примеров того, что можно делать с таблицей:

Получение необработанных эмбеддингов#

Пример
from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()
table = exp.table

embeddings = table.to_pandas()["vector"]
print(embeddings)

Расширенные запросы с предварительной и последующей фильтрацией#

Пример
from ultralytics import Explorer

exp = Explorer(model="yolo11n.pt")
exp.create_embeddings_table()
table = exp.table

# Тестовый эмбеддинг
embedding = [i for i in range(256)]
rs = table.search(embedding).metric("cosine").where("").limit(10)

Создание векторного индекса#

При работе с большими наборами данных можно создать отдельный векторный индекс, чтобы ускорить выполнение запросов. Для этого используется метод create_index таблицы LanceDB.

table.create_index(num_partitions=..., num_sub_vectors=...)

5. Применение эмбеддингов#

Таблицу эмбеддингов можно использовать для различных видов исследовательского анализа. Вот несколько примеров:

Индекс сходства#

В Explorer есть операция similarity_index:

  • Она оценивает сходство каждой точки данных с остальными точками набора данных.
  • Для этого она подсчитывает, сколько эмбеддингов изображений в сгенерированном пространстве эмбеддингов находятся от текущего изображения ближе, чем max_dist, рассматривая за раз top_k похожих изображений.

Она возвращает pandas DataFrame со следующими столбцами:

  • idx: индекс изображения в наборе данных
  • im_file: путь к файлу изображения
  • count: количество изображений в наборе данных, которые находятся от текущего изображения ближе, чем max_dist
  • sim_im_files: список путей к count похожим изображениям
Совет

Для заданных датасета, модели, max_dist и top_k созданный индекс сходства будет использоваться повторно. Если датасет изменился или нужно заново создать индекс сходства, передай force=True.

Индекс сходства
from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Индекс сходства можно использовать для создания собственных условий фильтрации датасета. Например, следующий код выводит изображения, у которых в датасете больше 30 похожих изображений, — это подходящие кандидаты для удаления почти дубликатов:

import numpy as np

sim_count = np.array(sim_idx["count"])
sim_idx["im_file"][sim_count > 30]

Визуализация пространства эмбеддингов#

Пространство эмбеддингов можно визуализировать с помощью выбранного инструмента построения графиков. Вот простой пример: он сокращает размерность эмбеддингов с помощью PCA и отображает их с помощью Matplotlib:

import matplotlib.pyplot as plt
from sklearn.decomposition import PCA

# Сократить размерность до 3 компонент с помощью PCA для визуализации в 3D
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Создать 3D-диаграмму рассеяния с помощью Matplotlib Axes3D
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# Диаграмма рассеяния
ax.scatter(reduced_data[:, 0], reduced_data[:, 1], reduced_data[:, 2], alpha=0.5)
ax.set_title("3D Scatter Plot of Reduced 256-Dimensional Data (PCA)")
ax.set_xlabel("Component 1")
ax.set_ylabel("Component 2")
ax.set_zlabel("Component 3")

plt.show()

Начни создавать собственные отчёты об изучении наборов данных компьютерного зрения с помощью API Explorer. Для вдохновения посмотри пример исследования VOC.

Приложения на базе Ultralytics Explorer#

Графический интерфейс Explorer построен на основе Explorer API.

Часто задаваемые вопросы#

  • Ultralytics Explorer API предназначен для изучения датасетов. Он позволяет фильтровать датасеты и искать в них с помощью SQL-запросов, поиска по сходству векторов и семантического поиска, а также масштабируется для работы с большими датасетами в задачах компьютерного зрения с моделями Ultralytics.

  • Чтобы установить API Ultralytics Explorer вместе с его зависимостями, выполни следующую команду:

    pip install "ultralytics[explorer]==8.3.11"

    Эта команда автоматически установит все необходимые внешние библиотеки для работы API Explorer. Дополнительные сведения о настройке см. в разделе об установке нашей документации.

  • С помощью API Ultralytics Explorer можно выполнять поиск по сходству: для этого создай таблицу эмбеддингов и выполни запрос, чтобы найти похожие изображения. Вот простой пример:

    from ultralytics import Explorer
    
    # Создать объект Explorer
    explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
    explorer.create_embeddings_table()
    
    # Найти изображения, похожие на заданное изображение
    similar_images_df = explorer.get_similar(img="path/to/image.jpg")
    print(similar_images_df.head())

    Подробнее см. в разделе «Поиск по сходству».

  • LanceDB, используемая внутри Ultralytics Explorer, предоставляет масштабируемые таблицы эмбеддингов на диске. Это позволяет создавать и повторно использовать эмбеддинги для больших датасетов, таких как COCO, не опасаясь нехватки памяти. Такие таблицы создаются только один раз, а затем используются повторно, что повышает эффективность обработки данных.

  • Функция Ask AI позволяет фильтровать датасеты с помощью запросов на естественном языке. Она использует большие языковые модели, чтобы преобразовывать эти запросы в SQL-запросы. Вот пример:

    from ultralytics import Explorer
    
    # Создать объект Explorer
    explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
    explorer.create_embeddings_table()
    
    # Запрос на естественном языке
    query_result = explorer.ask_ai("show me 100 images with exactly one person and 2 dogs. There can be other objects too")
    print(query_result.head())

    Больше примеров см. в разделе Ask AI.

Комментарии2

Задай вопрос, поделись результатами или помоги кому-нибудь.

  1. Jie Liu

    I have downloaded ultralytics-8.3.118 github zip package and install it with pip install -e .. Then I use pip install ultralytics[explorer] to install explorer, but I got a error as followed

    Requirement already satisfied: ultralytics[explorer] in /data/miniconda3/envs/app/lib/python3.10/site-packages (8.3.118)
    WARNING: ultralytics 8.3.118 does not provide the extra 'explorer'
    Requirement already satisfied: numpy<=2.1.1,>=1.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.26.4)
    Requirement already satisfied: matplotlib>=3.3.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (3.10.1)
    Requirement already satisfied: opencv-python>=4.6.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.11.0.86)
    Requirement already satisfied: pillow>=7.1.2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (11.2.1)
    Requirement already satisfied: pyyaml>=5.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (6.0.2)
    Requirement already satisfied: requests>=2.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.32.3)
    Requirement already satisfied: scipy>=1.4.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.15.2)
    Requirement already satisfied: torch>=1.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.3.1)
    Requirement already satisfied: torchvision>=0.9.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.18.1)
    Requirement already satisfied: tqdm>=4.64.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.67.1)
    Requirement already satisfied: psutil in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (7.0.0)
    Requirement already satisfied: py-cpuinfo in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (9.0.0)
    Requirement already satisfied: pandas>=1.1.4 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.2.3)
    Requirement already satisfied: seaborn>=0.11.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.13.2)
    Requirement already satisfied: ultralytics-thop>=2.0.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.0.14)
    Requirement already satisfied: contourpy>=1.0.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.3.2)
    Requirement already satisfied: cycler>=0.10 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (0.12.1)
    Requirement already satisfied: fonttools>=4.22.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (4.57.0)
    Requirement already satisfied: kiwisolver>=1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.4.8)
    Requirement already satisfied: packaging>=20.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (24.2)
    Requirement already satisfied: pyparsing>=2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (3.2.3)
    Requirement already satisfied: python-dateutil>=2.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (2.9.0.post0)
    Requirement already satisfied: pytz>=2020.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2022.7.1)
    Requirement already satisfied: tzdata>=2022.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2025.2)
    Requirement already satisfied: charset-normalizer<4,>=2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.4.1)
    Requirement already satisfied: idna<4,>=2.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.10)
    Requirement already satisfied: urllib3<3,>=1.21.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (1.26.20)
    Requirement already satisfied: certifi>=2017.4.17 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (2025.4.26)
    Requirement already satisfied: filelock in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.18.0)
    Requirement already satisfied: typing-extensions>=4.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (4.13.2)
    Requirement already satisfied: sympy in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (1.13.3)
    Requirement already satisfied: networkx in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.4.2)
    Requirement already satisfied: jinja2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.1.6)
    Requirement already satisfied: fsspec in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2025.3.2)
    Requirement already satisfied: nvidia-cuda-nvrtc-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: nvidia-cuda-runtime-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: nvidia-cuda-cupti-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: nvidia-cudnn-cu12==8.9.2.26 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (8.9.2.26)
    Requirement already satisfied: nvidia-cublas-cu12==12.1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.3.1)
    Requirement already satisfied: nvidia-cufft-cu12==11.0.2.54 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.0.2.54)
    Requirement already satisfied: nvidia-curand-cu12==10.3.2.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (10.3.2.106)
    Requirement already satisfied: nvidia-cusolver-cu12==11.4.5.107 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.4.5.107)
    Requirement already satisfied: nvidia-cusparse-cu12==12.1.0.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.0.106)
    Requirement already satisfied: nvidia-nccl-cu12==2.20.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.20.5)
    Requirement already satisfied: nvidia-nvtx-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: triton==2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.3.1)
    Requirement already satisfied: nvidia-nvjitlink-cu12 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from nvidia-cusolver-cu12==11.4.5.107->torch>=1.8.0->ultralytics[explorer]) (12.8.93)
    Requirement already satisfied: six>=1.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from python-dateutil>=2.7->matplotlib>=3.3.0->ultralytics[explorer]) (1.17.0)
    Requirement already satisfied: MarkupSafe>=2.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from jinja2->torch>=1.8.0->ultralytics[explorer]) (3.0.2)
    Requirement already satisfied: mpmath<1.4,>=1.1.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from sympy->torch>=1.8.0->ultralytics[explorer]) (1.3.0)

    when run code

    from ultralytics import Explorer
    
    # Create an Explorer object
    explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
    
    # Create embeddings for your dataset
    explorer.create_embeddings_table()
    
    # Search for similar images to a given image/images
    dataframe = explorer.get_similar(img="path/to/image.jpg")
    
    # Or search for similar images to a given index/indices
    dataframe = explorer.get_similar(idx=0)

    The error has arisen

    Traceback (most recent call last):
      File "/data/liujie/data/ultralytics-8.3.13/tutorial/debug/explorer.py", line 1, in <module>
        from ultralytics import Explorer
    ImportError: cannot import name 'Explorer' from 'ultralytics' (/data/liujie/data/ultralytics-8.3.118/ultralytics/__init__.py)

    please help me to install and use explorer

    1. Glenn JocherUltralytics(изменено)

      Hi @keeper-jie,

      The issue you're experiencing is because Ultralytics Explorer has been removed since version 8.3.12, and you're using version 8.3.118. That's why you're seeing the warning that the 'explorer' extra is not provided and why you can't import the Explorer class.

      As noted in our documentation, we've moved this functionality to Ultralytics Platform, our platform that offers similar and enhanced capabilities for exploring, visualizing, and managing your datasets without writing code.

      If you specifically need the Explorer API functionality in your code, you would need to downgrade to a version prior to 8.3.12. However, we recommend trying Ultralytics Platform instead, as it provides an improved experience with all the dataset exploration features you're looking for.

      Let me know if you need any further assistance with Ultralytics Platform or if you have any other questions.