Ultralytics Explorer API#

Giới thiệu#

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.

Cài đặt#

Explorer phụ thuộc vào các thư viện bên ngoài cho một số tính năng của nó. Các thư viện này được tự động cài đặt khi bạn sử dụng Explorer. Để cài đặt thủ công các phần phụ thuộc này, hãy sử dụng lệnh sau:

pip install ultralytics[explorer]

Cách sử dụng#

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)

Trong trường hợp bạn muốn bắt buộc cập nhật bảng embeddings, bạn có thể truyền force=True vào phương thức create_embeddings_table.

Bạn có thể truy cập trực tiếp đối tượng bảng LanceDB để thực hiện phân tích nâng cao. Tìm hiểu thêm về tính năng này trong phần Working with Embeddings Table section

1. Tìm kiếm độ tương đồng#

Tìm kiếm độ tương đồng là một kỹ thuật tìm kiếm các hình ảnh tương tự với một hình ảnh cho trước. Nó dựa trên ý tưởng rằng các hình ảnh tương tự sẽ có các embeddings tương tự nhau. Khi bảng embeddings được xây dựng, bạn có thể chạy tìm kiếm ngữ nghĩa bằng bất kỳ cách nào sau đây:

• Trên một chỉ mục cụ thể hoặc danh sách các chỉ mục trong dataset: exp.get_similar(idx=[1,10], limit=10)
• Trên bất kỳ hình ảnh hoặc danh sách hình ảnh nào không có trong dataset: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

Trong trường hợp có nhiều đầu vào, tổng hợp các embeddings của chúng sẽ được sử dụng.

Bạn nhận được một pandas DataFrame với số lượng limit điểm dữ liệu có độ tương đồng cao nhất với đầu vào, cùng với khoảng cách của chúng trong không gian embedding. Bạn có thể sử dụng dataset này để thực hiện lọc bổ sung.

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

Vẽ biểu đồ các hình ảnh tương tự#

Bạn cũng có thể vẽ biểu đồ cho các hình ảnh tương tự bằng phương thức plot_similar. Phương thức này nhận các tham số giống như get_similar và vẽ biểu đồ các hình ảnh tương tự theo dạng lưới.

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. Hỏi AI (Truy vấn bằng ngôn ngữ tự nhiên)#

Tính năng này cho phép bạn lọc tập dữ liệu của mình bằng ngôn ngữ tự nhiên mà không cần viết SQL. Trình tạo truy vấn được hỗ trợ bởi AI sẽ chuyển đổi câu lệnh của bạn thành một truy vấn và trả về các kết quả phù hợp. Ví dụ, bạn có thể hỏi: "hiển thị cho tôi 100 hình ảnh có đúng một người và 2 con chó. Cũng có thể có các đối tượng khác" và nó sẽ tạo truy vấn và hiển thị cho bạn các kết quả đó. Lưu ý: Tính năng này sử dụng các LLM, vì vậy kết quả mang tính xác suất và có thể không chính xác.

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. Truy vấn SQL#

Bạn có thể chạy các câu lệnh SQL trên dataset của mình bằng phương thức sql_query. Phương thức này nhận một câu lệnh SQL làm đầu vào và trả về một pandas DataFrame chứa kết quả.

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

Vẽ biểu đồ kết quả truy vấn SQL#

Bạn cũng có thể vẽ biểu đồ kết quả của một câu lệnh SQL bằng phương thức plot_sql_query. Phương thức này nhận các tham số giống như sql_query và vẽ biểu đồ kết quả theo dạng lưới.

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. Làm việc với Bảng Embeddings#

Bạn cũng có thể làm việc trực tiếp với bảng embeddings. Khi bảng embeddings được tạo, bạn có thể truy cập bảng này bằng cách sử dụng Explorer.table

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()
table = exp.table

Dưới đây là một số ví dụ về những gì bạn có thể làm với bảng:

Lấy Embeddings thô#

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()
table = exp.table

embeddings = table.to_pandas()["vector"]
print(embeddings)

Truy vấn nâng cao với bộ lọc trước và sau#

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)

Tạo chỉ mục Vector#

Khi sử dụng các dataset lớn, bạn cũng có thể tạo một vector index chuyên dụng để truy vấn nhanh hơn. Quá trình này được thực hiện bằng cách sử dụng phương thức create_index trên bảng LanceDB.

table.create_index(num_partitions=..., num_sub_vectors=...)

5. Các ứng dụng Embeddings#

Bạn có thể sử dụng bảng embeddings để thực hiện nhiều phân tích khám phá khác nhau. Dưới đây là một số ví dụ:

Chỉ mục độ tương đồng#

Explorer đi kèm với một thao tác similarity_index:

• Nó cố gắng ước tính mức độ tương đồng của từng điểm dữ liệu với phần còn lại của tập dữ liệu.
• Thao tác này thực hiện bằng cách đếm số lượng image embeddings nằm gần hình ảnh hiện tại hơn khoảng cách max_dist trong không gian embedding đã tạo, xem xét top_k hình ảnh tương tự tại một thời điểm.

Nó trả về một pandas DataFrame với các cột sau:

• idx: Chỉ mục của hình ảnh trong dataset
• im_file: Đường dẫn đến tệp hình ảnh
• count: Số lượng hình ảnh trong dataset có khoảng cách gần hơn max_dist so với hình ảnh hiện tại
• sim_im_files: Danh sách các đường dẫn đến count hình ảnh tương tự

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Bạn có thể sử dụng chỉ mục độ tương đồng để xây dựng các điều kiện tùy chỉnh nhằm lọc tập dữ liệu. Ví dụ, bạn có thể lọc ra các hình ảnh không tương đồng với bất kỳ hình ảnh nào khác trong tập dữ liệu bằng đoạn mã sau:

import numpy as np

sim_count = np.array(sim_idx["count"])
sim_idx["im_file"][sim_count > 30]

Trực quan hóa Không gian Embedding#

Bạn cũng có thể trực quan hóa không gian embedding bằng công cụ vẽ biểu đồ tùy chọn của mình. Ví dụ dưới đây là một ví dụ đơn giản sử dụng 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()

Bắt đầu tạo các báo cáo khám phá dataset CV của riêng bạn bằng cách sử dụng Explorer API. Để lấy cảm hứng, hãy xem qua VOC Exploration Example.

Các ứng dụng được xây dựng bằng Ultralytics Explorer#

Hãy thử GUI Demo của chúng tôi dựa trên Explorer API

Câu hỏi thường gặp#