مرحبًا بك في PetVerse!

1. مقدمة

مرحبًا بك في Petverse! يُسمح باصطحاب جميع الحيوانات الأليفة. 🐈🐶🐍🐟🦄

المتطلبات الأساسية

  • فهم أساسي لـ Google Cloud Console
  • فهم أساسي لجمل SQL

ما ستتعلمه

  • إنشاء مجموعات بيانات وجداول في BigQuery
  • إنشاء أعمدة ObjectRef للإشارة إلى الوسائط المتعددة في مجموعة بيانات في BigQuery
  • استخدام وظائف الذكاء الاصطناعي في BigQuery لتحسين مجموعة البيانات من محتوى البيانات غير المنظَّمة
  • إنشاء عمليات تضمين للوسائط المتعددة للبحث عن وسائط مشابهة
  • إنشاء تضمينات نصية لإجراء بحث دلالي باستخدام VECTOR_SEARCH
  • استخدام Gemini CLI لإنشاء تطبيق ويب

المتطلبات

  • حساب Google Cloud ومشروع Google Cloud مع حساب فوترة
  • متصفّح ويب، مثل Chrome

2. الإعداد والمتطلبات

إعداد البيئة بالسرعة التي تناسبك

  1. سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
  • رقم تعريف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره بعد ضبطه. تنشئ Cloud Console تلقائيًا سلسلة فريدة، ولا يهمّك عادةً ما هي. في معظم دروس البرمجة، عليك الرجوع إلى رقم تعريف مشروعك (يُشار إليه عادةً باسم PROJECT_ID). إذا لم يعجبك رقم التعريف الذي تم إنشاؤه، يمكنك إنشاء رقم تعريف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم من اختيارك ومعرفة ما إذا كان متاحًا. لا يمكن تغيير هذا الخيار بعد هذه الخطوة وسيظل ساريًا طوال مدة المشروع.
  • للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات عن كل هذه القيم الثلاث في المستندات.
  1. بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس التطبيقي حول الترميز الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تحمّل تكاليف فوترة تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

3- افتح Cloud Shell

انتقِل إلى https://shell.cloud.google.com/?show=ide%2Cterminal . انقر على تفويض عندما يُطلب منك ذلك.

1bfca4be2c270a9f.png

تأكَّد من ظهور كلّ من المحرّر ووحدة التحكّم:

785d186a8b11b32b.png

4. إنشاء نص برمجي مساعد

لتسهيل هذه التجربة، عليك إنشاء نص برمجي مساعد يضبط متغيرات البيئة ذات الصلة.

استبدِل <<Project ID>> برقم تعريف مشروعك أدناه.

انسخ الأمر التالي في نافذة Cloud Shell الطرفية واضغط على Enter لتنفيذه**.**

gcloud config set project <<PROJECT_ID>>

ffd97bad1f398b4b.png

انسخ الأمر التالي في نافذة Cloud Shell الطرفية واضغط على Enter لتنفيذه**.** سيؤدي ذلك إلى تفعيل الخدمات اللازمة وإنشاء الملف وتعديله في Cloud Shell.

gcloud services enable compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       aiplatform.googleapis.com \
                       storage-component.googleapis.com  \
                       bigqueryconnection.googleapis.com \
run.googleapis.com \
secretmanager.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com  \
iap.googleapis.com
edit  ~/petverse-setup.sh

من المفترض أن تظهر لك علامة تبويب جديدة باسم الملف. ألصِق النص البرمجي التالي في الملف الجديد:

#!/bin/bash

# -----------------------------------------------------------------------------
# 1. Global Variables: Set your desired project ID and region here.
# -----------------------------------------------------------------------------

# 🦄 🦄 Set your project ID here ⬇️.

# Example: PROJECT_ID="your-project-id"
PROJECT_ID=""

# Set your desired region here. Default is 'us-central1'.
# Example: REGION="us-east1"
REGION="us-central1"

# -----------------------------------------------------------------------------
# 2. Check and Authenticate
# -----------------------------------------------------------------------------

echo "  ➡️   Checking for active Google Cloud authentication..."

# Check if the user is authenticated; if not, prompt for authentication.
if ! gcloud auth list --format="value(account)" | grep -q @; then
  echo "⚠️   Not authenticated. Please authenticate now."
  gcloud auth login
fi

echo "  ✅   Authentication check passed."

# -----------------------------------------------------------------------------
# 3. Get Project ID from User if not set
# -----------------------------------------------------------------------------

# If PROJECT_ID is not set in the script or as an environment variable,
# prompt the user to choose one.
if [[ -z "$PROJECT_ID" ]] && [[ -n "$DEVSHELL_PROJECT_ID" ]]; then
  PROJECT_ID=$DEVSHELL_PROJECT_ID
fi

if [[ -z "$PROJECT_ID" ]]; then
  echo "  ⚠️   Project ID is not set. Listing available projects:"
 
  # List projects and store them in an array.
  projects_array=($(gcloud projects list --format="value(projectId)"))
 
  # Check if projects were found.
  if [[ ${#projects_array[@]} -eq 0 ]]; then
    echo "  ❌   No projects found. Please ensure your account has access to projects."
    exit 1
  fi
 
  # Display the projects and prompt for input.
  echo " "
  echo "Available Projects:"
  for project in "${projects_array[@]}"; do
    echo "$project"
  done
 
  echo " "
  read -p "Please enter your desired project ID from the list above: " PROJECT_ID
 
  # Validate the user's input by checking if it's in the array.
  if [[ ! " ${projects_array[@]} " =~ " ${PROJECT_ID} " ]]; then
    echo "  ❌   Invalid project ID. Please run the script again and select a valid ID."
    exit 1
  fi
fi

echo "  ✅   Project ID set to: $PROJECT_ID"

# -----------------------------------------------------------------------------
# 4. Set Environment Variables
# -----------------------------------------------------------------------------

# Set the project and region for the current session.
echo "  🔄   Setting Google Cloud configuration for this session..."
gcloud config set project "$PROJECT_ID"
gcloud config set compute/region "$REGION"

echo "  ✅   Google Cloud configuration updated."
echo "Project ID: $PROJECT_ID"
echo "Region: $REGION"
echo " "
echo "  🎉 🦄 🦄   Script execution complete. You can now use Google Cloud commands in this shell session."

استبدِل العنصر النائب الخاص بـ PROJECT_ID باسم مشروعك:

aec2195d576244dd.png

انسخ الأمر التالي ونفِّذه في الوحدة الطرفية:

chmod +x petverse-setup.sh
~/petverse-setup.sh

الناتج المتوقّع:

83d1f7405624443b.png

5- إنشاء حزمة تخزين

أنشئ حزمة في Cloud Storage وانسخ الوسائط المتاحة إلى حزمتك. سيتم استخدام هذا المجلد لتخزين الوسائط المتاحة لحيواناتنا الأليفة الرائعة. ستنشئ أيضًا اتصالاً للوصول إلى الحزمة من خلال BigQuery.

ألصِق ما يلي ونفِّذه في الوحدة الطرفية:

~/petverse-setup.sh
cd ~/
gcloud storage buckets create gs://$DEVSHELL_PROJECT_ID-petverse --uniform-bucket-level-access --location=us-central1
gcloud storage cp -r gs://sample-data-and-media/petverse/* gs://$DEVSHELL_PROJECT_ID-petverse/
bq mk --dataset --location=us-central1 --project_id=$DEVSHELL_PROJECT_ID petverse
bq mk --connection --location=us-central1 --project_id=$DEVSHELL_PROJECT_ID \
--connection_type=CLOUD_RESOURCE pet-connection
echo "your bucket is gs://$DEVSHELL_PROJECT_ID-petverse "

379f72ee2908da36.png

6. إنشاء جدول الحيوانات الأليفة

ستنشئ الآن جدولاً في BigQuery لتخزين معلومات عن حيواناتك الأليفة.

افتح علامة تبويب جديدة في المتصفّح. انتقِل إلى https://console.cloud.google.com/bigquery .

تأكَّد من اختيار المشروع نفسه الذي كنت تستخدمه في وحدة التحكّم:

f82010a317866e6.png

يمكنك الآن إنشاء جدول باستخدام البيانات الواردة في الملف pets.csv. يحتوي هذا الملف على أسماء حيواناتنا الأليفة وأطعمتها وألعابها المفضّلة ومعلومات أخرى مثيرة للاهتمام عنها.

انسخ الرمز التالي في طلب بحث SQL جديد لإنشاء جدول فعلي وتحميل البيانات.

LOAD DATA INTO petverse.pets
OPTIONS(
    description="Table for furry friend data"
  )
FROM FILES (
  skip_leading_rows=1,
  uris = ['gs://<<your_bucket_name>>/pets.csv'],
  format = 'CSV'
);

استبدِل العنصر النائب للحزمة في الرمز البرمجي بالحزمة التي أنشأتها في الخطوة السابقة.

يمكنك الاطّلاع على جميع حِزم التخزين في علامة تبويب متصفّح منفصلة تشير إلى عنوان URL هذا: https://console.cloud.google.com/storage/browser .

757813944bb3d8ba.png

استخدِم الزر تنفيذ لتنفيذ طلب البحث.

بعد تحميل البيانات بنجاح، انقر على الانتقال إلى الجدول.

d6aab61d533bedde.png

انقر على معاينة للاطّلاع على محتوى الجدول. 20fb1cbf8826efca.png

7. ربط BigQuery بحزمة التخزين

إذا نظرت في الحزمة التي أنشأتها سابقًا، ستجد مجموعة من ملفات الوسائط ذات الصلة بكل حيوان أليف.

243751f1b0aab329.gif

تتيح BigQuery إمكانية القراءة في هذه الحِزم واستخدام الملفات إلى جانب البيانات في الجداول. يُطلق على نوع القيمة هذا اسم ObjectRef.

احصل على رقم تعريف حساب الخدمة للربط الذي أنشأته سابقًا من خلال النقر عليه ضمن عمليات الربط الخارجية.

1d9d3275483f5650.png

انسخ معرّف حساب الخدمة.

انتقِل إلى "وحدة تحكّم المشرف في إدارة الهوية وإمكانية الوصول" في علامة تبويب جديدة في المتصفّح ( https://console.cloud.google.com/iam-admin/ ).

امنح حساب الخدمة إذن عارض عنصر التخزين ومستخدم Vertex AI (ستستخدم هذا الإذن لاحقًا).

f1ff6b305d914532.png

انقر على حفظ و🕰️ انتظر بضع دقائق.

في علامة التبويب BigQuery، استخدِم طلب البحث التالي في BigQuery Studio لاختبار عملية الربط بين BigQuery وحزمة التخزين.

استبدِل <<PROJECT_ID>> برقم تعريف مشروعك.

SET @@location='us-central1';
SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/yoda_profile_picture.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))

انقر على عرض النتائج. من المفترض أن تظهر لك البيانات الوصفية في النتائج:

9e3d986b797e413a.png

8. إضافة وسائط التخزين إلى البيانات المنظَّمة

يمكنك تحسين جدول الحيوانات الأليفة لإضافة عمود يتضمّن صورة الملف الشخصي لكل حيوان أليف عند توفّرها. ستضيف أيضًا عمودًا آخر يتضمّن مجموعة من مراجع الوسائط، وذلك لتضمين جميع الملفات الأخرى ذات الصلة بكل حيوان أليف.

يتطلّب الوصول إلى الوسائط المتعددة اتصالاً أنشأته في بداية هذا الدرس التطبيقي حول الترميز بعد إنشاء الحزمة.

الصِق الأوامر التالية في وحدة تحكّم BigQuery SQL ونفِّذها لإضافة عمودَين إلى جدول pets.

SET @@location='us-central1';
ALTER TABLE petverse.pets
ADD COLUMN IF NOT EXISTS profile_picture STRUCT<uri STRING, version STRING, authorizer STRING, details JSON>,
ADD COLUMN IF NOT EXISTS additional_media ARRAY<STRUCT<uri STRING, version STRING, authorizer STRING, details JSON>>;

انسخ العبارات التالية واستبدِل العنصر النائب PROJECT_ID برقم تعريف مشروعك.

SET @@location='us-central1';

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/yoda_profile_picture.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/Yoda_asks_for_cuddles.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 1;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/madonna_profile_picture.jpg', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/Madonna_description.wav', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 2;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/pixel_profile_picture.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/pixel_thug_life.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
                       (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/pixel_description.wav', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 3;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/sql_profile_picture.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/SQL_description.wav', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
                       (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/SQL_favorite_toy.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 4;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/buddy_golden_retriever.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = NULL
WHERE Id = 5;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/daisy_french_bulldog.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = NULL
WHERE Id = 6;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/max_german_shepherd.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/max_description_tells_jokes.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 7;

UPDATE petverse.pets SET profile_picture = NULL, additional_media = NULL WHERE Id = 8;

UPDATE petverse.pets SET profile_picture = NULL, additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/rocky_description.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))] WHERE Id = 9;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/pip_hamster.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/pip_Hamster_Wheel_Video_Generated.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 10;

UPDATE petverse.pets SET profile_picture = NULL, additional_media = NULL WHERE Id = 11;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/scales_snake.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = NULL
WHERE Id = 12;

UPDATE petverse.pets SET profile_picture = NULL, additional_media = NULL WHERE Id = 13;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/Joel_Profile_Picture.jpg', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/Joel_Catwalk.jpg', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
                       (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/Joel_Flowers.jpg', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
                       (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/Joel_Plays.jpg', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 14;

نفِّذ البيان. من المفترض أن تظهر عمليات التنفيذ الناجحة بعد بضع دقائق:

4fa3bba70440fa65.png

راجِع النتائج باستخدام معاينة الجدول. يجب أن تظهر لك البيانات الوصفية لصور الملف الشخصي الحالية والوسائط الإضافية للقطة التي تحمل اسم Pixel.

SELECT *
FROM `petverse.pets`
WHERE name = 'Pixel'

a1511d749e88d5f5.png

9- إنشاء أوصاف للحيوانات الأليفة

إذا عاينت جدول الحيوانات الأليفة، ستلاحظ أنّ بعض الحيوانات الأليفة، مثل Yoda أو Pixel أو Rocky، لا يتضمّن طعامها أو لعبتها المفضّلة.

قد تكون الإجابات عن هذه الأسئلة في الفيديوهات والمقاطع الصوتية ذات الصلة بهذه الحيوانات الأليفة. ستستخدم دوال الذكاء الاصطناعي المضمّنة للتحقّق من ذلك.

اختبِر ذلك باستخدام العبارة التالية:

SELECT name,
AI.GENERATE(
   prompt=> ('What are this pet\'s favorite toy and favorite foods', additional_media ),
    connection_id => 'us-central1.pet-connection',
    endpoint => 'gemini-2.5-flash',
output_schema => 'food STRING, toy STRING')
FROM petverse.pets
WHERE name = 'Rocky'

يمكنك الاطّلاع على فيديو Rocky في حزمة التخزين.

استخدِم العبارة التالية لتعديل الأوصاف الناقصة:

UPDATE petverse.pets AS p
SET FavoriteFood = aigen.food
FROM
  (
    SELECT Id, name,
          AI.GENERATE(
                prompt=> ('What are this pet\'s favorite toy and favorite foods', additional_media ),
                connection_id => 'us-central1.pet-connection',
                endpoint => 'gemini-2.5-flash',
                output_schema => 'food STRING').food
    FROM petverse.pets ) AS  aigen
WHERE p.Id = aigen.Id
AND p.FavoriteFood IS NULL
AND p.additional_media IS NOT NULL

استخدِم العبارة التالية لإنشاء وصف للحيوانات الأليفة استنادًا إلى الوسائط المتعددة الخاصة بها في عمود جديد:

ALTER TABLE petverse.pets ADD COLUMN MediaDescription STRING;
UPDATE petverse.pets AS p
SET MediaDescription = aigen.description
FROM
  (
    SELECT Id, name,
          AI.GENERATE(
                prompt=> ('Create a description in an epic tone for this pet based on these media: ', additional_media ),
                connection_id => 'us-central1.pet-connection',
                endpoint => 'gemini-2.5-flash',
                output_schema => 'description STRING').description
    FROM petverse.pets ) AS  aigen
WHERE p.Id = aigen.Id
AND p.MediaDescription IS NULL
AND p.additional_media IS NOT NULL

من المفترض أن تظهر بعض الأوصاف الإبداعية بعد بضع دقائق:

fab3b59caa69aec7.png

10. إنشاء تضمينات

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

SET @@location='us-central1';

CREATE OR REPLACE MODEL petverse.multimodalembedding
  REMOTE WITH CONNECTION `us-central1.pet-connection`
  OPTIONS(ENDPOINT = 'multimodalembedding@001');

CREATE TABLE IF NOT EXISTS petverse.profile_embeddings
AS
SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL petverse.multimodalembedding,
    (
      SELECT profile_picture as content,
      Id
      FROM petverse.pets)
 );

CREATE OR REPLACE MODEL petverse.textembedding
  REMOTE WITH CONNECTION `us-central1.pet-connection`
  OPTIONS (ENDPOINT = 'text-embedding-005');

CREATE OR REPLACE TABLE petverse.text_embeddings AS
SELECT * FROM ML.GENERATE_EMBEDDING(
  MODEL petverse.textembedding,
  (
    SELECT CONCAT(AdoptionStory, ' . This pet\'s hobby is: ', Hobby, ' and their nickname(s) is: ', COALESCE(Nicknames, Name)) AS content,
    Id, Name
    FROM petverse.pets
    WHERE LENGTH(AdoptionStory) > 0 AND LENGTH(Hobby) > 0
  )
)
WHERE LENGTH(ml_generate_embedding_status) = 0;

تحقَّق من الجدول الجديد من علامة تبويب النتائج.

c9e876d75147c343.png

استخدِم العبارة التالية للتحقّق من حالة جميع عمليات التضمين:

SELECT DISTINCT(ml_generate_embedding_status),
  COUNT(content.uri) AS num_rows
FROM petverse.profile_embeddings
GROUP BY 1;

في حال حدوث أي أخطاء، ستظهر لك في حالة غير فارغة. هذا هو الناتج الصحيح - لا توجد سجلات تتضمّن أخطاء**:**

e6754936c31ca5cf.png

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

736545fbc7ce4ac8.png

البحث عن حيوانات أليفة مشابهة

تتضمّن مجموعة البيانات التلقائية حيوانات أليفة مشابهة. في ما يلي مثالان: Pixel (المعرّف: 3) وSQL (المعرّف: 4):

cfebe01afc5f4858.png

يمكنك استخدام المسافة بين التضمينات لحساب الحيوانات الأليفة المشابهة:

SELECT
t2.id AS similar_pet_id,
COSINE_DISTANCE(t1.ml_generate_embedding_result, t2.ml_generate_embedding_result) AS distance
FROM
petverse.profile_embeddings AS t1,
petverse.profile_embeddings AS t2
WHERE
t1.Id = 3 -- The pet you want to find similar ones to
AND t1.Id != t2.Id -- Exclude the pet itself from the results
AND t1.content.uri IS NOT NULL
AND t2.content.uri IS NOT NULL
ORDER BY
distance
LIMIT 5;

يجب أن تحصل على نتائج تتضمّن أرقام تعريف للصور المتشابهة. سيشمل ذلك كل ما في الصورة. في هذا المثال، يتشابه Pixel وSQL، والحيوان الأليف الأكثر تشابهًا هو Joel (المعرّف: 14).

99ce203add04a6b1.png

في ما يلي صورة "جويل" كمرجع:

f78e0ca0fe235ba2.png

يمكنك استخدام الدالة VECTOR_SEARCH للبحث الدلالي في تضمينات النصوص. إذا كان هذا الجدول أكبر، عليك إنشاء فهرس لعمليات التضمين.

SELECT query.query, base.content, base.Name
FROM VECTOR_SEARCH(
  TABLE `petverse.text_embeddings`, 'ml_generate_embedding_result',
  (
  SELECT ml_generate_embedding_result, content AS query
  FROM ML.GENERATE_EMBEDDING(
  MODEL `petverse.textembedding`,
  (SELECT 'Pets who like to relax' AS content))
  ),
  top_k => 5, options => '{"fraction_lists_to_search": 0.50}')
ORDER BY distance DESC

جرِّب تغيير عبارة البحث الدلالي (Pets who like to relax) بالإضافة إلى المَعلمة fraction_lists_to_search وشاهِد ما يحدث. يمكنك الاطّلاع على مزيد من المعلومات حول هذه الوظائف هنا.

11. إنشاء صفحة ملف شخصي بأسلوب "البرمجة الوصفية"

ستستخدم Gemini CLI في Cloud Shell لبدء تشغيل تطبيق ويب بسيط تجريبي. تم تبسيط تطبيق الويب هذا في طلبه لتوضيح كيف يمكن أن يصبح Petverse حقيقة.

ارجع إلى Cloud Shell. ستحصل على تجربة أفضل عند استخدام وحدة التحكّم فقط في وضع ملء الشاشة:

b5061fb060f2a958.png

شغِّل النص البرمجي الخاص ببدء التهيئة للتأكّد من ضبط متغيرات البيئة، وأنشئ دليلاً يحتوي على هذا المشروع، ونفِّذ Gemini CLI:

~/petverse-setup.sh
mkdir petverse-profiles
cd petverse-profiles
gemini

من المفترض أن يظهر لك واجهة سطر الأوامر في Gemini:

910fda2312082974.png

استبدِل اسم الحزمة في الطلب أدناه.

الصِق الطلب في سطر أوامر Gemini.

You are a fullstack engineer creating an application to display the profiles of cats, dogs and other pets stored in BigQuery. The table where these are stored is called pets, in the dataset petverse.
1.Application Requirements: Display the pets with their profile picture, all the other information in the Pets table, and other media that may be available. The pictures are in a GCS bucket, the field in the table pets profile_picture.uri contains the URI for the storage bucket of that profile picture.  The field additional_media is an array of objectref that contains multiple URI to different media stored in a GCS bucket.
Important: In the code, in the values for the URIs retrieved from BigQuery, replace gs://<<YOUR_PROJECT_ID>>-petverse/ with https://storage.mtls.cloud.google.com/<<YOUR_PROJECT_ID>>-petverse/ as follows: replace('gs://', 'https://storage.mtls.cloud.google.com/'). Use the python library. Media can be pictures, videos and audio. Consider these formats in the code. Some pets may not have profile pictures or additional media.
2.Hosting: Create a web application hosted in a single container and service in Cloud Run, use the following syntax to deploy it using IAP. IMPORTANT: DO NOT ADD IAM AUTHENTICATION AND DO NOT ALLOW UNAUTHENTICATED: gcloud beta run deploy SERVICE_NAME  --region=REGION --image=IMAGE_URL  --no-allow-unauthenticated --iap
3.Database access: Display similar pets based on a similarity between embeddings in table petverse.profile_embeddings. 
Here's the schema for the pets table in CSV format (Field name, type, mode):
Id,INTEGER,NULLABLE
Name,STRING,NULLABLE
Species,STRING,NULLABLE
Breed,STRING,NULLABLE
Nationality,STRING,NULLABLE
Nicknames,STRING,NULLABLE
Hobby,STRING,NULLABLE
AdoptionStory,STRING,NULLABLE
FavoriteFood,STRING,NULLABLE
FavoriteToy,STRING,NULLABLE
profile_picture,RECORD,NULLABLE
additional_media,RECORD,REPEATED
profile_embeddings,FLOAT,REPEATED
Here's a sample query to check for similarity:
SELECT
t2.id AS similar_pet_id,
COSINE_DISTANCE(t1.ml_generate_embedding_result, t2.ml_generate_embedding_result) AS distance
FROM
petverse.profile_embeddings AS t1,
petverse.profile_embeddings AS t2
WHERE
t1.Id = 3 -- The pet you want to find similar ones to
AND t1.Id != t2.Id -- Exclude the pet itself from the results
AND t1.content.uri IS NOT NULL
AND t2.content.uri IS NOT NULL
ORDER BY
distance
LIMIT 5;
Complement the profile of each pet with a description. Here's an example of the access to such table:
SELECT Name, MediaDescription from petverse.pets;
4.For each access to BigQuery, show the SQL statement that is used in the console logs.
5.Search functionality: Add a search bar for a semantic search for pets. There's a text embedding for the Adoption story, the pet's past-time or hobby and their nicknames in the table: petverse.text_embeddings . This is a sample of semantic search:
SELECT query.query, base.content, base.Name FROM VECTOR_SEARCH(TABLE `petverse.text_embeddings`, 'ml_generate_embedding_result', ( SELECT ml_generate_embedding_result, content AS query FROM ML.GENERATE_EMBEDDING(MODEL `petverse.textembedding`,(SELECT 'Pets who like to relax' AS content))), top_k => 5, options => '{"fraction_lists_to_search": 0.50}') ORDER BY distance DESC
6.Use Python for the backend. Generate the deployment scripts for an authenticated service using IAP with the flags --no-allow-unauthenticated --iap
7. Make the UI look like a modern art museum.
8. Use the gunicorn library. Validate version dependencies.

هذه هي مغامرتك الآن. سيتم عرض خطة عليك وسيُطلب منك التأكيد على كل خطوة.

من غير المرجّح أن يعمل الرمز البرمجي وعملية النشر على الفور. عليك تكرار العملية باستخدام Gemini CLI إلى أن تحصل على النتيجة الصحيحة.

إذا رأيت العملية عالقة في حلقة، أوقِفها باستخدام CTRL/Command + C، وابحث عن المشكلة، ثم اطلبها مرة أخرى.

47d6e394fc4f5b60.png

ننصحك بقراءة كل تأكيد بعناية، واحدًا تلو الآخر، لفهم ما ستفعله واجهة سطر الأوامر:

6a62b9c077d4cd11.png

بعد بضع دقائق، من المفترض أن يكون التطبيق جاهزًا للتنفيذ. قد يبدو أنّ وحدة التحكّم متوقّفة:

ca51ecf7b1ce08bf.png

يمكنك تجربة التطبيق يدويًا في علامة تبويب Cloud Shell جديدة باستخدام gunicorn. تأكَّد من ضبط المشروع على ما يلي:

f0ee1095386f7ec.png

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

27bf3e2a8d429169.gif

إذا كان كل شيء يبدو على ما يُرام، يمكنك نشر التطبيق اختياريًا في Cloud Run.

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

2365a90ac6a7d4e5.png

بافتراض أنّ عملية النشر تعمل، من المفترض أن يظهر لك تطبيق Cloud Run قيد التنفيذ في وحدة تحكّم Cloud Run.

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

انتظِر بضع دقائق إلى أن يتم نشر عمليات ربط IAP، ثم انقر على عنوان URL في أعلى الصفحة. من المفترض أن يظهر الموقع الإلكتروني.

3943c556ba912466.png

12. تَنظيم

ستساعدك هذه الخطوة في حذف الموارد التي تم إنشاؤها في هذا الدرس التطبيقي حول الترميز.

احذف خدمة Cloud Run (عدِّل اسم الخدمات والمنطقة حسب الحاجة):

gcloud run services delete petverse-profiles --region us-central1

حذف جميع مواد عرض BigQuery:

bq rm -f petverse
gcloud bigquery connections delete pet-connection --location=us-central1