Ultralytics Explorer API'si#

Giriş#

Explorer API'si, veri kümelerini keşfetmeye yönelik bir Python API'sidir. Veri kümeni SQL sorguları, vektör benzerliği araması ve anlamsal aramayla filtrelemeyi ve aramayı destekler.

Kurulum#

Explorer, bazı işlevleri için harici kütüphanelere ihtiyaç duyar. Explorer'ı kullandığında bu kütüphaneler otomatik olarak yüklenir. Bu bağımlılıkları elle yüklemek için aşağıdaki komutu kullan:

pip install "ultralytics[explorer]==8.3.11"

Kullanım#

from ultralytics import Explorer

# Bir Explorer nesnesi oluştur
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")

# Veri kümen için gömmeler oluştur
explorer.create_embeddings_table()

# Verilen bir görüntüye/görüntülere benzer görüntüleri ara
df = explorer.get_similar(img="path/to/image.jpg")

# Ya da verilen bir dizine/dizinlere benzer görüntüleri ara
df = explorer.get_similar(idx=0)

Gömmeler tablosunu zorla güncellemek istersen create_embeddings_table yöntemine force=True parametresini iletebilirsin.

Gelişmiş analizler yapmak için LanceDB tablo nesnesine doğrudan erişebilirsin. Daha fazla bilgi için Gömmeler Tablosuyla Çalışma bölümüne bak.

1. Benzerlik Araması#

Benzerlik araması, verilen bir görüntüye benzeyen görüntüleri bulma tekniğidir. Benzer görüntülerin benzer gömmelere sahip olacağı fikrine dayanır. Gömmeler tablosu oluşturulduktan sonra benzerlik aramasını aşağıdaki yollardan herhangi biriyle çalıştırabilirsin:

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

Birden fazla girdi olması durumunda, gömmelerinin toplamı kullanılır.

Girdiyle en çok benzer limit veri noktasını ve bunların gömme uzayındaki uzaklıklarını içeren bir pandas DataFrame elde edersin. Daha fazla filtreleme yapmak için bu veri kümesini kullanabilirsin.

from ultralytics import Explorer

# bir Explorer nesnesi oluştur
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())

# Birden fazla görüntü kullanarak ara
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 Çizdirme#

Benzer görüntüleri plot_similar yöntemiyle de çizdirebilirsin. Bu yöntem get_similar ile aynı bağımsız değişkenleri alır ve benzer görüntüleri bir ızgarada gösterir.

from ultralytics import Explorer

# bir Explorer nesnesi oluştur
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 (Doğal Dil Sorgulama)#

Bu özellik, SQL yazmadan veri kümeni doğal dil kullanarak filtrelemeni sağlar. Yapay zekâ destekli sorgu oluşturucu, istemini bir sorguya dönüştürür ve eşleşen sonuçları döndürür. Örneğin, "bana tam olarak bir kişi ve 2 köpek içeren 100 görüntü göster. Başka nesneler de olabilir" diye sorabilirsin; özellik sorguyu oluşturur ve sonuçları gösterir. Not: Bu özellik LLM'ler 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

# bir Explorer nesnesi oluştur
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())

# sonuçları çizdir
plt = plot_query_result(df)
plt.show()

3. SQL Sorgulama#

Veri kümen üzerinde sql_query yöntemini kullanarak SQL sorguları çalıştırabilirsin. Bu yöntem girdi olarak bir SQL sorgusu alır ve sonuçları içeren bir pandas DataFrame döndürür.

from ultralytics import Explorer

# bir Explorer nesnesi oluştur
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ı Çizdirme#

SQL sorgusunun sonuçlarını plot_sql_query yöntemini kullanarak da çizdirebilirsin. Bu yöntem sql_query ile aynı bağımsız değişkenleri alır ve sonuçları bir ızgarada gösterir.

from ultralytics import Explorer

# bir Explorer nesnesi oluştur
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# SQL Sorgusunu çizdir
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

4. Gömmeler Tablosuyla Çalışma#

Gömmeler tablosuyla doğrudan da çalışabilirsin. Gömmeler tablosu oluşturulduktan sonra tabloya Explorer.table kullanarak erişebilirsin.

from ultralytics import Explorer

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

Tabloyla yapabileceklerine dair birkaç örnek:

Ham Gömmeleri Al#

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

# Sahte gömme
embedding = [i for i in range(256)]
rs = table.search(embedding).metric("cosine").where("").limit(10)

Vektör Dizini Oluştur#

Büyük veri kümeleri kullanırken daha hızlı sorgulama için özel bir vektör dizini de oluşturabilirsin. Bunun için LanceDB tablosunda create_index yöntemi kullanılır.

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

5. Gömme Uygulamaları#

Çeşitli keşif amaçlı analizler yapmak için gömmeler tablosunu kullanabilirsin. İşte birkaç örnek:

Benzerlik İndeksi#

Explorer, similarity_index işlemini içerir:

• Bu işlem, her veri noktasının veri kümesinin geri kalanına ne kadar benzediğini tahmin etmeye çalışır.
• İşlem, oluşturulan gömme uzayında mevcut görüntüye max_dist uzaklığından daha yakın olan görüntü gömmelerini sayar ve her seferinde top_k benzer görüntüyü dikkate alır.

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: Mevcut görüntüye max_dist uzaklığından daha yakın olan veri kümesi görüntülerinin sayısı
• sim_im_files: count benzer görüntülerin 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ştururken benzerlik indeksini 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]

Gömme Uzayını Görselleştir#

Gömme uzayını istediğin çizim aracıyla görselleştirebilirsin. Örneğin, Matplotlib kullanan basit bir örnek:

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

# 3B görselleştirme için PCA kullanarak boyutları 3 bileşene indir
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Matplotlib Axes3D kullanarak 3B dağılım grafiği oluştur
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# Dağılım grafiği
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'sini 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 Geliştirilen Uygulamalar#

Explorer API'sini temel alan GUI Demomuzu dene

Sık Sorulan Sorular#