استخدام Vertex AI Search على ملفات PDF (البيانات غير المنظَّمة) في Cloud Storage من خدمة Cloud Run

1. مقدمة

نظرة عامة

تتيح خدمة Vertex AI Search and Conversation (المعروفة سابقًا باسم Generative AI App Builder) للمطوّرين الاستفادة من قوة النماذج الأساسية وخبرة البحث وتكنولوجيات الذكاء الاصطناعي الحواري من 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 and Conversation.
اقرأ بنود الخدمة ووافِق عليها، ثم انقر على "متابعة" وفعِّل واجهة برمجة التطبيقات.

4. إنشاء تطبيق بحث عن البيانات غير المنظَّمة من Cloud Storage

في Google Cloud Console، انتقِل إلى صفحة "البحث والمحادثة". انقر على تطبيق جديد.
في جزء اختيار نوع التطبيق، اختَر بحث.
تأكَّد من تفعيل ميزات Enterprise لتلقّي إجابات مقتبسة حرفيًا من مستنداتك.
تأكَّد من تفعيل الخيار ميزات النماذج اللغوية الكبيرة المتقدّمة لتلقّي ملخّصات البحث.
في حقل اسم التطبيق، أدخِل اسمًا لتطبيقك. يظهر معرّف التطبيق تحت اسم التطبيق.
اختَر global (عالمي) كموقع جغرافي لتطبيقك، ثم انقر على متابعة.
في لوحة مخازن البيانات، انقر على إنشاء مخزن بيانات جديد.
في لوحة اختيار مصدر بيانات، انقر على Cloud Storage.
في لوحة استيراد البيانات من GCS، تأكَّد من اختيار مجلد.
في الحقل gs://‎، أدخِل القيمة التالية: cloud-samples-data/gen-app-builder/search/stanford-cs-224 تحتوي حزمة Cloud Storage هذه على ملفات PDF من مجلد Cloud Storage متاح للجميع لأغراض الاختبار.
اختَر المستندات غير المنظَّمة، ثمّ انقر على متابعة.
في لوحة ضبط مستودع البيانات، اختَر عالمي (Global) كموقع جغرافي لمستودع البيانات.
أدخِل اسمًا لمستودع البيانات. ستستخدم هذا الاسم لاحقًا في هذا الدرس التطبيقي حول الترميز عند نشر خدمة Cloud Run. انقر على إنشاء.
في لوحة مخازن البيانات، اختَر مخزن البيانات الجديد وانقر على إنشاء.
في صفحة البيانات الخاصة بمستودع البيانات، انقر على علامة التبويب النشاط للاطّلاع على حالة نقل البيانات. يظهر اكتمل الاستيراد في عمود "الحالة" عند اكتمال عملية الاستيراد.
انقر على علامة التبويب المستندات للاطّلاع على عدد المستندات التي تم استيرادها.
في قائمة التنقّل، انقر على معاينة لاختبار تطبيق البحث.
في شريط البحث، أدخِل final lab due date، ثم اضغط على Enter لعرض النتائج.

5- إنشاء خدمة Cloud Run

في هذا القسم، ستنشئ خدمة Cloud Run تقبل سلسلة طلب بحث عن عبارات البحث. ستستخدم هذه الخدمة مكتبات برامج Python لواجهة برمجة التطبيقات Discovery Engine API. بالنسبة إلى أوقات التشغيل الأخرى المتوافقة، يمكنك الاطّلاع على القائمة هنا.

إنشاء رمز المصدر للدالة

أولاً، أنشئ دليلاً وانتقِل إليه.

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 الخاص بـ Cloud Run كمتغيّر بيئة لاستخدامه لاحقًا.

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. تَنظيم

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

لحذف Cloud Function، انتقِل إلى Cloud Function Cloud Console على https://console.cloud.google.com/functions/ واحذف الدالة imagen_vqa (أو $FUNCTION_NAME إذا كنت قد استخدمت اسمًا مختلفًا).

إذا اخترت حذف المشروع بأكمله، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager، واختيار المشروع الذي أنشأته في الخطوة 2، ثم النقر على "حذف". إذا حذفت المشروع، عليك تغيير المشاريع في Cloud SDK. يمكنك الاطّلاع على قائمة بجميع المشاريع المتاحة من خلال تنفيذ gcloud projects list.