1. مقدمة
نظرة عامة
تتيح ميزة Vertex AI Search and Conversation (المعروفة سابقًا باسم "أداة إنشاء تطبيقات الذكاء الاصطناعي التوليدي") للمطوّرين الاستفادة من إمكانات النماذج الأساسية وخبرات البحث وتكنولوجيات الذكاء الاصطناعي الحواري في Google لإنشاء تطبيقات الذكاء الاصطناعي التوليدي على مستوى المؤسسة. يركّز هذا الدرس التطبيقي حول الترميز على استخدام Vertex AI Search، حيث يمكنك إنشاء تطبيق بحث بجودة Google استنادًا إلى بياناتك الخاصة وتضمين شريط بحث في صفحات الويب أو التطبيق.
Cloud Run هو نظام أساسي مُدار للحوسبة يتيح لك تشغيل الحاويات مباشرةً فوق بنية Google الأساسية القابلة للتوسّع. يمكنك نشر الرمز المكتوب بأي لغة برمجة على Cloud Run (مع إمكانية وضعه داخل حاوية) باستخدام خيار النشر المستند إلى المصدر.
في هذا الدرس التطبيقي، ستنشئ خدمة Cloud Run باستخدام النشر المستند إلى المصدر لاسترداد نتائج البحث للمحتوى غير المنظَّم في ملفات PDF في حزمة Cloud Storage. يمكنك الاطّلاع على المزيد من المعلومات حول نقل المحتوى غير المنظَّم هنا.
المعلومات التي ستطّلع عليها
- طريقة إنشاء تطبيق Vertex AI Search للبيانات غير المنظَّمة كملفات PDF تم نقلها من حزمة Cloud Storage
- كيفية إنشاء نقطة نهاية HTTP باستخدام النشر المستند إلى المصدر في Cloud Run
- كيفية إنشاء حساب خدمة وفقًا لمبدأ الحدّ الأدنى للامتيازات الممنوحة لخدمة Cloud Run بهدف استخدامها لطلب البحث في تطبيق Vertex AI Search
- كيفية استدعاء خدمة Cloud Run لطلب بحث عن تطبيق Vertex AI Search
2. الإعداد والمتطلبات
المتطلبات الأساسية
- تسجيل الدخول إلى Cloud Console
- سبق لك نشر خدمة Cloud Run. على سبيل المثال، يمكنك متابعة نشر خدمة ويب من خلال التشغيل السريع لرمز المصدر للبدء.
تفعيل Cloud Shell
- من Cloud Console، انقر على تفعيل Cloud Shell
.
إذا كانت هذه هي المرة الأولى التي تبدأ فيها Cloud Shell، ستظهر لك شاشة وسيطة تصف ماهيتها. إذا ظهرت لك شاشة وسيطة، انقر على متابعة.
من المفترَض أن تستغرق عملية إدارة الحسابات والاتصال بخدمة Cloud Shell بضع دقائق فقط.
يتم تحميل هذا الجهاز الافتراضي مع جميع أدوات التطوير اللازمة. وتوفّر هذه الشبكة دليلاً رئيسيًا دائمًا بسعة 5 غيغابايت ويتم تشغيله في Google Cloud، ما يحسّن بشكل كبير من أداء الشبكة والمصادقة. يمكنك تنفيذ معظم عملك، إن لم يكن كلّه، في هذا الدرس التطبيقي حول الترميز باستخدام متصفّح.
بعد الربط بخدمة Cloud Shell، من المفترض أن تتأكّد من أنّه تمّت مصادقتك وأنّ المشروع مضبوط على رقم تعريف مشروعك.
- شغِّل الأمر التالي في Cloud Shell لتأكيد مصادقتك:
gcloud auth list
مخرجات الأمر
Credentialed Accounts
ACTIVE ACCOUNT
* <my_account>@<my_domain.com>
To set the active account, run:
$ gcloud config set account `ACCOUNT`
- شغّل الأمر التالي في Cloud Shell للتأكد من معرفة الأمر gcloud بمشروعك:
gcloud config list project
مخرجات الأمر
[core] project = <PROJECT_ID>
إذا لم يكن كذلك، يمكنك تعيينه من خلال هذا الأمر:
gcloud config set project <PROJECT_ID>
مخرجات الأمر
Updated property [core/project].
3- تفعيل واجهات برمجة التطبيقات
قبل أن تتمكّن من بدء استخدام Vertex AI Search، عليك تفعيل العديد من واجهات برمجة التطبيقات.
أولاً، يتطلّب هذا الدرس التطبيقي حول الترميز استخدام واجهات برمجة تطبيقات Vertex AI Search and Conversation وBigQuery وCloud Storage. يمكنك تفعيل واجهات برمجة التطبيقات هذه هنا.
ثانيًا، اتّبِع الخطوات التالية لتفعيل Vertex AI Search and Conversation API:
- في Google Cloud Console، انتقِل إلى وحدة التحكّم في المحادثات وVertex AI Search.
- اقرأ بنود الخدمة ووافِق عليها، ثم انقر على "متابعة" وفعِّل واجهة برمجة التطبيقات.
4. إنشاء تطبيق بحث عن البيانات غير المنظَّمة من Cloud Storage
- في وحدة تحكُّم Google Cloud، انتقِل إلى قسم البحث صفحة المحادثات. انقر على تطبيق جديد.
- في لوحة اختيار نوع التطبيق، اختَر بحث.
- تأكَّد من تفعيل ميزات Enterprise لتلقّي الإجابات التي يتم استخراجها حرفيًا من مستنداتك.
- تأكَّد من أنّ خيار الميزات المتقدّمة للنماذج اللغوية الكبيرة مفعَّل لتلقّي تلخيص البحث.
- في الحقل اسم التطبيق، أدخِل اسمًا لتطبيقك. يظهر رقم تعريف التطبيق أسفل اسم التطبيق.
- اختَر عالمي (عالمي) كموقع جغرافي لتطبيقك، ثم انقر على متابعة.
- في لوحة مخازن البيانات، انقر على إنشاء مخزن بيانات جديد.
- في لوحة اختيار مصدر بيانات، اختَر Cloud Storage.
- في لوحة استيراد البيانات من GCS، تأكَّد من اختيار المجلد.
- في الحقل gs://، أدخِل القيمة التالية:
cloud-samples-data/gen-app-builder/search/stanford-cs-224تحتوي حزمة Cloud Storage هذه على ملفات PDF من مجلد متاح للجميع على Cloud Storage لأغراض الاختبار. - اختَر المستندات غير المنظَّمة، ثم انقر على متابعة.
- في لوحة ضبط تخزين البيانات، اختَر عالمي (عالمي) كموقع لمخزن البيانات.
- أدخِل اسمًا لتخزين البيانات. وستستخدم هذا الاسم لاحقًا في هذا الدرس التطبيقي حول الترميز عند نشر خدمة Cloud Run. انقر على إنشاء.
- في لوحة مخازن البيانات، اختَر مخزن البيانات الجديد وانقر على إنشاء.
- في صفحة البيانات على متجر البيانات، انقر على علامة التبويب النشاط للاطّلاع على حالة نقل البيانات. تظهر الحالة تم الاستيراد في عمود "الحالة" عند اكتمال عملية الاستيراد.
- انقر على علامة التبويب المستندات للاطّلاع على عدد المستندات التي تم استيرادها.
- في قائمة التنقّل، انقر على معاينة لاختبار تطبيق البحث.
- في شريط البحث، أدخِل
final lab due date، ثم اضغط على Enter لعرض النتائج.
5- إنشاء خدمة Cloud Run
في هذا القسم، ستُنشئ خدمة تشغيل السحابة الإلكترونية تقبل سلسلة طلب بحث لعبارات بحثك. ستستخدم هذه الخدمة مكتبات عملاء python لواجهة برمجة تطبيقات محرك الاكتشاف. ويمكنك الاطّلاع على القائمة هنا للحصول على بيئات تشغيل أخرى متوافقة.
إنشاء رمز المصدر للدالة
أولاً، أنشئ دليلاً وقرصًا مضغوطًا في هذا الدليل.
mkdir docs-search-service-python && cd $_
بعد ذلك، أنشِئ ملف requirements.txt يتضمّن المحتوى التالي:
blinker==1.6.3 cachetools==5.3.1 certifi==2023.7.22 charset-normalizer==3.3.0 click==8.1.7 Flask==3.0.0 google-api-core==2.12.0 google-auth==2.23.3 google-cloud-discoveryengine==0.11.2 googleapis-common-protos==1.61.0 grpcio==1.59.0 grpcio-status==1.59.0 idna==3.4 importlib-metadata==6.8.0 itsdangerous==2.1.2 Jinja2==3.1.2 MarkupSafe==2.1.3 numpy==1.26.1 proto-plus==1.22.3 protobuf==4.24.4 pyasn1==0.5.0 pyasn1-modules==0.3.0 requests==2.31.0 rsa==4.9 urllib3==2.0.7 Werkzeug==3.0.1 zipp==3.17.0
بعد ذلك، أنشِئ ملف مصدر main.py يتضمّن المحتوى التالي:
from typing import List
import json
import os
from flask import Flask
from flask import request
app = Flask(__name__)
from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine
project_id = os.environ.get('PROJECT_ID')
location = "global" # Values: "global", "us", "eu"
data_store_id = os.environ.get('SEARCH_ENGINE_ID')
print(project_id)
print(data_store_id)
@app.route("/")
def search_storage():
search_query = request.args.get("searchQuery")
result = search_sample(project_id, location, data_store_id, search_query)
return result
def search_sample(
project_id: str,
location: str,
data_store_id: str,
search_query: str,
) -> str:
# For more information, refer to:
# https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
client_options = (
ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
if location != "global"
else None
)
# Create a client
client = discoveryengine.SearchServiceClient(client_options=client_options)
# The full resource name of the search engine serving config
# e.g. projects/{project_id}/locations/{location}/dataStores/{data_store_id}/servingConfigs/{serving_config_id}
serving_config = client.serving_config_path(
project=project_id,
location=location,
data_store=data_store_id,
serving_config="default_config",
)
# Optional: Configuration options for search
# Refer to the `ContentSearchSpec` reference for all supported fields:
# https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest.ContentSearchSpec
content_search_spec = discoveryengine.SearchRequest.ContentSearchSpec(
# For information about snippets, refer to:
# https://cloud.google.com/generative-ai-app-builder/docs/snippets
snippet_spec=discoveryengine.SearchRequest.ContentSearchSpec.SnippetSpec(
return_snippet=True
),
# For information about search summaries, refer to:
# https://cloud.google.com/generative-ai-app-builder/docs/get-search-summaries
summary_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec(
summary_result_count=5,
include_citations=True,
ignore_adversarial_query=True,
ignore_non_summary_seeking_query=True,
),
)
# Refer to the `SearchRequest` reference for all supported fields:
# https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest
request = discoveryengine.SearchRequest(
serving_config=serving_config,
query=search_query,
page_size=10,
content_search_spec=content_search_spec,
query_expansion_spec=discoveryengine.SearchRequest.QueryExpansionSpec(
condition=discoveryengine.SearchRequest.QueryExpansionSpec.Condition.AUTO,
),
spell_correction_spec=discoveryengine.SearchRequest.SpellCorrectionSpec(
mode=discoveryengine.SearchRequest.SpellCorrectionSpec.Mode.AUTO
),
)
response = client.search(request)
return response.summary.summary_text
if __name__ == "__main__":
app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
إعداد متغيرات البيئة
في هذا الرمز البرمجي، عليك إنشاء بعض متغيّرات البيئة لتحسين إمكانية قراءة أوامر gcloud المستخدمة في هذا الدرس التطبيقي حول الترميز.
PROJECT_ID=$(gcloud config get-value project) SERVICE_NAME="search-storage-pdfs-python" SERVICE_REGION="us-central1" # update with your data store name SEARCH_ENGINE_ID=<your-data-store-name>
إنشاء حساب للخدمة
يشرح لك هذا الدرس التطبيقي حول الترميز كيفية إنشاء حساب خدمة لخدمة Cloud Run لاستخدامه في الوصول إلى Vertex AI Search API.
SERVICE_ACCOUNT="cloud-run-vertex-ai-search" SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com gcloud iam service-accounts create $SERVICE_ACCOUNT \ --display-name="Cloud Run Vertex AI Search service account" gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \ --role='roles/discoveryengine.editor'
نشر خدمة Cloud Run
يمكنك الآن استخدام عملية نشر مستندة إلى المصدر لإعداد خدمة Cloud Run الخاصة بك تلقائيًا.
gcloud run deploy $SERVICE_NAME \ --region=$SERVICE_REGION \ --source=. \ --service-account $SERVICE_ACCOUNT \ --update-env-vars SEARCH_ENGINE_ID=$SEARCH_ENGINE_ID,PROJECT_ID=$PROJECT_ID \ --no-allow-unauthenticated
وبعد ذلك يمكنك حفظ عنوان URL لتشغيل السحابة الإلكترونية كمتغيّر بيئة لاستخدامه لاحقًا.
ENDPOINT_URL="$(gcloud run services describe $SERVICE_NAME --region=$SERVICE_REGION --format='value(status.url)')"
6- الاتصال بخدمة Cloud Run
يمكنك الآن الاتصال بخدمة Cloud Run باستخدام سلسلة طلب بحث لطرح طلب على What is the final lab due date?.
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" "$ENDPOINT_URL?searchQuery=what+is+the+final+lab+due+date"
يجب أن تبدو نتائجك مشابهة لمثال الإخراج أدناه:
The final lab is due on Tuesday, March 21 at 4:30 PM [1].
7. تهانينا
تهانينا على إكمال الدرس التطبيقي حول الترميز.
ننصحك بمراجعة المستندات المتعلّقة بخدمتَي Vertex AI Search وCloud Run.
النقاط التي تناولناها
- طريقة إنشاء تطبيق Vertex AI Search للبيانات غير المنظَّمة كملفات PDF تم نقلها من حزمة Cloud Storage
- كيفية إنشاء نقطة نهاية HTTP باستخدام النشر المستند إلى المصدر في Cloud Run
- كيفية إنشاء حساب خدمة وفقًا لمبدأ الحدّ الأدنى للامتيازات الممنوحة لخدمة Cloud Run من أجل استخدامها لطلب البحث عن تطبيق Vertex AI Search
- كيفية استدعاء خدمة Cloud Run لطلب بحث عن تطبيق Vertex AI Search
8. تَنظيم
لتجنُّب تحصيل رسوم غير مقصودة (على سبيل المثال، إذا تم استدعاء هذه "الوظيفة السحابية" مرات أكثر من تخصيص استدعاء "الوظيفة السحابية" الشهرية في الفئة المجانية)، يمكنك إما حذف "دالة السحابة الإلكترونية" أو حذف المشروع الذي أنشأته في الخطوة 2.
لحذف دالة Cloud، انتقِل إلى Cloud Function في Cloud Console على الرابط https://console.cloud.google.com/functions/ واحذف الدالة imagen_vqa (أو $FUNCTION_NAME في حال استخدام اسم مختلف).
إذا اخترت حذف المشروع بالكامل، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager، واختيار المشروع الذي أنشأته في الخطوة الثانية، ثم اختيار "حذف". إذا حذفت المشروع، ستحتاج إلى تغيير المشاريع في حزمة تطوير البرامج (SDK) للسحابة الإلكترونية. يمكنك عرض قائمة بجميع المشاريع المتاحة من خلال تشغيل gcloud projects list.