Ultralytics Explorer API#

مقدمة#

The Explorer API is a Python API for exploring your datasets. It supports filtering and searching your dataset using SQL queries, vector similarity search, and semantic search.

التثبيت#

يعتمد Explorer على مكتبات خارجية لبعض وظائفه. يتم تثبيت هذه المكتبات تلقائياً عند استخدام Explorer. لتثبيت هذه التبعيات يدوياً، استخدم الأمر التالي:

pip install ultralytics[explorer]

الاستخدام#

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)

في حال كنت تريد فرض تحديث جدول التضمينات، يمكنك تمرير force=True إلى طريقة create_embeddings_table.

يمكنك الوصول مباشرة إلى كائن جدول LanceDB لإجراء تحليل متقدم. تعرف على المزيد حول ذلك في قسم العمل مع جدول التضمينات

1. البحث عن التشابه#

البحث عن التشابه هو تقنية للعثور على صور مشابهة لصورة معينة. يعتمد على فكرة أن الصور المتشابهةจะมี تضمينات متشابهة. بمجرد بناء جدول التضمينات، يمكنك تشغيل البحث الدلالي بأي من الطرق التالية:

• على مؤشر معين أو قائمة من المؤشرات في مجموعة البيانات: exp.get_similar(idx=[1,10], limit=10)
• على أي صورة أو قائمة صور غير موجودة في مجموعة البيانات: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

في حالة وجود مدخلات متعددة، يتم استخدام إجمالي تضميناتها.

تحصل على pandas DataFrame مع عدد limit لنقاط البيانات الأكثر تشابهاً مع المدخلات، إلى جانب مسافتها في فضاء التضمين. يمكنك استخدام مجموعة البيانات هذه لإجراء مزيد من التصفية.

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

رسم الصور المتشابهة#

يمكنك أيضاً رسم الصور المتشابهة باستخدام طريقة plot_similar. تأخذ هذه الطريقة نفس الوسائط مثل get_similar وترسم الصور المتشابهة في شبكة.

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. اسأل الذكاء الاصطناعي (الاستعلام باللغة الطبيعية)#

تتيح لك هذه الميزة تصفية مجموعة البيانات الخاصة بك باستخدام اللغة الطبيعية، دون كتابة SQL. يقوم منشئ الاستعلام المدعوم بالذكاء الاصطناعي بتحويل مطالبتك إلى استعلام وإرجاع النتائج المطابقة. على سبيل المثال، يمكنك أن تسأل: "show me 100 images with exactly one person and 2 dogs. There can be other objects too" وسيقوم بإنشاء الاستعلام وعرض تلك النتائج لك. ملاحظة: تستخدم هذه الميزة نماذج لغوية كبرى (LLMs)، لذا فإن النتائج احتمالية وقد تكون غير دقيقة.

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#

يمكنك تشغيل استعلامات SQL على مجموعة البيانات الخاصة بك باستخدام طريقة sql_query. تأخذ هذه الطريقة استعلام SQL كمدخل وتعيد pandas DataFrame بالنتائج.

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#

يمكنك أيضاً رسم نتائج استعلام SQL باستخدام طريقة plot_sql_query. تأخذ هذه الطريقة نفس الوسائط مثل sql_query وترسم النتائج في شبكة.

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. العمل مع جدول التضمينات#

يمكنك أيضاً العمل مع جدول التضمينات مباشرة. بمجرد إنشاء جدول التضمينات، يمكنك الوصول إليه باستخدام Explorer.table

from ultralytics import Explorer

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

فيما يلي بعض الأمثلة على ما يمكنك فعله بالجدول:

الحصول على التضمينات الخام#

from ultralytics import Explorer

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

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

الاستعلام المتقدم مع المرشحات القبلية والبعدية#

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)

إنشاء فهرس المتجهات#

عند استخدام مجموعات بيانات ضخمة، يمكنك أيضاً إنشاء مؤشر متجه مخصص لاستعلام أسرع. يتم ذلك باستخدام طريقة create_index على جدول LanceDB.

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

5. تطبيقات التضمينات#

يمكنك استخدام جدول التضمينات لإجراء مجموعة متنوعة من التحليلات الاستكشافية. وفيما يلي بعض الأمثلة:

فهرس التشابه#

يأتي Explorer مع عملية similarity_index:

• وهو يحاول تقدير مدى تشابه كل نقطة بيانات مع بقية مجموعة البيانات.
• يقوم بذلك عن طريق حساب عدد تضمينات الصور الأقرب من max_dist إلى الصورة الحالية في فضاء التضمين المُنشأ، مع الأخذ في الاعتبار top_k صورة متشابهة في كل مرة.

يعيد إطار بيانات pandas DataFrame بالأعمدة التالية:

• idx: مؤشر الصورة في مجموعة البيانات
• im_file: مسار ملف الصورة
• count: عدد الصور في مجموعة البيانات التي هي أقرب من max_dist إلى الصورة الحالية
• sim_im_files: قائمة المسارات إلى الصور المتشابهة count

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

يمكنك استخدام فهرس التشابه لبناء شروط مخصصة لتصفية مجموعة البيانات. على سبيل المثال، يمكنك تصفية الصور التي لا تشبه أي صورة أخرى في مجموعة البيانات باستخدام الكود التالي:

import numpy as np

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

تصور فضاء التضمين#

يمكنك أيضًا تصور فضاء التضمين باستخدام أداة الرسم التي تفضلها. على سبيل المثال، إليك مثال بسيط باستخدام 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()

ابدأ في إنشاء تقارير استكشاف مجموعة بيانات الرؤية الحاسوبية الخاصة بك باستخدام Explorer API. للحصول على الإلهام، راجع مثال استكشاف VOC.

التطبيقات المبنية باستخدام Ultralytics Explorer#

جرب العرض التوضيحي لواجهة المستخدم الرسومية الخاص بنا المستند إلى Explorer API

الأسئلة الشائعة#