نشر تطبيق ويب Go للذكاء الاصطناعي التوليدي تلقائيًا من نظام التحكّم في الإصدارات إلى 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 Editor

  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. كتابة الرمز

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

  1. انتقِل إلى دليل الصفحة الرئيسية:
    cd ~
  2. أنشئ الدليل codelab-genai:
    mkdir codelab-genai
  3. انتقِل إلى الدليل codelab-genai:
    cd codelab-genai
  4. ابدأ بإنشاء ملف go.mod للإعلان عن الوحدة:
    go mod init codelab-genai
  5. إنشاء ملف main.go:
    touch main.go
  6. افتح الملف main.go في "محرِّر Cloud Shell":
    cloudshell edit main.go
    من المفترض أن يظهر ملف فارغ الآن في الجزء العلوي من الشاشة. هذا هو المكان الذي يمكنك فيه تعديل ملف main.go هذا. توضيح أنّ الرمز يجب إدخاله في القسم العلوي من الشاشة
  7. عدِّل ملف main.go والصِق الرمز التالي فيه:
    package main

import (
    "fmt"
    "log"
    "net/http"
    "os"
)

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello, world!")
    })

    port := os.Getenv("PORT")

    if port == "" {
        port = "8080"
    }
    if err := http.ListenAndServe(":"+port, nil); err != nil {
        log.Fatal(err)
    }
}
    بعد بضع ثوانٍ، سيحفظ 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.go \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. تغيير الرمز

  1. ارجع إلى نافذة Cloud Shell في أسفل الشاشة.
  2. تأكَّد من أنّك لا تزال في الدليل الصحيح:
    cd ~/codelab-genai
  3. أعِد فتح main.go في "محرِّر Cloud Shell"
    cloudshell edit main.go
  4. ثبِّت حزمة تطوير البرامج (SDK) الخاصة بـ Vertex AI للغة Go:
    go get cloud.google.com/go/vertexai/genai
  5. ثبِّت مكتبة البيانات الوصفية للغة Go للحصول على رقم تعريف المشروع الحالي:
    go get cloud.google.com/go/compute/metadata
  6. استبدِل الرمز في ملف main.go بما يلي:
    package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "cloud.google.com/go/compute/metadata"
    "cloud.google.com/go/vertexai/genai"
)

func main() {
    ctx := context.Background()
    var projectId string
    var err error
    projectId = os.Getenv("GOOGLE_CLOUD_PROJECT")
    if projectId == "" {
        projectId, err = metadata.ProjectIDWithContext(ctx)
        if err != nil {
            return
        }
    }
    var client *genai.Client
    client, err = genai.NewClient(ctx, projectId, "us-central1")
    if err != nil {
        return
    }
    defer client.Close()

    model := client.GenerativeModel("gemini-1.5-flash-001")

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        animal := r.URL.Query().Get("animal")
        if animal == "" {
            animal = "dog"
        }

        resp, err := model.GenerateContent(
            ctx,
            genai.Text(
                fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal)),
        )

        if err != nil {
            w.WriteHeader(http.StatusServiceUnavailable)
            return
        }

        if len(resp.Candidates) > 0 && len(resp.Candidates[0].Content.Parts) > 0 {
            htmlContent := resp.Candidates[0].Content.Parts[0]
            w.Header().Set("Content-Type", "text/html; charset=utf-8")
            fmt.Fprint(w, htmlContent)
        }
    })

    port := os.Getenv("PORT")

    if port == "" {
        port = "8080"
    }
    if err := http.ListenAndServe(":"+port, nil); err != nil {
        log.Fatal(err)
    }
}

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. (اختياري) زيادة إمكانية مراقبة أعباء عمل الذكاء الاصطناعي

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

  1. أعِد فتح main.go في "محرِّر Cloud Shell"
    cloudshell edit ~/codelab-genai/main.go
  2. غيِّر حظر الاستيراد لتضمين مكتبات تسجيل البيانات المنظَّمة وJSON في Go:
    import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "log/slog"
    "net/http"
    "os"

    "cloud.google.com/go/compute/metadata"
    "cloud.google.com/go/vertexai/genai"
)
  3. بعد تهيئة عميل Vertex (السطر 33)، أضِف الأسطر التالية لتهيئة أداة تسجيل منظَّمة تستخدم الحقول المناسبة في Google Cloud Logging:
    opts := &slog.HandlerOptions{
	Level: slog.LevelDebug,
	ReplaceAttr: func(group []string, a slog.Attr) slog.Attr {
        if a.Key == slog.LevelKey {
            return slog.Attr{Key: "severity", Value: a.Value}
        }
        if a.Key == slog.MessageKey {
            return slog.Attr{Key: "message", Value: a.Value}
        }
        return slog.Attr{Key: a.Key, Value: a.Value}
	},
}

jsonHandler := slog.NewJSONHandler(os.Stdout, opts)
slog.SetDefault(slog.New(jsonHandler))
  4. بعد التحقّق من وجود ردّ على GenerateContent (السطر 69)، أضِف الأسطر التالية داخل كتلة if:
    jsonBytes, err := json.Marshal(resp)
if err != nil {
    slog.Error("Failed to marshal response to JSON", "error", err)
} else {
    jsonString := string(jsonBytes)
    slog.Debug("Complete response content", "json_response", jsonString)
}
    يكتب هذا الرمز stdout معلومات حول المحتوى الذي تم إنشاؤه باستخدام تنسيق التسجيل المنظَّم. يلتقط وكيل التسجيل في Cloud Run الناتج الذي تتم طباعته إلى stdout ويكتب هذا التنسيق إلى Cloud Logging.
  5. أعِد فتح Cloud Shell واكتب الأمر التالي للتأكّد من أنّك في الدليل الصحيح:
    cd ~/codelab-genai
  6. إجراء التغييرات:
    git commit -am "Observe generated content"
  7. ادفع التغييرات إلى 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. احذف أي حِزم Go لم تعُد بحاجة إليها: 
    cd ~
go clean -modcache
  3. تحذير! لا يمكن التراجع عن هذا الإجراء. إذا أردت حذف كل شيء على Cloud Shell لإخلاء بعض المساحة، يمكنك حذف دليل منزلك بأكمله. يجب الحرص على حفظ كل ما تريد الاحتفاظ به في مكان آخر. 
    sudo rm -rf $HOME

16. تهانينا

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

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

إذا كنت مهتمًا بالمشاركة في دراسة بحثية حول تجربة المستخدم (UX) لتحسين المنتجات التي عملت عليها اليوم، يمكنك التسجيل هنا.

في ما يلي بعض الخيارات لمواصلة التعلّم: