تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تنفيذ قصص مستخدمي JIRA باستخدام الذكاء الاصطناعي التوليدي

1. نظرة عامة

في هذا الدرس، ستُنشئ حلًا لتشغيل تنفيذ قصص استخدام JIRA آليًا باستخدام الذكاء الاصطناعي التوليدي (GenAI).

ما ستتعرّف عليه

تتضمّن التجارب عدة أجزاء رئيسية:

نشر تطبيق Cloud Run للدمج مع واجهات برمجة تطبيقات Gemini
إنشاء تطبيق Atlassian Forge ونشره في JIRA
LangChain ReAct Agents لأتمتة مهام GitLab

المتطلبات الأساسية

يفترض هذا التمرين أنّك على دراية ببيئة Cloud Console وCloud Shell.

2. الإعداد والمتطلبات

إعداد مشروع على السحابة الإلكترونية

سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها واجهات برمجة تطبيقات Google. ويمكنك تعديلها في أي وقت.
يكون معرّف المشروع فريدًا في جميع مشاريع Google Cloud وغير قابل للتغيير (لا يمكن تغييره بعد ضبطه). تُنشئ وحدة تحكّم Cloud Console سلسلة فريدة تلقائيًا، ولا يهمّك عادةً معرفة محتواها. في معظم مختبرات الرموز البرمجية، ستحتاج إلى الإشارة إلى معرّف المشروع (يُعرَف عادةً باسم PROJECT_ID). إذا لم يعجبك المعرّف الذي تم إنشاؤه، يمكنك إنشاء معرّف آخر عشوائي. يمكنك بدلاً من ذلك تجربة عنوانك الخاص لمعرفة ما إذا كان متاحًا. ولا يمكن تغييره بعد هذه الخطوة ويبقى ساريًا طوال مدة المشروع.
يُرجى العِلم أنّ هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. اطّلِع على مزيد من المعلومات عن كلّ من هذه القيم الثلاث في المستندات.

بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تُكلّفك المشاركة في هذا الدليل التعليمي للترميز الكثير، إن لم يكن أيّ تكلفة على الإطلاق. لإيقاف الموارد لتجنُّب تحصيل رسوم بعد انتهاء هذا الدليل التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يكون مستخدمو Google Cloud الجدد مؤهّلين للاستفادة من برنامج الفترة التجريبية المجانية التي تقدّم رصيدًا بقيمة 300 دولار أمريكي.

إعداد البيئة

افتح محادثة Gemini.

أو اكتب "السؤال من 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، وتشرح لأحد كبار المطوّرين في 5 نقاط رئيسية قصيرة الحالات التي تستدعي استخدام Cloud Run بدلاً من GKE.

اطّلِع على دليل الطلبات لمعرفة مزيد من المعلومات حول كتابة طلبات أفضل.

كيف يستخدم Gemini لـ 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، وهو مصمّم خصيصًا لتبسيط وتسريع تطوير نماذج الذكاء الاصطناعي التوليدي واستخدامها.

Google AI Studio

‫Google AI Studio هي أداة مستندة إلى الويب لإنشاء النماذج الأولية والتجربة باستخدام هندسة الطلبات وواجهة برمجة التطبيقات Gemini API.

تطبيق Gemini للويب (gemini.google.com)

تطبيق Gemini للويب (gemini.google.com) هو أداة مستندة إلى الويب مصمّمة لمساعدتك في استكشاف إمكانات نماذج الذكاء الاصطناعي في Gemini من Google والاستفادة منها.

تطبيق Google Gemini للأجهزة الجوّالة على Android وتطبيق Google على iOS

4. (قسم اختياري) إنشاء حساب خدمة

تم تنفيذ هذه الخطوات أثناء إعداد الميزات الاختبارية، وليس عليك تنفيذها.

تم تضمين هذه الخطوات لعرض كيفية إعداد حساب خدمة وأدوار إدارة الهوية وإمكانية الوصول.

ارجع إلى Google Cloud Console وفعِّل Cloud Shell من خلال النقر على الرمز على يسار شريط البحث.

في الوحدة الطرفية المفتوحة، شغِّل الأوامر التالية لإنشاء حساب خدمة ومفاتيح جديدة.

ستستخدم حساب الخدمة هذا لإجراء طلبات بيانات من واجهة برمجة التطبيقات إلى 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 وGemini Chat.

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

فعِّل الخدمات المطلوبة لاستخدام واجهات برمجة تطبيقات Vertex AI و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 Console.

امنح إذن الوصول إلى 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 هي مجموعات من الأدوات المصمّمة لتبسيط تطوير التطبيقات باستخدام LangChain وتحسينه. وتوفّر هذه الأدوات وظائف مختلفة حسب مجموعة الأدوات المحدّدة، ولكن بشكل عام، تساعد في ما يلي:

الربط بمصادر بيانات خارجية: يمكنك الوصول إلى المعلومات من واجهات برمجة التطبيقات وقواعد البيانات وغيرها من المصادر الخارجية ودمجها في تطبيقات LangChain.
أساليب توجيه الطلبات المتقدّمة: استخدِم طلبات معدّة مسبقًا أو أنشئ طلبات مخصّصة لتحسين التفاعلات مع النماذج اللغوية.
إنشاء السلاسل وإدارتها: يمكنك إنشاء سلاسل معقدة بسهولة وإدارتها بكفاءة.
التقييم والمراقبة: يمكنك تحليل أداء تطبيقات LangChain وسلاسلها.

تشمل بعض حِزم LangChain Toolkits الشائعة ما يلي:

أدوات تنفيذ الوكيل: أدوات لتطوير وكلاء يمكنهم التفاعل مع العالم الواقعي من خلال إجراءات مثل تصفّح الويب أو تنفيذ الرموز البرمجية.
مجموعة أدوات هندسة الطلبات: مجموعة من المراجع لإنشاء طلبات فعّالة

مجموعة أدوات GitLab

في هذا التمرين، ستستخدم مجموعة أدوات GitLab لبرمجة إنشاء طلبات الدمج في GitLab.

تحتوي حزمة أدوات Gitlab على أدوات تتيح لوكيل LLM التفاعل مع مستودع gitlab. الأداة هي حزمة لـ مكتبة python-gitlab.

يمكن لمجموعة أدوات GitLab تنفيذ المهام التالية:

إنشاء ملف: لإنشاء ملف جديد في المستودع
قراءة ملف: لقراءة ملف من المستودع
تعديل الملف: لتعديل ملف في المستودع
إنشاء طلب سحب: لإنشاء طلب سحب من فرع العمل الخاص بالبوت إلى الفرع الأساسي
الحصول على المشاكل: تُستخدَم هذه الوظيفة لجلب المشاكل من المستودع.
الحصول على مشكلة: لعرض تفاصيل عن مشكلة معيّنة.
التعليق على مشكلة: لنشر تعليق بشأن مشكلة معيّنة.
حذف ملف: لحذف ملف من المستودع

8. إعداد مستودع GitLab ومجموعة الأدوات

افتح GitLab، وأنشئ مشروعًا متاحًا للجميع، واضبط رمز الوصول إلى المشروع ضمن "Settings / Access Tokens".

استخدِم التفاصيل التالية:

اسم الرمز المميّز: devai-api-qwiklabs
الدور: Maintainer
اختَر النطاقات: api

انسخ قيمة رمز الوصول والصقها في ملف مؤقت على الكمبيوتر المحمول، وسيتم استخدامها في الخطوات التالية.

9. الاستعداد لنشر التطبيق على Cloud Run

ارجع إلى مثيل "محطات عمل Cloud" واستخدِم وحدة طرفية حالية أو افتح وحدة طرفية جديدة.

الحصول على بيانات اعتماد الوصول إلى حساب المستخدم من خلال عملية تفويض مستندة إلى الويب

انقر على الرابط واتّبِع الخطوات لإنشاء رمز إثبات الملكية.

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

في هذا البرنامج التعليمي، نتّبع أفضل الممارسات ونستخدم مدير الأسرار لتخزين قيم الرمز المميّز للوصول ومفتاح LangChain API والإشارة إليها في Cloud Run.

تخزين رمز JIRA Access Token في 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=-

تخزين مفتاح LangChain API في أداة 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 على جهازك أو إعداد حِزم الإنشاء أو Cloud Build. وهذا يعني أنّ الأمر الوحيد الموضّح أعلاه ينفّذ ما كان سيتطلّب الأمرَين gcloud builds submit وgcloud run deploy.

إذا قدّمت ملف Dockerfile(كما فعلنا في هذا المستودع)، ستستخدمه أداة Cloud Build لإنشاء صور الحاويات بدلاً من الاعتماد على حِزم الإنشاء لرصد صور الحاويات وإنشائها تلقائيًا. لمزيد من المعلومات عن حِزم الإنشاء، اطّلِع على المستندات.

راجِع سجلّات Cloud Build في وحدة التحكّم.

راجِع صورة Docker التي تم إنشاؤها في Artifact Registry.

افتح cloud-run-source-deploy/devai-api وراجِع الثغرات التي تم رصدها تلقائيًا. اطّلِع على المشاكل التي تتوفّر لها حلول، وتعرَّف على كيفية حلّها استنادًا إلى الوصف.

راجِع تفاصيل مثيل Cloud Run في Cloud Console.

اختبِر نقطة النهاية من خلال تنفيذ الأمر 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

توفّر "محطات عمل السحابة الإلكترونية" بيئات تطوير مُدارة على Google Cloud مع أمان مضمّن وبيئات تطوير مُعدّة مسبقًا وقابلة للتخصيص. بدلاً من مطالبة المطوّرين بتثبيت البرامج وتشغيل النصوص البرمجية الخاصة بالإعداد، يمكنك إنشاء إعدادات محطة عمل تحدّد بيئتك بطريقة يمكن تكرارها. يتم تطبيق أي تعديلات على إعدادات محطة عمل تلقائيًا على محطات العمل في المرة التالية التي يتم فيها تشغيلها. يمكن للمطوّرين الوصول إلى محطات العمل من خلال بيئة تطوير متكاملة مستندة إلى المتصفّح، أو من خلال عدة محرّرات رموز برمجية محلية (مثل VSCode أو أدوات JetBrains IDE مثل IntelliJ IDEA Ultimate وPyCharm Professional)، أو من خلال بروتوكول SSH.

تستخدم "محطات عمل السحابة الإلكترونية" موارد Google Cloud التالية لإدارة بيئات التطوير:

تحدِّد مجموعات محطات العمل مجموعة من محطات العمل في منطقة معيّنة وشبكة VPC التي تكون مرتبطة بها. لا ترتبط مجموعات محطات العمل بمجموعات Google Kubernetes Engine (GKE).
تعمل إعدادات محطات العمل كنماذج لمحطاتها. تحدِّد إعدادات محطة العمل تفاصيل مثل نوع مثيل الجهاز الافتراضي لمحطة العمل ومساحة التخزين الثابتة وبيئة تحديد صورة الحاوية وبيئة IDE أو "محرر الرموز البرمجية" المُستخدَمة وغير ذلك. يمكن للمشرفين وفرق المنصة أيضًا استخدام قواعد إدارة الهوية وإمكانية الوصول (IAM) لمنح إذن الوصول إلى الفِرق أو إلى مطوّرين فرديين.
محطات العمل هي بيئات تطوير تم إعدادها مسبقًا وتوفّر بيئة تطوير متكاملة (IDE) على السحابة الإلكترونية وأدوات لغوية ومكتبات وغير ذلك. يمكن بدء محطات العمل أو إيقافها عند الطلب، وتشغيلها على الأجهزة الافتراضية في Compute Engine في مشروعك، مع إرفاق قرص دائم لتخزين البيانات بين الجلسات.

ينشئ المشرفون وفرق المنصات إعدادات محطات العمل التي يشاركونها مع فريق التطوير. ينشئ كل مطوّر محطة عمل استنادًا إلى إعدادات محطة العمل.

في هذا الدرس التطبيقي، ستستخدم بيئة تطوير متكاملة مستندة إلى المتصفّح، ولكن تتيح لك محطات عمل السحابة الإلكترونية أيضًا استخدام واجهات تطوير شائعة أخرى:

يمكنك استخدام محرّرات بيئة تطوير البرامج (IDE) المحلية من JetBrains من خلال JetBrains Gateway.
إذا كنت تستخدم VSCode على الجهاز، يمكنك أيضًا الوصول إلى محطات العمل لتطوير التطبيقات عن بُعد من خلال بروتوكول النقل الآمن (SSH).
يمكنك أيضًا إعداد نفق SSH وحتى نفق TCP إلى محطة العمل من جهازك.

(قسم اختياري) إنشاء مجموعة محطات عمل

تم تنفيذ هذه الخطوات أثناء إعداد الميزات الاختبارية، وليس عليك تنفيذها.

تم تضمين هذه الخطوات لعرض كيفية إعداد "مجموعة محطات عمل السحابة الإلكترونية" و"الإعداد" و"محطة العمل".

راجِع هذا القسم وانتقِل إلى قسم "منصّة Forge".

إنشاء مجموعة "محطات عمل Google":

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

إنشاء إعدادات "محطات العمل"

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 Console. ابدأ تشغيل "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.

اختَر أحدث إصدار من Node.js LTS من خلال تنفيذ ما يلي في الوحدة الطرفية:

nvm install --lts
nvm use --lts

ثبِّت Forge CLI على مستوى النظام من خلال تنفيذ:

npm install -g @forge/cli

في هذا الدرس التطبيقي، سنستخدم متغيّرات البيئة لتسجيل الدخول.

إعداد مشروع JIRA

استخدام حسابك الشخصي لإنشاء مشاريع JIRA أو عرضها

راجِع مشاريع JIRA الحالية: https://admin.atlassian.com/

أنشئ مشروع JIRA جديدًا باستخدام حسابك الشخصي.

انتقِل إلى https://team.atlassian.com/your-work وانقر على ، ثم اختَر . بعد ذلك، اختَر "JIRA Software" (برنامج JIRA) - "Try it now" (تجربته الآن). اتّبِع التعليمات لإكمال عملية إنشاء المشروع أو الموقع الإلكتروني.

اختَر JIRA Software.

أنشئ مشروعًا جديدًا.

14. الرمز المميّز لواجهة برمجة تطبيقات Atlassian

أنشئ رمزًا مميزًا حاليًا لواجهة برمجة التطبيقات Atlassian API أو استخدِمه لتسجيل الدخول إلى واجهة سطر الأوامر.

تستخدِم واجهة سطر الأوامر الرمز المميّز عند تنفيذ الأوامر.

انتقِل إلى https://id.atlassian.com/manage/api-tokens.
انقر على إنشاء رمز مميّز لواجهة برمجة التطبيقات.
أدخِل تصنيفًا لوصف الرمز المميّز لواجهة برمجة التطبيقات. على سبيل المثال، forge-api-token.
انقر على إنشاء.
انقر على النسخ إلى الحافظة وأغلق مربّع الحوار.

نفِّذ الأمر أدناه في وحدة طرفية "محطات عمل السحابة الإلكترونية".

سجِّل الدخول إلى وحدة تحكّم سطر الأوامر في Forge لبدء استخدام أوامر Forge.

اضبط عنوان بريدك الإلكتروني على JIRA/FORGE. استبدِل هذا العنوان بعنوان بريدك الإلكتروني.

export FORGE_EMAIL=your-email

اضبط الرمز المميّز لواجهة برمجة التطبيقات في Forge. استبدِل الرمز المميّز لواجهة برمجة تطبيقات JIRA.

export FORGE_API_TOKEN=your-jira-api-token

اختبِر أداة Forge CLI من خلال تنفيذ الأمر أدناه. أدخِل "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" لتوضيحه.

راجِع التفسير.

افتح الملفات التالية واطلب من Gemini Code Assist شرحها:

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

تعديل تطبيق Forge باستخدام نقطة نهاية DevAI API Cloud Run

تحقَّق مما إذا تم ضبط رقم تعريف مشروع Google Cloud Platform:

gcloud config get project

إذا لم يكن الأمر كذلك، يمكنك إعداد مشروعك على Google Cloud Platform باستخدام معرّف المشروع من صفحة مختبر 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;
});

افتح ملف الواجهة الأمامية/الفهرس في المحرِّر: 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.

تطبيق Test 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، ضمن قسم "طلب الدمج" وLangSmith.

تفاصيل طلب الدمج في GitLab

عمليات تتبُّع نموذج LangSmith اللغوي الكبير

افتح بوابة LangSmith وراجِع تتبُّع LLM لمكالمة إنشاء مشكلة JIRA.

مثال على تتبُّع النموذج اللغوي الكبير 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. تهانينا!

تهانينا، لقد أكملت الدرس التطبيقي.

في ما يلي المواضيع التي تناولناها:

كيفية نشر تطبيقات Cloud Run للدمج مع واجهات برمجة تطبيقات Gemini
كيفية إنشاء تطبيق Atlassian Forge ونشره في JIRA
كيفية استخدام LangChain ReAct Agents لأتمتة مهام GitLab
كيفية مراجعة عمليات تتبُّع النماذج اللغوية الكبيرة في LangSmith

الخطوة التالية:

سنقدّم المزيد من الجلسات التدريبية قريبًا.

تَنظيم

لتجنُّب تحصيل رسوم من حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا الدليل التعليمي، يمكنك إما حذف المشروع الذي يحتوي على الموارد أو الاحتفاظ بالمشروع وحذف الموارد الفردية.

حذف المشروع

إنّ أسهل طريقة لإيقاف الفوترة هي حذف المشروع الذي أنشأته للدليل التعليمي.