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="yolo26n.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 для проведения расширенного анализа. Узнай об этом больше в разделе Работа с таблицей эмбеддингов.

Поиск сходства

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

• По заданному индексу или списку индексов в датасете: 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="yolo26n.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="yolo26n.pt")
exp.create_embeddings_table()

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

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

Эта функция позволяет фильтровать датасет с помощью естественного языка, без написания SQL. ИИ-генератор запросов преобразует твой промпт в запрос и возвращает соответствующие результаты. Например, ты можешь спросить: "покажи мне 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="yolo26n.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()

SQL-запросы

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

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo26n.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="yolo26n.pt")
exp.create_embeddings_table()

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

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

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

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

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

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

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()

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

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

Попробуй нашу GUI Demo, основанную на Explorer API

Часто задаваемые вопросы (FAQ)

Для чего используется Ultralytics Explorer API?

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

Как установить Ultralytics Explorer API?

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

pip install ultralytics[explorer]

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

Как использовать Ultralytics Explorer API для поиска сходства?

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

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.pt")
explorer.create_embeddings_table()

# Search for similar images to a given image
similar_images_df = explorer.get_similar(img="path/to/image.jpg")
print(similar_images_df.head())

Более подробную информацию можно найти в разделе Поиск сходства.

Какие преимущества использования LanceDB с Ultralytics Explorer?

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

Как работает функция Ask AI в Ultralytics Explorer API?

Функция Ask AI позволяет пользователям фильтровать датасеты с помощью запросов на естественном языке. Эта функция использует LLM для преобразования таких запросов в SQL-запросы на заднем плане. Вот пример:

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.pt")
explorer.create_embeddings_table()

# Query with natural language
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.