إضافة Firestore Vector Search إلى تطبيقاتك المتوافقة مع الأجهزة الجوّالة باستخدام إضافات Firebase

1- نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية إضافة ميزات بحث فعّالة إلى تطبيقك باستخدام ميزة البحث في تشابه متجهات Firestore. ستنفذ ميزة البحث الدلالي لتطبيق تدوين الملاحظات المكتوب بلغة Swift وSwiftUI.

وحدة تحكّم Cloud Firestore تعرض بعض المستندات التي تظهر أيضًا في تطبيق iOS على الجانب الأيسر

المعلومات التي ستطّلع عليها

ما ستحتاجه

  • Xcode 15.3
  • تمثّل هذه السمة رمز الدرس التطبيقي حول الترميز. وستنزِّل هذا التطبيق في خطوة لاحقة من الدرس التطبيقي حول الترميز.

2- إنشاء مشروع على Firebase وإعداده

لاستخدام إضافة Firebase Vector Search، تحتاج إلى مشروع على Firebase. في هذا الجزء من الدرس التطبيقي حول الترميز، عليك إنشاء مشروع جديد في Firebase وتفعيل الخدمات المطلوبة، مثل Cloud Firestore و"مصادقة Firebase".

إنشاء مشروع على Firebase

  1. سجِّل الدخول إلى Firebase.
  2. في وحدة تحكُّم Firebase، انقر على إضافة مشروع، ثم أدخِل اسمًا لمشروعك Firestore Vector Search Labإنشاء مشروع، الخطوة 1 من 3: اختيار اسم المشروع
  3. انقر خلال خيارات إنشاء المشروع. اقبل بنود Firebase إذا طُلب منك ذلك.
  4. على شاشة "إحصاءات Google"، ألغِ تحديد المربع تفعيل "إحصاءات Google" لهذا المشروع، لأنك لن تستخدم "إحصاءات Google" لهذا التطبيق.
  5. وأخيرًا، انقر على إنشاء مشروع.

لمزيد من المعلومات عن مشاريع Firebase، راجِع المقالة فهم مشاريع Firebase.

تفعيل منتجات Firebase وإعدادها في وحدة التحكّم

يستخدم التطبيق الذي تُنشئه العديد من منتجات Firebase المتوفّرة لتطبيقات Apple:

  • مصادقة Firebase للسماح للمستخدمين بتسجيل الدخول إلى تطبيقك بسهولة.
  • Cloud Firestore لحفظ البيانات المنظَّمة على السحابة الإلكترونية وتلقّي إشعار فوري عند تغيير البيانات
  • قواعد أمان Firebase لتأمين قاعدة بياناتك

يجب ضبط بعض هذه المنتجات بشكل خاص أو تفعيلها باستخدام "وحدة تحكُّم Firebase".

تفعيل مصادقة مجهولة المصدر لمصادقة Firebase

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

  1. في اللوحة الجانبية اليمنى من "وحدة تحكّم Firebase"، انقر على إنشاء > المصادقة. بعد ذلك، انقر على البدء.تفعيل ميزة "الوصول إلى Firebase"
  2. أنت الآن في لوحة بيانات المصادقة، حيث يمكنك الاطّلاع على المستخدمين الذين سجَّلوا الدخول إلى حساباتهم وضبط مقدّمي خدمات تسجيل الدخول وإدارة الإعدادات.
  3. اختَر علامة التبويب طريقة تسجيل الدخول (أو انقر هنا للانتقال مباشرةً إلى علامة التبويب).
  4. انقر على مجهول من خيارات مقدّم الخدمة، وبدِّل المفتاح إلى تفعيل، ثم انقر على حفظ.

إعداد Cloud Firestore

يستخدم تطبيق Swift هذا Cloud Firestore لحفظ الملاحظات. في ما يلي كيفية إعداد Cloud Firestore:

  1. في اللوحة الجانبية اليمنى من "وحدة تحكُّم Firebase"، انقر على إنشاء > Firestore Database. بعد ذلك، انقر على إنشاء قاعدة بيانات.تفعيل Cloud Firestore
  2. اختَر الموقع الجغرافي لقاعدة بياناتك، مع الحرص على اختيار موقع جغرافي يتوفّر فيه Gemini (يمكنك فقط استخدام us-central1). مع ذلك، يُرجى العلم أنّه لا يمكن تغيير هذا الموقع الجغرافي لاحقًا. انقر على Next (التالي).
  3. حدِّد الخيار البدء في وضع الاختبار. قراءة بيان إخلاء المسؤولية بشأن قواعد الأمان يضمن وضع الاختبار إمكانية الكتابة بحرية في قاعدة البيانات أثناء التطوير.إعداد قواعد الأمان لـ Firestore في وضع الاختبار
  4. انقر على إنشاء لإنشاء قاعدة البيانات.

3- ربط التطبيق المتوافق مع الأجهزة الجوّالة

في هذا القسم من الدرس التطبيقي حول الترميز، ستنزِّل رمز المصدر لتطبيق بسيط لتدوين الملاحظات وربطه بمشروع Firebase الذي أنشأته للتو.

تنزيل نموذج التطبيق

  1. انتقِل إلى https://github.com/FirebaseExtended/codelab-firestore- الوضعsearch-ios واستنسِخ المستودع في جهازك المحلي
  2. فتح مشروع Notes.xcodeproj في Xcode

ربط التطبيق بمشروعك على Firebase

ولكي يتمكّن تطبيقك من الوصول إلى خدمات Firebase، ستحتاج إلى إعداد التطبيق في وحدة تحكُّم Firebase. يمكنك ربط تطبيقات عملاء متعدّدة بمشروع Firebase نفسه. على سبيل المثال، إذا أنشأت تطبيق Android أو تطبيق ويب، يجب ربطها بمشروع Firebase نفسه.

لمزيد من المعلومات عن مشاريع Firebase، راجِع المقالة فهم مشاريع Firebase.

  1. في "وحدة تحكُّم Firebase"، انتقِل إلى صفحة النظرة العامة لمشروع Firebase.صفحة النظرة العامة في "وحدة تحكُّم Firebase"
  2. انقر على رمز iOS+ لإضافة تطبيق iOS.
  3. في شاشة إضافة Firebase إلى تطبيق Apple، أدخِل معرِّف الحزمة من مشروع Xcode (com.google.firebase.codelab.Notes).
  4. يمكنك إدخال لقب التطبيق (Notes لنظام التشغيل iOS) إذا أردت ذلك.
  5. انقر على Register app (تسجيل التطبيق) للانتقال إلى الخطوة التالية.
  6. نزِّل ملف GoogleServices-Info.plist.
  7. اسحب GoogleServices-Info.plist إلى مجلد الملاحظات في مشروع Xcode. ومن الطرق الجيدة إجراء ذلك من خلال إفلاته أسفل ملف Assets.xcassets.سحب ملف plist إلى Xcode
  8. اختَر نسخ العناصر إذا لزم الأمر، وتأكّد من اختيار الهدف الملاحظات في إضافة إلى الأهداف، وانقر على إنهاء.تحديد "نسخ عند اللزوم" في مربّع حوار خيارات إضافة الملفات
  9. في "وحدة تحكُّم Firebase"، يمكنك الآن النقر على بقية خطوات عملية الإعداد: في النموذج الذي نزّلته في بداية هذا القسم، تم تثبيت Firebase Apple SDK وعملية الإعداد. يمكنك إنهاء العملية بالنقر على متابعة إلى وحدة التحكم.

تشغيل التطبيق

حان الوقت الآن لاختبار التطبيق!

  1. بالعودة إلى Xcode، شغِّل التطبيق على iOS Simulator. في القائمة المنسدلة Run Destinations (تشغيل الوجهات)، اختَر أولاً أحد "محاكيات iOS".تحديد محاكي iOS في القائمة المنسدلة "Run Destinations" (تشغيل الوجهات)
  2. بعد ذلك، انقر على الزر تشغيل، أو اضغط على ⌘ + R.
  3. بمجرد تشغيل التطبيق بنجاح على المحاكي، أضف بعض الملاحظات.
  4. في وحدة تحكُّم Firebase، انتقِل إلى متصفِّح البيانات على Firestore للاطّلاع على المستندات الجديدة التي يتم إنشاؤها عند إضافة ملاحظات جديدة في التطبيق.وحدة تحكّم Cloud Firestore تعرض بعض المستندات، إلى جانب iOS Simulator الذي يعرض المستندات نفسها

4- تثبيت إضافة Vector Search باستخدام الإضافة Firestore

في هذا الجزء من الدرس التطبيقي حول الترميز، ستثبت إضافة Vector Search باستخدام الإضافة Firestore، وستضبطها حسب متطلبات تطبيق تدوين الملاحظات الذي تعمل عليه.

بدء تثبيت الإضافة

  1. في قسم Firestore، انقر على علامة التبويب الإضافات.اختيار علامة تبويب "إضافات Firebase" في وحدة تحكُّم Firestore
  2. انقر على استكشاف مركز الإضافات.علامة تبويب "إضافات Firebase" في وحدة تحكُّم Firestore
  3. اكتب "متجه".
  4. انقر على "Vector Search with Firestore" (إضافة البحث المتجهي إلى متجر Firestore).الصفحة المقصودة لمركز Firebase Extenios سينقلك هذا الإجراء إلى صفحة تفاصيل الإضافة، حيث يمكنك الاطّلاع على مزيد من المعلومات حول الإضافة وآلية عملها وخدمات Firebase التي تتطلّبها وكيفية ضبطها.
  5. انقر على التثبيت في وحدة تحكُّم Firebase.زر التثبيت للإضافة Vector Search مع الإضافة Firestore
  6. ستظهر لك قائمة بجميع مشروعاتك.
  7. اختَر المشروع الذي أنشأته في الخطوة الأولى من هذا الدرس التطبيقي حول الترميز.شاشة أداة اختيار مشروع Firebase

إعداد الإضافة

تستفيد إضافات Firebase من وظائف السحابة الإلكترونية لبرنامج Firebase، والتي تتطلب أن يكون مشروعك على نظام الدفع حسب الاستخدام بليز. قبل أن تتمكّن من استخدام إضافة Vector Search مع الإضافة Firestore، عليك ترقية مشروعك.

  1. انقر على ترقية المشروع للمتابعة. ترقية المشروع إلى خطة Blaze
  2. اختَر حساب فوترة حاليًا أو أنشِئ حسابًا جديدًا. انقر على متابعة.اختيار حساب فوترة
  3. اضبط ميزانية (مثل 10 ريال سعودي)، وانقر على متابعة، ثم انقر على شراء.إعداد الميزانية
  4. مراجعة واجهات برمجة التطبيقات التي تم تفعيلها والموارد التي تم إنشاؤهامراجعة واجهات برمجة التطبيقات المفعَّلة
  5. فعِّل الخدمات المطلوبة.تفعيل الخدمات المطلوبة
  6. عند تفعيل Cloud Storage، اختَر وضع الاختبار لقواعد الأمان.
  7. تأكَّد من أنّ خدمة Cloud Storage ستستخدم الموقع نفسه الذي تستخدمه مثيل Cloud Firestore.
  8. بعد تفعيل جميع الخدمات، انقر على التالي.انقر على "التالي" بعد تفعيل جميع الخدمات.
  9. تم منح الإذن بالوصول إلى المراجعة لهذه الإضافة.
  10. اضبط الإضافة:
    • اختَر Vertex AI ليكون النموذج اللغوي الكبير.
    • مسار المجموعة: الملاحظات
    • الحد الأقصى التلقائي لطلبات البحث: 3
    • اسم حقل الإدخال: text
    • اسم حقل الإخراج: التضمين
    • اسم حقل الحالة:* *الحالة*
    • تضمين المستندات الحالية: نعم
    • تعديل المستندات الحالية: نعم
    • موقع دالة السحابة الإلكترونية: us-central1
  11. انقر على تثبيت الإضافة لإنهاء عملية التثبيت.

قد تستغرق هذه العملية بضع دقائق. أثناء انتظار اكتمال التثبيت، لا تتردد في الانتقال إلى القسم التالي من البرنامج التعليمي وقراءة بعض المعلومات الأساسية حول تضمينات المتجهات.

5- الخلفية

إليك بعض المعلومات الأساسية حول طريقة عمل الإضافة Vector Search with Firestore أثناء انتظار انتهاء عملية التثبيت.

ما هي المتجهات والتضمينات وقواعد بيانات المتجه؟

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

كيف تعمل ميزة "البحث المتجه"؟

يعمل بحث المتجه من خلال مقارنة متجه الاستعلام بجميع المتجهات في قاعدة البيانات. يتم إرجاع المتجهات الأكثر تشابهًا مع متجه الاستعلام كنتائج البحث.

يمكن قياس التشابه بين متجهَين باستخدام مجموعة متنوعة من مقاييس المسافة. مقياس المسافة الأكثر شيوعًا هو تشابه جيب التمام، الذي يقيس الزاوية بين متجهين.

6- جرِّب إضافة Vector Search مع الإضافة Firestore

قبل استخدام الإضافة Vector Search with Firestore في تطبيق iOS الذي نزّلته سابقًا في هذا الدرس التطبيقي حول الترميز، يمكنك تجربة الإضافة في وحدة تحكُّم Firebase.

قراءة المستندات

تتضمن إضافات Firebase وثائق عن آلية عملها.

  1. بعد الانتهاء من تثبيت الإضافة، انقر على الزر Get started (البدء). صفحة النظرة العامة على "إضافة Firebase" في "وحدة تحكُّم Firebase"
  2. يمكنك الاطلاع على علامة التبويب "آلية عمل هذه الإضافة" التي تشرح ما يلي:
    • وكيفية احتساب عمليات التضمين للمستندات من خلال إضافتها إلى مجموعة notes
    • كيفية الاستعلام في الفهرس من خلال استدعاء الدالة ext-firestore-vector-search-queryCallable القابلة للاستدعاء،
    • أو كيفية إجراء استعلام في الفهرس من خلال إضافة مستند استعلام إلى مجموعة _firestore-vector-search/index/queries.
    • ويوضّح أيضًا كيفية إعداد دالة تضمين مخصّصة، وهو أمر مفيد إذا لم تستوفِ أيّ من النماذج اللغوية الكبيرة المتوافقة مع الإضافة متطلباتك، وكنت تريد استخدام نموذج لغوي كبير مختلف لحساب عمليات التضمين. مستندات إضافة Vector Search مع Firestore
  3. انقر على رابط لوحة بيانات Cloud Firestore للانتقال إلى النسخة الافتراضية من Firestore.
  4. الانتقال إلى المستند "_firestore-vector-search/index" من المفترَض أن يظهر لك أنّ الإضافة قد انتهت من احتساب عمليات التضمين لجميع مستندات الملاحظات التي أنشأتها في خطوة سابقة في هذا الدرس التطبيقي حول الترميز.إعدادات الفهرس داخل وحدة التحكّم في Firestore
  5. للتحقّق من ذلك، افتح أحد مستندات الملاحظات، ومن المفترض أن يظهر لك حقل إضافي باسم embedding من النوع vector<768>، بالإضافة إلى حقل status.حقل تضمين متّجه داخل وحدة التحكّم في Firestore

إنشاء نموذج مستند

يمكنك إنشاء مستند جديد في "وحدة تحكُّم Firebase" للاطّلاع على الإضافة عمليًا.

  1. في متصفّح البيانات Firestore، انتقِل إلى مجموعة notes وانقر على + إضافة مستند في العمود الأوسط.إضافة مستند جديد
  2. انقر على Auto-ID لإنشاء معرّف مستند فريد جديد.
  3. أضف حقلاً يسمى text من نوع السلسلة، والصق بعض النصوص في حقل value. من المهم ألا يكون هذا lorem ipsum أو بعض النصوص العشوائية الأخرى. اختَر مقالة إخبارية، على سبيل المثال.إضافة حقل نصي
  4. انقر على حفظ.
    • لاحظ كيف تُضيف الإضافة حقل حالة للإشارة إلى أنّها تعالج البيانات.
    • بعد فترة قصيرة، من المفترض أن يظهر لك حقل جديد embedding بقيمة vector<768>.
    تحديث حالة تضمينات المتجه للمستند الجديد

إجراء طلب بحث

تحتوي الإضافة Vector Search with Firestore على ميزة رائعة تتيح لك إجراء طلب بحث في فهرس المستند بدون الحاجة إلى ربط تطبيق.

  1. في قسم Firestore ضِمن "وحدة تحكُّم Firebase"، انتقِل إلى المستند _firestore-vector-search/index.
  2. انقر على + بدء المجموعةإضافة مجموعة فرعية جديدة.
  3. إنشاء مجموعة فرعية جديدة باسم queries
  4. أنشِئ مستندًا جديدًا واضبط الحقل query على نص يظهر في أحد مستنداتك. هذه الطريقة مناسبة تمامًا لطلبات البحث الدلالية، مثل "كيف يمكنني ربط مستندات Firestore باستخدام Swift" (إذا كانت إحدى الملاحظات التي أضفتها على الأقل تحتوي على نص يناقش هذا الموضوع).إضافة حقل طلب بحث
  5. قد يظهر خطأ في الحالةحدث خطأ.
  6. والسبب في ذلك هو عدم وجود فهرس. لإعداد إعدادات الفهرس غير المتوفّرة، انتقِل إلى وحدة تحكُّم Google Cloud لمشروعك من خلال اتّباع هذا الرابط، ثم اختيار مشروعك من القائمة.اختيار المشروع الصحيح
  7. في مستكشف سجلّ السحابة الإلكترونية، من المفترض أن تظهر لك الآن رسالة خطأ مفادها "تعذّر_PRESTATUS: إعدادات فهرس المتجه غير متوفّرة. يُرجى إنشاء الفهرس المطلوب باستخدام الأمر gcloud التالي: ..."رسالة خطأ في مستكشف السجلّات
  8. تتضمّن رسالة الخطأ أيضًا الأمر gcloud الذي عليك تنفيذه لضبط الفهرس غير المتوفر.
  9. نفِّذ الأمر التالي من سطر الأوامر. إذا لم يكن لديك واجهة سطر الأوامر gcloud مثبَّتًا على جهازك، اتّبِع التعليمات الواردة هنا لتثبيته.
    gcloud alpha firestore indexes composite create --project=INSERT-YOUR=PROJECT-ID-HERE --collection-group=notes --query-scope=COLLECTION --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=embedding
    يستغرق إنشاء الفهرس بضع دقائق. يمكنك الاطّلاع على مستوى التقدّم في علامة التبويب الفهارس في قسم Firestore ضِمن وحدة تحكُّم Firebase.حالة الفهرس الجديد
  10. بعد إعداد الفهرس، يمكنك إنشاء مستند استعلام جديد.
  11. من المفترض أن تظهر الآن قائمة بمعرّفات المستندات المطابقة في حقل النتائجنتيجة إجراء استعلام دلالي
  12. انسخ أحد أرقام التعريف هذه، ثم ارجع إلى مجموعة notes.
  13. يمكنك استخدام ⌘+F للبحث عن رقم تعريف المستند الذي نسخته، فهذا المستند هو أفضل مستند يتطابق مع طلب بحثك.البحث عن معرّف المستند في قائمة المستندات

7- تنفيذ البحث الدلالي

وقد حان الوقت أخيرًا لربط تطبيق الأجهزة الجوّالة بالإضافة "Vector Search" (بحث المتجهات باستخدام إضافة Firestore) وتنفيذ ميزة البحث الدلالي التي ستتيح للمستخدمين البحث في ملاحظاتهم باستخدام طلبات البحث اللغوية الطبيعية.

ربط الدالة القابلة للاستدعاء لإجراء الاستعلامات

تتضمن الإضافة Vector Search with Firestore ميزة Cloud Function يمكنك استدعاؤها من تطبيقك على الأجهزة الجوّالة لطلب البحث عن الفهرس الذي أنشأته سابقًا في هذا الدرس التطبيقي حول الترميز. في هذه الخطوة، ستنشئ اتصالاً بين تطبيق الأجهزة الجوّالة وهذه الدالة القابلة للاتصال. تتضمّن حزمة Swift SDK من Firebase واجهات برمجة تطبيقات تجعل تنفيذ المهام عن بُعد سلسًا.

  1. ارجع إلى Xcode وتأكّد من أنّك في المشروع الذي نسخته في خطوة سابقة ضمن هذا الدرس التطبيقي حول الترميز.
  2. افتح ملف NotesRepository.swift.
  3. ابحث عن السطر الذي يحتوي على private lazy var vectorSearchQueryCallable: Callable = functions.httpsCallable("").

لاستدعاء دالة Cloud قابلة للاستدعاء، عليك توفير اسم الدالة التي تريد استدعائها.

  1. انتقِل إلى وحدة تحكُّم Firebase لمشروعك، وافتح عنصر القائمة الدوالّ في قسم إنشاء.
  2. ستظهر لك قائمة بالدوالّ التي تمّ تثبيتها من خلال الإضافة.
  3. يُرجى البحث عن الاسم الذي يحمل الاسم ext-firestore-vector-search-queryCallable ونسخ اسمه.
  4. الصق الاسم في الرمز. من المفترض أن تظهر الآن.
    private lazy var vectorSearchQueryCallable: Callable<String, String> = functions.httpsCallable("ext-firestore-vector-search-queryCallable")

استدعاء دالة الاستعلام

  1. البحث عن الطريقة "performQuery"
  2. استدعاء الدالة القابلة للاتصال عن طريق استدعاء
    let result = try await vectorSearchQueryCallable(searchTerm)

ونظرًا لأن هذه مكالمة عن بُعد، فقد تفشل.

  1. أضف بعض المعالجة الأساسية للأخطاء لرصد أي أخطاء، وتسجيلها في وحدة تحكم Xcode.
    private func performQuery(searchTerm: String) async -> [String] {
  do {
    let result = try await vectorSearchQueryCallable(searchTerm)
    return [result]
  }
  catch {
    print(error.localizedDescription)
    return []
  }
}

ربط واجهة المستخدم

للسماح للمستخدمين بالبحث في ملاحظاتهم، ستُنفّذ شريط بحث في شاشة قائمة الملاحظات. عندما يكتب المستخدم عبارة بحث، عليك استدعاء طريقة performQuery التي طبّقتها في الخطوة السابقة. وبفضل معدِّلات طرق العرض searchable وtask التي يوفّرها SwiftUI، لن يتطلّب هذا الأمر سوى سطرين من الرمز.

  1. أولاً، يجب فتح "NotesListScreen.swift"
  2. لإضافة مربع بحث إلى العرض على شكل قائمة، أضف عنصر تعديل طريقة العرض .searchable(text: $searchTerm, prompt: "Search") أعلى السطر .navigationTitle("Notes") مباشرةً.
  3. ثم استدعِ دالة البحث بإضافة التعليمة البرمجية التالية أدناه مباشرة:
.task(id: searchTerm, debounce: .milliseconds(800)) {
  await notesRepository.semanticSearch(searchTerm: searchTerm)
}

يستدعي مقتطف الرمز هذا طريقة semanticSearch بشكل غير متزامن. ومن خلال توفير مهلة 800 ملي ثانية، يمكنك توجيه أداة تعديل المهام لرفض إدخال المستخدم بمقدار 0.8 ثانية. وهذا يعني أنّه لن يتم طلب "semanticSearch" إلا بعد أن يتوقف المستخدم مؤقتًا عن الكتابة لمدة تزيد عن 0.8 ثانية.

من المفترض أن تظهر التعليمة البرمجية الآن على النحو التالي:

...
List(repository.notes) { note in
  NavigationLink(value: note) {
    NoteRowView(note: note)
  }
  .swipeActions {
    Button(role: .destructive, action: { deleteNote(note: note) }) {
      Label("Delete", systemImage: "trash")
    }
  }
}
.searchable(text: $searchTerm, prompt: "Search")
.task(id: searchTerm, debounce: .milliseconds(800)) {
  await notesRepository.semanticSearch(searchTerm: searchTerm)
}
.navigationTitle("Notes")
...

تشغيل التطبيق

  1. اضغط على ⌘ + R (أو انقر على زر "تشغيل") لتشغيل التطبيق على "محاكي iOS"
  2. من المفترض أن تظهر لك الملاحظات نفسها التي أضفتها في التطبيق سابقًا ضمن هذا الدرس التطبيقي حول الترميز، بالإضافة إلى أي ملاحظات أضفتها من خلال "وحدة تحكُّم Firebase".
  3. من المفترض أن يظهر لك حقل بحث في أعلى قائمة الملاحظات.
  4. اكتب العبارة التي تظهر في أحد المستندات التي أضفتها. مرة أخرى، يعمل هذا بشكل أفضل مع طلبات البحث الدلالية، مثل "كيف يمكنني طلب واجهات برمجة تطبيقات Firebase غير المتزامنة من Swift" (حيث إنّ ملاحظة واحدة على الأقل من الملاحظات التي أضفتها تحتوي على نص يناقش هذا الموضوع).
  5. ربما تتوقع رؤية نتيجة البحث، ولكن بدلاً من ذلك، يكون عرض القائمة فارغًا، وتعرض وحدة تحكم Xcode رسالة خطأ: "تم استدعاء الدالة باستخدام وسيطة غير صالحة".

تطبيق Notes، مع قائمة نتائج فارغة

هذا يعني أنك أرسلت البيانات بتنسيق غير صحيح.

تحليل رسالة الخطأ

  1. لمعرفة المشكلة، انتقِل إلى "وحدة تحكُّم Firebase".
  2. انتقِل إلى قسم الدوالّ.
  3. ابحث عن الدالة ext-firestore-vector-search-queryCallable، وافتح القائمة الكاملة بالنقر على النقاط الرأسية الثلاث.
  4. اختَر عرض السجلات للانتقال إلى مستكشف السجلات.
  5. من المفترض أن تظهر لك رسالة خطأ.
Unhandled error ZodError: [
  {
    "code": "invalid_type",
    "expected": "object",
    "received": "string",
    "path": [],
    "message": "Expected object, received string"
  }
]

هذا يعني أنك أرسلت البيانات بتنسيق غير صحيح.

استخدم أنواع البيانات الصحيحة

لمعرفة التنسيق الذي تتوقع أن تكون به المعلّمات، اطّلِع على مستندات الإضافة.

  1. انتقِل إلى قسم الإضافات في "وحدة تحكُّم Firebase".
  2. انقر على إدارة ->إدارة واجهة Vector Search باستخدام الإضافة Firestore.
  3. في قسم آلية عمل هذه الإضافة، ستجد مواصفات لمَعلمات الإدخال والمخرجات.توثيق معلمة الإدخال وقيمة النتيجة
  4. الرجوع إلى Xcode والانتقال إلى NotesRepository.swift
  5. أضِف الرمز التالي في بداية الملف:
    private struct QueryRequest: Codable {
  var query: String
  var limit: Int?
  var prefilters: [QueryFilter]?
}

private struct QueryFilter: Codable {
  var field: String
  var `operator`: String
  var value: String

}

private struct QueryResponse: Codable {
  var ids: [String]
}
    يتطابق QueryRequest مع بنية مَعلمة الإدخال التي تتوقعها الإضافة، وفقًا لمستندات الإضافة. وهي تحتوي أيضًا على سمة prefilter مدمجة ستحتاج إليها لاحقًا.وتتطابق QueryResponse مع بنية استجابة الإضافة.
  6. البحث عن مواصفات الدوال القابلة للاتصال وتعديل أنواع المدخلات والمخرجات
    private lazy var vectorSearchQueryCallable: Callable<QueryRequest, QueryResponse> = functions.httpsCallable("ext-firestore-vector-search-queryCallable")
  7. تحديث استدعاء الدالة القابلة للاتصال في performQuery
    private func performQuery(searchTerm: String) async -> [String] {
  do {
    let queryRequest = QueryRequest(query: searchTerm,
                                    limit: 2)
    let result = try await vectorSearchQueryCallable(queryRequest)
    print(result.ids)
    return result.ids
  }
  catch {
    print(error.localizedDescription)
    return []
  }
}

تشغيل التطبيق مرة أخرى

  1. تشغيل التطبيق مرة أخرى
  2. اكتب طلب بحث يحتوي على عبارات مضمّنة في إحدى ملاحظاتك
  3. من المفترض أن تظهر الآن قائمة بالملاحظات التي تمّت فلترتها

لقطة شاشة للتطبيق تظهر فيها النتيجة المتوقعة

الفلترة المسبقة لبيانات المستخدمين

قبل الانطلاق في الرقص للاحتفال - هناك مشكلة في الإصدار الحالي من التطبيق: تحتوي مجموعة النتائج على بيانات من جميع المستخدمين.

يمكنك التحقق من ذلك من خلال تشغيل التطبيق على محاكي مختلف وإضافة المزيد من المستندات. ولن تظهر المستندات الجديدة إلا في هذا المحاكي. وفي حال تشغيل التطبيق مرة أخرى على جهاز المحاكي الآخر، لن تظهر لك سوى المستندات التي أنشأتها في المرة الأولى.

عند إجراء بحث، ستلاحظ أنّ طلب vectorSearchQueryCallable يعرض معرّفات المستندات التي قد تنتمي إلى المستخدم الآخر. لمنع حدوث ذلك، نحتاج إلى استخدام فلتر مسبق.

في performQuery، يمكنك تعديل الرمز على النحو التالي:

  let prefilters: [QueryFilter] = if let uid = user?.uid {
    [QueryFilter(field: "userId", operator: "==", value: uid)]
  }
  else {
    []
  }

  let queryRequest = QueryRequest(query: searchTerm,
                                  limit: 2,
                                  prefilters: prefilters)

سيؤدي هذا إلى فلترة البيانات مسبقًا بناءً على رقم تعريف المستخدم الذي سجّل دخوله. كما قد تتوقّع، يتطلب ذلك تحديث فهرس Firestore.

شغِّل الأمر التالي من سطر الأوامر لتحديد فهرس Firestore الجديد الذي يتضمن كلاً من عمليات تضمين userId والمتجهات في الحقل embedding.

gcloud alpha firestore indexes composite create --project=INSERT-YOUR-PROJECT-ID-HERE --collection-group=notes --query-scope=COLLECTION --field-config=order=ASCENDING,field-path=userId --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=embedding

بعد الانتهاء من إنشاء الفهرس، شغِّل التطبيق مرة أخرى للتحقّق من أنه يعمل على النحو المتوقَّع.

مجموعة نتائج تمت تصفيتها مسبقًا

8- تهانينا

تهانينا على إكمال هذا الدرس التطبيقي حول الترميز بنجاح.

في هذا الدرس التطبيقي حول الترميز، تعلّمت كيفية:

  • إعداد قاعدة بيانات Cloud Firestore مع تفعيل البحث الدلالي
  • إنشاء تطبيق SwiftUI بسيطًا للتفاعل مع قاعدة البيانات.
  • تنفيذ شريط البحث باستخدام معدِّل العرض القابل للبحث في SwiftUI ومعدِّل المهام.
  • يمكنك استدعاء دالة في السحابة الإلكترونية لإجراء بحث دلالي على قاعدة البيانات، باستخدام الواجهة القابلة للاستدعاء في Firestore SDK.

بفضل المعرفة التي اكتسبتها في هذا الدرس التطبيقي حول الترميز، يمكنك الآن إنشاء تطبيقات فعّالة تستفيد من إمكانات البحث الدلالي في Cloud Firestore لتزويد المستخدمين بتجربة بحث أكثر سهولة وفعالية.

لمعرفة المزيد حول حقل المتجه الجديد في Firestore وكيفية حساب تضمينات المتجهات، يمكنك الاطّلاع على المستندات.