API Ultralytics Explorer#

Введение#

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

Установка#

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

Чтобы принудительно обновить таблицу эмбеддингов, передай 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

# создать объект 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 изображений, на которых ровно один человек и 2 собаки. Другие объекты тоже могут присутствовать», — и система сформирует запрос и покажет результаты. Примечание: эта функция использует большие языковые модели, поэтому результаты вероятностные и могут быть неточными.

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 с результатами.

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

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.

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

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

# Сократить размерность до 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#

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

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