1. بررسی اجمالی
برنامههای هوش مصنوعی ژنرال مانند سایر برنامهها به قابلیت مشاهده نیاز دارند. آیا تکنیک های مشاهده پذیری خاصی برای هوش مصنوعی مولد نیاز است؟
در این آزمایشگاه، یک اپلیکیشن ساده Gen AI ایجاد خواهید کرد. آن را در Cloud Run مستقر کنید. و با استفاده از سرویسها و محصولات مشاهدهپذیری Google Cloud، آن را با قابلیتهای نظارت و گزارشگیری ضروری تنظیم کنید.
آنچه خواهید آموخت
- برنامه ای بنویسید که از Vertex AI با Cloud Shell Editor استفاده کند
- کد برنامه خود را در GitHub ذخیره کنید
- از gcloud CLI برای استقرار کد منبع برنامه خود در Cloud Run استفاده کنید
- قابلیت های نظارت و گزارش را به برنامه Gen AI خود اضافه کنید
- استفاده از متریک های مبتنی بر گزارش
- پیاده سازی گزارش و نظارت با Open Telemetry SDK
- بینشی در مورد مدیریت مسئول داده های هوش مصنوعی به دست آورید
2. پیش نیازها
اگر قبلاً یک حساب Google ندارید، باید یک حساب جدید ایجاد کنید .
3. راه اندازی پروژه
- با حساب Google خود وارد Google Cloud Console شوید.
- یک پروژه جدید ایجاد کنید یا استفاده مجدد از یک پروژه موجود را انتخاب کنید. شناسه پروژه پروژه ای که به تازگی ایجاد یا انتخاب کرده اید را یادداشت کنید.
- فعال کردن صورتحساب برای پروژه
- تکمیل این آزمایشگاه باید کمتر از 5 دلار هزینه صورت حساب داشته باشد.
- برای جلوگیری از هزینه های بیشتر، می توانید مراحل انتهای این آزمایشگاه را برای حذف منابع دنبال کنید.
- کاربران جدید واجد شرایط استفاده از نسخه آزمایشی رایگان 300 دلاری هستند.
- تأیید اینکه صورتحساب در پروژههای من در صورتحساب ابری فعال است
- اگر پروژه جدید شما می گوید که صورتحساب در ستون
Billing account
Billing is disabled
:- روی سه نقطه در ستون
Actions
کلیک کنید - روی تغییر صورتحساب کلیک کنید
- حساب صورتحساب مورد نظر برای استفاده را انتخاب کنید
- روی سه نقطه در ستون
- اگر در یک رویداد زنده شرکت میکنید، احتمالاً این حساب Google Cloud Platform Trial Billing Account نامیده میشود
- اگر پروژه جدید شما می گوید که صورتحساب در ستون
4. Cloud Shell Editor را آماده کنید
- به Cloud Shell Editor بروید. اگر پیام زیر از شما خواسته شد که درخواست اجازه دادن به پوسته ابری برای تماس با gcloud با اعتبار شما را دارد، برای ادامه روی تأیید کلیک کنید.
- پنجره ترمینال را باز کنید
- روی منوی همبرگر کلیک کنید
- روی ترمینال کلیک کنید
- روی New Terminal کلیک کنید
- روی منوی همبرگر کلیک کنید
- در ترمینال، شناسه پروژه خود را پیکربندی کنید:
gcloud config set project [PROJECT_ID]
[PROJECT_ID]
را با شناسه پروژه خود جایگزین کنید. به عنوان مثال، اگر ID پروژه شماlab-example-project
باشد، دستور به صورت زیر خواهد بود: اگر پیام زیر از شما خواسته شد که می گوید gcloud اعتبار شما را به GCPI API درخواست می کند، برای ادامه روی تأیید کلیک کنید.gcloud config set project lab-project-id-example
در اجرای موفقیت آمیز باید پیام زیر را مشاهده کنید: اگر یکUpdated property [core/project].
WARNING
مشاهده کردید و از شما پرسیده شدDo you want to continue (Y/N)?
، پس احتمالاً شناسه پروژه را اشتباه وارد کرده اید.N
را فشار دهید،Enter
فشار دهید و پس از یافتن شناسه پروژه صحیح، دوباره دستورgcloud config set project
را اجرا کنید. - (اختیاری) اگر برای پیدا کردن شناسه پروژه با مشکل مواجه هستید، دستور زیر را اجرا کنید تا شناسه پروژه همه پروژههای خود را بر اساس زمان ایجاد به ترتیب نزولی مرتب کنید:
gcloud projects list \ --format='value(projectId,createTime)' \ --sort-by=~createTime
5. Google API ها را فعال کنید
در ترمینال، API های Google را که برای این آزمایشگاه مورد نیاز است فعال کنید:
gcloud services enable \
run.googleapis.com \
cloudbuild.googleapis.com \
aiplatform.googleapis.com \
logging.googleapis.com \
monitoring.googleapis.com \
cloudtrace.googleapis.com
تکمیل این دستور کمی طول می کشد. در نهایت، پیام موفقیت آمیزی مشابه این را تولید می کند:
Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
اگر پیام خطایی دریافت کردید که با ERROR: (gcloud.services.enable) HttpError accessing
جزئیات خطا و حاوی جزئیات خطا مانند زیر است، پس از 1 تا 2 دقیقه تاخیر دوباره دستور را امتحان کنید.
"error": { "code": 429, "message": "Quota exceeded for quota metric 'Mutate requests' and limit 'Mutate requests per minute' of service 'serviceusage.googleapis.com' ...", "status": "RESOURCE_EXHAUSTED", ... }
6. یک برنامه Gen AI Go ایجاد کنید
در این مرحله شما یک کد از برنامه ساده مبتنی بر درخواست را می نویسید که از مدل Gemini برای نشان دادن 10 واقعیت سرگرم کننده در مورد حیوان مورد نظر شما استفاده می کند. برای ایجاد کد برنامه مراحل زیر را انجام دهید.
- در ترمینال، دایرکتوری
codelab-o11y
را ایجاد کنید:mkdir ~/codelab-o11y
- دایرکتوری فعلی را به
codelab-o11y
تغییر دهید:cd ~/codelab-o11y
- ماژول های Go را راه اندازی کنید:
go mod init codelab
- Vertex AI SDK for Go را نصب کنید:
go get cloud.google.com/go/vertexai/genai
- برای دریافت شناسه پروژه فعلی، کتابخانه فراداده را برای Go نصب کنید:
go get cloud.google.com/go/compute/metadata
- یک فایل
setup.go
ایجاد کنید و فایل را در Cloud Shell Editor باز کنید: برای میزبانی کد اولیه استفاده خواهد شد. یک فایل خالی جدید با نامcloudshell edit setup.go
setup.go
در پنجره ویرایشگر ظاهر می شود. - کد زیر را کپی کرده و در فایل
setup.go
باز شده قرار دهید:package main import ( "context" "os" "cloud.google.com/go/compute/metadata" ) func projectID(ctx context.Context) (string, error) { var projectID = os.Getenv("GOOGLE_CLOUD_PROJECT") if projectID == "" { return metadata.ProjectIDWithContext(ctx) } return projectID, nil }
- به پنجره ترمینال برگردید و دستور زیر را برای ایجاد و باز کردن فایل
main.go
در Cloud Shell Editor اجرا کنید: اکنون باید یک فایل خالی در پنجره ویرایشگر بالای ترمینال ظاهر شود. صفحه نمایش شما شبیه به شکل زیر خواهد بود:cloudshell edit main.go
- کد زیر را کپی کرده و در فایل
main.go
باز شده قرار دهید: پس از چند ثانیه، Cloud Shell Editor کد شما را به صورت خودکار ذخیره می کند.package main import ( "context" "fmt" "net/http" "os" "cloud.google.com/go/vertexai/genai" ) var model *genai.GenerativeModel func main() { ctx := context.Background() projectID, err := projectID(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("/", Handler) port := os.Getenv("PORT") if port == "" { port = "8080" } if err := http.ListenAndServe(":"+port, nil); err != nil { return } } func Handler(w http.ResponseWriter, r *http.Request) { animal := r.URL.Query().Get("animal") if animal == "" { animal = "dog" } prompt := fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal) resp, err := model.GenerateContent(r.Context(), genai.Text(prompt)) if err != nil { w.WriteHeader(http.StatusTooManyRequests) 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) } }
کد برنامه Gen AI را در Cloud Run مستقر کنید
- در پنجره ترمینال دستور استقرار کد منبع برنامه را در Cloud Run اجرا کنید.
اگر دستور زیر را مشاهده کردید، به شما اطلاع می دهد که این دستور یک مخزن جدید ایجاد می کند. رویgcloud run deploy codelab-o11y-service \ --source="${HOME}/codelab-o11y/" \ --region=us-central1 \ --allow-unauthenticated
Enter
کلیک کنید. فرآیند استقرار ممکن است تا چند دقیقه طول بکشد. پس از تکمیل فرآیند استقرار، خروجی هایی مانند زیر را مشاهده خواهید کرد: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)?
Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic. Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
- URL نمایش داده شده سرویس Cloud Run را در یک برگه یا پنجره جداگانه در مرورگر خود کپی کنید. همچنین، دستور زیر را در ترمینال اجرا کنید تا URL سرویس چاپ شود و در حالی که کلید Ctrl را نگه داشته اید، روی URL نشان داده شده کلیک کنید تا URL باز شود:
وقتی URL باز می شود، ممکن است خطای 500 دریافت کنید یا این پیام را ببینید:gcloud run services list \ --format='value(URL)' \ --filter='SERVICE:"codelab-o11y-service"'
این بدان معنی است که سرویس ها استقرار خود را به پایان نرسانده اند. چند لحظه صبر کنید و صفحه را رفرش کنید. در پایان متنی خواهید دید که با Fun Dog Facts شروع می شود و حاوی 10 واقعیت سرگرم کننده در مورد سگ است.Sorry, this is just a placeholder...
سعی کنید با برنامه تعامل داشته باشید تا حقایق جالبی در مورد حیوانات مختلف به دست آورید. برای انجام این کار، پارامتر animal
را به URL اضافه کنید، مانند ?animal=[ANIMAL]
که در آن [ANIMAL]
نام حیوان است. به عنوان مثال، ?animal=cat
برای دریافت 10 واقعیت سرگرم کننده در مورد گربه ها یا ?animal=sea turtle
برای دریافت 10 واقعیت سرگرم کننده در مورد لاک پشت های دریایی اضافه کنید.
7. تماس های Vertex API خود را بررسی کنید
ممیزی تماسهای Google API پاسخهایی را به سوالاتی مانند «چه کسی یک API خاص، کجا و چه زمانی را فراخوانی میکند؟» ارائه میدهد. ممیزی زمانی مهم است که برنامه خود را عیب یابی می کنید، مصرف منابع را بررسی می کنید یا تجزیه و تحلیل قانونی نرم افزاری را انجام می دهید.
گزارشهای حسابرسی به شما امکان میدهند فعالیتهای اداری و سیستمی را ردیابی کنید و همچنین تماسهای مربوط به عملیات API "خواندن داده" و "نوشتن داده" را ثبت کنید. برای بررسی درخواستهای Vertex AI برای تولید محتوا، باید گزارشهای حسابرسی "Data Read" را در کنسول Cloud فعال کنید .
- روی دکمه زیر کلیک کنید تا صفحه Audit Logs در کنسول Cloud باز شود
- مطمئن شوید که صفحه پروژه ای را که برای این آزمایشگاه ایجاد کرده اید انتخاب کرده باشد. پروژه انتخاب شده در گوشه سمت چپ بالای صفحه سمت راست از منوی همبرگر نشان داده شده است:
در صورت لزوم، پروژه صحیح را از جعبه ترکیبی انتخاب کنید. - در جدول پیکربندی گزارش های حسابرسی داده دسترسی ، در ستون Service، سرویس
Vertex AI API
را پیدا کنید و با انتخاب کادر انتخاب سمت چپ از نام سرویس، سرویس را انتخاب کنید. - در پانل اطلاعات سمت راست، نوع حسابرسی "Data Read" را انتخاب کنید.
- روی ذخیره کلیک کنید.
برای ایجاد گزارش های حسابرسی URL سرویس را باز کنید. با تغییر مقدار پارامتر ?animal=
صفحه را بازخوانی کنید تا نتایج متفاوتی دریافت کنید.
گزارش های حسابرسی را کاوش کنید
- روی دکمه زیر کلیک کنید تا صفحه Logs Explorer در کنسول Cloud باز شود:
- فیلتر زیر را در قسمت Query قرار دهید.
پنجره Query ویرایشگری است که در نزدیکی بالای صفحه Logs Explorer قرار دارد:LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND protoPayload.serviceName="aiplatform.googleapis.com"
- روی Run query کلیک کنید.
- یکی از ورودی های گزارش حسابرسی را انتخاب کنید و فیلدها را برای بازرسی اطلاعات ثبت شده در گزارش گسترش دهید.
شما می توانید جزئیات تماس API Vertex از جمله روش و مدل استفاده شده را مشاهده کنید. همچنین میتوانید هویت فراخوان و مجوزهایی را که به تماس اجازه میدهند، ببینید.
8. تعاملات با Gen AI را ثبت کنید
شما پارامترهای درخواست API یا دادههای پاسخ را در گزارشهای حسابرسی پیدا نمیکنید. با این حال، این اطلاعات می تواند برای عیب یابی برنامه و تجزیه و تحلیل گردش کار مهم باشد. در این مرحله ما این شکاف را با اضافه کردن لاگ برنامه برطرف می کنیم. گزارشگیری از بسته استاندارد Go log/slog
برای نوشتن گزارشهای ساختاریافته استفاده میکند. بسته log/slog
نمیداند که گزارشها را در Google Cloud بنویسد. از نوشتن در خروجی استاندارد پشتیبانی می کند. با این حال، Cloud Run ویژگی هایی را دارد که اطلاعات چاپ شده در خروجی استاندارد را ضبط می کند و به طور خودکار آن را در Cloud Logging وارد می کند. برای ثبت صحیح گزارشهای ساختیافته، گزارش چاپی باید بر اساس آن قالببندی شود. دستورالعمل های زیر را دنبال کنید تا قابلیت های ثبت ساختار یافته را به برنامه Go خود اضافه کنید.
- به پنجره (یا برگه) "Cloud Shell" در مرورگر خود بازگردید.
- در ترمینال،
setup.go
دوباره باز کنید:cloudshell edit ~/codelab-o11y/setup.go
- کد را با نسخه ای که لاگ را تنظیم می کند جایگزین کنید. برای جایگزینی کد، محتوای فایل را حذف کنید و سپس کد زیر را کپی کرده و در ویرایشگر قرار دهید:
package main import ( "context" "os" "log/slog" "cloud.google.com/go/compute/metadata" ) func projectID(ctx context.Context) (string, error) { var projectID = os.Getenv("GOOGLE_CLOUD_PROJECT") if projectID == "" { return metadata.ProjectIDWithContext(ctx) } return projectID, nil } func setupLogging() { opts := &slog.HandlerOptions{ Level: slog.LevelDebug, ReplaceAttr: func(group []string, a slog.Attr) slog.Attr { switch a.Key { case slog.LevelKey: a.Key = "severity" if level := a.Value.Any().(slog.Level); level == slog.LevelWarn { a.Value = slog.StringValue("WARNING") } case slog.MessageKey: a.Key = "message" case slog.TimeKey: a.Key = "timestamp" } return a }, } jsonHandler := slog.NewJSONHandler(os.Stdout, opts) slog.SetDefault(slog.New(jsonHandler)) }
- به ترمینال برگردید و
main.go
دوباره باز کنید:cloudshell edit ~/codelab-o11y/main.go
- کد برنامه را با نسخه ای جایگزین کنید که تعامل با مدل را ثبت می کند. برای جایگزینی کد، محتوای فایل را حذف کنید و سپس کد زیر را کپی کرده و در ویرایشگر قرار دهید:
package main import ( "context" "fmt" "net/http" "os" "encoding/json" "log/slog" "cloud.google.com/go/vertexai/genai" ) var model *genai.GenerativeModel func main() { ctx := context.Background() projectID, err := projectID(ctx) if err != nil { return } setupLogging() var client *genai.Client client, err = genai.NewClient(ctx, projectID, "us-central1") if err != nil { slog.ErrorContext(ctx, "Failed to marshal response to JSON", slog.Any("error", err)) os.Exit(1) } defer client.Close() model = client.GenerativeModel("gemini-1.5-flash-001") http.HandleFunc("/", Handler) port := os.Getenv("PORT") if port == "" { port = "8080" } if err := http.ListenAndServe(":"+port, nil); err != nil { slog.ErrorContext(ctx, "Failed to start the server", slog.Any("error", err)) os.Exit(1) } } func Handler(w http.ResponseWriter, r *http.Request) { animal := r.URL.Query().Get("animal") if animal == "" { animal = "dog" } prompt := fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal) resp, err := model.GenerateContent(r.Context(), genai.Text(prompt)) if err != nil { w.WriteHeader(http.StatusTooManyRequests) return } jsonBytes, err := json.Marshal(resp) if err != nil { slog.Error("Failed to marshal response to JSON", slog.Any("error", err)) } else { slog.DebugContext(r.Context(), "content is generated", slog.String("animal", animal), slog.String("prompt", prompt), slog.String("response", string(jsonBytes))) } 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) } }
گزارشگیری طوری پیکربندی شده است که گزارشها را در stdout
چاپ کند، جایی که توسط عامل گزارش Cloud Run جمعآوری میشود و به طور ناهمزمان در Cloud Logging وارد میشود. تابع main()
برای تنظیم گزارش ساختاری استاندارد Go برای استفاده از طرح JSON که از دستورالعملهای قالببندی ساختیافته پیروی میکند، اصلاح شده است. تمام عبارات return
آن با کدی جایگزین میشود که گزارشهای خطا را قبل از خروج مینویسد. تابع Handler()
برای نوشتن گزارش ساختار یافته هنگام دریافت پاسخ از فراخوانی Vertex AI API ابزاری است. گزارش پارامتر حیوانی درخواست و اعلان و پاسخ مدل را ضبط می کند.
پس از چند ثانیه، Cloud Shell Editor تغییرات شما را به صورت خودکار ذخیره می کند.
کد برنامه Gen AI را در Cloud Run مستقر کنید
- در پنجره ترمینال دستور استقرار کد منبع برنامه را در Cloud Run اجرا کنید.
اگر دستور زیر را مشاهده کردید، به شما اطلاع می دهد که این دستور یک مخزن جدید ایجاد می کند. رویgcloud run deploy codelab-o11y-service \ --source="${HOME}/codelab-o11y/" \ --region=us-central1 \ --allow-unauthenticated
Enter
کلیک کنید. فرآیند استقرار ممکن است تا چند دقیقه طول بکشد. پس از تکمیل فرآیند استقرار، خروجی هایی مانند زیر را مشاهده خواهید کرد: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)?
Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic. Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
- URL نمایش داده شده سرویس Cloud Run را در یک برگه یا پنجره جداگانه در مرورگر خود کپی کنید. همچنین، دستور زیر را در ترمینال اجرا کنید تا URL سرویس چاپ شود و در حالی که کلید Ctrl را نگه داشته اید، روی URL نشان داده شده کلیک کنید تا URL باز شود:
وقتی URL باز می شود، ممکن است خطای 500 دریافت کنید یا این پیام را ببینید:gcloud run services list \ --format='value(URL)' \ --filter='SERVICE:"codelab-o11y-service"'
این بدان معنی است که سرویس ها استقرار خود را به پایان نرسانده اند. چند لحظه صبر کنید و صفحه را رفرش کنید. در پایان متنی خواهید دید که با Fun Dog Facts شروع می شود و حاوی 10 واقعیت سرگرم کننده در مورد سگ است.Sorry, this is just a placeholder...
برای ایجاد گزارش برنامه، URL سرویس را باز کنید. با تغییر مقدار پارامتر ?animal=
صفحه را بازخوانی کنید تا نتایج متفاوتی دریافت کنید.
برای مشاهده لاگ های برنامه به صورت زیر عمل کنید:
- روی دکمه زیر کلیک کنید تا صفحه کاوشگر Logs در کنسول Cloud باز شود:
- فیلتر زیر را در قسمت Query (#2 در رابط کاربری Log explorer ) قرار دهید:
LOG_ID("run.googleapis.com%2Fstdout") AND severity=DEBUG
- روی Run query کلیک کنید.
نتیجه پرس و جو گزارشهایی را با پاسخ سریع و Vertex AI از جمله رتبهبندی ایمنی نشان میدهد.
9. تعداد تعاملات با Gen AI
Cloud Run معیارهای مدیریت شده را می نویسد که می تواند برای نظارت بر سرویس های مستقر شده استفاده شود. معیارهای نظارت مدیریت شده توسط کاربر کنترل بیشتری بر روی داده ها و تعداد دفعات به روز رسانی متریک فراهم می کند. برای پیاده سازی چنین معیاری نیاز به نوشتن کدی است که داده ها را جمع آوری کرده و در Cloud Monitoring می نویسد. مرحله بعدی (اختیاری) را برای نحوه اجرای آن با استفاده از OpenTelemetry SDK ببینید.
این مرحله جایگزینی برای پیاده سازی متریک کاربر در معیارهای مبتنی بر گزارش کد را نشان می دهد. معیارهای مبتنی بر گزارش به شما امکان می دهد معیارهای نظارتی را از ورودی های گزارشی که برنامه شما در Cloud Logging می نویسد ایجاد کنید. ما از گزارشهای برنامهای که در مرحله قبل پیادهسازی کردیم برای تعریف یک متریک مبتنی بر گزارش از نوع شمارنده استفاده خواهیم کرد. این معیار تعداد تماس های موفق با Vertex API را می شمارد.
- به پنجره کاوشگر Logs که در مرحله قبل استفاده کردیم نگاه کنید. در زیر پنجره Query منوی کشویی Actions را پیدا کرده و روی آن کلیک کنید تا باز شود. برای پیدا کردن منو، اسکرین شات زیر را ببینید:
- در منوی باز شده، Create Metric را انتخاب کنید تا پنل Create log-based metric باز شود.
- این مراحل را برای پیکربندی یک متریک شمارنده جدید در پانل متریک ایجاد گزارش مبتنی بر گزارش دنبال کنید:
- نوع متریک را تنظیم کنید: شمارنده را انتخاب کنید.
- فیلدهای زیر را در قسمت جزئیات تنظیم کنید:
- نام متریک گزارش : نام را روی
model_interaction_count
تنظیم کنید. برخی از محدودیت های نامگذاری اعمال می شود. برای جزئیات بیشتر به عیب یابی محدودیت های نامگذاری مراجعه کنید. - توضیحات : توضیحاتی را برای متریک وارد کنید. به عنوان مثال،
Number of log entries capturing successful call to model inference.
- واحدها : این قسمت را خالی بگذارید یا رقم
1
را وارد کنید.
- نام متریک گزارش : نام را روی
- مقادیر را در قسمت Filter selection بگذارید. توجه داشته باشید که فیلد Build filter دارای همان فیلتری است که برای دیدن گزارش های برنامه استفاده کردیم.
- (اختیاری) برچسبی اضافه کنید که به شمارش تعدادی تماس برای هر حیوان کمک می کند. توجه: این برچسب پتانسیل بالایی برای افزایش کاردینالیته متریک دارد و برای استفاده در تولید توصیه نمی شود:
- روی افزودن برچسب کلیک کنید.
- فیلدهای زیر را در قسمت Labels تنظیم کنید:
- نام برچسب : نام را روی
animal
قرار دهید. - توضیحات : توضیحات برچسب را وارد کنید. به عنوان مثال،
Animal parameter
. - نوع برچسب :
STRING
انتخاب کنید. - نام فیلد :
jsonPayload.animal
را تایپ کنید. - عبارت منظم : آن را خالی بگذارید.
- نام برچسب : نام را روی
- روی Done کلیک کنید
- برای ایجاد متریک روی Create Metric کلیک کنید.
همچنین میتوانید از صفحه معیارهای Log-based Metrics مبتنی بر گزارش، با استفاده از gcloud logging metrics create
دستور ایجاد CLI یا با منبع Terraform google_logging_metric
ایجاد کنید.
برای تولید داده های متریک، URL سرویس را باز کنید. صفحه باز شده را چندین بار بازخوانی کنید تا چندین تماس با مدل برقرار شود. سعی کنید مانند قبل از حیوانات مختلف در پارامتر استفاده کنید.
برای جستجوی دادههای متریک مبتنی بر گزارش، کوئری PromQL را وارد کنید. برای وارد کردن یک کوئری PromQL، موارد زیر را انجام دهید:
- روی دکمه زیر کلیک کنید تا صفحه Metrics explorer در کنسول Cloud باز شود:
- در نوار ابزار پنجره query-builder، دکمه ای را انتخاب کنید که نام آن < > MQL یا < > PromQL است. برای دیدن مکان دکمه به تصویر زیر مراجعه کنید.
- بررسی کنید که PromQL در تغییر زبان انتخاب شده باشد. تغییر زبان در همان نوار ابزار قرار دارد که به شما امکان می دهد پرس و جو خود را قالب بندی کنید.
- درخواست خود را در ویرایشگر Queries وارد کنید:
برای اطلاعات بیشتر در مورد استفاده از PromQL، به PromQL در Cloud Monitoring مراجعه کنید.sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
- روی Run Query کلیک کنید. نمودار خطی مشابه این اسکرین شات را خواهید دید:
توجه داشته باشید که وقتی کلید اجرای خودکار فعال است، دکمه Run Query نشان داده نمیشود.
10. (اختیاری) از تله متری باز برای نظارت و ردیابی استفاده کنید
همانطور که در مرحله قبل ذکر شد، امکان پیادهسازی معیارها با استفاده از OpenTelemetry (Otel) SDK وجود دارد. استفاده از OTel در معماری های میکرو سرویس یک اقدام توصیه شده است. این مرحله موارد زیر را شرح می دهد:
- راه اندازی اجزای OTel برای پشتیبانی از ردیابی و نظارت بر برنامه
- پر کردن پیکربندی OTel با ابرداده منابع محیط Cloud Run
- کاربرد فلاسک ابزار دقیق با قابلیت ردیابی خودکار
- پیاده سازی یک متریک شمارنده برای نظارت بر تعدادی از تماس های مدل موفق
- ردیابی را با گزارش های برنامه مرتبط کنید
معماری پیشنهادی برای خدمات در سطح محصول استفاده از جمعآورنده OTel برای جمعآوری و دریافت تمام دادههای مشاهدهپذیری برای یک یا چند سرویس است. کد در این مرحله به خاطر سادگی از کلکتور استفاده نمی کند. در عوض از صادرات OTel استفاده می کند که داده ها را مستقیماً در Google Cloud می نویسد.
اجزای OTel را برای ردیابی و نظارت متریک تنظیم کنید
- به پنجره (یا برگه) "Cloud Shell" در مرورگر خود بازگردید.
- در ترمینال،
setup.go
دوباره باز کنید:cloudshell edit ~/codelab-o11y/setup.go
- کد را با نسخه ای که ردیابی OpenTelemetry و مجموعه متریک را مقداردهی اولیه می کند جایگزین کنید. برای جایگزینی کد، محتوای فایل را حذف کنید و سپس کد زیر را کپی کرده و در ویرایشگر قرار دهید:
package main import ( "context" "errors" "fmt" "net/http" "os" "log/slog" "go.opentelemetry.io/contrib/detectors/gcp" "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp" "go.opentelemetry.io/contrib/propagators/autoprop" "go.opentelemetry.io/otel" sdkmetric "go.opentelemetry.io/otel/sdk/metric" "go.opentelemetry.io/otel/sdk/resource" sdktrace "go.opentelemetry.io/otel/sdk/trace" semconv "go.opentelemetry.io/otel/semconv/v1.27.0" "go.opentelemetry.io/otel/trace" cloudmetric "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric" cloudtrace "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace" "cloud.google.com/go/compute/metadata" ) var ( projID string ) func projectID(ctx context.Context) (string, error) { var projectID = os.Getenv("GOOGLE_CLOUD_PROJECT") if projectID == "" { return metadata.ProjectIDWithContext(ctx) } return projectID, nil } func setupLogging() { opts := &slog.HandlerOptions{ Level: slog.LevelDebug, ReplaceAttr: func(group []string, a slog.Attr) slog.Attr { switch a.Key { case slog.LevelKey: a.Key = "severity" if level := a.Value.Any().(slog.Level); level == slog.LevelWarn { a.Value = slog.StringValue("WARNING") } case slog.MessageKey: a.Key = "message" case slog.TimeKey: a.Key = "timestamp" } return a }, } jsonHandler := slog.NewJSONHandler(os.Stdout, opts) instrumentedHandler := handlerWithSpanContext(jsonHandler) slog.SetDefault(slog.New(instrumentedHandler)) } type spanContextLogHandler struct { slog.Handler } func handlerWithSpanContext(handler slog.Handler) *spanContextLogHandler { return &spanContextLogHandler{Handler: handler} } func (t *spanContextLogHandler) Handle(ctx context.Context, record slog.Record) error { if s := trace.SpanContextFromContext(ctx); s.IsValid() { trace := fmt.Sprintf("projects/%s/traces/%s", projID, s.TraceID()) record.AddAttrs( slog.Any("logging.googleapis.com/trace", trace), ) record.AddAttrs( slog.Any("logging.googleapis.com/spanId", s.SpanID()), ) record.AddAttrs( slog.Bool("logging.googleapis.com/trace_sampled", s.TraceFlags().IsSampled()), ) } return t.Handler.Handle(ctx, record) } func setupTelemetry(ctx context.Context) (shutdown func(context.Context) error, err error) { var shutdownFuncs []func(context.Context) error shutdown = func(ctx context.Context) error { var err error for _, fn := range shutdownFuncs { err = errors.Join(err, fn(ctx)) } shutdownFuncs = nil return err } projID, err = projectID(ctx) if err != nil { err = errors.Join(err, shutdown(ctx)) return } res, err2 := resource.New( ctx, resource.WithDetectors(gcp.NewDetector()), resource.WithTelemetrySDK(), resource.WithAttributes(semconv.ServiceNameKey.String(os.Getenv("K_SERVICE"))), ) if err2 != nil { err = errors.Join(err2, shutdown(ctx)) return } otel.SetTextMapPropagator(autoprop.NewTextMapPropagator()) texporter, err2 := cloudtrace.New(cloudtrace.WithProjectID(projID)) if err2 != nil { err = errors.Join(err2, shutdown(ctx)) return } tp := sdktrace.NewTracerProvider( sdktrace.WithSampler(sdktrace.AlwaysSample()), sdktrace.WithResource(res), sdktrace.WithBatcher(texporter)) shutdownFuncs = append(shutdownFuncs, tp.Shutdown) otel.SetTracerProvider(tp) mexporter, err2 := cloudmetric.New(cloudmetric.WithProjectID(projID)) if err2 != nil { err = errors.Join(err2, shutdown(ctx)) return } mp := sdkmetric.NewMeterProvider( sdkmetric.WithReader(sdkmetric.NewPeriodicReader(mexporter)), sdkmetric.WithResource(res), ) shutdownFuncs = append(shutdownFuncs, mp.Shutdown) otel.SetMeterProvider(mp) return shutdown, nil } func registerHttpHandler(route string, handleFn http.HandlerFunc) { instrumentedHandler := otelhttp.NewHandler(otelhttp.WithRouteTag(route, handleFn), route) http.Handle(route, instrumentedHandler) }
- به ترمینال برگردید و دستور زیر را برای به روز رسانی تعاریف ماژول Go در فایل
go.mod
اجرا کنید:go mod tidy
- به ترمینال برگردید و
main.go
دوباره باز کنید:cloudshell edit ~/codelab-o11y/main.go
- کد فعلی را با نسخه ای جایگزین کنید که ردیابی HTTP را ابزار می کند و متریک عملکرد را می نویسد. برای جایگزینی کد، محتوای فایل را حذف کنید و سپس کد زیر را کپی کرده و در ویرایشگر قرار دهید:
package main import ( "context" "errors" "fmt" "net/http" "os" "encoding/json" "log/slog" "cloud.google.com/go/vertexai/genai" "go.opentelemetry.io/otel" "go.opentelemetry.io/otel/attribute" "go.opentelemetry.io/otel/metric" ) var model *genai.GenerativeModel var counter metric.Int64Counter const scopeName = "genai-o11y/go/workshop/example" func main() { ctx := context.Background() projectID, err := projectID(ctx) if err != nil { return } setupLogging() shutdown, err := setupTelemetry(ctx) if err != nil { slog.ErrorContext(ctx, "error setting up OpenTelemetry", slog.Any("error", err)) os.Exit(1) } meter := otel.Meter(scopeName) counter, err = meter.Int64Counter("model_call_counter") if err != nil { slog.ErrorContext(ctx, "error setting up OpenTelemetry", slog.Any("error", err)) os.Exit(1) } var client *genai.Client client, err = genai.NewClient(ctx, projectID, "us-central1") if err != nil { slog.ErrorContext(ctx, "Failed to marshal response to JSON", slog.Any("error", err)) os.Exit(1) } defer client.Close() model = client.GenerativeModel("gemini-1.5-flash-001") registerHttpHandler("/", Handler) port := os.Getenv("PORT") if port == "" { port = "8080" } if err = errors.Join(http.ListenAndServe(":"+port, nil), shutdown(ctx)); err != nil { slog.ErrorContext(ctx, "Failed to start the server", slog.Any("error", err)) os.Exit(1) } } func Handler(w http.ResponseWriter, r *http.Request) { animal := r.URL.Query().Get("animal") if animal == "" { animal = "dog" } prompt := fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal) resp, err := model.GenerateContent(r.Context(), genai.Text(prompt)) if err != nil { w.WriteHeader(http.StatusTooManyRequests) return } jsonBytes, err := json.Marshal(resp) if err != nil { slog.ErrorContext(r.Context(), "Failed to marshal response to JSON", slog.Any("error", err)) } else { slog.DebugContext(r.Context(), "content is generated", slog.String("animal", animal), slog.String("prompt", prompt), slog.String("response", string(jsonBytes))) } if len(resp.Candidates) > 0 && len(resp.Candidates[0].Content.Parts) > 0 { clabels := []attribute.KeyValue{attribute.Key("animal").String(animal)} counter.Add(r.Context(), 1, metric.WithAttributes(clabels...)) htmlContent := resp.Candidates[0].Content.Parts[0] w.Header().Set("Content-Type", "text/html; charset=utf-8") fmt.Fprint(w, htmlContent) } }
این برنامه اکنون از OpenTelemetry SDK برای ابزار اجرای کد با ردیابی و برای پیاده سازی شمارش تعدادی از اجرای موفق به عنوان یک معیار استفاده می کند. روش main()
برای تنظیم صادرکنندگان OpenTelemetry برای ردیابی ها و معیارها برای نوشتن مستقیم به Google Cloud Tracing و Monitoring اصلاح شده است. همچنین پیکربندی های اضافی را برای پر کردن ردیابی ها و معیارهای جمع آوری شده با ابرداده های مربوط به محیط Cloud Run انجام می دهد. تابع Handler()
برای افزایش شمارنده متریک هر بار که فراخوانی Vertex AI API نتایج معتبری را برمی گرداند به روز می شود.
پس از چند ثانیه، Cloud Shell Editor تغییرات شما را به صورت خودکار ذخیره می کند.
کد برنامه Gen AI را در Cloud Run مستقر کنید
- در پنجره ترمینال دستور استقرار کد منبع برنامه را در Cloud Run اجرا کنید.
اگر دستور زیر را مشاهده کردید، به شما اطلاع می دهد که این دستور یک مخزن جدید ایجاد می کند. رویgcloud run deploy codelab-o11y-service \ --source="${HOME}/codelab-o11y/" \ --region=us-central1 \ --allow-unauthenticated
Enter
کلیک کنید. فرآیند استقرار ممکن است تا چند دقیقه طول بکشد. پس از تکمیل فرآیند استقرار، خروجی هایی مانند زیر را مشاهده خواهید کرد: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)?
Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic. Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
- URL نمایش داده شده سرویس Cloud Run را در یک برگه یا پنجره جداگانه در مرورگر خود کپی کنید. همچنین، دستور زیر را در ترمینال اجرا کنید تا URL سرویس چاپ شود و در حالی که کلید Ctrl را نگه داشته اید، روی URL نشان داده شده کلیک کنید تا URL باز شود:
وقتی URL باز می شود، ممکن است خطای 500 دریافت کنید یا این پیام را ببینید:gcloud run services list \ --format='value(URL)' \ --filter='SERVICE:"codelab-o11y-service"'
این بدان معنی است که سرویس ها استقرار خود را به پایان نرسانده اند. چند لحظه صبر کنید و صفحه را رفرش کنید. در پایان متنی خواهید دید که با Fun Dog Facts شروع می شود و حاوی 10 واقعیت سرگرم کننده در مورد سگ است.Sorry, this is just a placeholder...
برای تولید داده های تله متری، URL سرویس را باز کنید. با تغییر مقدار پارامتر ?animal=
صفحه را بازخوانی کنید تا نتایج متفاوتی دریافت کنید.
ردپای برنامه را کاوش کنید
- روی دکمه زیر کلیک کنید تا صفحه Trace explorer در کنسول Cloud باز شود:
- یکی از جدیدترین ردیابی ها را انتخاب کنید. شما قرار است 5 یا 6 دهانه را ببینید که در تصویر زیر به نظر می رسد.
- دامنه ای را پیدا کنید که تماس را به کنترل کننده رویداد ردیابی می کند (روش
fun_facts
). این آخرین بازه با نام/
خواهد بود. - در قسمت Trace details Logs & events را انتخاب کنید. گزارشهای برنامهای را خواهید دید که با این محدوده خاص مرتبط هستند. همبستگی با استفاده از شناسه های ردیابی و دهانه در ردیابی و در گزارش شناسایی می شود. شما باید گزارش برنامه را ببینید که دستور و پاسخ Vertex API را نوشته است.
متریک شمارنده را کاوش کنید
- روی دکمه زیر کلیک کنید تا صفحه Metrics explorer در کنسول Cloud باز شود:
- در نوار ابزار پنجره query-builder، دکمه ای را انتخاب کنید که نام آن < > MQL یا < > PromQL است. برای دیدن مکان دکمه به تصویر زیر مراجعه کنید.
- بررسی کنید که PromQL در تغییر زبان انتخاب شده باشد. تغییر زبان در همان نوار ابزار قرار دارد که به شما امکان می دهد پرس و جو خود را قالب بندی کنید.
- درخواست خود را در ویرایشگر Queries وارد کنید:
sum(rate(workload_googleapis_com:model_call_counter{monitored_resource="generic_task"}[${__interval}]))
- روی Run Query کلیک کنید. وقتی کلید اجرای خودکار فعال است، دکمه اجرای پرس و جو نشان داده نمی شود.
11. (اختیاری) اطلاعات حساس مبهم از سیاهههای مربوط
در مرحله 10 اطلاعاتی در مورد تعامل برنامه با مدل Gemini ثبت کردیم. این اطلاعات شامل نام حیوان، درخواست واقعی و پاسخ مدل بود. اگرچه ذخیره این اطلاعات در گزارش باید ایمن باشد، اما برای بسیاری از سناریوهای دیگر درست نیست. درخواست ممکن است شامل برخی از اطلاعات شخصی یا حساس باشد که کاربر نمی خواهد ذخیره شود. برای رفع این مشکل میتوانید دادههای حساسی که در Cloud Logging نوشته شدهاند را مبهم کنید. برای به حداقل رساندن تغییرات کد راه حل زیر توصیه می شود.
- یک موضوع PubSub برای ذخیره ورودی های گزارش ورودی ایجاد کنید
- یک سینک گزارش ایجاد کنید که گزارشهای دریافت شده را به موضوع PubSub هدایت میکند.
- یک خط لوله Dataflow ایجاد کنید که گزارشهای هدایتشده به موضوع PubSub را به دنبال این مراحل تغییر میدهد:
- یک ورودی گزارش از موضوع PubSub را بخوانید
- بار ورودی ورودی را برای اطلاعات حساس با استفاده از API بازرسی DLP بررسی کنید
- با استفاده از یکی از روش های ویرایش DLP، اطلاعات حساس موجود در محموله را ویرایش کنید
- ورودی log مبهم را در Cloud Logging بنویسید
- خط لوله را مستقر کنید
12. (اختیاری) پاکسازی کنید
برای جلوگیری از خطر تحمیل هزینه برای منابع و APIهای مورد استفاده در Codelab، توصیه می شود پس از اتمام آزمایشگاه پاکسازی کنید. ساده ترین راه برای حذف صورتحساب، حذف پروژه ای است که برای Codelab ایجاد کرده اید.
- برای حذف پروژه دستور delete project را در ترمینال اجرا کنید:
با حذف پروژه Cloud، صورتحساب تمام منابع و APIهای مورد استفاده در آن پروژه متوقف میشود. باید این پیام را ببینید که در آنPROJECT_ID=$(gcloud config get-value project) gcloud projects delete ${PROJECT_ID} --quiet
PROJECT_ID
شناسه پروژه شما خواهد بود:Deleted [https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID]. You can undo this operation for a limited period by running the command below. $ gcloud projects undelete PROJECT_ID See https://cloud.google.com/resource-manager/docs/creating-managing-projects for information on shutting down projects.
- (اختیاری) اگر خطایی دریافت کردید، با مرحله 5 مشورت کنید تا شناسه پروژه ای را که در طول آزمایشگاه استفاده کرده اید پیدا کنید. آن را با دستور در دستورالعمل اول جایگزین کنید. به عنوان مثال، اگر ID پروژه شما
lab-example-project
باشد، دستور به صورت زیر خواهد بود:gcloud projects delete lab-project-id-example --quiet
13. تبریک می گویم
در این آزمایشگاه، یک اپلیکیشن Gen AI ایجاد کردید که از مدل Gemini برای پیشبینی استفاده میکند. و برنامه را با قابلیت های ضروری نظارت و گزارش گیری مجهز کرد. شما برنامه را مستقر کرده اید و از کد منبع به Cloud Run تغییر می دهید. سپس شما محصولات Google Cloud Observability را دنبال میکنید تا عملکرد برنامه را ردیابی کنید، بنابراین میتوانید از قابلیت اطمینان برنامه اطمینان حاصل کنید.
اگر میخواهید برای بهبود محصولاتی که امروز با آنها کار میکنید، در یک مطالعه تحقیقاتی تجربه کاربری (UX) شرکت کنید، اینجا ثبتنام کنید .
در اینجا چند گزینه برای ادامه یادگیری وجود دارد:
- Codelab نحوه استقرار برنامه چت مجهز به جمینی در Cloud Run
- Codelab نحوه استفاده از فراخوانی تابع Gemini با Cloud Run
- نحوه استفاده از Cloud Run Jobs Video Intelligence API برای پردازش صحنه به صحنه ویدیو
- کارگاه درخواستی Google Kubernetes Engine Onboard
- درباره پیکربندی سنجههای شمارنده و توزیع با استفاده از گزارشهای برنامه بیشتر بیاموزید
- معیارهای OTLP را با استفاده از OpenTelemetry بنویسید
- اشاره به استفاده از Open Telemetry در Google Cloud