Ultralytics Explorer API#

Введение#

The Explorer API is a Python API for exploring your datasets. It supports filtering and searching your dataset using SQL queries, vector similarity search, and semantic search.

Установка#

Для работы некоторых функций 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)

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

Ты получаешь DataFrame pandas с количеством 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. Спросить ИИ (Запросы на естественном языке)#

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

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-запрос в качестве входных данных и возвращает DataFrame pandas с результатами.

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#

Попробуй нашу демонстрацию графического интерфейса на базе Explorer API

FAQ#