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

Эта функция позволяет фильтровать датасет на естественном языке без написания 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-запрос в качестве входных данных и возвращает 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()

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

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

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

FAQ#

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

Ultralytics Explorer API разработан для комплексного исследования датасетов. Он позволяет пользователям фильтровать и искать в датасетах с помощью SQL-запросов, поиска векторного сходства и семантического поиска. Этот мощный Python API может обрабатывать большие датасеты, что делает его идеальным для различных задач компьютерного зрения с использованием моделей 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="yolo11n.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, без нехватки памяти. Эти таблицы создаются только один раз и могут использоваться повторно, что повышает эффективность обработки данных.

Как работает функция «Спросить ИИ» в Ultralytics Explorer API?#

Функция «Спросить ИИ» позволяет пользователям фильтровать датасеты с помощью запросов на естественном языке. Эта функция использует LLMs для преобразования таких запросов в SQL-запросы в фоновом режиме. Вот пример:

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo11n.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())

Дополнительные примеры ты найдешь в разделе «Спросить ИИ».