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

لكتابة تطبيق في Next.js، اتّبِع الخطوات التالية:

  1. انتقِل إلى الدليل الرئيسي:
    cd ~
  2. أنشئ تطبيق codelab-genai Next.js جديدًا:
    npx create-next-app@latest codelab-genai \
    --ts \
    --eslint \
    --tailwind \
    --no-src-dir \
    --app \
    --no-import-alias
  3. إذا طُلب منك تثبيت create-next-app، اضغط على Enter للمتابعة:
    Need to install the following packages:
create-next-app@14.2.14
Ok to proceed? (y)
  4. انتقِل إلى دليل codelab-genai:
    cd codelab-genai
  5. افتح الملف page.tsx في "محرِّر Cloud Shell":
    cloudshell edit app/page.tsx
    من المفترض أن يظهر ملف في أعلى الشاشة. هذا هو المكان الذي يمكنك فيه تعديل ملف page.tsx هذا. عرض أنّ الرمز يظهر في القسم العلوي من الشاشة
  6. احذف الرمز الحالي. انسخ الرمز التالي والصِقه في ملف page.tsx الذي تم فتحه:
    import React from "react";

export default function Home() {
return (
    <main>
        Hello World!
    </main>
);
}
    بعد بضع ثوانٍ، سيحفظ 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/app/page.tsx \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. ثبِّت حزمة تطوير البرامج (SDK) الخاصة بـ Node.js Vertex AI:
    npm install @google-cloud/vertexai
  4. ثبِّت حزمة تطوير البرامج (SDK) الخاصة بخدمة "المصادقة من Google" في Node.js:
    npm install google-auth-library
  5. إنشاء app/actions.ts في "الوحدة الطرفية"
    touch app/actions.ts
  6. افتح actions.ts في "محرِّر Cloud Shell".
    cloudshell edit app/actions.ts
  7. انسخ الرمز التالي والصِقه في ملف actions.ts الذي تم فتحه:
    'use server'

import { VertexAI } from '@google-cloud/vertexai';
import { GoogleAuth } from 'google-auth-library';
const auth = new GoogleAuth();

export async function getFunFactsAction(animal: string) {
    const project = await auth.getProjectId();

    const vertex = new VertexAI({ project: project });
    const generativeModel = vertex.getGenerativeModel({
        model: 'gemini-1.5-flash'
    });

    const prompt = `Give me 10 fun facts about ${animal || 'dog'}. 
            Return as json as an array in the format ['fact 1', 'fact 2']
            Remove backticks and other markdown formatting.`;
    const resp = await generativeModel.generateContent(prompt);

    if (!resp.response.candidates) {
        throw new Error('Did not receive response candidates.')
    }

    console.log({ text: resp.response.candidates[0].content.parts[0].text })

    const factArray = JSON.parse(resp.response.candidates[0].content.parts[0].text || '');
    return factArray;
};
  8. افتح page.tsx في "محرِّر Cloud Shell".
    cloudshell edit ~/codelab-genai/app/page.tsx
  9. استبدِل الرمز في ملف page.tsx بما يلي:
    'use client'

import React, { useState } from "react";
import { getFunFactsAction } from "./actions";

export default function Home() {
    const [animal, setAnimal] = useState('');
    const [funFacts, setFunFacts] = useState<string[]>([]);
    async function getNewFunFacts() {
        const funFacts = await getFunFactsAction(animal);
        setFunFacts(funFacts);
    }
    return (
        <main>
            <h1 className="text-xl">Animal Fun Facts!</h1>
            <label className="text-lg p-2 m-2">Animal</label>
            <input
                placeholder="dog"
                value={animal}
                onChange={(e) => setAnimal(e.target.value)}
                className="text-black border-2 p-2 m-2 rounded"
            />
            <button
                onClick={getNewFunFacts}
                className="font-bold border-2 p-2 m-2 rounded hover:bg-white hover:text-black"
            >
                Get New Fun Facts
            </button>
            <ul className="list-disc list-inside">
                {funFacts.map(function (thing) {
                    return <li key={thing}>{thing}</li>
                })}
            </ul>
        </main>
    );
}

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. أعِد فتح actions.ts في "محرِّر Cloud Shell"
    cloudshell edit ~/codelab-genai/app/actions.ts
  2. بعد استدعاء الدالة await generativeModel.generateContent(prompt) (السطر 19)، أضِف السطر التالي:
        console.log(JSON.stringify({
        severity: 'DEBUG',
        message: 'Content is generated',
        prompt: prompt,
        response: resp.response,
    }));
    يكتب هذا الرمز stdout معلومات حول المحتوى الذي تم إنشاؤه باستخدام تنسيق التسجيل المنظَّم. يلتقط وكيل التسجيل في Cloud Run الناتج الذي تتم طباعته إلى stdout ويكتب هذا التنسيق إلى Cloud Logging.
  3. أعِد فتح Cloud Shell واكتب الأمر التالي للتأكّد من أنّك في الدليل الصحيح:
    cd ~/codelab-genai
  4. إجراء التغييرات:
    git commit -am "observe generated content"
  5. ادفع التغييرات إلى 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 لنشر تطبيقك تلقائيًا عند إجراء تغيير على الرمز المصدر لتطبيقك. بعد ذلك، عدّلت تطبيقك ونشرته مرة أخرى.

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

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