Ultralytics Explorer API#

Giới thiệu#

Explorer API là một Python API dùng để khám phá các tập dữ liệu của bạn. API này hỗ trợ lọc và tìm kiếm tập dữ liệu của bạn bằng các truy vấn SQL, tìm kiếm độ tương đồng véc-tơ và tìm kiếm ngữ nghĩa.

Cài đặt#

Explorer phụ thuộc vào các thư viện bên ngoài cho một số chức năng. Các thư viện này sẽ được tự động cài đặt khi bạn sử dụng Explorer. Để cài đặt thủ công các dependency 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)

Nếu muốn buộc cập nhật bảng embeddings, bạn có thể truyền force=True vào method 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ề nội dung này trong phần Làm việc với bảng Embeddings

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

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

• Trên một index hoặc danh sách các index cụ thể 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 thuộc dataset: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

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

Bạn nhận được một pandas DataFrame với limit điểm dữ liệu tương tự 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 để tiếp tục lọc.

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ẽ các hình ảnh tương tự#

Bạn cũng có thể vẽ các hình ảnh tương tự bằng method plot_similar. Method này nhận các đối số giống như get_similar và vẽ các hình ảnh tương tự trong một 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 ngôn ngữ tự nhiên)#

Tính năng này cho phép bạn lọc dataset bằng ngôn ngữ tự nhiên mà không cần viết SQL. Trình tạo truy vấn sử dụng AI sẽ chuyển prompt 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ể yêu cầu: "hiển thị cho tôi 100 hình ảnh có chính xác một người và 2 con chó. Có thể có cả các đối tượng khác" và hệ thống sẽ tạo truy vấn rồi hiển thị các kết quả đó. Lưu ý: Tính năng này sử dụng 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 truy vấn SQL trên dataset bằng method sql_query. Method này nhận một truy vấn SQL làm đầu vào và trả về pandas DataFrame chứa các 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ẽ kết quả truy vấn SQL#

Bạn cũng có thể vẽ kết quả của một truy vấn SQL bằng method plot_sql_query. Method này nhận các đối số giống như sql_query và vẽ kết quả trong một 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. Sau khi bảng embeddings được tạo, bạn có thể truy cập bảng bằ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ể thực hiện 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 các 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 Vector Index#

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. Thao tác này được thực hiện bằng method create_index trên bảng LanceDB.

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

5. Ứng dụng của Embeddings#

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

Chỉ số tương đồng#

Explorer cung cấp một operation similarity_index:

• Thao tác này 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 dataset.
• Operation thực hiện việc này bằng cách đếm số embeddings hình ảnh nằm gần hơn max_dist so với hình ảnh hiện tại trong không gian embedding đã tạo, đồng thời xem xét top_k hình ảnh tương tự mỗi lần.

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

• idx: Index của hình ảnh trong dataset
• im_file: Đường dẫn đến tệp hình ảnh
• count: Số hình ảnh trong dataset gần hơn max_dist so với hình ảnh hiện tại
• sim_im_files: Danh sách đườ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 similarity index để xây dựng các điều kiện tùy chỉnh nhằm lọc dataset. Ví dụ, bạn có thể lọc bỏ những hình ảnh không tương tự bất kỳ hình ảnh nào khác trong dataset bằng đoạn code 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ẽ tùy chọn. 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()

Hãy bắt đầu tạo các báo cáo khám phá dataset CV của riêng bạn bằng Explorer API. Để tham khảo ý tưởng, hãy xem Ví dụ khám phá VOC.

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

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

FAQ#