با افزونه های Firebase، جستجوی وکتور Firestore را به برنامه های تلفن همراه خود اضافه کنید

1. بررسی اجمالی

در این کد لبه، یاد خواهید گرفت که چگونه با استفاده از جستجوی تشابه برداری بردار Firestore، ویژگی های جستجوی قدرتمندی را به برنامه خود اضافه کنید. شما یک ویژگی جستجوی معنایی را برای یک برنامه یادداشت برداری که با Swift و SwiftUI نوشته شده است، پیاده سازی خواهید کرد.

کنسول Cloud Firestore برخی از اسناد را نشان می دهد که در برنامه iOS در سمت راست نیز قابل مشاهده هستند.

آنچه خواهید آموخت

  • نحوه نصب Vector Search با پسوند Firestore برای محاسبه جاسازی های برداری.
  • نحوه فراخوانی توابع ابری Firebase از یک برنامه سوئیفت.
  • نحوه از پیش فیلتر کردن داده ها بر اساس کاربر وارد شده.

آنچه شما نیاز خواهید داشت

  • Xcode 15.3
  • کد نمونه کد لبه. شما این را در مرحله بعد از Codelab دانلود خواهید کرد.

2. یک پروژه Firebase ایجاد و راه اندازی کنید

برای استفاده از افزونه Firebase Vector Search، به یک پروژه Firebase نیاز دارید. در این قسمت از Codelab، یک پروژه Firebase جدید ایجاد می‌کنید و خدمات مورد نیاز مانند Cloud Firestore و Firebase Authentication را فعال می‌کنید.

یک پروژه Firebase ایجاد کنید

  1. وارد Firebase شوید
  2. در کنسول Firebase، روی افزودن پروژه کلیک کنید، سپس نام پروژه خود را Firestore Vector Search Lab کنید یک پروژه ایجاد کنید، مرحله 1 از 3: انتخاب نام پروژه
  3. روی گزینه های ایجاد پروژه کلیک کنید. در صورت درخواست، شرایط Firebase را بپذیرید.
  4. در صفحه Google Analytics، تیک گزینه Enable Google Analytics for this project را بردارید، زیرا از Analytics برای این برنامه استفاده نخواهید کرد.
  5. در نهایت بر روی Create project کلیک کنید.

برای کسب اطلاعات بیشتر درباره پروژه‌های Firebase، به درک پروژه‌های Firebase مراجعه کنید.

طرح قیمت گذاری Firebase خود را ارتقا دهید

برای استفاده از برنامه‌های افزودنی Firebase و سرویس‌های ابری زیربنایی آن‌ها، پروژه Firebase شما باید در طرح قیمت‌گذاری (Blaze) باشد، به این معنی که به یک حساب صورت‌حساب Cloud مرتبط است.

  • حساب Cloud Billing به یک روش پرداخت مانند کارت اعتباری نیاز دارد.
  • اگر تازه وارد Firebase و Google Cloud هستید، بررسی کنید که آیا واجد شرایط دریافت اعتبار 300 دلاری و یک حساب آزمایشی رایگان Cloud Billing هستید یا خیر.
  • اگر این نرم‌افزار کد را به‌عنوان بخشی از یک رویداد انجام می‌دهید، از سازمان‌دهنده خود بپرسید که آیا اعتبارات Cloud موجود است یا خیر.

برای ارتقای پروژه خود به پلن Blaze، مراحل زیر را دنبال کنید:

  1. در کنسول Firebase، برنامه خود را ارتقا دهید.
  2. طرح Blaze را انتخاب کنید. دستورالعمل های روی صفحه را دنبال کنید تا یک حساب Cloud Billing را به پروژه خود پیوند دهید.
    اگر به عنوان بخشی از این ارتقاء نیاز به ایجاد یک حساب Cloud Billing داشتید، ممکن است لازم باشد برای تکمیل ارتقاء به جریان ارتقاء در کنسول Firebase برگردید.

محصولات Firebase را در کنسول فعال و تنظیم کنید

برنامه‌ای که می‌سازید از چندین محصول Firebase استفاده می‌کند که برای برنامه‌های اپل در دسترس هستند:

  • Firebase Authentication به کاربران شما اجازه می دهد به راحتی وارد برنامه شما شوند.
  • Cloud Firestore برای ذخیره داده‌های ساخت‌یافته در فضای ابری و دریافت اطلاع‌رسانی فوری هنگام تغییر داده‌ها.
  • قوانین امنیتی Firebase برای ایمن سازی پایگاه داده شما.

برخی از این محصولات نیاز به پیکربندی خاصی دارند یا باید با استفاده از کنسول Firebase فعال شوند.

احراز هویت ناشناس را برای احراز هویت Firebase فعال کنید

این برنامه از احراز هویت ناشناس استفاده می کند تا به کاربران اجازه دهد بدون نیاز به ایجاد حساب کاربری، شروع به استفاده از برنامه کنند. این منجر به فرآیند سوار شدن با اصطکاک کم می شود. برای کسب اطلاعات بیشتر در مورد احراز هویت ناشناس (و نحوه ارتقاء به یک حساب نامگذاری شده)، به بهترین روش ها برای احراز هویت ناشناس مراجعه کنید.

  1. در پانل سمت چپ کنسول Firebase، روی Build > Authentication کلیک کنید. سپس روی Get start کلیک کنید. فعال کردن احراز هویت Firebase
  2. اکنون در داشبورد احراز هویت هستید، جایی که می توانید کاربران ثبت نام شده را ببینید، ارائه دهندگان ورود به سیستم را پیکربندی کنید و تنظیمات را مدیریت کنید.
  3. برگه روش ورود به سیستم را انتخاب کنید (یا برای رفتن مستقیم به برگه اینجا را کلیک کنید ).
  4. از گزینه‌های ارائه‌دهنده ناشناس کلیک کنید، سوئیچ را روی Enable تغییر دهید و سپس روی ذخیره کلیک کنید.

Cloud Firestore را راه اندازی کنید

این برنامه Swift از Cloud Firestore برای ذخیره یادداشت ها استفاده می کند.

در اینجا نحوه راه اندازی Cloud Firestore در پروژه Firebase آمده است:

  1. در پنل سمت چپ کنسول Firebase، Build را گسترش دهید و سپس پایگاه داده Firestore را انتخاب کنید.
  2. روی ایجاد پایگاه داده کلیک کنید.
  3. شناسه پایگاه داده را روی (default) بگذارید.
  4. یک مکان برای پایگاه داده خود انتخاب کنید، سپس روی Next کلیک کنید.
    برای یک برنامه واقعی، می خواهید مکانی را انتخاب کنید که به کاربران شما نزدیک باشد.
  5. در حالت تست روی Start کلیک کنید. سلب مسئولیت در مورد قوانین امنیتی را بخوانید.
    بعداً در این کد، قوانین امنیتی را برای ایمن سازی داده های خود اضافه خواهید کرد. بدون افزودن قوانین امنیتی برای پایگاه داده خود، یک برنامه را به صورت عمومی توزیع یا افشا نکنید .
  6. روی ایجاد کلیک کنید.

راه اندازی فضای ذخیره سازی ابری برای Firebase

برنامه وب از Cloud Storage برای Firebase برای ذخیره، آپلود و اشتراک گذاری تصاویر استفاده می کند.

در اینجا نحوه راه اندازی Cloud Storage برای Firebase در پروژه Firebase آمده است:

  1. در پانل سمت چپ کنسول Firebase، Build را گسترش دهید و سپس Storage را انتخاب کنید.
  2. روی Get start کلیک کنید.
  3. مکانی را برای سطل ذخیره سازی پیش فرض خود انتخاب کنید.
    سطل‌ها در US-WEST1 ، US-CENTRAL1 ، و US-EAST1 می‌توانند از لایه «همیشه رایگان» برای Google Cloud Storage استفاده کنند. سطل‌ها در همه مکان‌های دیگر از قیمت و استفاده از Google Cloud Storage پیروی می‌کنند.
  4. در حالت تست روی Start کلیک کنید. سلب مسئولیت در مورد قوانین امنیتی را بخوانید.
    بعداً در این کد، قوانین امنیتی را برای ایمن کردن داده‌های خود اضافه خواهید کرد. بدون افزودن قوانین امنیتی برای سطل ذخیره‌سازی خود ، برنامه‌ای را به صورت عمومی توزیع یا افشا نکنید .
  5. روی ایجاد کلیک کنید.

3. اپلیکیشن موبایل را وصل کنید

در این بخش از Codelab، کد منبع یک برنامه یادداشت برداری ساده را دانلود کرده و آن را به پروژه Firebase که ایجاد کرده اید متصل می کنید.

نمونه برنامه را دانلود کنید

  1. به https://github.com/FirebaseExtended/codelab-firestore-vectorsearch-ios بروید و مخزن را در دستگاه محلی خود شبیه سازی کنید.
  2. پروژه Notes.xcodeproj را در Xcode باز کنید

برنامه را به پروژه Firebase خود وصل کنید

برای اینکه برنامه شما بتواند به خدمات Firebase دسترسی داشته باشد، باید برنامه را در کنسول Firebase راه اندازی کنید. می توانید چندین برنامه کلاینت را به یک پروژه Firebase متصل کنید، برای مثال اگر یک برنامه اندروید یا وب ایجاد می کنید، باید آنها را به همان پروژه Firebase متصل کنید.

برای کسب اطلاعات بیشتر درباره پروژه‌های Firebase، به درک پروژه‌های Firebase مراجعه کنید.

  1. در کنسول Firebase، به صفحه نمای کلی پروژه Firebase خود بروید. صفحه نمای کلی کنسول Firebase
  2. برای افزودن برنامه iOS خود، روی نماد iOS+ کلیک کنید.
  3. در افزودن Firebase به صفحه برنامه Apple خود ، شناسه بسته را از پروژه Xcode ( com.google.firebase.codelab.Notes ) وارد کنید.
  4. اگر دوست دارید، می‌توانید نام مستعار برنامه ( Notes for iOS ) را وارد کنید.
  5. برای رفتن به مرحله بعدی روی ثبت برنامه کلیک کنید.
  6. فایل GoogleServices-Info.plist را دانلود کنید.
  7. GoogleServices-Info.plist را به پوشه Notes پروژه Xcode خود بکشید. یک راه خوب برای انجام این کار، قرار دادن آن در زیر فایل Assets.xcassets . کشیدن فایل plist به Xcode
  8. در صورت نیاز کپی موارد را انتخاب کنید، مطمئن شوید که هدف Notes در افزودن به اهداف انتخاب شده است و روی Finish کلیک کنید. انتخاب «کپی در صورت نیاز» در گزینه‌های انتخاب برای افزودن فایل‌ها
  9. در کنسول Firebase، اکنون می‌توانید روی بقیه مراحل راه‌اندازی کلیک کنید: نمونه‌ای که در ابتدای این بخش دانلود کرده‌اید، قبلاً Firebase Apple SDK را نصب کرده و راه‌اندازی اولیه را تنظیم کرده است. می‌توانید با کلیک روی Continue to console، فرآیند را به پایان برسانید.

برنامه را اجرا کنید

اکنون زمان آن است که برنامه را به چرخش درآورید!

  1. به Xcode برگردید، برنامه را در شبیه ساز iOS اجرا کنید. در منوی Run Destinations ابتدا یکی از شبیه سازهای iOS را انتخاب کنید. انتخاب یک شبیه ساز iOS در منوی کشویی Run Destinations
  2. سپس، روی دکمه Run کلیک کنید یا ⌘ + R را فشار دهید
  3. هنگامی که برنامه با موفقیت در Simulator راه اندازی شد، چند یادداشت اضافه کنید.
  4. در کنسول Firebase، به مرورگر داده Firestore بروید تا هنگام افزودن یادداشت‌های جدید در برنامه، بتوانید اسناد جدید ایجاد شده را مشاهده کنید. کنسول Cloud Firestore که برخی از اسناد را نشان می دهد، در کنار شبیه ساز iOS که همان اسناد را نشان می دهد

4. جستجوی برداری با پسوند Firestore را نصب کنید

در این قسمت از Codelab، جستجوی برداری با پسوند Firestore را نصب می‌کنید و آن را مطابق با الزامات برنامه یادداشت‌برداری که روی آن کار می‌کنید پیکربندی می‌کنید.

نصب افزونه را آغاز کنید

  1. هنوز در بخش Firestore، روی تب Extensions کلیک کنید. انتخاب تب Firebase Extensions در کنسول Firestore
  2. روی Explore Extensions Hub کلیک کنید. تب Firebase Extensions در کنسول Firestore
  3. "بردار" را تایپ کنید.
  4. بر روی "جستجوی برداری با پسوند Firestore" کلیک کنید. صفحه فرود Firebase Extensios Hub این شما را به صفحه جزئیات برنامه افزودنی می برد، جایی که می توانید اطلاعات بیشتری در مورد برنامه افزودنی، نحوه عملکرد آن، خدمات Firebase مورد نیاز و نحوه پیکربندی آن بخوانید.
  5. بر روی Install در کنسول Firebase کلیک کنید. دکمه نصب برای جستجوی برداری با پسوند Firestore
  6. لیستی از تمام پروژه های خود به شما ارائه می شود.
  7. پروژه ای را که در مرحله اول این کد لبه ایجاد کرده اید انتخاب کنید. صفحه انتخابگر پروژه Firebase

پسوند را پیکربندی کنید

  1. APIهای فعال و منابع ایجاد شده را مرور کنید. بررسی API های فعال شده
  2. خدمات مورد نیاز را فعال کنید فعال کردن خدمات مورد نیاز
  3. پس از فعال شدن همه سرویس ها، روی Next کلیک کنید. بعد از فعال کردن همه سرویس ها، روی next کلیک کنید
  4. بازبینی دسترسی به این افزونه داده شده است.
  5. پسوند را پیکربندی کنید:
    • Vertex AI را به عنوان LLM انتخاب کنید
    • مسیر مجموعه : یادداشت ها
    • محدودیت پرس و جو پیش فرض : 3
    • نام فیلد ورودی : متن
    • نام فیلد خروجی: embedding
    • نام فیلد وضعیت: * *وضعیت*
    • قراردادن اسناد موجود : بله
    • به روز رسانی اسناد موجود : بله
    • محل عملکرد ابر : us-central1
  6. برای اتمام نصب بر روی Install extension کلیک کنید.

این ممکن است چند دقیقه طول بکشد. در حالی که منتظر تکمیل نصب هستید، با خیال راحت به بخش بعدی آموزش بروید و برخی اطلاعات پس زمینه در مورد جاسازی های برداری را بخوانید.

5. پس زمینه

در حالی که منتظر پایان نصب هستید، در اینجا اطلاعاتی در زمینه نحوه عملکرد جستجوی برداری با پسوند Firestore وجود دارد.

Vectors، Embeddings و Vector Database چیست؟

  • بردارها اشیای ریاضی هستند که بزرگی و جهت یک کمیت را نشان می دهند. می توان از آنها برای نمایش داده ها به گونه ای استفاده کرد که مقایسه و جستجو را آسان تر کند.
  • Embedding ها بردارهایی هستند که معنای یک کلمه یا عبارت را نشان می دهند. آنها با آموزش یک شبکه عصبی بر روی مجموعه بزرگی از متن و یادگیری روابط بین کلمات ایجاد می شوند.
  • پایگاه داده های برداری پایگاه هایی هستند که برای ذخیره و جستجوی داده های برداری بهینه شده اند. آنها امکان جستجوی کارآمد نزدیکترین همسایه را فراهم می کنند، که فرآیند یافتن مشابه ترین بردارها به بردار پرس و جو داده شده است.

جستجوی برداری چگونه کار می کند؟

جستجوی برداری با مقایسه بردار پرس و جو با تمام بردارهای پایگاه داده کار می کند. بردارهایی که بیشتر شبیه بردار پرس و جو هستند به عنوان نتایج جستجو برگردانده می شوند.

شباهت بین دو بردار را می توان با استفاده از انواع متریک های فاصله اندازه گیری کرد. رایج ترین متریک فاصله، تشابه کسینوس است که زاویه بین دو بردار را اندازه می گیرد.

6. جستجوی برداری با پسوند Firestore را امتحان کنید

قبل از استفاده از افزونه Vector Search با Firestore در برنامه iOS که قبلاً در این کد لبه دانلود کرده‌اید، می‌توانید افزونه را در کنسول Firebase امتحان کنید.

مستندات را بخوانید

افزونه های Firebase شامل مستنداتی در مورد نحوه کار آنها می شود.

  1. پس از اتمام نصب برنامه افزودنی، روی دکمه شروع کار کلیک کنید. صفحه نمای کلی برنامه افزودنی Firebase در کنسول Firebase
  2. تب "این افزونه چگونه کار می کند" را بررسی کنید - توضیح می دهد:
    • نحوه محاسبه جاسازی برای اسناد با افزودن آنها به مجموعه notes ،
    • چگونه با فراخوانی تابع فراخوانی ext-firestore-vector-search-queryCallable ایندکس پرس و جو کنیم،
    • یا اینکه چگونه با افزودن یک سند پرس و جو به مجموعه _firestore-vector-search/index/queries از نمایه پرس و جو کنیم.
    • همچنین نحوه راه‌اندازی یک تابع تعبیه سفارشی را توضیح می‌دهد - اگر هیچ یک از LLM‌های پشتیبانی شده توسط افزونه نیازهای شما را برآورده نمی‌کند و می‌خواهید از LLM دیگری برای محاسبه جاسازی‌ها استفاده کنید، مفید است. مستندات جستجوی برداری با پسوند Firestore
  3. روی پیوند داشبورد Cloud Firestore کلیک کنید تا به نمونه Firestore خود بروید
  4. به سند _firestore-vector-search/index بروید. باید نشان دهد که برنامه افزودنی محاسبه جاسازی‌ها را برای تمام اسناد یادداشت‌هایی که در مرحله قبلی در این Codelab ایجاد کرده‌اید، به پایان رسانده است. پیکربندی ایندکس داخل کنسول Firestore
  5. برای تأیید این موضوع، یکی از اسناد یادداشت ها را باز کنید، و باید یک فیلد اضافی به نام embedding of type vector<768> و همچنین یک فیلد status را مشاهده کنید. یک فیلد تعبیه شده برداری در داخل کنسول Firestore

یک سند نمونه ایجاد کنید

می‌توانید یک سند جدید در کنسول Firebase ایجاد کنید تا برنامه افزودنی را در عمل ببینید.

  1. هنوز در مرورگر داده Firestore، به مجموعه notes بروید و روی + افزودن سند در ستون وسط کلیک کنید. افزودن یک سند جدید
  2. برای ایجاد شناسه سند منحصر به فرد جدید روی Auto-ID کلیک کنید.
  3. فیلدی به نام text از نوع رشته اضافه کنید و مقداری متن را در فیلد مقدار قرار دهید. مهم است که این متن لورم ایپسوم یا متن تصادفی دیگری نباشد. برای مثال، یک مقاله خبری را انتخاب کنید. افزودن فیلد متنی
  4. روی ذخیره کلیک کنید.
    • توجه کنید که چگونه برنامه افزودنی یک فیلد وضعیت اضافه می کند تا نشان دهد که در حال پردازش داده است.
    • پس از مدت کوتاهی، باید یک embedding جدید با مقدار vector<768> را مشاهده کنید.
    به روز رسانی وضعیت جاسازی های برداری برای سند جدید

یک پرس و جو انجام دهید

جستجوی برداری با برنامه افزودنی Firestore دارای یک ویژگی کوچک است که به شما امکان می دهد بدون نیاز به اتصال یک برنامه، فهرست سند را جستجو کنید.

  1. در بخش Firestore کنسول Firebase، به سند _firestore-vector-search/index بروید.
  2. روی + شروع مجموعه کلیک کنید افزودن یک زیر مجموعه جدید
  3. یک زیر مجموعه جدید به نام queries ایجاد کنید
  4. یک سند جدید ایجاد کنید و قسمت query را روی متنی تنظیم کنید که در یکی از اسناد شما وجود دارد. این برای پرس و جوهای معنایی، مانند «چگونه می توانم اسناد Firestore را با Swift نقشه برداری کنم» بهترین کار را دارد (به شرطی که حداقل یکی از یادداشت هایی که اضافه کردید حاوی متنی باشد که این موضوع را مورد بحث قرار می دهد). افزودن فیلد پرس و جو
  5. ممکن است خطایی در وضعیت مشاهده کنید خطایی رخ داد
  6. این به دلیل کمبود شاخص است. برای تنظیم پیکربندی فهرست گمشده، با دنبال کردن این پیوند ، به کنسول Google Cloud برای پروژه خود بروید و سپس پروژه خود را از لیست انتخاب کنید. انتخاب پروژه صحیح
  7. در Cloud Log Explorer، اکنون باید یک پیغام خطایی ببینید که می گوید "FAILED_PRECONDITION: پیکربندی نمایه برداری گم شده است. لطفاً با دستور gcloud زیر فهرست مورد نیاز را ایجاد کنید: ..." پیام خطا در کاوشگر گزارش
  8. پیام خطا همچنین حاوی یک دستور gcloud است که برای پیکربندی فهرست گم شده باید اجرا کنید.
  9. دستور زیر را از خط فرمان خود اجرا کنید. اگر gcloud CLI را روی دستگاه خود نصب نکرده اید، دستورالعمل های اینجا را برای نصب آن دنبال کنید.
    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
    ایجاد ایندکس چند دقیقه طول می کشد. می توانید پیشرفت را در تب Indexes در بخش Firestore کنسول Firebase بررسی کنید. وضعیت شاخص جدید
  10. پس از تنظیم فهرست، می توانید یک سند پرس و جو جدید ایجاد کنید.
  11. اکنون باید فهرستی از شناسه‌های اسناد منطبق را در فیلد نتایج مشاهده کنید نتیجه انجام یک پرس و جو معنایی
  12. یکی از آن شناسه ها را کپی کنید و به مجموعه notes برگردید.
  13. از ⌘+F برای جستجوی شناسه سندی که کپی کرده‌اید استفاده کنید - این سندی است که به بهترین شکل با درخواست شما مطابقت دارد. یافتن شناسه سند در لیست اسناد

7. جستجوی معنایی را اجرا کنید

بالاخره زمان آن رسیده است که اپلیکیشن موبایل خود را به جستجوی برداری با افزونه Firestore متصل کنید و یک ویژگی جستجوی معنایی را پیاده سازی کنید که به کاربران شما امکان می دهد یادداشت های خود را با استفاده از جستارهای زبان طبیعی جستجو کنند.

تابع قابل فراخوانی را برای انجام پرس و جو وصل کنید

جستجوی برداری با برنامه افزودنی Firestore شامل یک تابع ابری است که می‌توانید از برنامه تلفن همراه خود برای جستجوی فهرستی که قبلاً در این کد ایجاد کرده‌اید، تماس بگیرید. در این مرحله بین اپلیکیشن موبایل خود و این تابع قابل فراخوانی ارتباط برقرار می کنید. Swift SDK Firebase شامل APIهایی است که فراخوانی عملکردهای راه دور را یکپارچه می کند.

  1. به Xcode برگردید و مطمئن شوید که در پروژه‌ای هستید که در مرحله قبلی در این نرم‌افزار شبیه‌سازی کرده‌اید.
  2. فایل NotesRepository.swift را باز کنید.
  3. خط حاوی private lazy var vectorSearchQueryCallable: Callable = functions.httpsCallable("") private lazy var vectorSearchQueryCallable: Callable = functions.httpsCallable("")

برای فراخوانی یک تابع Cloud قابل فراخوانی، باید نام تابعی را که می‌خواهید فراخوانی کنید، وارد کنید.

  1. برای پروژه خود به کنسول Firebase بروید و آیتم منوی Functions را در بخش Build باز کنید.
  2. لیستی از توابع نصب شده توسط افزونه را مشاهده خواهید کرد.
  3. موردی را با نام ext-firestore-vector-search-queryCallable جستجو کنید و نام آن را کپی کنید.
  4. نام را در کد خود قرار دهید. اکنون باید خوانده شود
    private lazy var vectorSearchQueryCallable: Callable<String, String> = functions.httpsCallable("ext-firestore-vector-search-queryCallable")

تابع query را فراخوانی کنید

  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 را فشار دهید (یا روی دکمه Run کلیک کنید) تا برنامه در شبیه ساز iOS راه اندازی شود
  2. باید همان یادداشت‌هایی را که قبلاً در این نرم‌افزار در برنامه اضافه کرده‌اید، و همچنین یادداشت‌هایی را که از طریق کنسول Firebase اضافه کرده‌اید، ببینید.
  3. شما باید یک قسمت جستجو را در بالای لیست یادداشت ها ببینید
  4. عبارتی را تایپ کنید که در یکی از اسنادی که اضافه کرده اید ظاهر می شود. باز هم، این برای پرس‌و‌جوهای معنایی بهترین کار را دارد، مانند «چگونه می‌توانم APIهای Firebase ناهمزمان را از سویفت فراخوانی کنم» (به شرطی که حداقل یکی از یادداشت‌هایی که اضافه کردید حاوی متنی باشد که این موضوع را مورد بحث قرار می‌دهد).
  5. احتمالاً انتظار دارید نتیجه جستجو را ببینید، اما در عوض، نمای لیست خالی است و کنسول Xcode یک پیام خطا نشان می دهد: "عملکرد با یک آرگومان نامعتبر فراخوانی شد"

برنامه یادداشت ها، با لیست نتایج خالی

این بدان معناست که شما داده ها را با فرمت اشتباه ارسال کرده اید.

پیام خطا را تجزیه و تحلیل کنید

  1. برای پیدا کردن مشکل، به کنسول Firebase بروید
  2. به بخش توابع بروید
  3. تابع ext-firestore-vector-search-queryCallable را پیدا کنید، منوی سرریز را با کلیک بر روی سه نقطه عمودی باز کنید.
  4. برای رفتن به کاوشگر گزارش‌ها، View logs را انتخاب کنید
  5. شما باید یک خطا ببینید
Unhandled error ZodError: [
  {
    "code": "invalid_type",
    "expected": "object",
    "received": "string",
    "path": [],
    "message": "Expected object, received string"
  }
]

این بدان معناست که شما داده ها را با فرمت اشتباه ارسال کرده اید.

از انواع داده های صحیح استفاده کنید

برای اینکه بدانید برنامه افزودنی انتظار دارد پارامترها در کدام قالب باشند، مستندات برنامه افزودنی را بررسی کنید.

  1. به بخش Extensions در کنسول Firebase بروید
  2. روی Manage -> کلیک کنید مدیریت جستجوی برداری با پسوند Firestore
  3. در قسمت How this extension works ، مشخصات پارامترهای ورودی و خروجی را خواهید دید. مستندسازی پارامتر ورودی و مقدار نتیجه
  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 های برداری در فیلد 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 را فراخوانی کنید.

با دانشی که در این نرم افزار کد به دست آوردید، اکنون می توانید برنامه های کاربردی قدرتمندی بسازید که از قابلیت های جستجوی معنایی Cloud Firestore استفاده می کنند تا تجربه جستجوی شهودی و کارآمدتری را برای کاربران فراهم کنند.

برای کسب اطلاعات بیشتر در مورد فیلد برداری جدید Firestore و نحوه محاسبه جاسازی های برداری، مستندات را بررسی کنید.