Ultralytics Explorer API#

Giriş#

Explorer API, veri kümelerini keşfetmeni sağlayan bir Python API'sidir. Veri kümelerini SQL sorguları, vektör benzerlik araması ve anlamsal arama kullanarak filtrelemeni ve aramanı destekler.

Kurulum#

Explorer, bazı işlevleri için harici kitaplıklara ihtiyaç duyar. Bunlar Explorer'ı kullandığında otomatik olarak yüklenir. Bu bağımlılıkları manuel olarak yüklemek için aşağıdaki komutu kullan:

pip install ultralytics[explorer]

Kullanım#

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)

Embedding'ler tablosunu zorla güncellemek istersen force=True değerini create_embeddings_table metoduna geçirebilirsin.

Gelişmiş analiz gerçekleştirmek için LanceDB tablo nesnesine doğrudan erişebilirsin. Daha fazla bilgi için Embedding'ler Tablosuyla Çalışma bölümüne göz at.

1. Benzerlik Araması#

Benzerlik araması, verilen bir görüntüye benzer görüntüleri bulma tekniğidir. Benzer görüntülerin benzer embedding'lere sahip olacağı fikrine dayanır. Embedding'ler tablosu oluşturulduktan sonra anlamsal aramayı aşağıdaki yöntemlerden herhangi biriyle çalıştırabilirsin:

• Veri kümesindeki belirli bir dizinde veya dizin listesinde: exp.get_similar(idx=[1,10], limit=10)
• Veri kümesinde bulunmayan herhangi bir görüntüde veya görüntü listesinde: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

Birden fazla girdi olması durumunda embedding'lerinin toplamı kullanılır.

Girdiyle en benzer limit veri noktası sayısını ve bunların embedding uzayındaki uzaklığını içeren bir pandas DataFrame elde edersin. Daha ileri filtreleme gerçekleştirmek için bu veri kümesini kullanabilirsin.

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

Benzer Görüntüleri Çizme#

Benzer görüntüleri plot_similar metodunu kullanarak da çizebilirsin. Bu metot, get_similar ile aynı bağımsız değişkenleri alır ve benzer görüntüleri bir ızgarada çizer.

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. AI'ya Sor (Doğal Dil Sorgulama)#

Bu özellik, SQL yazmadan veri kümeni doğal dil kullanarak filtrelemeni sağlar. AI destekli sorgu oluşturucu, istemini bir sorguya dönüştürür ve eşleşen sonuçları döndürür. Örneğin şunu sorabilirsin: "tam olarak bir kişi ve 2 köpek içeren 100 görüntü göster. Başka nesneler de olabilir"; bu özellik sorguyu oluşturur ve bu sonuçları gösterir. Not: Bu özellik LLM'leri kullanır; bu nedenle sonuçlar olasılıksaldır ve hatalı olabilir.

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. SQL Sorgulama#

sql_query metodunu kullanarak veri kümen üzerinde SQL sorguları çalıştırabilirsin. Bu metot, girdi olarak bir SQL sorgusu alır ve sonuçları içeren bir pandas DataFrame döndürür.

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 Sorgusu Sonuçlarını Çizme#

Bir SQL sorgusunun sonuçlarını plot_sql_query metodunu kullanarak da çizebilirsin. Bu metot, sql_query ile aynı bağımsız değişkenleri alır ve sonuçları bir ızgarada çizer.

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. Embedding'ler Tablosuyla Çalışma#

Embedding'ler tablosuyla doğrudan da çalışabilirsin. Embedding'ler tablosu oluşturulduktan sonra ona Explorer.table kullanarak erişebilirsin

from ultralytics import Explorer

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

Tabloyla yapabileceklerine ilişkin bazı örnekler:

Ham Embedding'leri Alma#

from ultralytics import Explorer

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

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

Ön ve Son Filtrelerle Gelişmiş Sorgulama#

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)

Vektör Dizini Oluşturma#

Büyük veri kümeleri kullanırken daha hızlı sorgulama için özel bir vektör dizini de oluşturabilirsin. Bu işlem, LanceDB tablosunda create_index metodu kullanılarak gerçekleştirilir.

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

5. Embedding Uygulamaları#

Çeşitli keşifsel analizler gerçekleştirmek için embedding'ler tablosunu kullanabilirsin. İşte bazı örnekler:

Benzerlik Dizini#

Explorer, similarity_index işlemiyle birlikte gelir:

• Her veri noktasının veri kümesinin geri kalanına ne kadar benzediğini tahmin etmeye çalışır.
• Bunu, oluşturulan embedding uzayında geçerli görüntüye max_dist değerinden daha yakın olan görüntü embedding'lerinin sayısını, aynı anda top_k benzer görüntüyü dikkate alarak hesaplayarak yapar.

Aşağıdaki sütunları içeren bir pandas DataFrame döndürür:

• idx: Görüntünün veri kümesindeki dizini
• im_file: Görüntü dosyasının yolu
• count: Geçerli görüntüye max_dist değerinden daha yakın olan veri kümesindeki görüntülerin sayısı
• sim_im_files: count benzer görüntünün yollarının listesi

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Veri kümesini filtrelemek için özel koşullar oluşturmak üzere benzerlik dizinini kullanabilirsin. Örneğin, aşağıdaki kodu kullanarak veri kümesindeki başka hiçbir görüntüye benzemeyen görüntüleri filtreleyebilirsin:

import numpy as np

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

Embedding Uzayını Görselleştirme#

Embedding uzayını seçtiğin çizim aracıyla da görselleştirebilirsin. Örneğin, Matplotlib kullanılarak hazırlanmış basit bir örnek:

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

Explorer API'yi kullanarak kendi CV veri kümesi keşif raporlarını oluşturmaya başla. İlham almak için VOC Keşif Örneğine göz at.

Ultralytics Explorer Kullanılarak Oluşturulan Uygulamalar#

Explorer API'yi temel alan GUI Demosunu dene

SSS#