פריסת תהליכים באמצעות Cloud Run

אפשר לפרוס תהליכים של Genkit כנקודות קצה מסוג HTTPS באמצעות Cloud Run. ל-Cloud Run יש כמה אפשרויות פריסת, כולל פריסת קונטיינרים. בדף הזה נסביר איך לפרוס את התהליכים ישירות מהקוד.

לפני שמתחילים

• מתקינים את Google Cloud CLI.
• כדאי שתכירו את המושג flows ב-Genkit ואת האופן שבו כותבים אותם. בדף הזה נניח שכבר יש לכם תהליכים שאתם רוצים לפרוס.
• מומלץ, אבל לא חובה, שכבר השתמשתם ב-Google Cloud וב-Cloud Run.

1. הגדרת פרויקט ב-Google Cloud

אם עדיין לא הגדרתם פרויקט ב-Google Cloud, עליכם לפעול לפי השלבים הבאים:

1. יוצרים פרויקט חדש ב-Google Cloud באמצעות מסוף Cloud או בוחרים פרויקט קיים.

2. מקשרים את הפרויקט לחשבון לחיוב, שנדרש ל-Cloud Run.

3. מגדירים את Google Cloud CLI לשימוש בפרויקט:

   gcloud init

2. הכנת פרויקט Node לפריסה

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

הוספת סקריפטים להתחלה ול-build לקובץ package.json

כשפורסים פרויקט Node.js ב-Cloud Run, כלים לפריסה מצפים לפרויקט עם סקריפט start, ואפשר גם עם סקריפט build. בפרויקט TypeScript אופייני, הסקריפטים הבאים בדרך כלל מספיקים:

"scripts": {
  "start": "node lib/index.js",
  "build": "tsc"
},

הוספת קוד להגדרה ולהפעלה של שרת ה-flow

בקובץ שבו פועל הסקריפט start, מוסיפים קריאה ל-startFlowServer. השיטה הזו תפעיל שרת Express שמוגדר להציג את התהליכים שלכם בתור נקודות קצה באינטרנט.

בזמן ביצוע הקריאה, מציינים את הפלואים שרוצים להציג:

ai.startFlowServer({
  flows: [menuSuggestionFlow],
});

יש גם כמה פרמטרים אופציונליים שאפשר לציין:

• port: יציאת הרשת להאזנה. אם לא צוין יציאה, השרת מקשיב ביציאה שמוגדרת במשתנה הסביבה PORT. אם לא מגדירים את PORT, הערך שמוגדר כברירת מחדל הוא 3400.
• cors: מדיניות ה-CORS של שרת התהליך. אם אתם מתכוונים לגשת לנקודות הקצה האלה מאפליקציית אינטרנט, סביר להניח שתצטרכו לציין זאת.
• pathPrefix: תחילית נתיב אופציונלית שאפשר להוסיף לפני נקודות הקצה של התהליך.
• jsonParserOptions: אפשרויות להעברה אל מנתח גוף ה-JSON של Express

אופציונלי: הגדרת מדיניות הרשאה

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

כשפורסים את התהליכים באמצעות Cloud Run, יש שתי אפשרויות לאישור:

• אימות מבוסס-IAM ב-Cloud: שימוש במתקני ניהול הגישה המקוריים של Google Cloud כדי לפקח על הגישה לנקודות הקצה. במאמר אימות במסמכי התיעוד של Cloud Run מוסבר איך מספקים את פרטי הכניסה האלה.

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

אם רוצים להגדיר מדיניות הרשאה בקוד, משתמשים בפרמטר authPolicy בהגדרת התהליך:

const myFlow = ai.defineFlow(
  {
    name: "myFlow",
    authPolicy: (auth, input) => {
      if (!auth) {
        throw new Error("Authorization required.");
      }
      // Custom checks go here...
    },
  },
  async () => {
    // ...
  }
);

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

איך מאפשרים לפרטי כניסה ל-API להיות זמינים לתהליכים שנפרסו

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

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

Gemini (AI מבית Google)

1. מוודאים ש-Google AI זמין באזור שלכם.

2. יוצרים מפתח API ל-Gemini API באמצעות Google AI Studio.

3. מאפשרים את מפתח ה-API בסביבת Cloud Run:

   1. במסוף Cloud, מפעילים את Secret Manager API.
   2. בדף Secret Manager יוצרים סוד חדש שמכיל את מפתח ה-API.
   3. אחרי שיוצרים את הסוד, באותו דף מקצים לחשבון השירות שמוגדרת לו כברירת מחדל ב-Compute גישה לסוד באמצעות התפקיד Secret Manager Secret Accessor. (אפשר למצוא את השם של חשבון שירות ברירת המחדל של Compute בדף IAM).

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

Gemini‏ (Vertex AI)

1. במסוף Cloud, מפעילים את Vertex AI API בפרויקט.

2. בדף IAM, מוודאים שלחשבון השירות המוגדר כברירת מחדל ל-Compute הוקצה התפקיד Vertex AI User.

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

3. פריסת תהליכים ב-Cloud Run

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

Gemini (AI מבית Google)

gcloud run deploy --update-secrets=GOOGLE_GENAI_API_KEY=<your-secret-name>:latest

Gemini‏ (Vertex AI)

gcloud run deploy

כלי הפריסה יציג לכם בקשה למידע הנדרש.

כשמתבקשים לאשר הפעלות לא מאומתות:

• משיבים Y אם אתם לא משתמשים ב-IAM ובמקום זאת הגדרתם מדיניות הרשאה בקוד.
• משיבים N כדי להגדיר את השירות כך שיחייב פרטי כניסה ל-IAM.

אופציונלי: ניסיון בתהליך הפריסה

בסיום הפריסה, הכלי ידפיס את כתובת ה-URL של השירות. אפשר לבדוק את זה באמצעות curl:

curl -X POST https://<service-url>/menuSuggestionFlow \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" -d '{"data": "banana"}'