Ultralytics Explorer API#

Giới thiệu#

Explorer API là Python API để khám phá các bộ dữ liệu của bạn. API hỗ trợ lọc và tìm kiếm trong bộ dữ liệu bằng truy vấn SQL, tìm kiếm độ tương đồng vector 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 để cung cấp một số chức năng. Các thư viện này sẽ được cài đặt tự động khi bạn sử dụng Explorer. Để cài đặt thủ công các dependency này, hãy dùng lệnh sau:

pip install "ultralytics[explorer]==8.3.11"

Cách sử dụng#

from ultralytics import Explorer

# Tạo đối tượng Explorer
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")

# Tạo embedding cho bộ dữ liệu
explorer.create_embeddings_table()

# Tìm kiếm hình ảnh tương tự với một hoặc nhiều hình ảnh cho trước
df = explorer.get_similar(img="path/to/image.jpg")

# Hoặc tìm kiếm hình ảnh tương tự với một hoặc nhiều chỉ mục cho trước
df = explorer.get_similar(idx=0)

Nếu muốn buộc cập nhật bảng embedding, 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 trong phần Làm việc với bảng Embedding.

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

Tìm kiếm độ tương đồng là kỹ thuật tìm 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ó embedding tương tự. Sau khi tạo bảng embedding, bạn có thể chạy tìm kiếm độ tương đồng theo bất kỳ cách nào sau đây:

• Trên một chỉ mục hoặc danh sách chỉ mục nhất định trong bộ dữ liệu: 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 bộ dữ liệu: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

Nếu có nhiều đầu vào, hệ thống sẽ sử dụng embedding tổng hợp của chúng.

Bạn nhận được một pandas DataFrame chứa limit điểm dữ liệu tương tự nhất với đầu vào, cùng với khoảng cách giữa chúng trong không gian embedding. Bạn có thể dùng bộ dữ liệu này để tiếp tục lọc.

from ultralytics import Explorer

# tạo đối tượng 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())

# Tìm kiếm bằng nhiều hình ảnh
similar = exp.get_similar(
    img=["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/bus.jpg"],
    limit=10,
)
print(similar.head())

Vẽ hình ảnh tương tự#

Bạn cũng có thể vẽ 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ẽ các hình ảnh tương tự theo dạng lưới.

from ultralytics import Explorer

# tạo đối tượng 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 (Truy vấn bằng ngôn ngữ tự nhiên)#

Tính năng này cho phép bạn lọc bộ dữ liệu bằng ngôn ngữ tự nhiên mà không cần viết SQL. Trình tạo truy vấn ứng dụng AI chuyển prompt của bạn thành 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 đối tượng khác nữa"; tính năng sẽ tạo truy vấn và 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

# tạo đối tượng 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())

# vẽ kết quả
plt = plot_query_result(df)
plt.show()

3. Truy vấn SQL#

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

from ultralytics import Explorer

# tạo đối tượng 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())

Vẽ kết quả truy vấn SQL#

Bạn cũng có thể vẽ kết quả của truy vấn 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ẽ kết quả theo dạng lưới.

from ultralytics import Explorer

# tạo đối tượng Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# vẽ Truy vấn SQL
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

4. Làm việc với bảng Embedding#

Bạn cũng có thể làm việc trực tiếp với bảng embedding. Sau khi tạo bảng embedding, 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 việc bạn có thể thực hiện với bảng:

Lấy embedding 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

# Embedding giả
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 bộ dữ liệu lớn, bạn cũng có thể tạo chỉ mục vector chuyên dụng để truy vấn nhanh hơn. Thực hiện việc này bằng phương thức create_index trên bảng LanceDB.

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

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

Bạn có thể dùng bảng embedding để 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 có sẵn thao tác similarity_index:

• Thao tác này ướ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 bộ dữ liệu.
• Thao tác này đếm số embedding hình ảnh nằm gần hình ảnh hiện tại hơn max_dist trong không gian embedding được tạo, đồng thời xét top_k hình ảnh tương tự mỗi lần.

Thao tác này trả về pandas DataFrame với các cột sau:

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

import matplotlib.pyplot as plt
from sklearn.decomposition import PCA

# Giảm số chiều xuống còn 3 thành phần bằng PCA để trực quan hóa trong không gian 3D
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Tạo biểu đồ phân tán 3D bằng Matplotlib Axes3D
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# Biểu đồ phân tán
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 báo cáo khám phá bộ dữ liệu 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.

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

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

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