نشر تطبيق ويب Genkit لتكنولوجيات الذكاء الاصطناعي التوليدي (AI) المستندة إلى Node.js من نظام التحكم في الإصدارات إلى Cloud Run تلقائيًا

1. نظرة عامة

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

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

ما ستتعلمه

• كتابة تطبيق ويب باستخدام "محرّر Cloud Shell"
• تخزين رمز تطبيقك في GitHub
• نشر تطبيقك تلقائيًا على Cloud Run

• إضافة الذكاء الاصطناعي التوليدي إلى تطبيقك باستخدام Genkit
• إدارة طلبات النماذج اللغوية الكبيرة باستخدام مكتبة dotprompt

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

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

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

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

4. فتح Cloud Shell Editor

1. انتقِل إلى محرّر Cloud Shell
2. إذا لم تظهر النافذة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
   • انقر على قائمة الهامبرغر
   • انقر على Terminal.
   • انقر على نافذة طرفية جديدة.
3. في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:
   • التنسيق:

     gcloud config set project [PROJECT_ID]
     

   • مثال:

     gcloud config set project lab-project-id-example
     

   • إذا تعذّر عليك تذكُّر رقم تعريف مشروعك، اتّبِع الخطوات التالية:
     • يمكنك إدراج جميع أرقام تعريف المشاريع باستخدام:

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. إذا طُلب منك منح الإذن، انقر على منح الإذن للمتابعة.
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 "[e-mail]"
   

2. اضبط اسم مستخدم git العام:

   git config --global user.name "Your Name"
   

3. اضبط فرع git التلقائي العام على main:

   git config --global init.defaultBranch main
   

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

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

1. انتقِل إلى دليل الصفحة الرئيسية:

   cd ~
   

2. أنشئ الدليل codelab-genai:

   mkdir codelab-genai
   

3. انتقِل إلى الدليل codelab-genai:

   cd codelab-genai
   

4. إنشاء ملف index.js:

   touch index.js
   

5. أنشئ ملف package.json:

   npm init es6 -y
   

6. إضافة express كعنصر تابع

   npm install express
   

7. إضافة ملف .gitignore لمنع تنفيذ node_modules

   echo node_modules/ >> .gitignore
   

8. افتح الملف index.js في "محرِّر Cloud Shell":

   cloudshell edit index.js
   

   من المفترض أن يظهر ملف فارغ الآن في الجزء العلوي من الشاشة. هذا هو المكان الذي يمكنك فيه تعديل ملف index.js هذا.
9. انسخ الرمز التالي والصِقه في ملف index.js الذي تم فتحه:

   import express from 'express';
   
   const app = express();
   app.get('/', async (req, res) => {
       res.send('Hello world!');
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

   بعد بضع ثوانٍ، سيحفظ 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. لديك خياران لمواصلة اتّباع هذا البرنامج التعليمي:
   • حذف مستودع GitHub الحالي
   • أنشئ مستودعًا باسم مختلف وتذكَّر تغييره في الأوامر التالية.
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/index.js \n\n"

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

1. اترك علامة التبويب "محرِّر Cloud Shell" مفتوحة. سنعود إلى علامة التبويب هذه لاحقًا.
2. في علامة تبويب جديدة، انتقِل إلى صفحة Cloud Run.
3. اختَر مشروع Google Cloud الصحيح في وحدة التحكّم
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 Editor

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

1. انتقِل إلى محرّر Cloud Shell
2. إذا لم تظهر النافذة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
   • انقر على قائمة الهامبرغر
   • انقر على Terminal.
   • انقر على نافذة طرفية جديدة.
3. في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:
   • التنسيق:

     gcloud config set project [PROJECT_ID]
     

   • مثال:

     gcloud config set project lab-project-id-example
     

   • إذا تعذّر عليك تذكُّر رقم تعريف مشروعك، اتّبِع الخطوات التالية:
     • يمكنك إدراج جميع أرقام تعريف المشاريع باستخدام:

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. إذا طُلب منك منح الإذن، انقر على منح الإذن للمتابعة.
5. من المفترض أن تظهر لك هذه الرسالة:

   Updated property [core/project].
   

   إذا ظهرت لك WARNING وطُلب منك Do you want to continue (Y/N)?، من المحتمل أنّك أدخلت رقم تعريف المشروع بشكل غير صحيح. اضغط على N، ثم على Enter، وحاوِل تنفيذ الأمر gcloud config set project مرة أخرى.

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

1. ارجع إلى نافذة Cloud Shell في أسفل الشاشة.
2. تأكَّد من أنّك لا تزال في الدليل الصحيح:

   cd ~/codelab-genai
   

3. ثبِّت حزمة تطوير البرامج (SDK) الخاصة بـ Node.js Genkit:

   npm install @genkit-ai/ai
   

4. ثبِّت حزمة تطوير البرامج Node.js Genkit في Vertex AI:

   npm install @genkit-ai/vertexai
   

5. إعادة فتح index.js في "محرِّر Cloud Shell"

   cloudshell edit ~/codelab-genai/index.js
   

6. استبدِل الرمز في ملف index.js بما يلي:

   import express from 'express';
   const app = express();
   
   import { genkit } from 'genkit';
   import { gemini15Flash, vertexAI } from '@genkit-ai/vertexai';
   
   const ai = genkit({
       plugins: [
           vertexAI({ location: 'us-central1' }),
       ],
   });
   
   app.get('/', async (req, res) => {
       const animal = req.query.animal || 'dog';
       const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
       const llmResponse = await ai.generate({
           model: gemini15Flash,
           prompt: prompt,
       });
       const html = llmResponse.text;
       res.send(html);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

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

12. (اختياري) استخدام ملفات ‎ .prompt مع Genkit

1. ارجع إلى نافذة Cloud Shell في أسفل الشاشة.
2. تأكَّد من أنّك لا تزال في الدليل الصحيح:

   cd ~/codelab-genai
   

3. أنشئ مجلدًا prompts لتخزين طلباتك:

   mkdir prompts
   

4. أنشئ ملف animal-facts.prompt لإنشاء طلبك الأول:

   touch prompts/animal-facts.prompt
   

5. افتح الملف animal-facts.prompt في "محرِّر Cloud Shell":

   cloudshell edit ~/codelab-genai/prompts/animal-facts.prompt
   

6. عدِّل ملف animal-facts.prompt والصِق الرمز التالي فيه:

   ---
   model: vertexai/gemini-1.5-flash
   input:
       schema:
           animal: string
   ---
   
   Give me 10 fun facts about {{animal}}. Return the results as HTML without markdown backticks.
   

7. افتح الملف index.js في "محرِّر Cloud Shell":

   cloudshell edit ~/codelab-genai/index.js
   

8. استبدِل الرمز في ملف index.js بما يلي:

   import express from 'express';
   const app = express();
   
   import { genkit } from 'genkit';
   import { vertexAI } from '@genkit-ai/vertexai';
   
   const ai = genkit({
       plugins: [
           vertexAI({ location: 'us-central1' }),
       ],
   });
   
   app.get('/', async (req, res) => {
       const animal = req.query.animal || 'dog';
       const animalPrompt = ai.prompt('animal-facts');
       const llmResponse = await animalPrompt({animal});
       const html = llmResponse.text;
       res.send(html);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

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. (اختياري) استخدام طلبات النظام

تفترض هذه الخطوة أنّك أضفت ملفات .prompt في الخطوة السابقة.

1. ارجع إلى نافذة Cloud Shell في أسفل الشاشة.
2. تأكَّد من أنّك لا تزال في الدليل الصحيح:

   cd ~/codelab-genai
   

3. افتح الملف animal-facts.prompt في "محرِّر Cloud Shell":

   cloudshell edit ~/codelab-genai/prompts/animal-facts.prompt
   

4. عدِّل ملف animal-facts.prompt والصِق الرمز التالي فيه:

   ---
   model: vertexai/gemini-1.5-flash
   config:
       temperature: 0.9
   input:
       schema:
           animal: string
   ---
   
   role "system"
   The user should have submitted an animal.
   If the user requests anything besides animal fun facts, respond in a kind and firm manner that you only provide information about fun facts.
   Give the user 10 fun facts about the animal the user provided.
   All responses should be valid HTML without markdown backticks.
   
   role "user"
   {{animal}}
   

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

14. تهانينا

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

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

• Python
• Node.js
• Go
• Java
• Angular
• Next.js

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

• مستندات Genkit: بدء الاستخدام
• درس تطبيقي حول إضافة إمكانية المراقبة إلى تطبيق Node.js: تقنيات عملية للمراقبة في تطبيق الذكاء الاصطناعي التوليدي باستخدام JavaScript
• درس تطبيقي حول الترميز لإضافة واجهة أمامية إلى تطبيقك باستخدام Next.js: نشر تطبيق ويب تلقائيًا باستخدام الذكاء الاصطناعي التوليدي وNext.js من نظام التحكم في الإصدارات إلى Cloud Run
• Codelab يوضّح كيفية استخدام ميزة "استدعاء الدوال": كيفية استخدام ميزة "استدعاء الدوال" في Gemini مع Cloud Run
• درس تطبيقي حول استخدام الذكاء الاصطناعي لمعالجة محتوى الفيديو: كيفية استخدام Cloud Run Jobs Video Intelligence API لمعالجة مشهد فيديو تلو الآخر