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

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

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

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

מה תלמדו

  • כתיבת אפליקציית אינטרנט באמצעות Cloud Shell Editor
  • אחסון קוד האפליקציה ב-GitHub
  • פריסת האפליקציה ב-Cloud Run באופן אוטומטי
  • הוספת AI גנרטיבי לאפליקציה באמצעות Genkit
  • ניהול הנחיות LLM באמצעות ספריית dotprompt

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

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

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

  1. נכנסים למסוף Google Cloud.
  2. מפעילים את החיוב במסוף Cloud.
    • השלמת ה-Lab הזה אמורה לעלות פחות מ-1 $בארה"ב במשאבי Cloud.
    • כדי למנוע חיובים נוספים, תוכלו לפעול לפי השלבים שמפורטים בסוף שיעור ה-Lab הזה כדי למחוק את המשאבים.
    • משתמשים חדשים זכאים לתקופת ניסיון בחינם בשווי 300$‎.
    • יש לכם כוונה להשתתף באירוע של AI גנרטיבי למפתחים? יכול להיות שתהיה לך אפשרות לקבל זיכוי בסך 1$.
  3. יוצרים פרויקט חדש או בוחרים לעשות שימוש חוזר בפרויקט קיים.

4. פתיחת Cloud Shell Editor

  1. עוברים אל Cloud Shell Editor.
  2. אם מסוף ה-SSH לא מופיע בחלק התחתון של המסך, פותחים אותו:
    • לוחצים על תפריט שלושת הקווים סמל התפריט של שלושת הקווים.
    • לוחצים על Terminal (מסוף).
    • לוחצים על מסוף חדשפתיחת טרמינל חדש ב-Cloud Shell Editor
  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. אם מתבקשים לאשר, לוחצים על Authorize (מתן הרשאה) כדי להמשיך. לוחצים כדי לאשר את Cloud Shell
  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 "you@example.com"
  2. מגדירים את שם המשתמש הגלובלי ב-git:
    git config --global user.name "Your Name"
  3. מגדירים את ההסתעפות main:
    git config --global init.defaultBranch main
    כברירת המחדל הגלובלית ב-git

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 כדי למנוע ביצוע commit של 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.
    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. מוסיפים את כל הקבצים בספרייה הנוכחית ל-commit הזה:
    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 במסוף התפריט הנפתח של פרויקטים במסוף Google Cloud
  4. לוחצים על קישור המאגר.
  5. לוחצים על SET UP WITH CLOUD BUILD (הגדרה באמצעות 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.
      • בדף 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. גוללים למטה לקטע Authentication (אימות).
  7. לוחצים על Allow unauthenticated invocations (אישור הפעלות לא מאומתות).
  8. לוחצים על יצירה.

בסיום ה-build (הפעולה תימשך כמה דקות), מריצים את הפקודה הזו ונכנסים לכתובת ה-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. אם מסוף ה-SSH לא מופיע בחלק התחתון של המסך, פותחים אותו:
    • לוחצים על תפריט שלושת הקווים סמל התפריט של שלושת הקווים.
    • לוחצים על Terminal (מסוף).
    • לוחצים על מסוף חדשפתיחת טרמינל חדש ב-Cloud Shell Editor
  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. אם מתבקשים לאשר, לוחצים על Authorize (מתן הרשאה) כדי להמשיך. לוחצים כדי לאשר את 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. מתקינים את Node.js Genkit SDK:
    npm install @genkit-ai/ai
  4. מתקינים את Node.js Genkit SDK ל-Vertex AI:
    npm install @genkit-ai/vertexai
  5. מתקינים את Node.js Google Auth SDK:
    npm install google-auth-library
  6. פותחים מחדש את index.js ב-Cloud Shell Editor
    cloudshell edit ~/codelab-genai/index.js
  7. מחליפים את הקוד בקובץ index.js בקוד הבא:
    import express from 'express';
const app = express();

import { generate } from '@genkit-ai/ai';
import { gemini15Flash, vertexAI } from '@genkit-ai/vertexai';

import { GoogleAuth } from 'google-auth-library';
const auth = new GoogleAuth();

app.get('/', async (req, res) => {
    const project = await auth.getProjectId();

    const animal = req.query.animal || 'dog';
    const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
    const result = await generate({
        plugins: [
            vertexAI({ projectId: project, location: 'us-central1' }),
        ],
        model: gemini15Flash,
        prompt,
    });
    const html = result.text;
    res.send(html);
});

const port = process.env.PORT || 8080;
app.listen(port, () => {
    console.log(`codelab-genai: listening on port ${port}`);
});

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 מופעלים כברירת מחדל. כדי לבדוק בקשות ליצירת תוכן, צריך להפעיל את יומני הביקורת Data Access:

  1. נכנסים לדף Audit Logs במסוף Google Cloud:

    אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שבה הכותרת המשנית היא 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. נכנסים לדף Log Explorer במסוף Google Cloud:

  3. בחלון השאילתה, מקלידים:
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
protoPayload.serviceName="aiplatform.googleapis.com"
  4. לוחצים על Run query.

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

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

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

  1. פותחים מחדש את index.js ב-Cloud Shell Editor
    cloudshell edit ~/codelab-genai/index.js
  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. נכנסים לדף Log Explorer במסוף Google Cloud:

  2. בחלון השאילתה, מקלידים:
    LOG_ID("run.googleapis.com%2Fstdout")
severity=DEBUG
  3. לוחצים על Run query.

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

15. (אופציונלי) הסרת המשאבים

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

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

מומלץ גם למחוק משאבים לא נחוצים מהדיסק של cloudshell. אפשר:

  1. מוחקים את ספריית הפרויקט ב-codelab: 
    rm -rf ~/codelab-genai
  2. אזהרה! אי אפשר לבטל את הפעולה הזו. אם רוצים למחוק את כל התוכן ב-Cloud Shell כדי לפנות מקום, אפשר למחוק את כל ספריית הבית. חשוב לוודא שכל מה שרוצים לשמור נשמר במקום אחר. 
    sudo rm -rf $HOME

16. מזל טוב

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

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

אם אתם רוצים להשתתף במחקר בנושא חוויית משתמש (UX) כדי לשפר את המוצרים שבהם עבדתם היום, אפשר להירשם כאן.

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