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

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

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

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

מה תלמדו

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

• הוספת AI גנרטיבי לאפליקציה באמצעות Vertex AI

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

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

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

1. נכנסים ל-מסוף Google Cloud.
2. מפעילים את החיוב במסוף Cloud.
   • העלות של השלמת ה-Lab הזה במשאבי Cloud צריכה להיות פחות מ-1$.
   • כדי למחוק משאבים ולמנוע חיובים נוספים, אפשר לבצע את השלבים בסוף ה-Lab הזה.
   • משתמשים חדשים זכאים לתקופת ניסיון בחינם בשווי 300$.
   • מגיעים לאירוע של Gen AI for Devs? יכול להיות שתוכלו לקבל קרדיט בסך 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. אם הטרמינל לא מופיע בתחתית המסך, פותחים אותו:
   • לוחצים על סמל התפריט .
   • לוחצים על 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. כתיבת הקוד

כדי לכתוב אפליקציה ב-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 Editor:

   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. לוחצים על 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/app/page.tsx \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 בתור מאגר
      • אם המאגר לא מופיע, לוחצים על הקישור ניהול מאגרי מידע מקושרים.
   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. לוחצים על אפשר הפעלות לא מאומתות.
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.

הוספת Vertex AI לאפליקציה

1. חוזרים לטרמינל של Cloud Shell בתחתית המסך.
2. מוודאים שאתם עדיין בספרייה הנכונה:

   cd ~/codelab-genai
   

3. מתקינים את Node.js Vertex AI SDK:

   npm install @google-cloud/vertexai
   

4. מתקינים את Node.js Google Auth SDK:

   npm install google-auth-library
   

5. יצירת app/actions.ts במסוף

   touch app/actions.ts
   

6. פתיחה של actions.ts ב-Cloud Shell Editor

   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 Editor

   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. אחרי שה-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"
   

יכול להיות שיחלפו כמה דקות עד שה-build יסתיים והשינויים יופיעו.

אפשר לראות את ההיסטוריה של כל השינויים כאן: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. (אופציונלי) בדיקת השימוש ב-Vertex AI

בדומה לשירותים אחרים של Google Cloud, אפשר לבצע ביקורת על פעולות ב-Vertex AI. יומני הביקורת עוזרים לענות על השאלות 'מי עשה מה, איפה ומתי?'. יומני ביקורת אדמיניסטרטיביים של Vertex AI מופעלים כברירת מחדל. כדי לבדוק בקשות ליצירת תוכן, צריך להפעיל יומני ביקורת של גישה לנתונים:

יומני ביקורת של נתונים עשויים להיות כרוכים בעלויות נוספות.

1. במסוף Google Cloud, עוברים לדף Audit Logs:
   Go to Audit Logs
   אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא IAM & Admin.
2. מוודאים שהפרויקט הקיים ב-Google Cloud הוא הפרויקט שבו אתם יוצרים את האפליקציה של Cloud Run.
3. בטבלה Data Access audit logs configuration, מוצאים את האפשרות Vertex AI API בעמודה Service.
4. בכרטיסייה Log Types (סוגי יומנים), בוחרים את סוגי יומני הביקורת Data Access‏ Admin read ו-Data read.
5. לוחצים על שמירה.

אחרי ההפעלה, תוכלו לראות יומני ביקורת לכל הפעלה של האפליקציה. כדי לראות את יומני הביקורת עם פרטי ההפעלה:

1. חוזרים לאפליקציה שפרסתם ומרעננים את הדף כדי להפעיל את היומן.
2. במסוף Google Cloud, נכנסים לדף Log Explorer:
   כניסה ל-Log Explorer
   
3. בחלון השאילתה מקלידים:

   LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
   protoPayload.serviceName="aiplatform.googleapis.com"
   

4. לוחצים על Run query.

ביומני ביקורת מתועד השימוש ב-Vertex AI API, אבל אי אפשר לראות בהם נתונים שקשורים לעומסי עבודה, כמו הנחיות או פרטי תשובות.

14. (אופציונלי) הגדלת יכולת הצפייה בעומס העבודה של ה-AI

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

1. פתיחה מחדש של actions.ts ב-Cloud Shell Editor

   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 מידע על תוכן שנוצר באמצעות פורמט רישום מובנה ביומן. סוכן Logging ב-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, נכנסים לדף Log Explorer:
   כניסה ל-Log Explorer
   
2. בחלון השאילתה מקלידים:

   LOG_ID("run.googleapis.com%2Fstdout")
   severity=DEBUG
   

3. לוחצים על Run query.

תוצאת השאילתה מציגה יומנים עם הנחיה ותגובה של Vertex AI, כולל 'דירוגי בטיחות' שאפשר להשתמש בהם למעקב אחר שיטות עבודה מומלצות בנושא בטיחות

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

15. (אופציונלי) ניקוי

ב-Cloud Run לא מחויבים כשלא משתמשים בשירות, אבל יכול להיות שתחויבו על אחסון קובץ האימג' של הקונטיינר ב-Artifact Registry. כדי להימנע מחיובים, אפשר למחוק את הפרויקט בענן. כשמוחקים פרויקט בענן, החיוב על כל המשאבים שנעשה בהם שימוש באותו פרויקט נפסק.

אם רוצים, אפשר למחוק את הפרויקט:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

אפשר גם למחוק משאבים מיותרים מהדיסק של Cloud Shell. אתם יכולים:

1. מוחקים את ספריית הפרויקט של ה-codelab:

   rm -rf ~/codelab-genai
   

2. אזהרה! אי אפשר לבטל את הפעולה הזו. אם אתם רוצים למחוק את כל מה שיש ב-Cloud Shell כדי לפנות מקום, אתם יכולים למחוק את כל ספריית הבית. חשוב לוודא שכל מה שרוצים לשמור נשמר במקום אחר.

   sudo rm -rf $HOME
   

16. מזל טוב

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

אם נהניתם מהמעבדה הזו, אתם יכולים לנסות אותה שוב בשפת תכנות או במסגרת אחרת:

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

ריכזנו כאן כמה אפשרויות להמשך הלמידה:

• ‫Docs: אפשר להשתמש ב-Genkit כהפשטת מודל גמישה שמקלה על שילוב של כל API של מודל ושימוש במודלים שמתוחזקים על ידי הקהילה.
• Codelab: איך פורסים אפליקציית צ'אט מבוססת Gemini ב-Cloud Run
• איך משתמשים ב-Gemini function calling עם Cloud Run
• איך משתמשים ב-Cloud Run Jobs Video Intelligence API כדי לעבד סרטון סצנה אחר סצנה
• סדנה על פי דרישה: Google Kubernetes Engine Onboard