Ultralytics Explorer API#

Введение#

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

Установка#

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

pip install ultralytics[explorer]

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

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
df = explorer.get_similar(img="path/to/image.jpg")

# Or search for similar images to a given index/indices
df = explorer.get_similar(idx=0)

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

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

1. Поиск по сходству#

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

• По заданному индексу или списку индексов в наборе данных: 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

# create an Explorer object
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())

# Search using multiple indices
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

# create an Explorer object
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. Запрос к AI (запросы на естественном языке)#

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

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# create an Explorer object
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())

# plot the results
plt = plot_query_result(df)
plt.show()

3. Запросы SQL#

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

from ultralytics import Explorer

# create an Explorer object
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, и отображает результаты в виде сетки.

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# plot the SQL Query
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

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

Ты также можешь работать непосредственно с таблицей эмбеддингов. После создания таблицы эмбеддингов к ней можно обращаться с помощью 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

# Dummy embedding
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 похожим изображениям

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

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

import numpy as np

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

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

Ты также можешь визуализировать пространство эмбеддингов с помощью удобного инструмента построения графиков. Например, вот простой пример с использованием Matplotlib:

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

# Reduce dimensions using PCA to 3 components for visualization in 3D
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Create a 3D scatter plot using Matplotlib Axes3D
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# Scatter plot
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()

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

Приложения, созданные с помощью Ultralytics Explorer#

Попробуй нашу демоверсию GUI на основе Explorer API

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