Ultralytics Explorer API
Примечание сообщества ⚠️
По состоянию на ultralytics>=8.3.10
, поддержка Ultralytics explorer была прекращена. Но не волнуйтесь! Теперь вы можете получить доступ к аналогичным и даже расширенным функциям через Ultralytics HUB, нашу интуитивно понятную платформу без кода, предназначенную для оптимизации вашего рабочего процесса. С Ultralytics HUB вы можете продолжать исследовать, визуализировать и управлять своими данными без особых усилий, и все это без написания единой строки кода. Обязательно ознакомьтесь с ним и воспользуйтесь его мощными функциями!🚀
Введение
Explorer API — это API на языке python для изучения ваших наборов данных. Он поддерживает фильтрацию и поиск в вашем наборе данных с использованием SQL-запросов, поиска векторного сходства и семантического поиска.
Смотреть: Обзор Ultralytics Explorer API
Установка
Для работы 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
dataframe = explorer.get_similar(img="path/to/image.jpg")
# Or search for similar images to a given index/indices
dataframe = explorer.get_similar(idx=0)
Примечание
Таблица эмбеддингов для заданной пары набора данных и модели создается только один раз и используется повторно. В основе лежит LanceDB, которая масштабируется на диске, поэтому вы можете создавать и повторно использовать эмбеддинги для больших наборов данных, таких как COCO, не исчерпав память.
В случае, если вы хотите принудительно обновить таблицу эмбеддингов, вы можете передать force=True
в create_embeddings_table
метод.
Вы можете напрямую получить доступ к объекту таблицы LanceDB для выполнения расширенного анализа. Узнайте больше об этом в разделе Работа с таблицей эмбеддингов
1. Поиск по сходству
Поиск по сходству — это метод поиска изображений, похожих на заданное изображение. Он основан на идее, что похожие изображения будут иметь похожие embeddings. После создания таблицы embeddings вы можете запустить семантический поиск любым из следующих способов:
- По заданному индексу или списку индексов в наборе данных:
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())
from ultralytics import Explorer
# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()
similar = exp.get_similar(idx=1, limit=10)
print(similar.head())
# Search using multiple indices
similar = exp.get_similar(idx=[1, 10], 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()
from ultralytics import Explorer
# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()
plt = exp.plot_similar(idx=1, limit=10)
plt.show()
2. Задавайте вопросы ИИ (запросы на естественном языке)
Это позволяет вам писать, как вы хотите фильтровать свой набор данных, используя естественный язык. Вам не обязательно уметь писать SQL-запросы. Наш генератор запросов на основе искусственного интеллекта автоматически сделает это под капотом. Например, вы можете сказать: "покажи мне 100 изображений ровно с одним человеком и 2 собаками. Там могут быть и другие объекты", и он внутренне сгенерирует запрос и покажет вам эти результаты. Примечание: это работает с использованием LLM под капотом, поэтому результаты являются вероятностными и иногда могут быть неверными.
Ask AI
from ultralytics import Explorer
from ultralytics.data.explorer import plot_query_result
# 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 с результатами.
SQL-запрос
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
и отображает результаты в виде сетки.
Построение результатов SQL-запроса
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
Совет
Explorer работает на LanceDB таблицы внутри. Вы можете получить прямой доступ к этой таблице, используя 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=...)
Более подробную информацию о доступных типах векторных индексов и параметрах конфигурации можно найти в документации по индексированию LanceDB. В будущем мы планируем поддерживать создание векторных индексов непосредственно через Explorer API.
5. Применение эмбеддингов
Вы можете использовать таблицу embeddings для выполнения различных исследовательских анализов. Вот несколько примеров:
Индекс сходства
Explorer поставляется с similarity_index
операция:
- Он пытается оценить, насколько схож каждый элемент данных с остальным набором данных.
- Это происходит путем подсчета количества вложений изображений, которые находятся ближе, чем
max_dist
к текущему изображению в сгенерированном пространстве встраивания, учитываяtop_k
похожих изображений за раз.
Он возвращает pandas dataframe со следующими столбцами:
idx
: Индекс изображения в наборе данныхim_file
: Путь к файлу изображенияcount
: Количество изображений в наборе данных, которые находятся ближе, чемmax_dist
к текущему изображениюsim_im_files
: Список путей кcount
похожие изображения
Совет
Для данного набора данных, модели, max_dist
& top_k
сгенерированный индекс подобия будет использоваться повторно. Если ваш набор данных изменился или вам просто необходимо повторно сгенерировать индекс подобия, вы можете передать force=True
.
Индекс сходства
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
Скоро
- [ ] Объединение определенных меток из наборов данных. Пример - Импортировать все
person
метки из COCO иcar
метки из Cityscapes - [ ] Удалять изображения, индекс сходства которых выше заданного порога
- [ ] Автоматически сохранять новые наборы данных после объединения/удаления записей
- [ ] Расширенная визуализация набора данных
Часто задаваемые вопросы
Для чего используется Ultralytics Explorer API?
API Ultralytics Explorer предназначен для всестороннего исследования наборов данных. Он позволяет пользователям фильтровать и искать наборы данных с помощью SQL-запросов, поиска векторного сходства и семантического поиска. Этот мощный API на языке Python может обрабатывать большие наборы данных, что делает его идеальным для различных задач компьютерного зрения с использованием моделей Ultralytics.
Как установить API Ultralytics Explorer?
Чтобы установить Ultralytics Explorer API вместе с его зависимостями, используйте следующую команду:
pip install ultralytics[explorer]
Это автоматически установит все необходимые внешние библиотеки для функциональности Explorer API. Для получения дополнительной информации об установке обратитесь к разделу установки в нашей документации.
Как я могу использовать API Ultralytics Explorer для поиска по сходству?
Вы можете использовать Ultralytics Explorer API для выполнения поиска по сходству, создав таблицу embeddings и запросив в ней похожие изображения. Вот основной пример:
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, предоставляет масштабируемые таблиц embeddings на диске. Это гарантирует, что вы можете создавать и повторно использовать embeddings для больших наборов данных, таких как COCO, не исчерпав память. Эти таблицы создаются только один раз и могут быть использованы повторно, что повышает эффективность обработки данных.
Как работает функция Ask AI в Ultralytics Explorer API?
Функция Ask AI позволяет пользователям фильтровать наборы данных, используя запросы на естественном языке. Эта функция использует LLM для преобразования этих запросов в 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())
Дополнительные примеры можно найти в разделе Ask AI.