פריסה אוטומטית של אפליקציית אינטרנט של AI גנרטיבי ב-Node.js Genkit ממערכת בקרת הגרסאות ל-Cloud Run

1. סקירה כללית

פריסת אפליקציית אינטרנט בפעם הראשונה יכולה להיות משימה מרתיעה. גם אחרי הפריסה הראשונה, אם התהליך מסובך מדי, יכול להיות שלא תרצו לפרוס גרסאות חדשות של האפליקציה. בעזרת פריסה רציפה, אתם יכולים לפרוס שינויים באפליקציה שלכם בקלות ובאופן אוטומטי.

במעבדה הזו תכתבו אפליקציית אינטרנט ותגדירו את Cloud Run כך שהאפליקציה תיפרס באופן אוטומטי כשמתבצע שינוי בקוד המקור שלה. לאחר מכן משנים את האפליקציה ומבצעים פריסה מחדש.

מה תלמדו

• כתיבת אפליקציית אינטרנט באמצעות Cloud Shell Editor
• שמירת קוד האפליקציה ב-GitHub
• פריסה אוטומטית של האפליקציה ב-Cloud Run

• הוספת AI גנרטיבי לאפליקציה באמצעות Genkit
• ניהול הנחיות ל-LLM באמצעות ספריית dotprompt

2. דרישות מוקדמות

1. אם אין לכם חשבון Google, אתם צריכים ליצור חשבון Google.
   • משתמשים בחשבון לשימוש אישי במקום בחשבון לצורכי עבודה או בחשבון בית ספרי. יכול להיות שבחשבונות לצורכי עבודה או בחשבונות בית ספריים יש הגבלות שלא מאפשרות להפעיל את ממשקי ה-API שנדרשים למעבדה הזו.
2. אם אין לכם חשבון ב-GitHub, אתם צריכים ליצור חשבון ב-GitHub
   • אם יש לכם חשבון GitHub קיים, אתם יכולים להשתמש בו. יש סיכוי גבוה יותר ש-GitHub יחסום חשבון חדש כספאם.
   • כדי להקטין את הסיכוי שהחשבון שלכם יסומן כספאם, מומלץ להגדיר אימות דו-שלבי בחשבון GitHub.

3. הגדרת הפרויקט

1. נכנסים ל-מסוף Google Cloud.
2. מפעילים את החיוב במסוף Cloud.
   • העלות של השלמת ה-Lab הזה במשאבי Cloud צריכה להיות פחות מ-1$.
   • כדי למנוע חיובים נוספים, אפשר למחוק את המשאבים לפי השלבים שמפורטים בסוף ה-Lab הזה.
   • משתמשים חדשים זכאים לתקופת ניסיון בחינם בשווי 300$.
   • מגיעים לאירוע בנושא AI גנרטיבי למפתחים? יכול להיות שיהיה זמין קרדיט בסך 1$.
3. יוצרים פרויקט חדש או בוחרים להשתמש בפרויקט קיים.
4. מוודאים שהחיוב מופעל בדף My projects (הפרויקטים שלי) בחיוב ב-Cloud
   • אם הפרויקט החדש מופיע עם הערך Billing is disabled בעמודה Billing account:
     1. לוחצים על סמל האפשרויות הנוספות (3 נקודות) בעמודה Actions.
     2. לוחצים על שינוי פרטי החיוב.
     3. בוחרים את החשבון לחיוב שבו רוצים להשתמש.
   • אם אתם משתתפים באירוע Gen AI for Devs, סביר להניח שהשם של החשבון יהיה Google Cloud Platform Trial Billing Account.

4. פתיחת Cloud Shell Editor

1. עוברים אל Cloud Shell Editor.
2. אם הטרמינל לא מופיע בתחתית המסך, פותחים אותו:
   • לוחצים על סמל האפשרויות הנוספות (3 קווים) .
   • לוחצים על Terminal (מסוף).
   • לוחצים על New 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. הפעלת ממשקי ה-API

בטרמינל, מפעילים את ממשקי ה-API:

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 Editor:

   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. לוחצים על Authorize github (אישור גישה ל-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 Editor פתוחה. נחזור לכרטיסייה הזו מאוחר יותר.
2. בכרטיסייה חדשה, נכנסים אל הדף Cloud Run.
3. בוחרים את הפרויקט הנכון ב-Google Cloud במסוף
4. לוחצים על CONNECT REPO (קישור מאגר)
5. לוחצים על SET UP WITH CLOUD BUILD
   .
   1. בוחרים באפשרות GitHub בתור ספק המאגר
      .
      • אם לא התחברתם לחשבון GitHub בדפדפן, מתחברים באמצעות פרטי הכניסה.
   2. לוחצים על אימות ואז על המשך.
   3. אחרי שמתחברים, מוצגת הודעה בדף Cloud Run: The GitHub App is not installed on any of your repositories. (אפליקציית GitHub לא מותקנת באף אחד מהמאגרים שלכם).
   4. לוחצים על הלחצן INSTALL GOOGLE CLOUD BUILD (התקנת Google Cloud Build).
      • בדף Installation Setup (הגדרת ההתקנה), בוחרים באפשרות Only select repositories (בחירת מאגרים בלבד) ובוחרים במאגר codelab-genai שיצרתם באמצעות CLI.
      • לוחצים על התקנה.
      • הערה: אם יש לכם הרבה מאגרי GitHub, יכול להיות שיעברו כמה דקות עד שהם ייטענו.
   5. בוחרים באפשרות your-user-name/codelab-genai בתור מאגר
      • אם המאגר לא מופיע, לוחצים על הקישור Manage Connected Repositories (ניהול מאגרים מקושרים).
   6. עזיבת Branch בתור ^main$
   7. לוחצים על Go, ‏ Node.js, ‏ Python, ‏ Java,‏ ‎.NET Core, ‏ Ruby או PHP באמצעות buildpacks של Google Cloud
      • לא משנים את השדות האחרים (Build context directory,‏ Entrypoint ו-Function target).
   8. לוחצים על שמירה.
6. גוללים למטה אל אימות.
7. לוחצים על Allow unauthenticated invocations (מתן הרשאה להפעלות לא מאומתות).
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 Editor.
2. אם הטרמינל לא מופיע בתחתית המסך, פותחים אותו:
   • לוחצים על סמל האפשרויות הנוספות (3 קווים) .
   • לוחצים על Terminal (מסוף).
   • לוחצים על New 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. מתקינים את Node.js Genkit SDK:

   npm install @genkit-ai/ai
   

4. מתקינים את Node.js Genkit SDK ל-Vertex AI:

   npm install @genkit-ai/vertexai
   

5. פתיחה מחדש של index.js ב-Cloud Shell Editor

   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. אחרי שה-build מסתיים, מריצים את הפקודה הזו ונכנסים לאפליקציה שפרסתם:

   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 Editor:

   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 Editor:

   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. אחרי שה-build מסתיים, מריצים את הפקודה הזו ונכנסים לאפליקציה שפרסתם:

   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 Editor:

   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. אחרי שה-build מסתיים, מריצים את הפקודה הזו ונכנסים לאפליקציה שפרסתם:

   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: תחילת העבודה
• שיעור Codelab להוספת ניראות לאפליקציית Node.js: טכניקות ניראות (observability) מעשיות לאפליקציות AI גנרטיבי ב-JavaScript
• שיעור Codelab להוספת קצה קדמי לאפליקציה באמצעות Next.js: פריסה אוטומטית של אפליקציית אינטרנט מבוססת-AI גנרטיבי ב-Next.js מניהול גרסאות ל-Cloud Run
• שיעור Codelab שמסביר איך להשתמש בבקשות להפעלת פונקציות: איך משתמשים בבקשות להפעלת פונקציות של Gemini עם Cloud Run
• שיעור Codelab לשימוש ב-AI לעיבוד תוכן וידאו: איך משתמשים ב-Cloud Run Jobs Video Intelligence API כדי לעבד סרטון לפי סצנות