דף זה תורגם על ידי Cloud Translation API.

הטמעת סיפורי משתמשים ב-JIRA באמצעות GenAI

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

במעבדה הזו תלמדו איך ליצור פתרון לאוטומציה של הטמעת סיפורי שימוש ב-JIRA באמצעות GenAI.

מה תלמדו

הסדנה מורכבת מכמה חלקים עיקריים:

פריסה של אפליקציית Cloud Run לשילוב עם ממשקי Gemini API
יצירת אפליקציה של Atlassian Forge ל-JIRA ופריסה שלה
LangChain ReAct Agents לאוטומציה של משימות ב-GitLab

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

ההנחה בשיעור ה-Lab הזה היא שיש לכם היכרות עם סביבות Cloud Console ו-Cloud Shell.

2. הגדרה ודרישות

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

נכנסים למסוף Google Cloud ויוצרים פרויקט חדש או משתמשים מחדש בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או חשבון Google Workspace, עליכם ליצור חשבון.

שם הפרויקט הוא השם המוצג של המשתתפים בפרויקט. זוהי מחרוזת תווים שלא משמשת את Google APIs. תמיד תוכלו לעדכן אותו.
מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud ואי אפשר לשנות אותו אחרי שמגדירים אותו. מסוף Cloud יוצר מחרוזת ייחודית באופן אוטומטי. בדרך כלל לא משנה מה המחרוזת הזו. ברוב ה-codelabs תצטרכו להפנות למזהה הפרויקט (בדרך כלל מזהים אותו בתור PROJECT_ID). אם המזהה שנוצר לא מוצא חן בעיניכם, תוכלו ליצור מזהה אקראי אחר. לחלופין, אפשר לנסות כתובת משלכם ולבדוק אם היא זמינה. לא ניתן לשנות את השם אחרי השלב הזה, והוא יישאר למשך כל פרק הזמן של הפרויקט.
לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. מידע נוסף על כל שלושת הערכים האלה זמין במסמכי העזרה.

בשלב הבא, כדי להשתמש במשאבים או ב-API של Cloud, תצטרכו להפעיל את החיוב במסוף Cloud. השלמת הקודלאב הזה לא תעלה הרבה, אם בכלל. כדי להשבית את המשאבים ולמנוע חיובים אחרי סיום המדריך, אפשר למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים להשתתף בתוכנית תקופת ניסיון בחינם בסך 300$.

הגדרת הסביבה

פותחים את Gemini Chat.

אפשר גם להקליד 'שאל Gemini' בסרגל החיפוש.

מפעילים את Cloud AI Companion API:

לוחצים על 'Start chatting' ופועלים לפי אחת מהשאלות לדוגמה או מקלידים הנחיה משלכם כדי לנסות את התכונה.

הנחיות שאפשר לנסות:

הסבר על Cloud Run ב-5 נקודות עיקריות.
אתם מנהלי מוצרים ב-Google Cloud Run, ואתם צריכים להסביר לתלמיד/ה על Cloud Run ב-5 נקודות עיקריות קצרות.
אתם מנהלי מוצרים ב-Google Cloud Run, ואתם צריכים להסביר את Cloud Run למפתח Kubernetes מוסמך ב-5 נקודות עיקריות קצרות.
אתם מנהלי מוצר של Google Cloud Run, ואתם צריכים להסביר למפתח בכיר מתי כדאי להשתמש ב-Cloud Run לעומת GKE, ב-5 נקודות מפתח קצרות.

במדריך להנחיות מוסבר איך לכתוב הנחיות טובות יותר.

איך Gemini for Google Cloud משתמש בנתונים שלכם

המחויבות של Google לפרטיות

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

נתונים שאתם שולחים ומקבלים

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

הצפנה של הנחיות

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

נתוני תוכנית שנוצרו מ-Gemini

‫Gemini מאומן על קוד מ-Google Cloud (מצד ראשון) ועל קוד נבחר של צד שלישי. אתם אחראים על האבטחה, הבדיקה והיעילות של הקוד שלכם, כולל כל השלמה, יצירה או ניתוח של קוד ש-Gemini מציעה לכם.

מידע נוסף על האופן שבו Google מטפלת בהנחיות

3. אפשרויות לבדיקה של הנחיות

יש כמה דרכים לבדוק את ההנחיות.

Vertex AI Studio

Vertex AI Studio הוא חלק מפלטפורמת Vertex AI של Google Cloud, שמיועדת במיוחד לפשט ולהאיץ את הפיתוח והשימוש במודלים של AI גנרטיבי.

Google AI Studio

Google AI Studio הוא כלי מבוסס-אינטרנט ליצירת אב טיפוס ולניסויים בתכנון הנחיות וב-Gemini API.

אפליקציית Gemini בדפדפן (gemini.google.com)

אפליקציית האינטרנט של Google Gemini‏ (gemini.google.com) היא כלי מבוסס-אינטרנט שמיועד לעזור לכם לגלות את מלוא הפוטנציאל של מודלי ה-AI של Gemini מבית Google ולהשתמש בו.

אפליקציית Google Gemini לנייד ל-Android ו-אפליקציית Google ל-iOS

4. (קטע אופציונלי) יצירת חשבון שירות

השלבים האלה בוצעו במהלך הגדרת הסדנה – אין צורך להריץ אותם.

השלבים האלה מצורפים כדי להראות איך מגדירים חשבון שירות ותפקידים ב-IAM.

חוזרים למסוף Google Cloud ומפעילים את Cloud Shell בלחיצה על הסמל שמשמאל לסרגל החיפוש.

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

תשתמשו בחשבון השירות הזה כדי לבצע קריאות API ל-Vertex AI Gemini API מאפליקציית Cloud Run.

מגדירים את פרטי הפרויקט באמצעות פרטי הפרויקט ב-Qwiklabs.

לדוגמה: qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR_QWIKLABS_PROJECT_ID

יוצרים חשבון שירות ומעניקים לו תפקידים.

PROJECT_ID=$(gcloud config get-value project)
SERVICE_ACCOUNT_NAME='vertex-client'
DISPLAY_NAME='Vertex Client'
KEY_FILE_NAME='vertex-client-key'

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME --project $PROJECT_ID --display-name "$DISPLAY_NAME"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudbuild.builds.editor"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/artifactregistry.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/secretmanager.secretAccessor"


gcloud iam service-accounts keys create $KEY_FILE_NAME.json --iam-account=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

אם מתבקשים לאשר, לוחצים על 'אישור' כדי להמשיך.

מפעילים את השירותים הנדרשים כדי להשתמש ב-Vertex AI APIs וב-Gemini Chat.

gcloud services enable \
    generativelanguage.googleapis.com \
    aiplatform.googleapis.com \
    cloudaicompanion.googleapis.com \
    run.googleapis.com \
    cloudresourcemanager.googleapis.com

מפעילים את השירותים הנדרשים כדי להשתמש ב-Vertex AI APIs וב-Gemini Chat.

gcloud services enable \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    runapps.googleapis.com \
    workstations.googleapis.com \
    servicemanagement.googleapis.com \
    secretmanager.googleapis.com \
    containerscanning.googleapis.com

(END OF OPTIONAL SECTION)

5. מתן גישה ל-Cloud Workstations

פותחים את Cloud Workstations במסוף Cloud.

מעניקים גישה ל-Cloud Workstation לתלמיד Qwiklabs שהוקצה לו הרשאה.

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

פרטים נוספים מופיעים בהמשך.

לוחצים על הלחצן ADD PRINCIPAL.

מדביקים את כתובת האימייל של התלמיד/ה ב-Qwiklabs ובוחרים בתפקיד Cloud Workstations User.

לוחצים על Start ואז על Launch כדי לפתוח את תחנת העבודה ולהמשיך בשלבים הבאים באמצעות הטרמינל המובנה.

שכפול של מאגר GitHub

יוצרים תיקייה ומשכפלים את מאגר GitHub.

mkdir github
cd github
git clone https://github.com/GoogleCloudPlatform/genai-for-developers.git

באמצעות פריט התפריט File / Open Folder, פותחים את github/genai-for-developers.

6. הפעלת Gemini Code Assist

לוחצים על סמל Gemini בפינה הימנית התחתונה, ואז לוחצים על Login to Google Cloud.

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

לוחצים על 'פתיחה' כדי לעבור לקישור.

בוחרים את חשבון התלמיד/ה ב-Qwiklabs ולוחצים על 'כניסה' במסך הבא.

מעתיקים את קוד האימות:

חוזרים למסוף ומדביקים את הקוד.

ממתינים עד שהאימות יושלם ולוחצים על 'בחירת פרויקט ב-Google'.

בחלון הקופץ, בוחרים את הפרויקט ב-Qwiklabs.

דוגמה:

פותחים את הקובץ devai-api/app/routes.py, לוחצים לחיצה ימנית במקום כלשהו בקובץ ובוחרים באפשרות Gemini > Explain this" בתפריט ההקשר.

קוראים את ההסבר של Gemini לגבי הקובץ שנבחר.

7. ערכות כלים של LangChain

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

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

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

ערכות כלים להפעלת סוכנים: כלים לפיתוח סוכנים שיכולים לקיים אינטראקציה עם העולם האמיתי באמצעות פעולות כמו גלישה באינטרנט או ביצוע קוד.
Prompt Engineering Toolkit: אוסף משאבים ליצירת הנחיות יעילות.

GitLab Toolkit

במעבדה הזו נשתמש ב-Toolkit של GitLab כדי ליצור בקשות מיזוג באופן אוטומטי ב-GitLab.

ערכת הכלים של Gitlab מכילה כלים שמאפשרים לסוכני LLM לקיים אינטראקציה עם מאגר Gitlab. הכלי הוא מעטפת לספרייה python-gitlab.

ערכת הכלים של GitLab יכולה לבצע את המשימות הבאות:

Create File – יצירת קובץ חדש במאגר.
קריאת קובץ – קריאת קובץ מהמאגר.
עדכון קובץ – עדכון קובץ במאגר.
Create Pull Request – יצירת בקשת משיכה מההסתעפות הפעילה של הרובוט להסתעפות הבסיסית.
Get Issues – אחזור בעיות מהמאגר.
Get Issue – אחזור פרטים על בעיה ספציפית.
תגובה על בעיה – פרסום תגובה לגבי בעיה ספציפית.
Delete File – מחיקה של קובץ מהמאגר.

8. הגדרת Toolkit ומאגר GitLab

פותחים את GitLab, יוצרים פרויקט ציבורי חדש ומגדירים אסימון גישה לפרויקט בקטע Settings / Access Tokens.

יש להשתמש בפרטים הבאים:

שם הטוקן: devai-api-qwiklabs
תפקיד: Maintainer
בוחרים את ההיקפים: api

מעתיקים את הערך של אסימון הגישה ומדביקים אותו בקובץ זמני במחשב הנייד. הערך הזה ישמש בשלבים הבאים.

9. הכנה לפריסה של אפליקציה ב-Cloud Run

חוזרים למכונה של Cloud Workstations ומשתמשים בטרמינל קיים או פותחים טרמינל חדש.

קבלת פרטי הכניסה לחשבון המשתמש באמצעות תהליך הרשאה מבוסס-אינטרנט.

לוחצים על הקישור ופועלים לפי השלבים ליצירת קוד אימות.

gcloud auth login

מגדירים את פרטי הפרויקט באמצעות פרטי הפרויקט ב-Qwiklabs.

לדוגמה: qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR-QWIKLABS-PROJECT-ID

מגדירים את שאר משתני הסביבה:

export PROJECT_ID=$(gcloud config get-value project)
export LOCATION=us-central1
export REPO_NAME=devai-api
export SERVICE_NAME=devai-api

מגדירים את משתני הסביבה הנדרשים לשילוב עם GitLab.

export GITLAB_PERSONAL_ACCESS_TOKEN=gitlab-token

כדי להימנע מחשיפת מידע רגיש במסוף, מומלץ להשתמש ב-read -s. זוהי דרך מאובטחת להגדיר משתני סביבה בלי שהערך יופיע בהיסטוריית הפקודות של המסוף. אחרי ההרצה, צריך להדביק את הערך וללחוץ על Enter.

כדי להשתמש בפקודה הזו, צריך לעדכן את מזהה המשתמש ואת שם המאגר ב-GitLab.

לדוגמה: export GITLAB_REPOSITORY="gitrey/qwiklabs-test"

export GITLAB_REPOSITORY="USERID/REPOSITORY"

מגדירים את שאר משתני הסביבה:

export GITLAB_URL="https://gitlab.com"
export GITLAB_BRANCH="devai"
export GITLAB_BASE_BRANCH="main"

10. הגדרת המעקב של LangSmith LLM

יוצרים חשבון LangSmith ויוצרים מפתח Service API בקטע 'הגדרות'. https://docs.smith.langchain.com/

מגדירים את משתני הסביבה הנדרשים לשילוב עם LangSmith.

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

export LANGCHAIN_API_KEY=langchain-service-api-key

11. הגדרת JIRA

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

הגדרת משתני הסביבה הנדרשים לפריסה של שירות Cloud Run.

export JIRA_API_TOKEN=jira-token
export JIRA_USERNAME="YOUR-EMAIL"
export JIRA_INSTANCE_URL="https://YOUR-JIRA-PROJECT.atlassian.net"
export JIRA_PROJECT_KEY="YOUR-JIRA-PROJECT-KEY"
export JIRA_CLOUD=true

12. פריסה של Devai-API ב-Cloud Run

מוודאים שנמצאים בתיקייה הנכונה.

cd ~/github/genai-for-developers/devai-api

במסגרת הסדנה הזו, אנחנו פועלים לפי השיטות המומלצות ומשתמשים ב-Secret Manager כדי לאחסן את הערכים של אסימון הגישה ומפתח ה-API של LangChain ב-Cloud Run, ולהפנות אליהם.

אחסון אסימון הגישה ל-JIRA ב-Secret Manager.

echo -n $JIRA_API_TOKEN | \
 gcloud secrets create JIRA_API_TOKEN \
 --data-file=-

אחסון אסימון הגישה של GitLab ב-Secret Manager.

echo -n $GITLAB_PERSONAL_ACCESS_TOKEN | \
 gcloud secrets create GITLAB_PERSONAL_ACCESS_TOKEN \
 --data-file=-

מאחסנים את מפתח ה-API של LangChain ב-Secret Manager.

echo -n $LANGCHAIN_API_KEY | \
 gcloud secrets create LANGCHAIN_API_KEY \
 --data-file=-

פריסת האפליקציה ב-Cloud Run.

gcloud run deploy "$SERVICE_NAME" \
  --source=. \
  --region="$LOCATION" \
  --allow-unauthenticated \
  --service-account vertex-client \
  --set-env-vars PROJECT_ID="$PROJECT_ID" \
  --set-env-vars LOCATION="$LOCATION" \
  --set-env-vars GITLAB_URL="$GITLAB_URL" \
  --set-env-vars GITLAB_REPOSITORY="$GITLAB_REPOSITORY" \
  --set-env-vars GITLAB_BRANCH="$GITLAB_BRANCH" \
  --set-env-vars GITLAB_BASE_BRANCH="$GITLAB_BASE_BRANCH" \
  --set-env-vars JIRA_USERNAME="$JIRA_USERNAME" \
  --set-env-vars JIRA_INSTANCE_URL="$JIRA_INSTANCE_URL" \
  --set-env-vars JIRA_PROJECT_KEY="$JIRA_PROJECT_KEY" \
  --set-env-vars JIRA_CLOUD="$JIRA_CLOUD" \
  --set-env-vars LANGCHAIN_TRACING_V2="$LANGCHAIN_TRACING_V2" \
  --update-secrets="LANGCHAIN_API_KEY=LANGCHAIN_API_KEY:latest" \
  --update-secrets="GITLAB_PERSONAL_ACCESS_TOKEN=GITLAB_PERSONAL_ACCESS_TOKEN:latest" \
  --update-secrets="JIRA_API_TOKEN=JIRA_API_TOKEN:latest" \
  --min-instances=1 \
  --max-instances=3

משיבים Y כדי ליצור מאגר Docker ב-Artifact Registry.

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in 
region [us-central1] will be created.

Do you want to continue (Y/n)?  y

אפשר לעיין בתהליך gcloud run deploy SERVICE_NAME --source=. שבהמשך. מידע נוסף

מאחורי הקלעים, הפקודה הזו משתמשת ב-buildpacks וב-Cloud Build של Google Cloud כדי ליצור באופן אוטומטי קובצי אימג' של קונטיינרים מקוד המקור, בלי שתצטרכו להתקין את Docker במכונה או להגדיר buildpacks או Cloud Build. כלומר, הפקודה היחידה שמתוארת למעלה מבצעת את הפעולות שהיו נדרשות אחרת באמצעות הפקודות gcloud builds submit ו-gcloud run deploy.

אם סיפקתם קובץ Dockerfile(כפי שעשינו במאגר הזה), Cloud Build ישתמש בו כדי ליצור קובצי אימג' של קונטיינרים, במקום להסתמך על ה-buildpacks כדי לזהות קובצי אימג' של קונטיינרים וליצור אותם באופן אוטומטי. מידע נוסף על buildpacks זמין במסמכי התיעוד.

בודקים את היומנים של Cloud Build במסוף.

בודקים את קובץ האימג' של Docker שנוצר ב-Artifact Registry.

פותחים את cloud-run-source-deploy/devai-api ובודקים את נקודות החולשה שזוהו באופן אוטומטי. בודקים אילו מהן יש תיקונים זמינים ומעיינים בתיאור כדי להבין איך אפשר לתקן את הבעיה.

בודקים את פרטי המכונה של Cloud Run במסוף Cloud.

בודקים את נקודת הקצה על ידי הרצת הפקודה curl.

curl -X POST \
   -H "Content-Type: application/json" \
   -d '{"prompt": "Create HTML, CSS and JavaScript using React.js framework to implement Login page with username and password fields, validation and documentation. Provide complete implementation, do not omit anything."}' \
   $(gcloud run services list --filter="(devai-api)" --format="value(URL)")/generate

(קטע אופציונלי) הגדרה של Cloud Workstation

Cloud Workstations מספק סביבות פיתוח מנוהלות ב-Google Cloud עם אבטחה מובנית וסביבות פיתוח מוגדרות מראש שניתנות להתאמה אישית. במקום לדרוש מהמפתחים להתקין תוכנה ולהריץ סקריפטים להגדרה, אפשר ליצור הגדרה של תחנת עבודה שמציינת את הסביבה שלכם באופן שניתן לשחזור. כל עדכון של הגדרת תחנת עבודה יחול באופן אוטומטי על תחנות העבודה בפעם הבאה שהן יופעלו. למפתחים יש גישה למכונות העבודה דרך סביבת פיתוח משולבת (IDE) מבוססת-דפדפן, מכמה עורכי קוד מקומיים (כמו VSCode או סביבת פיתוח משולבת של JetBrains כמו IntelliJ IDEA Ultimate ו-PyCharm Professional) או דרך SSH.

Cloud Workstations משתמש במשאבים הבאים של Google Cloud כדי לנהל את סביבות הפיתוח:

אשכולות של תחנות עבודה מגדירים קבוצה של תחנות עבודה באזור מסוים ואת רשת ה-VPC שאליהן הן מחוברות. אשכולות של תחנות עבודה לא קשורים לאשכולות של Google Kubernetes Engine‏ (GKE).
הגדרות של תחנות עבודה משמשות כתבניות לתחנות עבודה. בהגדרות של תחנת העבודה מוגדרים פרטים כמו סוג המכונה הווירטואלית (VM) של תחנת העבודה, אחסון מתמיד, סביבה להגדרת קובץ האימג' בקונטיינר, סביבת הפיתוח המשולבת (IDE) או עורך הקוד שבהם רוצים להשתמש ועוד. אדמינים וצוותים של פלטפורמות יכולים גם להשתמש בכללי ניהול זהויות והרשאות גישה (IAM) כדי להעניק גישה לצוותים או למפתחים ספציפיים.
תחנות עבודה הן סביבות פיתוח מוגדרות מראש שמספקות סביבת פיתוח משולבת (IDE) בענן, כלים לשפות, ספריות ועוד. אפשר להפעיל או להפסיק תחנות עבודה על פי דרישה, ולהריץ אותן במכונות וירטואליות של Compute Engine בפרויקט, עם דיסק מתמיד שמחובר כדי לאחסן נתונים בין סשנים.

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

במעבדה הזו תשתמשו בסביבת פיתוח משולבת (IDE) מבוססת-דפדפן, אבל Cloud Workstations תומך גם בממשקי פיתוח נפוצים אחרים:

אתם יכולים להשתמש בסביבות הפיתוח המקומיות של JetBrains דרך JetBrains Gateway
אם אתם משתמשים ב-VSCode מקומי, תוכלו לגשת גם למכונות העבודה שלכם לפיתוח מרחוק דרך SSH.
אפשר גם להגדיר מנהרות SSH ואפילו TCP ל-Workstation מהמחשב המקומי.

(קטע אופציונלי) יצירת אשכול של Workstations

השלבים האלה בוצעו במהלך הגדרת הסדנה – אין צורך להריץ אותם.

השלבים האלה מפורטים כדי להראות איך מגדירים את Cloud Workstations Cluster, ‏ Configuration ו-Workstation.

קוראים את הקטע הזה וממשיכים לקטע 'פלטפורמת Forge'.

יוצרים אשכול של Workstations:

gcloud workstations clusters create ws-cluster --region=us-central1

יצירת הגדרה אישית של Workstations

gcloud workstations configs create devai-config \
--cluster=ws-cluster \
--machine-type=e2-standard-8 \
--region=us-central1 \
--running-timeout=21600 \
--idle-timeout=1800 \
--container-predefined-image=codeoss \
--pd-disk-size=200 \
--pd-disk-type=pd-standard \
--service-account=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com \
--pool-size=1

יצירת תחנת עבודה

gcloud workstations create devai-workstation \
--cluster=ws-cluster \
--config=devai-config \
--region=us-central1

אפשר לראות את תחנות העבודה הזמינות במסוף Cloud. מפעילים את 'devai-workstation'.

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

פותחים את הצ'אט של Gemini בחלונית הימנית ושואלים את Gemini:

'You are a Cloud Workstations Product Manager, tell me about Cloud Workstations'.

'You are Cloud Workstations Product Manager, Can I create my custom Cloud Workstations image with my company tools so new developers can onboard in minutes?'.

(END OF OPTIONAL SECTION)

13. פלטפורמת Forge

Forge היא פלטפורמה שמאפשרת למפתחים ליצור אפליקציות שמשולבות עם מוצרי Atlassian, כמו Jira, ‏ Confluence, ‏ Compass ו-Bitbucket.

התקנת Forge CLI

מריצים את הפקודות הבאות במסוף.

מורידים את Node Version Manager‏ ( nvm) ומגדירים אותו כזמין בנתיב בסשן מסוף הנוכחי.

cd ~/github/genai-for-developers

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash


export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion

מתקינים את nvm.

כדי לבחור את גרסת ה-LTS האחרונה של Node.js, מריצים את הפקודה הבאה בטרמינל:

nvm install --lts
nvm use --lts

כדי להתקין את Forge CLI באופן גלובלי, מריצים את הפקודה:

npm install -g @forge/cli

בשיעור ה-Lab הזה נשתמש במשתני סביבה כדי להתחבר.

הגדרת פרויקט ב-JIRA

שימוש בחשבון האישי ליצירה או לצפייה בפרויקטים ב-JIRA

בודקים את הפרויקטים הקיימים ב-JIRA: https://admin.atlassian.com/

יוצרים פרויקט חדש ב-JIRA באמצעות החשבון האישי.

עוברים אל https://team.atlassian.com/your-work ולוחצים על ואז על . לאחר מכן, בוחרים באפשרות 'JIRA Software' – 'Try it now' (לנסות עכשיו). פועלים לפי ההוראות כדי להשלים את יצירת הפרויקט או האתר.

בוחרים באפשרות JIRA Software.

יוצרים פרויקט חדש.

14. טוקן API של Atlassian

יוצרים אסימון API קיים של Atlassian או משתמשים בו כדי להתחבר ל-CLI.

ה-CLI משתמש באסימון שלכם כשמריצים פקודות.

עוברים לכתובת https://id.atlassian.com/manage/api-tokens.
לוחצים על Create API token.
מזינים תווית לתיאור של טוקן ה-API. לדוגמה, forge-api-token.
לוחצים על יצירה.
לוחצים על העתקה ללוח וסוגרים את תיבת הדו-שיח.

מריצים את הפקודה הבאה במסוף של Cloud Workstations.

כדי להתחיל להשתמש בפקודות של Forge, צריך להתחבר ל-CLI של Forge.

מגדירים את כתובת האימייל ב-JIRA או ב-FORGE. מחליפים את הכתובת בכתובת האימייל שלכם.

export FORGE_EMAIL=your-email

מגדירים את טוקן ה-API של Forge. מחליפים את הטוקן של JIRA API.

export FORGE_API_TOKEN=your-jira-api-token

מריצים את הפקודה הבאה כדי לבדוק את ה-CLI של Forge. כשתתבקשו לאסוף נתוני ניתוח, עליכם להשיב No.

forge settings set usage-analytics false

בודקים אם אתם מחוברים לחשבון.

forge whoami

פלט לדוגמה.

Logged in as John Green (johngreen@email.com)
Account ID: 123090:aaabbcc-076a-455c-99d0-d1aavvccdd

יצירת אפליקציה ב-Forge

בודקים שאתם נמצאים בתיקייה ~/github/genai-for-developers.

מריצים את הפקודה כדי ליצור אפליקציה ב-Forge.

forge create

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

שם האפליקציה: devai-jira-ui-qwiklabs
בוחרים קטגוריה: UI Kit
בוחרים מוצר: Jira
בוחרים תבנית: jira-issue-panel

עוברים לתיקיית האפליקציה.

cd devai-jira-ui-qwiklabs/

מריצים את פקודת הפריסה.

forge deploy

פלט לדוגמה:

Deploying your app to the development environment.
Press Ctrl+C to cancel.

Running forge lint...
No issues found.

✔ Deploying devai-jira-ui-qwiklabs to development...

ℹ Packaging app files
ℹ Uploading app
ℹ Validating manifest
ℹ Snapshotting functions
ℹ Deploying to environment

✔ Deployed

Deployed devai-jira-ui-qwiklabs to the development environment.

מתקינים את האפליקציה.

forge install

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

בוחרים מוצר: Jira
מזינים את כתובת ה-URL של האתר: your-domain.atlassian.net

פלט לדוגמה:

Select the product your app uses.

? Select a product: Jira

Enter your site. For example, your-domain.atlassian.net

? Enter the site URL: genai-for-developers.atlassian.net

Installing your app onto an Atlassian site.
Press Ctrl+C to cancel.

? Do you want to continue? Yes

✔ Install complete!

Your app in the development environment is now installed in Jira on genai-for-developers.atlassian.net

פותחים את אתר JIRA ויוצרים משימה חדשה ב-JIRA עם התיאור הבא:

Create HTML, CSS and JavaScript using React.js framework to implement Login page with username and password fields, validation and documentation. Provide complete implementation, do not omit anything.

כשפותחים את המשימה, מופיע הלחצן devai-jira-ui-qwiklabs.

לוחצים על הלחצן ובודקים את השינויים בממשק המשתמש.

הצגת יומני הקצה העורפי של Forge.

forge logs

Atlassian Developer Console

אפשר גם להציג ולנהל אפליקציות שנפרסו ב-Atlassian Developer Console.

בדיקת היומנים – עוברים לסביבה Development,

בדיקת המניפסט וקוד המקור של אפליקציית Forge

פותחים את הקובץ devai-jira-ui-qwiklabs/manifest.yml ומשתמשים ב-Gemini Code Assist כדי להסביר אותו.

קוראים את ההסבר.

פותחים את הקבצים הבאים ומבקשים מ-Gemini Code Assist להסביר אותם:

devai-jira-ui-qwiklabs/src/frontend/index.jsx
devai-jira-ui-qwiklabs/src/resolvers/index.js

עדכון אפליקציית Forge באמצעות נקודת קצה של DevAI API ב-Cloud Run

בודקים אם מזהה הפרויקט ב-GCP מוגדר:

gcloud config get project

אם לא, מגדירים את פרויקט GCP באמצעות מזהה הפרויקט שבדף של סדנת Qwiklabs:

לדוגמה: qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR_QWIKLABS_PROJECT_ID

מגדירים את כתובת ה-URL של שירות Cloud Run:

export DEVAI_API_URL=$(gcloud run services list --filter="(devai-api)" --format="value(URL)")

forge variables set DEVAI_API_URL $DEVAI_API_URL

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

forge variables list

פלט לדוגמה

עדכון המניפסט והקוד של אפליקציית Forge

קטעי הקוד האלה נמצאים במאגר בתיקייה sample-devai-jira-ui.

פותחים את קובץ המניפסט בעורך: devai-jira-ui-qwiklabs/manifest.yml

מוסיפים את השורות הבאות בסוף הקובץ – מחליפים את נקודת הקצה של Cloud Run בנקודה שהפרסתם.

permissions:
  scopes:
    - read:jira-work
    - write:jira-work
  external:
    fetch:
      client:
        - devai-api-gjerpi6qqq-uc.a.run.app/generate # replace with YOUR CLOUD RUN URL

פותחים את קובץ המפַתח/האינדקס בעורך: devai-jira-ui-qwiklabs/src/resolvers/index.js

מוסיפים את השורות הבאות אחרי הפונקציה getText הקיימת.

resolver.define('getApiKey', (req) => {
  return process.env.LLM_API_KEY;
});

resolver.define('getDevAIApiUrl', (req) => {
  return process.env.DEVAI_API_URL;
});

פותחים את הקובץ frontend/index בעורך: devai-jira-ui-qwiklabs/src/frontend/index.jsx

מחליפים את index.jsx בתוכן שבהמשך. מעדכנים את הקישור למזהה המשתמש או למאגר ב-GitLab.

יש שני מקומות שבהם צריך לעדכן את YOUR-GIT-USERID ואת YOUR-GIT-REPO.

מחפשים את השורה הזו בקובץ ומבצעים את השינויים:

https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests

import React from 'react';
import ForgeReconciler, { Text, Link, useProductContext } from '@forge/react';
import { requestJira } from '@forge/bridge';
import { invoke } from '@forge/bridge';
import api, { route, assumeTrustedRoute } from '@forge/api';

// const apiKey = await invoke("getApiKey")
const devAIApiUrl = await invoke("getDevAIApiUrl")


const App = () => {
  const context = useProductContext();

  const [description, setDescription] = React.useState();

  const fetchDescriptionForIssue = async () => {
    const issueId = context?.extension.issue.id;
  
    const res = await requestJira(`/rest/api/2/issue/${issueId}`);
    const data = await res.json();
    
    // const genAI = new GoogleGenerativeAI(apiKey);
    // const model = genAI.getGenerativeModel({ model: "gemini-pro"});
    // const prompt = `You are principal software engineer at Google and given requirements below to implement.\nPlease provide implementation details and documentation.\n\nREQUIREMENTS:\n\n${data.fields.description}`
    // const result = await model.generateContent(prompt);
    // const text = result.response.text();
    // const jsonText = JSON.stringify(text);

    const bodyGenerateData = `{"prompt": ${JSON.stringify(data.fields.description)}}`;

    const generateRes = await api.fetch(devAIApiUrl+'/generate',
      {
        body: bodyGenerateData,
        method: 'post',
        headers: { 'Content-Type': 'application/json' },
      }
    )


    const resData = await generateRes.text();
    const jsonText = JSON.stringify(resData);

    const bodyData = `{
      "body": ${jsonText}
    }`;

    console.log("bodyData", bodyData)
    // Add Gemini response as a comment on the JIRA issue
    await requestJira(`/rest/api/2/issue/${issueId}/comment`, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: bodyData
    });
    // Add link to the GitLab merge request page as a comment
    await requestJira(`/rest/api/2/issue/${issueId}/comment`, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: `{"body": "[GitLab Merge Request|https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests]"}`
    });


    return "Response will be added as a comment. Please refresh in a few moments.";
  };

  React.useEffect(() => {
    if (context) {
      fetchDescriptionForIssue().then(setDescription);
    }
  }, [context]);

  return (
    <>
      <Text>{description}</Text>
      <Link href='https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests' openNewTab={true}>GitLab Merge Request</Link>
    </>
  );
};

ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

פריסה מחדש של אפליקציית Forge

מוסיפים יחסי תלות בקובץ package.json:

"@forge/api": "4.0.0",

יחסי תלות של התקנות:

npm install

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

forge deploy

פלט לדוגמה:

ℹ Uploading app
ℹ Validating manifest
ℹ Snapshotting functions
ℹ Deploying to environment

✔ Deployed

Deployed devai-jira-ui-qwiklabs to the development environment.

We've detected new scopes or egress URLs in your app.
Run forge install --upgrade and restart your tunnel to put them into effect.

התקנת האפליקציה המעודכנת:

forge install --upgrade

פלט לדוגמה:

Upgrading your app on the Atlassian site.

Your app will be upgraded with the following additional scopes:
- read:jira-work
- write:jira-work

Your app will exchange data with the following urls:
- devai-api-7su2ctuqpq-uc.a.run.app

? Do you want to continue? Yes

✔ Upgrade complete!

Your app in the development environment is now the latest in Jira on genai-for-developers.atlassian.net.

בדיקת אפליקציית Forge

פותחים משימה קיימת ב-JIRA או יוצרים משימה חדשה בפרויקט ב-JIRA.

אם כבר הוספתם את הלוח הקודם, תצטרכו להסיר אותו.

לוחצים על ... ובוחרים באפשרות 'הסרה' בתפריט. לאחר מכן, אפשר ללחוץ שוב על הלחצן.

בדיקת התגובות ב-Jira

אחרי שתקבלו תשובה מ-DEVAI API, יתווספו שתי תגובות בבעיה ב-JIRA.

בקשת מיזוג ב-GitLab
פרטי ההטמעה של סיפור המשתמש ב-Gemini

עוברים בין הכרטיסיות History ו-Comments כדי לרענן את התצוגה.

הפעלת האפשרות ליצור בקשות מיזוג ב-GitLab

פותחים את הקובץ devai-api/app/routes.py ומבטלים את ההערה של השורות הבאות בשיטה generate_handler:

print(f"{response.text}\n")

    # resp_text = response.candidates[0].content.parts[0].text

    # pr_prompt = f"""Create GitLab merge request using provided details below.
    # Create new files, commit them and push them to opened merge request.
    # When creating new files, remove the lines that start with ``` before saving the files.

    # DETAILS: 
    # {resp_text}
    # """

    # print(pr_prompt)
    # agent.invoke(pr_prompt)

פריסת מחדש של אפליקציית Cloud Run

מוודאים שנמצאים בתיקייה הנכונה.

cd ~/github/genai-for-developers/devai-api

אם אתם משתמשים באותו סשן מסוף, יכול להיות שעדיין מוגדרים כל משתני הסביבה.

כדי לבדוק את זה, מריצים את הפקודה echo $GITLAB_REPOSITORY במסוף.

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

חשוב לאפס את משתני הסביבה הנדרשים לפני פריסה מחדש של האפליקציה.

כדי להשתמש בפקודה הזו, צריך לעדכן את מזהה המשתמש ואת שם המאגר ב-GitLab.

export GITLAB_REPOSITORY="USERID/REPOSITORY"

מגדירים את שאר משתני הסביבה:

export GITLAB_URL="https://gitlab.com"
export GITLAB_BRANCH="devai"
export GITLAB_BASE_BRANCH="main"

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

export LOCATION=us-central1
export REPO_NAME=devai-api
export SERVICE_NAME=devai-api
export PROJECT_ID=$(gcloud config get-value project)

export JIRA_USERNAME="YOUR-EMAIL"
export JIRA_INSTANCE_URL="https://YOUR-JIRA-PROJECT.atlassian.net"
export JIRA_PROJECT_KEY="YOUR-JIRA-PROJECT-KEY"
export JIRA_CLOUD=true

ערכת הכלים של GitLab תשתמש בהסתעפות devai כדי לדחוף את השינויים לבקשת המיזוג.

מוודאים שכבר יצרתם את ההסתעפות הזו.

פריסת האפליקציה ב-Cloud Run.

gcloud run deploy "$SERVICE_NAME" \
  --source=. \
  --region="$LOCATION" \
  --allow-unauthenticated \
  --service-account vertex-client \
  --set-env-vars PROJECT_ID="$PROJECT_ID" \
  --set-env-vars LOCATION="$LOCATION" \
  --set-env-vars GITLAB_URL="$GITLAB_URL" \
  --set-env-vars GITLAB_REPOSITORY="$GITLAB_REPOSITORY" \
  --set-env-vars GITLAB_BRANCH="$GITLAB_BRANCH" \
  --set-env-vars GITLAB_BASE_BRANCH="$GITLAB_BASE_BRANCH" \
  --set-env-vars JIRA_USERNAME="$JIRA_USERNAME" \
  --set-env-vars JIRA_INSTANCE_URL="$JIRA_INSTANCE_URL" \
  --set-env-vars JIRA_PROJECT_KEY="$JIRA_PROJECT_KEY" \
  --set-env-vars JIRA_CLOUD="$JIRA_CLOUD" \
  --set-env-vars LANGCHAIN_TRACING_V2="$LANGCHAIN_TRACING_V2" \
  --update-secrets="LANGCHAIN_API_KEY=LANGCHAIN_API_KEY:latest" \
  --update-secrets="GITLAB_PERSONAL_ACCESS_TOKEN=GITLAB_PERSONAL_ACCESS_TOKEN:latest" \
  --update-secrets="JIRA_API_TOKEN=JIRA_API_TOKEN:latest" \
  --min-instances=1 \
  --max-instances=3

אימות השילוב מקצה לקצה

מתחילים את התהליך מהמשימה ב-JIRA בלחיצה שוב על הלחצן, ומאמתים את הפלט במאגר GitLab בקטע Merge request (בקשת מיזוג) וב-LangSmith.

פרטי הבקשה למיזוג ב-GitLab.

מעקבים של LangSmith LLM

פותחים את LangSmith portal ובודקים את המעקב אחר LLM בקריאה ליצירת בעיה ב-JIRA.

נתיב לדוגמה של LLM ב-LangSmith.

(קטע אופציונלי) דחיפת השינויים למאגר ב-GitHub

נכנסים לאתר GitHub ויוצרים מאגר חדש כדי לדחוף את השינויים של הסדנה הזו למאגר האישי שלכם.

חוזרים למכונה של Cloud Workstations ומגדירים את שם המשתמש ואת כתובת האימייל ב-Git במסוף.

מעדכנים את הערכים לפני שמריצים את הפקודות.

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

יוצרים מפתח SSH ומוסיפים אותו למאגר ב-GitHub.

צריך לעדכן את כתובת האימייל לפני שמריצים את הפקודות.

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

ssh-keygen -t ed25519 -C "your-email-address"

eval "$(ssh-agent -s)"

ssh-add ~/.ssh/id_ed25519

cat ~/.ssh/id_ed25519.pub

מוסיפים את המפתח הציבורי שנוצר לחשבון GitHub.

פותחים את הדף https://github.com/settings/keys ולוחצים על New SSH key.

בשם המפתח, מזינים 'qwiklabs-key' ומעתיקים/מדביקים את הפלט מהפקודה האחרונה.

חוזרים לטרמינל, שומרים את השינויים ודוחפים אותם.

cd ~/github/genai-for-developers

git remote rm origin

מגדירים את המקור המרוחק באמצעות המאגר שנוצר למעלה.

מחליפים את הכתובת בכתובת ה-URL של המאגר.

git remote add origin git@github.com:YOUR-GITHUB-USERID/YOUR-GITHUB-REPO.git

מוסיפים, שומרים ודוחפים את השינויים.

git add .

git commit -m "lab changes"

git push -u origin main

15. מעולה!

כל הכבוד, סיימת את שיעור ה-Lab!

הנושאים שעסקנו בהם:

איך לפרוס אפליקציות של Cloud Run כדי לשלב אותן עם ממשקי Gemini API.
איך יוצרים ומפרסים אפליקציה של Atlassian Forge ל-JIRA.
איך משתמשים ב-LangChain ReAct Agents לאוטומציה של משימות ב-GitLab.
איך בודקים את עקבות ה-LLM ב-LangSmith.

השלב הבא:

בקרוב נוסיף עוד סשנים מעשיים.

הסרת המשאבים

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

מחיקת הפרויקט

הדרך הקלה ביותר לבטל את החיוב היא למחוק את הפרויקט שיצרתם בשביל המדריך.