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

۱. مرور کلی

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

آنچه یاد خواهید گرفت

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

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

• ایکس‌کد ۱۵.۳
• نمونه کد codelab. این کد را در مرحله بعدی codelab دانلود خواهید کرد.

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

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

ایجاد یک پروژه فایربیس

1. با استفاده از حساب گوگل خود وارد کنسول فایربیس شوید.
2. برای ایجاد یک پروژه جدید، روی دکمه کلیک کنید و سپس نام پروژه را وارد کنید (برای مثال، Firestore Vector Search Codelab ).
   
3. روی ادامه کلیک کنید.
4. در صورت درخواست، شرایط Firebase را مرور و قبول کنید و سپس روی ادامه کلیک کنید.
5. (اختیاری) دستیار هوش مصنوعی را در کنسول Firebase (با نام "Gemini در Firebase") فعال کنید.
6. برای این codelab، به گوگل آنالیتیکس نیاز ندارید ، بنابراین گزینه گوگل آنالیتیکس را غیرفعال کنید .
7. روی ایجاد پروژه کلیک کنید، منتظر بمانید تا پروژه شما آماده شود و سپس روی ادامه کلیک کنید.

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

طرح قیمت‌گذاری فایربیس خود را ارتقا دهید

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

• یک حساب Cloud Billing به یک روش پرداخت، مانند کارت اعتباری، نیاز دارد.
• اگر در استفاده از فایربیس و گوگل کلود تازه‌کار هستید، بررسی کنید که آیا واجد شرایط دریافت اعتبار ۳۰۰ دلاری و یک حساب کاربری رایگان ابری هستید یا خیر.
• اگر این codelab را به عنوان بخشی از یک رویداد انجام می‌دهید، از برگزارکننده خود بپرسید که آیا امکان استفاده از فضای ابری (Cloud credits) وجود دارد یا خیر.

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

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

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

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

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

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

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

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

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

راه اندازی کلود فایر استور

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

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

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

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

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

در اینجا نحوه تنظیم فضای ذخیره‌سازی ابری برای فایربیس در پروژه فایربیس شما آورده شده است:

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

۳. برنامه موبایل را وصل کنید

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

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

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

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

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

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

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

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

حالا وقتشه که یه نگاهی به برنامه بندازیم!

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

۴. افزونه Vector Search with Firestore را نصب کنید

در این بخش از آزمایشگاه کد، افزونه‌ی Vector Search with Firestore را نصب خواهید کرد و آن را با الزامات برنامه‌ی یادداشت‌برداری که روی آن کار می‌کنید، پیکربندی خواهید کرد.

نصب افزونه را شروع کنید

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

پیکربندی افزونه

1. API های فعال شده و منابع ایجاد شده را بررسی کنید.
2. سرویس‌های مورد نیاز را فعال کنید.
3. پس از فعال کردن همه سرویس‌ها، روی «بعدی» کلیک کنید.
4. دسترسی‌های داده شده به این افزونه را بررسی کنید.
5. افزونه را پیکربندی کنید:
   • Vertex AI را به عنوان LLM انتخاب کنید
   • مسیر جمع‌آوری : یادداشت‌ها
   • محدودیت پیش‌فرض پرس‌وجو : ۳
   • نام فیلد ورودی : متن
   • نام فیلد خروجی: جاسازی
   • نام فیلد وضعیت: * *وضعیت*
   • جاسازی اسناد موجود : بله
   • به‌روزرسانی اسناد موجود : بله
   • محل عملکرد ابری : us-central1
6. برای اتمام نصب، روی نصب افزونه کلیک کنید.

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

۵. پیشینه

در حالی که منتظر اتمام نصب هستید، در اینجا اطلاعاتی در مورد نحوه‌ی کار افزونه‌ی Vector Search with Firestore ارائه شده است.

بردارها، جاسازی‌ها و پایگاه‌های داده برداری چیستند؟

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

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

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

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

۶. جستجوی برداری با افزونه Firestore را امتحان کنید

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

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

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

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

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

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

1. همچنان در مرورگر داده‌های Firestore، به مجموعه notes بروید و روی + افزودن سند در ستون وسط کلیک کنید.
2. برای ایجاد یک شناسه سند منحصر به فرد جدید، روی «شناسه خودکار» کلیک کنید.
3. یک فیلد به نام text از نوع string اضافه کنید و متنی را در فیلد 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. در Cloud Log Explorer، اکنون باید پیام خطایی با عنوان «FAILED_PRECONDITION: Missing vector index configuration. Please create the required index with the following gcloud command: ...» مشاهده کنید.
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
   

   ایجاد ایندکس چند دقیقه طول می‌کشد. می‌توانید پیشرفت کار را در تب Indexes در بخش Firestore کنسول Firebase بررسی کنید.
10. پس از تنظیم ایندکس، می‌توانید یک سند پرس‌وجوی جدید ایجاد کنید.
11. اکنون باید لیستی از شناسه‌های سند منطبق را در فیلد نتایج مشاهده کنید.
12. یکی از آن شناسه‌ها را کپی کنید و به مجموعه notes برگردید.
13. برای جستجوی شناسه سندی که کپی کرده‌اید از کلیدهای ⌘+F استفاده کنید - این سندی است که به بهترین شکل با عبارت شما مطابقت دارد.

۷. جستجوی معنایی را پیاده‌سازی کنید

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

اتصال تابع قابل فراخوانی برای انجام کوئری‌ها

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

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

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

4. به کنسول فایربیس مربوط به پروژه خود بروید و در بخش ساخت (Build) ، گزینه‌ی «Functions» را از منو باز کنید.
5. لیستی از توابعی که توسط افزونه نصب شده‌اند را مشاهده خواهید کرد.
6. به دنبال فایلی با نام ext-firestore-vector-search-queryCallable بگردید و نام آن را کپی کنید.
7. نام را در کد خود جایگذاری کنید. اکنون باید اینطور باشد:

   private lazy var vectorSearchQueryCallable: Callable<String, String> = functions.httpsCallable("ext-firestore-vector-search-queryCallable")
   

تابع پرس و جو را فراخوانی کنید

1. متد performQuery را پیدا کنید
2. با فراخوانی، تابع قابل فراخوانی خود را فراخوانی کنید

   let result = try await vectorSearchQueryCallable(searchTerm)
   

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

3. برای گرفتن هرگونه خطا و ثبت آنها در کنسول 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 view که توسط 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 شما را به صورت ناهمگام فراخوانی می‌کند. با تعیین زمان انقضای ۸۰۰ میلی‌ثانیه، به اصلاح‌کننده‌ی وظیفه دستور می‌دهید که ورودی کاربر را به مدت ۰.۸ ثانیه متوقف کند. این بدان معناست که semanticSearch فقط زمانی فراخوانی می‌شود که کاربر تایپ کردن را بیش از ۰.۸ ثانیه متوقف کند.

کد شما اکنون باید به این شکل باشد:

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

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

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

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. به بخش افزونه‌ها در کنسول فایربیس بروید
2. روی مدیریت کلیک کنید ->
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

پس از اتمام ساخت ایندکس، برنامه را دوباره اجرا کنید تا تأیید شود که طبق انتظار کار می‌کند.

۸. تبریک

تبریک - شما با موفقیت این آزمایشگاه کد را به پایان رساندید!

در این آزمایشگاه کد، شما یاد گرفتید که چگونه:

• یک پایگاه داده Cloud Firestore با جستجوی معنایی فعال راه‌اندازی کنید.
• یک برنامه SwiftUI ساده برای تعامل با پایگاه داده ایجاد کنید.
• با استفاده از اصلاح‌کننده نمای قابل جستجو و اصلاح‌کننده وظیفه SwiftUI، یک نوار جستجو پیاده‌سازی کنید.
• با استفاده از رابط فراخوانی‌پذیر Firestore SDK، یک تابع ابری را برای انجام جستجوی معنایی در پایگاه داده فراخوانی کنید.

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

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