۱. نمای کلی
استقرار برنامه وب برای اولینبار میتواند ترسناک باشد. حتی پساز اولین استقرار، اگر فرایند خیلی دشوار باشد، ممکن است از استقرار نسخههای جدید برنامهتان اجتناب کنید. با استقرار مداوم، میتوانید تغییرات برنامهتان را بهراحتی و بهطور خودکار مستقر کنید.
در این آزمایشگاه، یک برنامه وب مینویسید و Cloud Run را پیکربندی میکنید تا وقتی تغییری در کد منبع برنامهتان ایجاد میشود، برنامه شما را بهطور خودکار مستقر کند. سپس برنامه را اصلاح میکنید و دوباره آن را مستقر میکنید.
آنچه خواهید آموخت
- نوشتن برنامه وب با «ویرایشگر Cloud Shell»
- ذخیره کردن کد برنامه در GitHub
- مستقر کردن خودکار برنامه در Cloud Run
- افزودن هوش مصنوعی زایا به برنامه بااستفاده از Vertex AI
۲. پیشنیازها
- اگر ازقبل حساب Google ندارید، باید حساب Google ایجاد کنید.
- بهجای حساب کاری یا تحصیلی، از حساب شخصی استفاده کنید. حسابهای کاری و تحصیلی ممکن است محدودیتهایی داشته باشند که مانع از فعال کردن میاناهای برنامهسازی کاربردی موردنیاز برای این آزمایشگاه شود.
- اگر ازقبل حساب GitHub ندارید، باید حساب GitHub ایجاد کنید
- اگر حساب GitHub دارید، از حساب موجود استفاده کنید. GitHub احتمالاً حساب جدید را بهعنوان هرزنامه مسدود میکند.
- اصالتسنجی دوعاملی را در حساب GitHub خود پیکربندی کنید تا احتمال علامتگذاری حسابتان بهعنوان هرزنامه کاهش یابد.
۳. راهاندازی پروژه
- به سیستم کنسول Google Cloud وارد شوید.
- صدور صورتحساب را در «کنسول Cloud» فعال کنید.
- تکمیل این آزمایشگاه باید کمتر از ۱ دلار امریکا در منابع Cloud هزینه داشته باشد.
- برای جلوگیری از کسر هزینههای بیشتر، میتوانید مراحل انتهای این آزمایشگاه را برای حذف منابع دنبال کنید.
- کاربران جدید واجدشرایط دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
- آیا در رویداد «هوش مصنوعی زایا برای توسعهدهندگان» شرکت میکنید؟ ممکن است اعتبار ۱ دلاری دردسترس باشد.
- پروژه جدیدی ایجاد کنید یا انتخاب کنید که از پروژه موجودی دوباره استفاده کنید.
- تأیید کنید که صدور صورتحساب در پروژههای من در «صدور صورتحساب Cloud» فعال است
- اگر پروژه جدیدتان در ستون
Billing account،Billing is disabledرا نشان میدهد:- روی سه نقطه در ستون
Actionsکلیک کنید - روی تغییر صورتحساب کلیک کنید
- حساب صورتحسابی را که میخواهید استفاده کنید انتخاب کنید
- روی سه نقطه در ستون
- اگر در رویداد Gen AI for Devs شرکت میکنید، احتمالاً نام حساب Google Cloud Platform Trial Billing Account خواهد بود
- اگر پروژه جدیدتان در ستون
۴. باز کردن «ویرایشگر Cloud Shell»
- به ویرایشگر Cloud Shell بروید
- اگر پایانه در پایین صفحه نشان داده نمیشود، آن را باز کنید:
- روی منوِ همبرگری
کلیک کنید - روی پایانه کلیک کنید.
- روی پایانه جدید
کلیک کنید.
- روی منوِ همبرگری
- در پایانه، پروژه خود را با این فرمان تنظیم کنید:
- قالب:
gcloud config set project [PROJECT_ID] - مثال:
gcloud config set project lab-project-id-example - اگر شناسه پروژهتان را بهخاطر نمیآورید:
- میتوانید همه شناسههای پروژهتان را با این دستور فهرست کنید:
gcloud projects list | awk '/PROJECT_ID/{print $2}'

- میتوانید همه شناسههای پروژهتان را با این دستور فهرست کنید:
- قالب:
- اگر از شما خواسته شد که مجوز دهید، برای ادامه روی مجوز دادن کلیک کنید.

- باید این پیام را ببینید:
اگرUpdated property [core/project].
WARNINGرا میبینید و از شما خواسته میشودDo you want to continue (Y/N)?، احتمالاً شناسه پروژه را اشتباه وارد کردهاید.Nرا فشار دهید،Enterرا فشار دهید، و دوباره فرمانgcloud config set projectرا اجرا کنید.
۵. فعال کردن میاناهای برنامهسازی کاربردی
در پایانه، میاناهای برنامهسازی کاربردی را فعال کنید:
gcloud services enable \
run.googleapis.com \
cloudbuild.googleapis.com \
aiplatform.googleapis.com
ممکن است چند دقیقه طول بکشد تا این فرمان تکمیل شود، اما درنهایت باید پیام موفقیتی مشابه این پیام تولید کند:
Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
۶. پیکربندی Git
- ایمیل کاربر git سراسریتان را تنظیم کنید:
git config --global user.email "you@example.com" - نام کاربری git سراسریتان را تنظیم کنید:
git config --global user.name "Your Name" - شاخه پیشفرض git سراسری را روی
mainتنظیم کنید:git config --global init.defaultBranch main
۷. کدتان را بنویسید
برای نوشتن برنامه در Python:
- به فهرست راهنمای خانه بروید:
cd ~ - فهرست راهنمای
codelab-genaiرا ایجاد کنید:mkdir codelab-genai - به فهرست راهنمای
codelab-genaiبروید:cd codelab-genai - ایجاد فایل
main.py:touch main.py requirements.txtرا با فهرست وابستگیها ایجاد کنید:cat > requirements.txt << EOF Flask==3.0.0 gunicorn==20.1.0 EOF- فایل
main.pyرا در «ویرایشگر Cloud Shell» باز کنید: اکنون باید فایل خالی در بخش بالای صفحه ظاهر شود. در اینجا میتوانید این فایلcloudshell edit main.pymain.pyرا ویرایش کنید.
- کد زیر را کپی کنید و آن را در فایل
main.pyبازشده جایگذاری کنید: پساز چند ثانیه، Cloud Shell Editor کدتان را بهطور خودکار ذخیره میکند. این کد به درخواستهای http با خوشامدگویی «Hello world!» پاسخ میدهد.import os from flask import Flask app = Flask(__name__) @app.route("/") def hello_world(): return f"Hello world!" if __name__ == "__main__": app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
کد اولیه برنامه شما تکمیل شده و آماده ذخیره شدن در کنترل نسخه است.
۸. ایجاد مخزن
- به پایانه Cloud Shell در پایین صفحه برگردید.
- مطمئن شوید که هنوز در دایرکتوری صحیح هستید:
cd ~/codelab-genai - مقداردهی اولیه مخزن git
git init -b main - به سیستم GitHub CLI وارد شوید
gh auth loginEnterرا فشار دهید تا گزینههای پیشفرض را بپذیرید و دستورالعملهای موجود در ابزار GitHub CLI را دنبال کنید، ازجمله:- میخواهید به سیستم کدام حساب وارد شوید؟
GitHub.com - پروتکل ترجیحی شما برای عملیات Git در این میزبان چیست؟
HTTPS - Git با اعتبارنامههای GitHub شما اصالتسنجی شود؟
Y(اگر این مورد نشان داده نشد، از آن رد شوید.) - چگونه میخواهید GitHub CLI را اصالتسنجی کنید؟
Login with a web browser - کد یکبارمصرف را کپی کنید
- https://github.com/login/device را باز کنید
- کد یکبارمصرف را جایگذاری کنید
- روی صدور مجوز GitHub کلیک کنید
- ورود به سیستم را تکمیل کنید
- میخواهید به سیستم کدام حساب وارد شوید؟
- تأیید کنید که به سیستم وارد شدهاید:
اگر با موفقیت به سیستم وارد شده باشید، این دستور باید نام کاربری GitHub شما را برگرداند.gh api user -q ".login" - ایجاد متغیر
GITHUB_USERNAMEGITHUB_USERNAME=$(gh api user -q ".login") - تأیید کنید که متغیر محیط را ایجاد کردهاید:
اگر متغیر را با موفقیت ایجاد کرده باشید، این دستور باید نام کاربری GitHub شما را برگرداند.echo ${GITHUB_USERNAME} - مخزن GitHub خالی با نام
codelab-genaiایجاد کنید: اگر این خطا را دریافت کردید:gh repo create codelab-genai --private سپس ازقبل مخزنی بهنامGraphQL: Name already exists on this account (createRepository)
codelab-genaiدارید. برای ادامه دادن این آموزش دو گزینه دارید:- حذف مخزن GitHub موجود
- مخزنی با نام متفاوت ایجاد کنید و فراموش نکنید که آن را در فرمانهای زیر تغییر دهید.
- مخزن
codelab-genaiرا بهعنوانoriginراه دور اضافه کنید:git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai
۹. همرسانی کد
- مطمئن شوید در دایرکتوری درست هستید:
cd ~/codelab-genai - همه فایلهای موجود در دایرکتوری فعلی را به این ثبت اضافه کنید:
git add . - اولین commit را ایجاد کنید:
git commit -m "add http server" - ثبت خود را به شاخه
mainاز مخزنoriginارسال کنید:git push -u origin main
میتوانید این فرمان را اجرا کنید و به نشانی وب حاصل بروید تا کد برنامهتان را در GitHub ببینید:
echo -e "\n\nTo see your code, visit this URL:\n \
https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/main.py \n\n"
۱۰. راهاندازی استقرار خودکار
- برگه Cloud Shell Editor را باز بگذارید. بعداً به این برگه برمیگردیم.
- در برگه جدید، به صفحه Cloud Run بروید
- «پروژه Google Cloud» صحیح را در کنسول
انتخاب کنید - روی اتصال مخزن کلیک کنید
- روی راهاندازی با CLOUD BUILD کلیک کنید
- GitHub را بهعنوان ارائهدهنده مخزن انتخاب کنید
- اگر در مرورگر به سیستم حساب GitHub خود وارد نشدهاید، با اطلاعات کاربریتان به سیستم وارد شوید.
- روی اصالتسنجی کردن و سپس روی ادامه دادن کلیک کنید.
- پساز ورود به سیستم، پیامی در صفحه Cloud Run خواهید دید که میگوید برنامه GitHub در هیچیک از مخازن شما نصب نشده است.
- روی دکمه نصب GOOGLE CLOUD BUILD کلیک کنید.
- در صفحه «راهاندازی نصب»، فقط مخازن انتخابی را انتخاب کنید و مخزن codelab-genai را که ازطریق CLI ایجاد کردید انتخاب کنید.
- روی نصب کلیک کنید
- توجه: اگر مخازن GitHub زیادی دارید، ممکن است بارگیری آن چند دقیقه طول بکشد.
your-user-name/codelab-genaiرا بهعنوان مخزن انتخاب کنید- اگر مخزن وجود ندارد، روی پیوند مدیریت مخزنهای متصل کلیک کنید.
- شعبه بهعنوان
^main$باقی بماند - روی Go، Node.js، Python، Java، .NET Core، Ruby، یا PHP ازطریق بستههای ساخت Google Cloud کلیک کنید
- فیلدهای دیگر (
Build context directory،Entrypoint، وFunction target) را همانطور که هستند رها کنید.
- فیلدهای دیگر (
- روی ذخیره کلیک کنید.
- GitHub را بهعنوان ارائهدهنده مخزن انتخاب کنید
- به اصالتسنجی پیمایش کنید
- روی مجاز کردن فراخوانیهای تأییدنشده کلیک کنید
- روی ایجاد کردن کلیک کنید
وقتی ساختن کامل شد (که چند دقیقه طول میکشد)، این فرمان را اجرا کنید و برای مشاهده برنامه درحال اجرا، به نشانی وب حاصل بروید:
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"
۱۱. تغییر کد
بازگشت به Cloud Shell Editor
اگر Cloud Shell Editor همچنان باز است، میتوانید از این مراحل رد شوید.
- به ویرایشگر Cloud Shell بروید
- اگر پایانه در پایین صفحه نشان داده نمیشود، آن را باز کنید:
- روی منوِ همبرگری
کلیک کنید - روی پایانه کلیک کنید.
- روی پایانه جدید
کلیک کنید.
- روی منوِ همبرگری
- در پایانه، پروژه خود را با این فرمان تنظیم کنید:
- قالب:
gcloud config set project [PROJECT_ID] - مثال:
gcloud config set project lab-project-id-example - اگر شناسه پروژهتان را بهخاطر نمیآورید:
- میتوانید همه شناسههای پروژهتان را با این دستور فهرست کنید:
gcloud projects list | awk '/PROJECT_ID/{print $2}'

- میتوانید همه شناسههای پروژهتان را با این دستور فهرست کنید:
- قالب:
- اگر از شما خواسته شد که مجوز دهید، برای ادامه روی مجوز دادن کلیک کنید.

- باید این پیام را ببینید:
اگرUpdated property [core/project].
WARNINGرا میبینید و از شما خواسته میشودDo you want to continue (Y/N)?، احتمالاً شناسه پروژه را اشتباه وارد کردهاید.Nرا فشار دهید،Enterرا فشار دهید، و دوباره فرمانgcloud config set projectرا اجرا کنید.
افزودن Vertex AI به برنامه
- به پایانه Cloud Shell در پایین صفحه برگردید.
- مطمئن شوید که هنوز در دایرکتوری صحیح هستید:
cd ~/codelab-genai - وابستگی Vertex AI SDK را به وابستگیهای موجود اضافه کنید:
sed -i -e '$agoogle-cloud-aiplatform==1.59.0' requirements.txt - کتابخانه google auth را به وابستگیهای موجود اضافه کنید:
sed -i -e '$agoogle-auth==2.32.0' requirements.txt - باز کردن مجدد
main.pyدر «ویرایشگر Cloud Shell»cloudshell edit main.py - کد موجود در فایل
main.pyرا با این کد جایگزین کنید:import os from flask import Flask, request import google.auth import vertexai from vertexai.generative_models import GenerativeModel _, project = google.auth.default() app = Flask(__name__) @app.route("/") def hello_world(): vertexai.init(project=project, location="us-central1") model = GenerativeModel("gemini-1.5-flash") animal = request.args.get("animal", "dog") prompt = f"Give me 10 fun facts about {animal}. Return this as html without backticks." response = model.generate_content(prompt) return response.text if __name__ == "__main__": app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
۱۲. استقرار مجدد
- مطمئن شوید که هنوز در دایرکتوری درست در Cloud Shell هستید:
cd ~/codelab-genai - این فرمانها را اجرا کنید تا نسخه جدیدی از برنامهتان را به مخزن git محلیتان ارسال کنید:
git add . git commit -m "add latest changes" - تغییرات را به GitHub روانه کنید:
git push - وقتی ساختن کامل شد، این فرمان را اجرا کنید و به برنامه مستقرشدهتان بروید:
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"
ممکن است چند دقیقه طول بکشد تا ساخت تکمیل شود و بتوانید تغییرات را ببینید.
میتوانید سابقه همه بازبینیها را در اینجا ببینید: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions
۱۳. (اختیاری) ممیزی کردن استفاده از Vertex AI
مانند سایر سرویسهای Google Cloud، میتوانید عملیات Vertex AI را ممیزی کنید. گزارشهای ممیزی به شما کمک میکند به این سؤالات پاسخ دهید: «چه کسی چه کاری را در کجا و چه زمانی انجام داد؟». گزارشهای ممیزی اداری برای Vertex AI بهطور پیشفرض فعال است. برای ممیزی درخواستهای تولید محتوا باید گزارشهای ممیزی «دسترسی به داده» را فعال کنید:
- در کنسول Google Cloud، به صفحه گزارشهای ممیزی بروید:
اگر از نوار جستجو برای پیدا کردن این صفحه استفاده میکنید، نتیجهای را انتخاب کنید که عنوان فرعی آن IAM و سرپرست است. - مطمئن شوید پروژه Google Cloud موجود همان پروژهای است که برنامه Cloud Run را در آن ایجاد میکنید.
- در جدول پیکربندی گزارشهای ممیزی «دسترسی به داده»،
Vertex AI APIرا از ستون «سرویس» انتخاب کنید. - در برگه انواع گزارش، انواع گزارش ممیزی «دسترسی به داده»
Admin readوData readرا انتخاب کنید. - روی ذخیره کلیک کنید.
پساز فعال کردن آن، میتوانید گزارشهای ممیزی را برای هر فراخوانی برنامه ببینید. برای دیدن گزارشهای ممیزی با جزئیات فراخوانی، کارهای زیر را انجام دهید:
- به برنامه مستقرشدهتان برگردید و صفحه را بازآوری کنید تا گزارش راهاندازی شود.
- در کنسول Google Cloud، به صفحه کاوشگر گزارش بروید:
- در پنجره پرسمان، این عبارت را تایپ کنید:
LOG_ID("cloudaudit.googleapis.com%2Fdata_access") protoPayload.serviceName="aiplatform.googleapis.com" - روی اجرای پُرسمان کلیک کنید.
گزارشهای ممیزی استفاده از Vertex AI API را ضبط میکنند اما به شما اجازه نمیدهند دادههای مربوط به حجم کاری مانند پیاموارهها یا جزئیات پاسخ را مشاهده کنید.
۱۴. (اختیاری) افزایش مشاهدهپذیری حجم کاری هوش مصنوعی
گزارشهای ممیزی اطلاعات مربوط به حجم کاری را ضبط نمیکنند. برای افزایش مشاهدهپذیری حجمهای کاریتان، باید این اطلاعات را بهطور صریح ثبت کنید. برای انجام این کار میتوانید از چارچوب ثبت گزارش دلخواهتان استفاده کنید. مراحل زیر نشان میدهد که چگونه این کار را بااستفاده از سازوکار ثبت گزارش Node.js بومی انجام دهید.
- باز کردن مجدد
main.pyدر «ویرایشگر Cloud Shell»cloudshell edit ~/codelab-genai/main.py - بعداز خط
import os(خط ۱)، خطوط زیر را اضافه کنید: این خطوط قالببندی پیشفرض گزارشهای Python را تغییر میدهند تا از قالببندی ساختاریافته JSON پیروی کنند که میتواند در Google Cloud وارد شود.import sys, json, logging class JsonFormatter(logging.Formatter): def format(self, record): json_log_object = { "severity": record.levelname, "message": record.getMessage(), } json_log_object.update(getattr(record, "json_fields", {})) return json.dumps(json_log_object) logger = logging.getLogger(__name__) sh = logging.StreamHandler(sys.stdout) sh.setFormatter(JsonFormatter()) logger.addHandler(sh) logger.setLevel(logging.DEBUG) - بعداز خطی که
model.generate_content(prompt)را فراخوانی میکند (خط ۳۴)، خطوط زیر را اضافه کنید: این کد اطلاعات ساختاریافته درباره تولید محتوا را درjson_fields = {"prompt": prompt, "response": response.to_dict()} logger.debug("Content is generated", extra={"json_fields": json_fields})stdoutچاپ میکند، جایی که توسط عامل ثبت گزارش خوانده میشود و به Cloud Logging منتقل میشود. - Cloud Shell را دوباره باز کنید و فرمان زیر را تایپ کنید تا مطمئن شوید در دایرکتوری درست هستید:
cd ~/codelab-genai - تغییرات را ثبت کنید:
git commit -am "observe generated content" - تغییرات را به GitHub ارسال کنید تا استقرار مجدد نسخه اصلاحشده را راهاندازی کنید:
git push
پساز استقرار نسخه جدید، میتوانید اطلاعات اشکالزدایی مربوط به تماسها با Vertex AI را مشاهده کنید.
برای دیدن گزارشهای برنامهتان، کارهای زیر را انجام دهید:
- در کنسول Google Cloud، به صفحه کاوشگر گزارش بروید:
- در پنجره پرسمان، این عبارت را تایپ کنید:
LOG_ID("run.googleapis.com%2Fstdout") severity=DEBUG - روی اجرای پُرسمان کلیک کنید.
نتیجه پُرسمان گزارشهایی را با پیامواره و پاسخ Vertex AI نشان میدهد، ازجمله «ردهبندیهای ایمنی» که میتوان از آنها برای نظارت بر شیوههای ایمنی استفاده کرد
۱۵. (اختیاری) پاکسازی
درحالیکه Cloud Run وقتی سرویس درحال استفاده نیست هزینهای دریافت نمیکند، ممکن است همچنان برای ذخیره کردن تصویر کانتینر در Artifact Registry هزینه دریافت شود. میتوانید پروژه Cloud خود را حذف کنید تا هزینهای برایتان ایجاد نشود. با حذف پروژه Cloud، صدور صورتحساب برای همه منابع استفادهشده در آن پروژه متوقف میشود.
اگر میخواهید، پروژه را حذف کنید:
gcloud projects delete $GOOGLE_CLOUD_PROJECT
همچنین ممکن است بخواهید منابع غیرضروری را از دیسک cloudshell خود حذف کنید. میتوانید:
- فهرست راهنمای پروژه codelab را حذف کنید:
rm -rf ~/codelab-genai - هشدار! این کنش واگردشدنی نیست! اگر میخواهید همه چیز را در Cloud Shell خود حذف کنید تا فضا آزاد شود، میتوانید کل دایرکتوری اصلی خود را حذف کنید. مطمئن شوید هر چیزی را که میخواهید نگه دارید در جای دیگری ذخیره کردهاید.
sudo rm -rf $HOME
۱۶. تبریک میگوییم
در این آزمایشگاه، یک برنامه وب نوشتید و Cloud Run را پیکربندی کردید تا وقتی تغییری در کد منبع برنامهتان ایجاد شد، برنامه شما را بهطور خودکار مستقر کند. سپس برنامهتان را اصلاح کردید و دوباره آن را مستقر کردید.
اگر از این آزمایشگاه لذت بردید، میتوانید آن را دوباره در چارچوب یا زبان کدنویسی دیگری امتحان کنید: