نشر تطبيق ويب Python للذكاء الاصطناعي التوليدي تلقائيًا من نظام التحكّم في الإصدارات إلى Cloud Run

1. نظرة عامة

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

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

ما ستتعلمه

  • كتابة تطبيق ويب باستخدام "محرّر Cloud Shell"
  • تخزين الرمز البرمجي للتطبيق في GitHub
  • نشر تطبيقك تلقائيًا على Cloud Run
  • إضافة الذكاء الاصطناعي التوليدي إلى تطبيقك باستخدام Vertex AI

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

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

3- إعداد المشروع

  1. سجِّل الدخول إلى Google Cloud Console.
  2. فعِّل الفوترة في Cloud Console.
  3. أنشِئ مشروعًا جديدًا أو اختَر إعادة استخدام مشروع حالي.
  4. تأكَّد من تفعيل الفوترة في مشاريعي ضمن
      فوترة Cloud
    • إذا كان مشروعك الجديد يعرض Billing is disabled في العمود Billing account:
      1. انقر على النقاط الثلاث في العمود Actions
      2. انقر على تغيير الفوترة.
      3. اختَر حساب الفوترة الذي تريد استخدامه
    • إذا كنت ستشارك في فعالية "الذكاء الاصطناعي التوليدي للمطوّرين"، من المحتمل أن يكون اسم الحساب هو حساب فوترة تجريبي على Google Cloud Platform.

4. فتح "محرّر Cloud Shell"

  1. الانتقال إلى محرّر Cloud Shell
  2. إذا لم تظهر المحطة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
    • انقر على قائمة الهامبرغر رمز قائمة الخطوط الثلاثة
    • انقر على Terminal.
    • انقر على نافذة طرفية جديدةفتح نافذة طرفية جديدة في "محرِّر Cloud Shell".
  3. في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:
    • التنسيق:
      gcloud config set project [PROJECT_ID]
    • مثال:
      gcloud config set project lab-project-id-example
    • إذا تعذّر عليك تذكُّر رقم تعريف مشروعك، اتّبِع الخطوات التالية:
      • يمكنك إدراج جميع أرقام تعريف المشاريع باستخدام:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      ضبط رقم تعريف المشروع في نافذة Cloud Shell Editor
  4. إذا طُلب منك منح الإذن، انقر على منح الإذن للمتابعة. انقر لتفويض Cloud Shell
  5. من المفترض أن تظهر لك هذه الرسالة:
    Updated property [core/project].
    إذا ظهرت لك WARNING وطُلب منك Do you want to continue (Y/N)?، من المحتمل أنّك أدخلت رقم تعريف المشروع بشكل غير صحيح. اضغط على N، ثم على Enter، وحاوِل تنفيذ الأمر gcloud config set project مرة أخرى.

5- تفعيل واجهات برمجة التطبيقات

في الوحدة الطرفية، فعِّل واجهات برمجة التطبيقات:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com

قد يستغرق تنفيذ هذا الأمر بضع دقائق، ولكن من المفترض أن يعرض في النهاية رسالة نجاح مشابهة لما يلي:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. إعداد Git

  1. اضبط عنوان البريد الإلكتروني لمستخدم git العام:
    git config --global user.email "you@example.com"
  2. اضبط اسم مستخدم git العام:
    git config --global user.name "Your Name"
  3. اضبط فرع git التلقائي العام على main:
    git config --global init.defaultBranch main

7. كتابة الرمز

لكتابة تطبيق بلغة Python، اتّبِع الخطوات التالية:

  1. انتقِل إلى الدليل الرئيسي:
    cd ~
  2. أنشئ الدليل codelab-genai:
    mkdir codelab-genai
  3. انتقِل إلى دليل codelab-genai:
    cd codelab-genai
  4. إنشاء ملف main.py:
    touch main.py
  5. أنشئ requirements.txt مع قائمة التبعيات:
    cat > requirements.txt << EOF
Flask==3.0.0
gunicorn==20.1.0
EOF
  6. افتح الملف main.py في "محرِّر Cloud Shell":
    cloudshell edit main.py
    من المفترض أن يظهر ملف فارغ الآن في الجزء العلوي من الشاشة. هذا هو المكان الذي يمكنك فيه تعديل ملف main.py هذا. عرض أنّ الرمز يظهر في القسم العلوي من الشاشة
  7. انسخ الرمز التالي والصِقه في ملف main.py الذي تم فتحه:
    import os

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello_world():
    return f"Hello world!"


if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
    بعد بضع ثوانٍ، سيحفظ Cloud Shell Editor الرمز تلقائيًا. يستجيب هذا الرمز لطلبات http من خلال رسالة الترحيب "Hello world!‎".

تم الانتهاء من الرمز الأولي لتطبيقك وأصبح جاهزًا للتخزين في نظام التحكم في الإصدارات.

8. إنشاء مستودع

  1. ارجع إلى نافذة Cloud Shell في أسفل الشاشة.
  2. تأكَّد من أنّك لا تزال في الدليل الصحيح:
    cd ~/codelab-genai
  3. تهيئة مستودع git
    git init -b main
  4. تسجيل الدخول إلى GitHub CLI
    gh auth login
    اضغط على Enter لقبول الخيارات التلقائية واتّبِع التعليمات في أداة GitHub CLI، بما في ذلك:
    1. ما هو الحساب الذي تريد تسجيل الدخول إليه؟ GitHub.com
    2. ما هو البروتوكول المفضّل لديك لتنفيذ عمليات Git على هذا المضيف؟ HTTPS
    3. هل تريد مصادقة Git باستخدام بيانات اعتماد GitHub؟ Y (تخطَّ هذه الخطوة إذا لم تظهر لك هذه الرسالة.)
    4. كيف تريد مصادقة GitHub CLI؟ Login with a web browser
    5. نسخ الرمز الذي يُستخدَم لمرة واحدة
    6. افتح https://github.com/login/device
    7. لصق الرمز الذي يُستخدَم لمرة واحدة
    8. انقر على تفويض github.
    9. إكمال عملية تسجيل الدخول
  5. تأكَّد من تسجيل الدخول باتّباع الخطوات التالية:
    gh api user -q ".login"
    إذا سجّلت الدخول بنجاح، من المفترض أن يعرض هذا الأمر اسم مستخدم GitHub.
  6. إنشاء متغيّر GITHUB_USERNAME
    GITHUB_USERNAME=$(gh api user -q ".login")
  7. تأكَّد من إنشاء متغيّر البيئة:
    echo ${GITHUB_USERNAME}
    إذا أنشأت المتغيّر بنجاح، من المفترض أن يعرض اسم مستخدم GitHub.
  8. أنشئ مستودع GitHub فارغًا باسم codelab-genai:
    gh repo create codelab-genai --private
    إذا ظهرت لك رسالة الخطأ:
    GraphQL: Name already exists on this account (createRepository)
    لديك حاليًا مستودع باسم codelab-genai. لديك خياران لمواصلة اتّباع هذا البرنامج التعليمي:
  9. أضِف مستودع codelab-genai باعتباره المستودع البعيد origin:
    git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai

9- مشاركة الرمز

  1. تأكَّد من أنّك في الدليل الصحيح:
    cd ~/codelab-genai
  2. أضِف جميع الملفات في الدليل الحالي إلى عملية الإيداع هذه:
    git add .
  3. أنشئ عملية الإيداع الأولى:
    git commit -m "add http server"
  4. ادفع عملية الالتزام إلى فرع main في مستودع origin:
    git push -u origin main

يمكنك تنفيذ هذا الأمر والانتقال إلى عنوان URL الناتج لعرض الرمز البرمجي لتطبيقك على GitHub:

echo -e "\n\nTo see your code, visit this URL:\n \
    https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/main.py \n\n"

10. إعداد عمليات النشر التلقائية

  1. اترك علامة التبويب "محرِّر Cloud Shell" مفتوحة. سنعود إلى علامة التبويب هذه لاحقًا.
  2. في علامة تبويب جديدة، انتقِل إلى صفحة Cloud Run.
  3. اختَر مشروع Google Cloud الصحيح في وحدة التحكّم القائمة المنسدلة الخاصة بالمشاريع في Google Cloud Console
  4. انقر على ربط مستودع.
  5. انقر على الإعداد باستخدام Cloud Build
      .
    1. اختَر GitHub كموفِّر المستودع
        .
      • إذا لم تكن مسجِّلاً الدخول إلى حسابك على GitHub في المتصفّح، سجِّل الدخول باستخدام بيانات الاعتماد الخاصة بك.
    2. انقر على المصادقة، ثمّ على متابعة.
    3. بعد تسجيل الدخول، ستظهر لك رسالة في صفحة Cloud Run تفيد بأنّه لم يتم تثبيت تطبيق GitHub على أي من مستودعاتك.
    4. انقر على الزر تثبيت Google Cloud Build.
      • في صفحة "إعداد التثبيت"، اختَر اختيار المستودعات فقط واختَر المستودع codelab-genai الذي أنشأته من خلال واجهة سطر الأوامر.
      • انقر على تثبيت.
      • ملاحظة: إذا كان لديك الكثير من مستودعات GitHub، قد يستغرق تحميلها بضع دقائق.
    5. اختَر your-user-name/codelab-genai كـ المستودع
      • إذا لم يكن المستودع متاحًا، انقر على الرابط إدارة المستودعات المرتبطة.
    6. اترك الفرع على ^main$
    7. انقر على Go أو Node.js أو Python أو Java أو ‎.NET Core أو Ruby أو PHP من خلال حِزم الإنشاء في Google Cloud
      • اترك الحقول الأخرى (Build context directory وEntrypoint وFunction target) كما هي.
    8. انقر على حفظ.
  6. انتقِل للأسفل وصولاً إلى المصادقة
  7. انقر على السماح بعمليات الاستدعاء غير المصادق عليها.
  8. انقر على إنشاء.

بعد انتهاء عملية الإنشاء (التي ستستغرق عدة دقائق)، نفِّذ الأمر التالي وانتقِل إلى عنوان URL الناتج لعرض تطبيقك قيد التشغيل:

echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

11. تغيير الرمز

الرجوع إلى "محرّر Cloud Shell"

إذا كان Cloud Shell Editor لا يزال مفتوحًا، يمكنك تخطّي هذه الخطوات.

  1. الانتقال إلى محرّر Cloud Shell
  2. إذا لم تظهر المحطة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
    • انقر على قائمة الهامبرغر رمز قائمة الخطوط الثلاثة
    • انقر على Terminal.
    • انقر على نافذة طرفية جديدةفتح نافذة طرفية جديدة في &quot;محرِّر Cloud Shell&quot;.
  3. في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:
    • التنسيق:
      gcloud config set project [PROJECT_ID]
    • مثال:
      gcloud config set project lab-project-id-example
    • إذا تعذّر عليك تذكُّر رقم تعريف مشروعك، اتّبِع الخطوات التالية:
      • يمكنك إدراج جميع أرقام تعريف المشاريع باستخدام:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      ضبط رقم تعريف المشروع في نافذة Cloud Shell Editor
  4. إذا طُلب منك منح الإذن، انقر على منح الإذن للمتابعة. انقر لتفويض Cloud Shell
  5. من المفترض أن تظهر لك هذه الرسالة:
    Updated property [core/project].
    إذا ظهرت لك WARNING وطُلب منك Do you want to continue (Y/N)?، من المحتمل أنّك أدخلت رقم تعريف المشروع بشكل غير صحيح. اضغط على N، ثم على Enter، وحاوِل تنفيذ الأمر gcloud config set project مرة أخرى.

إضافة Vertex AI إلى تطبيقك

  1. ارجع إلى نافذة Cloud Shell في أسفل الشاشة.
  2. تأكَّد من أنّك لا تزال في الدليل الصحيح:
    cd ~/codelab-genai
  3. أضِف عنصر Vertex AI SDK الاعتمادي إلى العناصر الاعتمادية الحالية:
    sed -i -e '$agoogle-cloud-aiplatform==1.59.0' requirements.txt
  4. أضِف مكتبة مصادقة Google إلى الاعتمادات الحالية:
    sed -i -e '$agoogle-auth==2.32.0' requirements.txt
  5. أعِد فتح main.py في "محرِّر Cloud Shell"
    cloudshell edit main.py
  6. استبدِل الرمز في ملف main.py بما يلي:
    import os

from flask import Flask, request

import google.auth
import vertexai
from vertexai.generative_models import GenerativeModel

_, project = google.auth.default()

app = Flask(__name__)

@app.route("/")
def hello_world():
    vertexai.init(project=project, location="us-central1")
    model = GenerativeModel("gemini-1.5-flash")
    animal = request.args.get("animal", "dog") 
    prompt = f"Give me 10 fun facts about {animal}. Return this as html without backticks."
    response = model.generate_content(prompt)
    return response.text

if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

12. إعادة النشر

  1. تأكَّد من أنّك لا تزال في الدليل الصحيح في Cloud Shell:
    cd ~/codelab-genai
  2. نفِّذ الأوامر التالية لتثبيت إصدار جديد من تطبيقك في مستودع git المحلي:
    git add .
git commit -m "add latest changes"
  3. إرسال التغييرات إلى GitHub:
    git push
  4. بعد الانتهاء من إنشاء الإصدار، شغِّل الأمر التالي وانتقِل إلى تطبيقك الذي تم نشره:
    echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

قد يستغرق اكتمال الإصدار عدة دقائق قبل أن تتمكّن من رؤية التغييرات.

يمكنك الاطّلاع على سجلّ جميع المراجعات هنا: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. (اختياري) تدقيق استخدامك لـ Vertex AI

كما هو الحال مع خدمات Google Cloud الأخرى، يمكنك تدقيق عمليات Vertex AI. تساعدك سجلّات التدقيق في الإجابة عن الأسئلة: "من نفّذ الإجراء وما هو الإجراء ومكانه وتاريخه؟". يتم تفعيل سجلّات التدقيق الإدارية في Vertex AI تلقائيًا. للتدقيق في الطلبات التي تم إرسالها لإنشاء محتوى، عليك تفعيل سجلّات التدقيق في الوصول إلى المعلومات:

  1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة سجلّات التدقيق:

    إذا كنت تستخدم شريط البحث للعثور على هذه الصفحة، اختَر النتيجة التي عنوانها الفرعي هو إدارة الهوية وإمكانية الوصول.
  2. تأكَّد من أنّ مشروع Google Cloud الحالي هو المشروع الذي ستنشئ فيه تطبيق Cloud Run.
  3. في جدول إعدادات سجلّات تدقيق الوصول إلى البيانات، ابحث عن Vertex AI API واختَره من عمود "الخدمة".
  4. في علامة التبويب أنواع السجلات، اختَر نوعَي سجلّ التدقيق "الوصول إلى البيانات" Admin read وData read.
  5. انقر على حفظ.

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

  1. ارجِع إلى تطبيقك الذي تم نشره وأعِد تحميل الصفحة لتفعيل السجلّ.
  2. في Google Cloud Console، انتقِل إلى صفحة مستكشف السجلّات:

  3. في نافذة طلب البحث، اكتب ما يلي:
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
protoPayload.serviceName="aiplatform.googleapis.com"
  4. انقر على Run query (تنفيذ طلب البحث).

تسجّل سجلّات التدقيق استخدام Vertex AI API، ولكنّها لا تتيح لك الاطّلاع على البيانات ذات الصلة بأحمال العمل، مثل الطلبات أو تفاصيل الردود.

14. (اختياري) زيادة إمكانية تتبّع بيانات مهام الذكاء الاصطناعي

لا تسجّل سجلّات التدقيق معلومات ذات صلة بأحمال العمل. لزيادة إمكانية تتبّع البيانات لأحمال العمل، عليك تسجيل هذه المعلومات بشكل صريح. يمكنك استخدام إطار التسجيل المفضّل لديك لإجراء ذلك. توضّح الخطوات التالية كيفية إجراء ذلك باستخدام آلية التسجيل الأصلية في Node.js.

  1. أعِد فتح main.py في "محرِّر Cloud Shell"
    cloudshell edit ~/codelab-genai/main.py
  2. بعد السطر import os (السطر 1)، أضِف الأسطر التالية:
    import sys, json, logging

class JsonFormatter(logging.Formatter):
    def format(self, record):
        json_log_object = {
            "severity": record.levelname,
            "message": record.getMessage(),
        }
        json_log_object.update(getattr(record, "json_fields", {}))
        return json.dumps(json_log_object)
logger = logging.getLogger(__name__)
sh = logging.StreamHandler(sys.stdout)
sh.setFormatter(JsonFormatter())
logger.addHandler(sh)
logger.setLevel(logging.DEBUG)
    تغيّر هذه الأسطر التنسيق التلقائي لسجلات Python لتتّبع التنسيق المنظَّم بتنسيق JSON الذي يمكن إدخاله إلى Google Cloud.
  3. بعد السطر الذي يستدعي model.generate_content(prompt) (السطر 34)، أضِف الأسطر التالية:
        json_fields = {"prompt": prompt, "response": response.to_dict()}
    logger.debug("Content is generated", extra={"json_fields": json_fields})
    يطبع هذا الرمز المعلومات المنظَّمة حول إنشاء المحتوى إلى stdout حيث يقرأها وكيل التسجيل ويتم إدخالها إلى Cloud Logging.
  4. أعِد فتح Cloud Shell واكتب الأمر التالي للتأكّد من أنّك في الدليل الصحيح:
    cd ~/codelab-genai
  5. إجراء التغييرات:
    git commit -am "observe generated content"
  6. ادفع التغييرات إلى GitHub لتفعيل إعادة نشر النسخة المعدَّلة:
    git push

بعد نشر الإصدار الجديد، يمكنك الاطّلاع على معلومات تصحيح الأخطاء حول طلبات البيانات من Vertex AI.

للاطّلاع على سجلّات التطبيق، اتّبِع الخطوات التالية:

  1. في Google Cloud Console، انتقِل إلى صفحة مستكشف السجلّات:

  2. في نافذة طلب البحث، اكتب ما يلي:
    LOG_ID("run.googleapis.com%2Fstdout")
severity=DEBUG
  3. انقر على Run query (تنفيذ طلب البحث).

تعرض نتيجة طلب البحث السجلات التي تتضمّن الطلب وردّ Vertex AI، بما في ذلك "تقييمات الأمان" التي يمكن استخدامها لمراقبة ممارسات الأمان.

15. (اختياري) إخلاء مساحة تخزين

على الرغم من أنّ Cloud Run لا تفرض رسومًا عندما لا تكون الخدمة قيد الاستخدام، قد يتم تحصيل رسوم منك مقابل تخزين صورة الحاوية في Artifact Registry. يمكنك حذف مشروعك على Cloud لتجنُّب تحمّل رسوم. يؤدي حذف مشروعك على السحابة الإلكترونية إلى إيقاف الفوترة لجميع الموارد المستخدَمة في هذا المشروع.

إذا أردت، يمكنك حذف المشروع باتّباع الخطوات التالية:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

يمكنك أيضًا حذف الموارد غير الضرورية من قرص cloudshell. يمكنك إجراء ما يلي:

  1. احذف دليل مشروع الدرس البرمجي: 
    rm -rf ~/codelab-genai
  2. تحذير! لا يمكن التراجع عن هذا الإجراء. إذا أردت حذف كل المحتوى على Cloud Shell لإخلاء بعض المساحة، يمكنك حذف دليل منزلك بأكمله. يجب التأكّد من حفظ كل ما تريد الاحتفاظ به في مكان آخر. 
    sudo rm -rf $HOME

16. تهانينا

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

إذا استمتعت بهذا المختبر، يمكنك تجربته مرة أخرى بلغة ترميز أو إطار عمل آخرَين: