פריסת אוטומטית של אפליקציית אינטרנט מבוססת-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

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

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

4. פתיחת Cloud Shell Editor

  1. עוברים אל Cloud Shell Editor.
  2. אם מסוף ה-CLI לא מופיע בחלק התחתון של המסך, פותחים אותו:
    • לוחצים על תפריט שלושת הקווים סמל התפריט של שלושת הקווים.
    • לוחצים על 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:
    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. יש שתי אפשרויות להמשך המדריך:
  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/app/page.tsx \n\n"

10. הגדרת פריסות אוטומטיות

  1. משאירים את הכרטיסייה של Cloud Shell Editor פתוחה. נשוב לכרטיסייה הזו בהמשך.
  2. בכרטיסייה חדשה, נכנסים אל הדף של Cloud Run.
  3. בוחרים את הפרויקט הנכון ב-Google Cloud במסוף התפריט הנפתח של פרויקטים במסוף Google Cloud
  4. לוחצים על CONNECT REPO (קישור המאגר).
  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. אם מסוף ה-CLI לא מופיע בחלק התחתון של המסך, פותחים אותו:
    • לוחצים על תפריט שלושת הקווים סמל התפריט של שלושת הקווים.
    • לוחצים על 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. מתקינים את Vertex AI SDK ל-Node.js:
    npm install @google-cloud/vertexai
  4. מתקינים את Node.js Google Auth SDK:
    npm install google-auth-library
  5. יצירת app/actions.ts ב-Terminal
    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 מופעלים כברירת מחדל. כדי לבדוק בקשות ליצירת תוכן, צריך להפעיל את יומני הביקורת 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. פותחים מחדש את 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. נכנסים לדף 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 לפרוס את האפליקציה באופן אוטומטי כשמתבצע שינוי בקוד המקור של האפליקציה. לאחר מכן שיניתם את האפליקציה ופרסמתם אותה שוב.

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

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