۱. مرور کلی
استقرار یک برنامه وب برای اولین بار میتواند دلهرهآور باشد. حتی پس از اولین استقرار، اگر این فرآیند کار زیادی داشته باشد، ممکن است از استقرار نسخههای جدید برنامه خود خودداری کنید. با استقرار مداوم، میتوانید تغییرات برنامه خود را به راحتی و به طور خودکار اعمال کنید.
در این آزمایش، شما یک برنامه وب مینویسید و Cloud Run را طوری پیکربندی میکنید که وقتی تغییری در کد منبع برنامه شما ایجاد میشود، به طور خودکار برنامه شما را مستقر کند. سپس برنامه خود را تغییر داده و دوباره آن را مستقر میکنید.
آنچه یاد خواهید گرفت
- با ویرایشگر Cloud Shell یک برنامه وب بنویسید
- کد برنامه خود را در GitHub ذخیره کنید
- برنامه خود را به صورت خودکار در Cloud Run مستقر کنید
- با استفاده از Vertex AI، هوش مصنوعی مولد را به برنامه خود اضافه کنید
۲. پیشنیازها
- اگر از قبل حساب گوگل ندارید، باید یک حساب گوگل ایجاد کنید .
- به جای حساب کاری یا تحصیلی از یک حساب شخصی استفاده کنید. حسابهای کاری و تحصیلی ممکن است محدودیتهایی داشته باشند که مانع از فعال کردن APIهای مورد نیاز برای این آزمایشگاه توسط شما شود.
- اگر هنوز حساب کاربری گیتهاب ندارید، باید یک حساب کاربری گیتهاب ایجاد کنید.
- اگر حساب گیتهاب دارید، از آن استفاده کنید. گیتهاب احتمالاً حسابهای کاربری جدید را به عنوان اسپم مسدود میکند.
- احراز هویت دو مرحلهای را در حساب GitHub خود پیکربندی کنید تا احتمال علامتگذاری حسابتان به عنوان هرزنامه کاهش یابد.
۳. راهاندازی پروژه
- وارد کنسول ابری گوگل شوید.
- فعال کردن پرداخت در کنسول ابری
- تکمیل این آزمایشگاه باید کمتر از ۱ دلار آمریکا از طریق منابع ابری هزینه داشته باشد.
- شما میتوانید مراحل انتهای این آزمایش را برای حذف منابع دنبال کنید تا از هزینههای بیشتر جلوگیری شود.
- کاربران جدید واجد شرایط استفاده از دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
- در رویداد Gen AI for Devs شرکت میکنید؟ ممکن است یک اعتبار ۱ دلاری در دسترس باشد.
- یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید.
- تأیید کنید که پرداخت در پروژههای من در پرداخت ابری فعال شده است
- اگر در ستون
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اجرا کنید.
۵. فعال کردن APIها
در ترمینال، APIها را فعال کنید:
gcloud services enable \
run.googleapis.com \
cloudbuild.googleapis.com \
aiplatform.googleapis.com
تکمیل این دستور ممکن است چند دقیقه طول بکشد، اما در نهایت باید پیامی مشابه این پیام موفقیتآمیز نمایش داده شود:
Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
۶. پیکربندی گیت
- ایمیل کاربر سراسری گیت خود را تنظیم کنید:
git config --global user.email "you@example.com" - نام کاربری سراسری گیت خود را تنظیم کنید:
git config --global user.name "Your Name" - شاخه پیشفرض سراسری گیت خود را روی
mainتنظیم کنید:git config --global init.defaultBranch main
۷. کد خود را بنویسید
برای نوشتن یک برنامه در Go:
- به دایرکتوری خانه بروید:
cd ~ - دایرکتوری
codelab-genaiرا ایجاد کنید:mkdir codelab-genai - به پوشه
codelab-genaiبروید:cd codelab-genai - برای تعریف ماژول، یک فایل go.mod راهاندازی کنید:
go mod init codelab-genai - یک فایل
main.goایجاد کنید:touch main.go - فایل
main.goرا در ویرایشگر Cloud Shell باز کنید: اکنون باید یک فایل خالی در قسمت بالای صفحه نمایش داده شود. اینجاست که میتوانید فایلcloudshell edit main.gomain.goرا ویرایش کنید.
-
main.goویرایش کنید و کد زیر را در آن قرار دهید: بعد از چند ثانیه، ویرایشگر پوسته ابری (Cloud Shell Editor) کد شما را به طور خودکار ذخیره میکند. این کد به درخواستهای http با خوشامدگویی «سلام دنیا!» ما پاسخ میدهد.package main import ( "fmt" "log" "net/http" "os" ) func main() { http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { fmt.Fprintln(w, "Hello, world!") }) port := os.Getenv("PORT") if port == "" { port = "8080" } if err := http.ListenAndServe(":"+port, nil); err != nil { log.Fatal(err) } }
کد اولیه شما برای برنامهتان تکمیل شده و آماده ذخیره در کنترل نسخه است.
۸. ایجاد یک مخزن
- به ترمینال Cloud Shell در پایین صفحه خود برگردید.
- مطمئن شوید که هنوز در دایرکتوری صحیح هستید:
cd ~/codelab-genai - مخزن گیت خود را مقداردهی اولیه کنید
git init -b main - وارد رابط خط فرمان گیتهاب (GitHub CLI) شوید
برای پذیرش گزینههای پیشفرض،gh auth loginEnterفشار دهید و دستورالعملهای ابزار GitHub CLI را دنبال کنید، از جمله:- با چه حسابی میخواهید وارد شوید؟
GitHub.com - پروتکل ترجیحی شما برای عملیات گیت روی این میزبان چیست؟
HTTPS - آیا گیت را با اطلاعات کاربری گیتهاب خود تأیید میکنید؟
Y(اگر این مورد نمایش داده نمیشود، از آن صرف نظر کنید.) - چگونه میخواهید GitHub CLI را احراز هویت کنید؟
Login with a web browser - کد یکبار مصرف خود را کپی کنید
- https://github.com/login/device را باز کنید.
- کد یکبار مصرف خود را وارد کنید
- روی تأیید گیتهاب کلیک کنید
- ورود خود را تکمیل کنید
- با چه حسابی میخواهید وارد شوید؟
- تأیید کنید که وارد سیستم شدهاید:
اگر با موفقیت وارد سیستم شده باشید، باید نام کاربری GitHub شما نمایش داده شود.gh api user -q ".login" - یک متغیر
GITHUB_USERNAMEایجاد کنیدGITHUB_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را به عنوان remoteoriginاضافه کنید:git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai
۹. کد خود را به اشتراک بگذارید
- تأیید کنید که در دایرکتوری صحیح هستید:
cd ~/codelab-genai - تمام فایلهای موجود در دایرکتوری فعلی را به این کامیت اضافه کنید:
git add . - اولین کامیت را ایجاد کنید:
git commit -m "add http server" - کامیت خود را به شاخه
mainمخزنoriginارسال کنید:git push -u origin main
میتوانید این دستور را اجرا کنید و برای مشاهده کد برنامه خود در GitHub، به URL حاصل مراجعه کنید:
echo -e "\n\nTo see your code, visit this URL:\n \
https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/main.go \n\n"
۱۰. راهاندازی استقرار خودکار
- برگه ویرایشگر پوسته ابری را باز بگذارید. بعداً به این برگه باز خواهیم گشت.
- در یک برگه جدید، از صفحه Cloud Run دیدن کنید
- پروژه صحیح Google Cloud را در کنسول انتخاب کنید

- روی اتصال مخزن کلیک کنید
- روی راهاندازی با فضای ابری کلیک کنید
- گیتهاب را به عنوان ارائهدهنده مخزن انتخاب کنید
- اگر در مرورگر وارد حساب GitHub خود نشدهاید، با اطلاعات کاربری خود وارد شوید.
- روی تأیید اعتبار کلیک کنید و سپس روی ادامه کلیک کنید.
- پس از ورود، در صفحه Cloud Run پیامی با این مضمون مشاهده خواهید کرد: «برنامه گیتهاب روی هیچ یک از مخازن شما نصب نشده است».
- روی دکمهی نصب گوگل کلود بیلد (INSTALL GOOGLE CLOUD BUILD) کلیک کنید.
- در صفحه تنظیمات نصب، گزینه Only select repositories را انتخاب کنید و مخزن codelab-genai را که از طریق CLI ایجاد کردهاید، انتخاب کنید.
- روی نصب کلیک کنید
- توجه: اگر مخازن گیتهاب زیادی دارید، بارگیری این مرحله ممکن است چند دقیقه طول بکشد.
-
your-user-name/codelab-genaiبه عنوان مخزن انتخاب کنید.- اگر مخزن موجود نیست، روی پیوند مدیریت مخازن متصل کلیک کنید.
- شاخه را به عنوان
^main$رها کنید - از طریق بستههای ساخت گوگل کلود، روی Go، Node.js، Python، Java، .NET Core، Ruby یا PHP کلیک کنید.
- فیلدهای دیگر (
Build context directory،EntrypointوFunction target) را به همان صورت که هستند، رها کنید.
- فیلدهای دیگر (
- روی ذخیره کلیک کنید
- گیتهاب را به عنوان ارائهدهنده مخزن انتخاب کنید
- به پایین بروید تا به بخش احراز هویت برسید
- روی «مجاز کردن فراخوانیهای احراز هویت نشده» کلیک کنید
- روی ایجاد کلیک کنید
پس از اتمام ساخت (که چند دقیقه طول میکشد)، این دستور را اجرا کنید و برای مشاهده برنامه در حال اجرا، به 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"
۱۱. کد خود را تغییر دهید
- به ترمینال Cloud Shell در پایین صفحه خود برگردید.
- مطمئن شوید که هنوز در دایرکتوری صحیح هستید:
cd ~/codelab-genai -
main.goدر ویرایشگر Cloud Shell دوباره باز کنید.cloudshell edit main.go - نصب Vertex AI SDK برای Go:
go get cloud.google.com/go/vertexai/genai - برای دریافت شناسه پروژه فعلی، کتابخانه Metadata را برای Go نصب کنید:
go get cloud.google.com/go/compute/metadata - کد را در فایل
main.goخود با کد زیر جایگزین کنید:package main import ( "context" "fmt" "log" "net/http" "os" "cloud.google.com/go/compute/metadata" "cloud.google.com/go/vertexai/genai" ) func main() { ctx := context.Background() var projectId string var err error projectId = os.Getenv("GOOGLE_CLOUD_PROJECT") if projectId == "" { projectId, err = metadata.ProjectIDWithContext(ctx) if err != nil { return } } var client *genai.Client client, err = genai.NewClient(ctx, projectId, "us-central1") if err != nil { return } defer client.Close() model := client.GenerativeModel("gemini-1.5-flash-001") http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { animal := r.URL.Query().Get("animal") if animal == "" { animal = "dog" } resp, err := model.GenerateContent( ctx, genai.Text( fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal)), ) if err != nil { w.WriteHeader(http.StatusServiceUnavailable) return } if len(resp.Candidates) > 0 && len(resp.Candidates[0].Content.Parts) > 0 { htmlContent := resp.Candidates[0].Content.Parts[0] w.Header().Set("Content-Type", "text/html; charset=utf-8") fmt.Fprint(w, htmlContent) } }) port := os.Getenv("PORT") if port == "" { port = "8080" } if err := http.ListenAndServe(":"+port, nil); err != nil { log.Fatal(err) } }
۱۲. استقرار مجدد
- مطمئن شوید که هنوز در پوشهی صحیح در Cloud Shell هستید:
cd ~/codelab-genai - این دستورات را اجرا کنید تا نسخه جدیدی از برنامه خود را در مخزن محلی git خود قرار دهید:
git add . git commit -m "add latest changes" - تغییرات را به گیتهاب ارسال کنید:
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 خود را بررسی کنید
مانند سایر سرویسهای Google Cloud، میتوانید عملیات Vertex AI را حسابرسی کنید . گزارشهای حسابرسی به شما کمک میکنند تا به سؤالات «چه کسی، چه کاری را، کجا و چه زمانی انجام داده است؟» پاسخ دهید. گزارشهای حسابرسی اداری برای Vertex AI به طور پیشفرض فعال هستند. برای حسابرسی درخواستهای تولید محتوا، باید گزارشهای حسابرسی دسترسی به دادهها را فعال کنید :
- در کنسول گوگل کلود، به صفحه گزارشهای حسابرسی (Audit Logs ) بروید:
اگر از نوار جستجو برای یافتن این صفحه استفاده میکنید، نتیجهای را انتخاب کنید که زیرعنوان آن IAM & Admin باشد. - مطمئن شوید که پروژه Google Cloud موجود، همان پروژهای است که برنامه Cloud Run خود را در آن ایجاد میکنید.
- در جدول پیکربندی گزارشهای حسابرسی دسترسی به دادهها ، از ستون سرویس، گزینهی Select
Vertex AI APIپیدا کنید. - در برگه «انواع گزارش» ، انواع گزارش حسابرسی دسترسی به دادهها، یعنی
Admin readوData readرا انتخاب کنید. - روی ذخیره کلیک کنید.
پس از فعال کردن آن، میتوانید گزارشهای حسابرسی را برای هر فراخوانی برنامه مشاهده کنید. برای مشاهده گزارشهای حسابرسی به همراه جزئیات فراخوانی، مراحل زیر را انجام دهید:
- به برنامهی مستقر شدهی خود برگردید و صفحه را رفرش کنید تا گزارش اجرا شود.
- در کنسول گوگل کلود، به صفحه Log Explorer بروید:
- در پنجره پرس و جو تایپ کنید:
LOG_ID("cloudaudit.googleapis.com%2Fdata_access") protoPayload.serviceName="aiplatform.googleapis.com" - روی اجرای پرسوجو کلیک کنید.
گزارشهای حسابرسی، استفاده از API هوش مصنوعی Vertex را ثبت میکنند، اما به شما اجازه نمیدهند دادههای مرتبط با حجم کار مانند اعلانها یا جزئیات پاسخ را مشاهده کنید.
۱۴. (اختیاری) افزایش قابلیت مشاهده حجم کار هوش مصنوعی شما
لاگهای حسابرسی اطلاعات مربوط به حجم کار را ثبت نمیکنند. برای افزایش قابلیت مشاهده حجم کار خود، باید این اطلاعات را به طور صریح ثبت کنید. میتوانید از چارچوب ثبت لاگ مورد علاقه خود برای انجام این کار استفاده کنید. مراحل زیر یک راه برای انجام این کار با استفاده از کتابخانه ثبت لاگ ساختاریافته Go را نشان میدهد.
-
main.goدر ویرایشگر Cloud Shell دوباره باز کنید.cloudshell edit ~/codelab-genai/main.go - بلوک import خود را تغییر دهید تا شامل گزارشگیری ساختاریافته Go و کتابخانههای JSON باشد:
import ( "context" "encoding/json" "fmt" "log" "log/slog" "net/http" "os" "cloud.google.com/go/compute/metadata" "cloud.google.com/go/vertexai/genai" ) - پس از مقداردهی اولیه کلاینت Vertex (خط ۳۳)، خطوط زیر را برای مقداردهی اولیه یک logger ساختاریافته که از فیلدهای مناسب برای Google Cloud Logging استفاده میکند، اضافه کنید:
opts := &slog.HandlerOptions{ Level: slog.LevelDebug, ReplaceAttr: func(group []string, a slog.Attr) slog.Attr { if a.Key == slog.LevelKey { return slog.Attr{Key: "severity", Value: a.Value} } if a.Key == slog.MessageKey { return slog.Attr{Key: "message", Value: a.Value} } return slog.Attr{Key: a.Key, Value: a.Value} }, } jsonHandler := slog.NewJSONHandler(os.Stdout, opts) slog.SetDefault(slog.New(jsonHandler)) - پس از بررسی پاسخ به
GenerateContent(خط ۶۹)، خطوط زیر را درون بلوک if اضافه کنید: این کد با استفاده از فرمت گزارشگیری ساختاریافته، اطلاعات مربوط به محتوای تولید شده را در خروجی استانداردjsonBytes, err := json.Marshal(resp) if err != nil { slog.Error("Failed to marshal response to JSON", "error", err) } else { jsonString := string(jsonBytes) slog.Debug("Complete response content", "json_response", jsonString) }stdoutمینویسد. یک عامل گزارشگیری در Cloud Run، خروجی چاپ شده درstdoutرا ضبط کرده و این فرمت را در گزارشگیری ابری (Cloud Logging) مینویسد . - Cloud Shell را دوباره باز کنید و دستور زیر را تایپ کنید تا مطمئن شوید که در دایرکتوری صحیح هستید:
cd ~/codelab-genai - تغییرات را اعمال کنید:
git commit -am "Observe generated content" - تغییرات را به GitHub ارسال کنید تا نسخه اصلاحشده مجدداً منتشر شود:
git push
پس از استقرار نسخه جدید، میتوانید اطلاعات اشکالزدایی مربوط به فراخوانیهای Vertex AI را مشاهده کنید.
برای مشاهده لاگهای برنامه خود، مراحل زیر را انجام دهید:
- در کنسول گوگل کلود، به صفحه Log Explorer بروید:
- در پنجره پرس و جو تایپ کنید:
LOG_ID("run.googleapis.com%2Fstdout") severity=DEBUG - روی اجرای پرسوجو کلیک کنید.
نتیجهی پرسوجو، گزارشهایی با پاسخ سریع و هوش مصنوعی Vertex شامل «رتبهبندیهای ایمنی» را نشان میدهد که میتوانند برای نظارت بر شیوههای ایمنی مورد استفاده قرار گیرند.
۱۵. (اختیاری) تمیز کردن
اگرچه Cloud Run در صورت عدم استفاده از سرویس، هزینهای دریافت نمیکند، اما ممکن است همچنان برای ذخیره تصویر کانتینر در Artifact Registry هزینه دریافت شود. میتوانید پروژه Cloud خود را حذف کنید تا از پرداخت هزینهها جلوگیری کنید. حذف پروژه Cloud، پرداخت هزینه برای تمام منابع استفاده شده در آن پروژه را متوقف میکند.
اگر مایلید، پروژه را حذف کنید:
gcloud projects delete $GOOGLE_CLOUD_PROJECT
همچنین ممکن است بخواهید منابع غیرضروری را از دیسک cloudshell خود حذف کنید. میتوانید:
- پوشه پروژه codelab را حذف کنید:
rm -rf ~/codelab-genai - هر بسته go که ممکن است دیگر به آن نیاز نداشته باشید را پاک کنید:
cd ~ go clean -modcache - هشدار! این اقدام قابل بازگشت نیست! اگر میخواهید همه چیز را در Cloud Shell خود حذف کنید تا فضا آزاد شود، میتوانید کل دایرکتوری خانگی خود را حذف کنید . مراقب باشید که هر چیزی که میخواهید نگه دارید در جای دیگری ذخیره شده باشد.
sudo rm -rf $HOME
۱۶. تبریک
در این آزمایش، شما یک برنامه وب نوشتید و Cloud Run را طوری پیکربندی کردید که وقتی تغییری در کد منبع برنامه شما ایجاد میشود، به طور خودکار برنامه شما را مستقر کند. سپس برنامه خود را اصلاح کردید و دوباره آن را مستقر کردید.
اگر از این آزمایش لذت بردید، میتوانید دوباره آن را با زبان یا چارچوب کدنویسی دیگری امتحان کنید:
اگر علاقهمند به شرکت در یک مطالعه تحقیقاتی تجربه کاربری (UX) برای بهبود محصولاتی که امروز با آنها کار کردهاید هستید، اینجا ثبت نام کنید .
در اینجا چند گزینه برای ادامه تحصیل شما وجود دارد:
- مستندات: از Genkit به عنوان یک انتزاع مدل انعطافپذیر استفاده کنید که ادغام هر API مدل و استفاده از مدلهای نگهداریشده توسط جامعه را آسان میکند.
- Codelab: نحوه استقرار برنامه چت مبتنی بر Gemini در Cloud Run
- نحوه استفاده از فراخوانی تابع Gemini با Cloud Run
- کارگاه آموزشی بر اساس تقاضا: موتور کوبرنتیز گوگل (Google Kubernetes Engine) به صورت آنبورد
- نحوه استفاده از API هوش ویدیویی Cloud Run Jobs برای پردازش صحنه به صحنه یک ویدیو