Ultralytics Explorer API'si
ultralytics>=8.3.12 sürümü itibarıyla Ultralytics Explorer kaldırılmıştır. Explorer'ı kullanmak için pip install ultralytics==8.3.11 yükle. Benzer (ve genişletilmiş) veri kümesi keşif özellikleri Ultralytics Platform üzerinde kullanılabilir.
Giriş#
Explorer API, veri kümelerini keşfetmeye yönelik bir Python API'sidir. Veri kümeni SQL sorgularıyla filtrelemeyi ve aramayı, vektör benzerliği aramasını ve anlamsal aramayı destekler.
İzle: Ultralytics Explorer API'ye Genel Bakış
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ömme tablosunu güncellemeyi zorlamak için create_embeddings_table yöntemine force=True değerini ilet.
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ı#
Vektör arama olarak da bilinen benzerlik araması, verilen bir görüntüye benzeyen görüntüleri bulma tekniğidir. Benzer görüntülerin benzer gömme vektörlerine sahip olacağı fikrine dayanır. Gömme tablosu oluşturulduktan sonra benzerlik aramasını aşağıdaki yöntemlerden 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 doğal dil kullanarak veri kümeni filtrelemene olanak tanır. 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; oluşturucu sorguyu üretir 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
# 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.
Explorer, arka planda LanceDB tablolarını kullanır. Bu tabloya Explorer.table nesnesini kullanarak doğrudan erişebilir; ham sorgular çalıştırabilir, ön ve son filtreleri aşağı itebilirsin.
from ultralytics import Explorer
exp = Explorer()
exp.create_embeddings_table()
table = exp.tableTabloyla 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_distuzaklığından daha yakın olan görüntü gömmelerini sayar ve her seferindetop_kbenzer 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 diziniim_file: Görüntü dosyasının yolucount: Mevcut görüntüyemax_distuzaklığından daha yakın olan veri kümesi görüntülerinin sayısısim_im_files:countbenzer görüntülerin yollarının listesi
Belirli bir veri kümesi, model, max_dist ve top_k için benzerlik dizini oluşturulduktan sonra yeniden kullanılır. Veri kümen değiştiyse veya benzerlik dizinini yeniden oluşturman gerekiyorsa force=True değerini ilet.
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 dizinini kullanabilirsin. Örneğin, aşağıdaki kod veri kümesinde 30'dan fazla benzer görüntüsü bulunan ve neredeyse yinelenen görüntüleri kaldırmak için uygun adaylar olan görüntüleri listeler:
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ı seçtiğin çizim aracıyla da görselleştirebilirsin. Gömme vektörlerini PCA ile indirgemeye ve Matplotlib ile çizmeye yönelik 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 GUI, Explorer API üzerine kuruludur.
Sık Sorulan Sorular#
Ultralytics Explorer API, veri kümesi keşfi için tasarlanmıştır. Veri kümelerini SQL sorguları, vektör benzerliği araması ve anlamsal aramayla filtrelemene ve aramana olanak tanır; ayrıca Ultralytics modelleriyle bilgisayarlı görü görevleri için büyük veri kümelerine ölçeklenebilir.
Ultralytics Explorer API’yi bağımlılıklarıyla birlikte yüklemek için aşağıdaki komutu kullan:
pip install "ultralytics[explorer]==8.3.11"Bu işlem, Explorer API işlevselliği için gerekli tüm harici kütüphaneleri otomatik olarak yükler. Ek kurulum ayrıntıları için belgelerimizin kurulum bölümüne bak.
Ultralytics Explorer API’yi, bir gömme tablosu oluşturup benzer görüntüler için bu tabloda sorgulama yaparak benzerlik aramaları gerçekleştirmek için kullanabilirsin. İşte basit bir örnek:
from ultralytics import Explorer # Bir Explorer nesnesi oluştur explorer = Explorer(data="coco128.yaml", model="yolo11n.pt") explorer.create_embeddings_table() # Verilen bir görüntüye benzer görüntüleri ara similar_images_df = explorer.get_similar(img="path/to/image.jpg") print(similar_images_df.head())Daha fazla bilgi için Benzerlik Araması bölümünü ziyaret et.
Ultralytics Explorer tarafından arka planda kullanılan LanceDB, ölçeklenebilir ve disk üzerinde saklanan gömme tabloları sunar. Böylece belleğin tükenmesi endişesi olmadan COCO gibi büyük veri kümeleri için gömmeler oluşturabilir ve yeniden kullanabilirsin. Bu tablolar yalnızca bir kez oluşturulur ve yeniden kullanılabilir; böylece veri işleme verimliliği artar.
Ask AI özelliği, doğal dil sorgularını kullanarak veri kümelerini filtrelemene olanak tanır. Bu özellik, sorguları arka planda SQL sorgularına dönüştürmek için LLM’lerden yararlanır. İşte bir örnek:
from ultralytics import Explorer # Bir Explorer nesnesi oluştur explorer = Explorer(data="coco128.yaml", model="yolo11n.pt") explorer.create_embeddings_table() # Doğal dil ile sorgula query_result = explorer.ask_ai("show me 100 images with exactly one person and 2 dogs. There can be other objects too") print(query_result.head())Daha fazla örnek için Ask AI bölümüne göz at.
Yorumlar2
Bir soru sor, sonuçlarını paylaş veya başka birine yardım et.
Jie LiuI have downloaded
ultralytics-8.3.118 github zip packageand install it withpip install -e .. Then I usepip install ultralytics[explorer]to install explorer, but I got a error as followedRequirement already satisfied: ultralytics[explorer] in /data/miniconda3/envs/app/lib/python3.10/site-packages (8.3.118) WARNING: ultralytics 8.3.118 does not provide the extra 'explorer' Requirement already satisfied: numpy<=2.1.1,>=1.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.26.4) Requirement already satisfied: matplotlib>=3.3.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (3.10.1) Requirement already satisfied: opencv-python>=4.6.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.11.0.86) Requirement already satisfied: pillow>=7.1.2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (11.2.1) Requirement already satisfied: pyyaml>=5.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (6.0.2) Requirement already satisfied: requests>=2.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.32.3) Requirement already satisfied: scipy>=1.4.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.15.2) Requirement already satisfied: torch>=1.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.3.1) Requirement already satisfied: torchvision>=0.9.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.18.1) Requirement already satisfied: tqdm>=4.64.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.67.1) Requirement already satisfied: psutil in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (7.0.0) Requirement already satisfied: py-cpuinfo in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (9.0.0) Requirement already satisfied: pandas>=1.1.4 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.2.3) Requirement already satisfied: seaborn>=0.11.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.13.2) Requirement already satisfied: ultralytics-thop>=2.0.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.0.14) Requirement already satisfied: contourpy>=1.0.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.3.2) Requirement already satisfied: cycler>=0.10 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (0.12.1) Requirement already satisfied: fonttools>=4.22.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (4.57.0) Requirement already satisfied: kiwisolver>=1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.4.8) Requirement already satisfied: packaging>=20.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (24.2) Requirement already satisfied: pyparsing>=2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (3.2.3) Requirement already satisfied: python-dateutil>=2.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (2.9.0.post0) Requirement already satisfied: pytz>=2020.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2022.7.1) Requirement already satisfied: tzdata>=2022.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2025.2) Requirement already satisfied: charset-normalizer<4,>=2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.4.1) Requirement already satisfied: idna<4,>=2.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.10) Requirement already satisfied: urllib3<3,>=1.21.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (1.26.20) Requirement already satisfied: certifi>=2017.4.17 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (2025.4.26) Requirement already satisfied: filelock in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.18.0) Requirement already satisfied: typing-extensions>=4.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (4.13.2) Requirement already satisfied: sympy in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (1.13.3) Requirement already satisfied: networkx in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.4.2) Requirement already satisfied: jinja2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.1.6) Requirement already satisfied: fsspec in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2025.3.2) Requirement already satisfied: nvidia-cuda-nvrtc-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: nvidia-cuda-runtime-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: nvidia-cuda-cupti-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: nvidia-cudnn-cu12==8.9.2.26 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (8.9.2.26) Requirement already satisfied: nvidia-cublas-cu12==12.1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.3.1) Requirement already satisfied: nvidia-cufft-cu12==11.0.2.54 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.0.2.54) Requirement already satisfied: nvidia-curand-cu12==10.3.2.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (10.3.2.106) Requirement already satisfied: nvidia-cusolver-cu12==11.4.5.107 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.4.5.107) Requirement already satisfied: nvidia-cusparse-cu12==12.1.0.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.0.106) Requirement already satisfied: nvidia-nccl-cu12==2.20.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.20.5) Requirement already satisfied: nvidia-nvtx-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: triton==2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.3.1) Requirement already satisfied: nvidia-nvjitlink-cu12 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from nvidia-cusolver-cu12==11.4.5.107->torch>=1.8.0->ultralytics[explorer]) (12.8.93) Requirement already satisfied: six>=1.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from python-dateutil>=2.7->matplotlib>=3.3.0->ultralytics[explorer]) (1.17.0) Requirement already satisfied: MarkupSafe>=2.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from jinja2->torch>=1.8.0->ultralytics[explorer]) (3.0.2) Requirement already satisfied: mpmath<1.4,>=1.1.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from sympy->torch>=1.8.0->ultralytics[explorer]) (1.3.0)when run code
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 dataframe = explorer.get_similar(img="path/to/image.jpg") # Or search for similar images to a given index/indices dataframe = explorer.get_similar(idx=0)The error has arisen
Traceback (most recent call last): File "/data/liujie/data/ultralytics-8.3.13/tutorial/debug/explorer.py", line 1, in <module> from ultralytics import Explorer ImportError: cannot import name 'Explorer' from 'ultralytics' (/data/liujie/data/ultralytics-8.3.118/ultralytics/__init__.py)please help me to install and use explorer
Glenn JocherUltralytics(düzenlendi)Hi @keeper-jie,
The issue you're experiencing is because Ultralytics Explorer has been removed since version 8.3.12, and you're using version 8.3.118. That's why you're seeing the warning that the 'explorer' extra is not provided and why you can't import the Explorer class.
As noted in our documentation, we've moved this functionality to Ultralytics Platform, our platform that offers similar and enhanced capabilities for exploring, visualizing, and managing your datasets without writing code.
If you specifically need the Explorer API functionality in your code, you would need to downgrade to a version prior to 8.3.12. However, we recommend trying Ultralytics Platform instead, as it provides an improved experience with all the dataset exploration features you're looking for.
Let me know if you need any further assistance with Ultralytics Platform or if you have any other questions.