واجهة Explorer API من Ultralytics#

مقدمة#

واجهة برمجة تطبيقات المستكشف (Explorer API) هي واجهة برمجة تطبيقات بايثون (Python) استكشاف مجموعات البيانات الخاصة بك. وهي تدعم تصفية والبحث في مجموعة بياناتك باستخدام استعلامات لغة الاستعلامات المركبة (SQL)، والبحث عن التشابه المتجهي، والبحث الدلالي.

التثبيت#

يعتمد 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. ويحوّل مولّد الاستعلامات المدعوم بالذكاء الاصطناعي طلبك إلى استعلام ويعرض النتائج المطابقة. على سبيل المثال، يمكنك أن تطلب: "اعرض لي 100 صورة تحتوي كل واحدة منها على شخص واحد بالضبط و2 من الكلاب. يمكن أن توجد كائنات أخرى أيضًا"، وسيُنشئ الاستعلام ويعرض لك تلك النتائج. ملاحظة: تستخدم هذه الميزة نماذج اللغة الكبيرة (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

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