این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

تکنیک‌های عملی مشاهده‌پذیری برای کاربرد هوش مصنوعی تولیدی در پایتون

۱. مرور کلی

برنامه‌های کاربردی هوش مصنوعی نسل بعد مانند هر برنامه دیگری نیاز به مشاهده‌پذیری دارند. آیا تکنیک‌های مشاهده‌پذیری خاصی برای هوش مصنوعی نسل بعد مورد نیاز است؟

در این آزمایشگاه، شما یک برنامه ساده Gen AI ایجاد خواهید کرد. آن را در Cloud Run مستقر خواهید کرد. و آن را با استفاده از خدمات و محصولات رصدپذیری Google Cloud به قابلیت‌های ضروری نظارت و ثبت وقایع مجهز خواهید کرد.

آنچه یاد خواهید گرفت

برنامه‌ای بنویسید که از Vertex AI با ویرایشگر Cloud Shell استفاده کند
کد برنامه خود را در GitHub ذخیره کنید
از gcloud CLI برای استقرار کد منبع برنامه خود در Cloud Run استفاده کنید

قابلیت‌های نظارت و ثبت وقایع را به برنامه Gen AI خود اضافه کنید
استفاده از معیارهای مبتنی بر لاگ
پیاده‌سازی ثبت وقایع و نظارت با Open Telemetry SDK
کسب بینش در مورد مدیریت مسئولانه داده‌های هوش مصنوعی

۲. پیش‌نیازها

اگر از قبل حساب گوگل ندارید، باید یک حساب جدید ایجاد کنید .

۳. راه‌اندازی پروژه

با حساب گوگل خود وارد کنسول ابری گوگل شوید.
یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید. شناسه پروژه‌ای را که ایجاد یا انتخاب کرده‌اید، یادداشت کنید.
فعال کردن صورتحساب برای پروژه.
- تکمیل این آزمایشگاه باید کمتر از ۵ دلار در هزینه‌های صدور صورتحساب هزینه داشته باشد.
- شما می‌توانید مراحل انتهای این آزمایش را برای حذف منابع دنبال کنید تا از هزینه‌های بیشتر جلوگیری شود.
- کاربران جدید واجد شرایط استفاده از دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
تأیید کنید که پرداخت در پروژه‌های من در پرداخت ابری فعال شده است
- اگر در ستون Billing account در پروژه جدید شما نوشته شده باشد Billing is disabled :
  1. روی سه نقطه در ستون Actions کلیک کنید
  2. روی تغییر صورتحساب کلیک کنید
  3. حساب پرداختی که می‌خواهید استفاده کنید را انتخاب کنید
- اگر در یک رویداد زنده شرکت می‌کنید، احتمالاً نام حساب کاربری ، حساب پرداخت آزمایشی پلتفرم ابری گوگل خواهد بود.

۴. ویرایشگر Cloud Shell را آماده کنید

به ویرایشگر Cloud Shell بروید. اگر با پیام زیر مواجه شدید که از شما می‌خواهد به cloud shell اجازه دهید با اطلاعات کاربری شما gcloud را فراخوانی کند، برای ادامه روی Authorize کلیک کنید.
پنجره ترمینال را باز کنید
1. روی منوی همبرگری کلیک کنید
2. روی ترمینال کلیک کنید
3. روی ترمینال جدید کلیک کنید
در ترمینال، شناسه پروژه خود را پیکربندی کنید:
```
gcloud config set project [PROJECT_ID]
```
به جای [PROJECT_ID] ، شناسه پروژه خود را قرار دهید. برای مثال، اگر شناسه پروژه شما lab-example-project باشد، دستور به صورت زیر خواهد بود:
```
gcloud config set project lab-project-id-example
```
اگر با پیام زیر مواجه شدید که می‌گوید gcloud درخواست اعتبارنامه شما را برای GCPI API دارد، برای ادامه روی تأیید (Authorize) کلیک کنید.

در صورت اجرای موفقیت‌آمیز، باید پیام زیر را مشاهده کنید:
```
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
```

۵. فعال کردن APIهای گوگل

در ترمینال، APIهای گوگل مورد نیاز برای این آزمایشگاه را فعال کنید:

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 دریافت کردید و حاوی جزئیات خطایی مانند زیر بود، دستور را پس از ۱-۲ دقیقه تأخیر دوباره امتحان کنید.

"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",
  ...
}

۶. یک برنامه پایتون Gen AI ایجاد کنید

در این مرحله شما یک کد برای برنامه ساده مبتنی بر درخواست خواهید نوشت که از مدل Gemini برای نمایش 10 حقیقت جالب در مورد حیوان مورد نظر شما استفاده می‌کند. برای ایجاد کد برنامه، مراحل زیر را دنبال کنید.

در ترمینال، دایرکتوری codelab-o11y را ایجاد کنید:
```
mkdir ~/codelab-o11y
```
دایرکتوری فعلی را به codelab-o11y تغییر دهید:
```
cd ~/codelab-o11y
```

فایل requirements.txt را با لیست وابستگی‌ها ایجاد کنید:

cat > requirements.txt << EOF
Flask==3.0.0
gunicorn==23.0.0
google-cloud-aiplatform==1.59.0
google-auth==2.32.0
EOF

یک فایل 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 fun_facts():
    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 کد شما را به طور خودکار ذخیره می‌کند.

کد برنامه 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 نمایش داده شده را در یک تب یا پنجره جداگانه در مرورگر خود کپی کنید. روش دیگر، اجرای دستور زیر در ترمینال برای چاپ آدرس اینترنتی سرویس و کلیک بر روی آدرس اینترنتی نشان داده شده در حالی که کلید Ctrl را نگه داشته‌اید تا آدرس اینترنتی باز شود:
```
gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
```
وقتی URL باز می‌شود، ممکن است خطای ۵۰۰ دریافت کنید یا پیام زیر را ببینید:
```
Sorry, this is just a placeholder...
```
این یعنی سرویس‌ها هنوز استقرار خود را به پایان نرسانده اند. چند لحظه صبر کنید و صفحه را رفرش کنید. در پایان متنی را خواهید دید که با «دانستنی‌های جالب درباره سگ‌ها» شروع می‌شود و شامل ۱۰ حقیقت جالب درباره سگ‌ها است.

سعی کنید با برنامه تعامل داشته باشید تا حقایق جالبی در مورد حیوانات مختلف به دست آورید. برای انجام این کار، پارامتر animal را به URL اضافه کنید، مانند ?animal=[ANIMAL] که در آن [ANIMAL] نام یک حیوان است. به عنوان مثال، برای دریافت 10 حقیقت جالب در مورد گربه‌ها، ? ?animal=cat یا برای دریافت 10 حقیقت جالب در مورد لاک‌پشت‌های ?animal=sea turtle را اضافه کنید.

۷. فراخوانی‌های API مربوط به Vertex خود را بررسی کنید

حسابرسی فراخوانی‌های API گوگل، پاسخ‌هایی به سوالاتی مانند «چه کسی، کجا و چه زمانی یک API خاص را فراخوانی می‌کند؟» ارائه می‌دهد. حسابرسی هنگام عیب‌یابی برنامه، بررسی مصرف منابع یا انجام تجزیه و تحلیل‌های قانونی نرم‌افزار اهمیت دارد.

گزارش‌های حسابرسی به شما امکان می‌دهند فعالیت‌های مدیریتی و سیستمی را ردیابی کنید و همچنین فراخوانی‌های مربوط به عملیات API «خواندن داده» و «نوشتن داده» را ثبت کنید. برای حسابرسی درخواست‌های Vertex AI برای تولید محتوا، باید گزارش‌های حسابرسی «خواندن داده» را در کنسول Cloud فعال کنید .

برای باز کردن صفحه گزارش‌های حسابرسی در کنسول ابری، روی دکمه زیر کلیک کنید
مطمئن شوید که پروژه‌ای که برای این آزمایشگاه ایجاد کرده‌اید، در صفحه انتخاب شده باشد. پروژه انتخاب شده در گوشه سمت چپ بالای صفحه، درست از منوی همبرگری نشان داده می‌شود:

در صورت لزوم، پروژه صحیح را از combobox انتخاب کنید.
در جدول پیکربندی گزارش‌های حسابرسی دسترسی به داده‌ها ، در ستون سرویس، سرویس Vertex AI API را پیدا کنید و با انتخاب کادر انتخاب واقع در سمت چپ نام سرویس، آن را انتخاب کنید.
در پنل اطلاعات سمت راست، نوع حسابرسی «خواندن داده‌ها» را انتخاب کنید.
روی ذخیره کلیک کنید.

برای ایجاد گزارش‌های حسابرسی، آدرس اینترنتی سرویس را باز کنید. صفحه را رفرش کنید و در عین حال مقدار پارامتر ?animal= را تغییر دهید تا نتایج متفاوتی دریافت کنید.

بررسی گزارش‌های حسابرسی

برای باز کردن صفحه Logs Explorer در کنسول Cloud، روی دکمه زیر کلیک کنید:
فیلتر زیر را در کادر Query قرار دهید.
```
LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND
protoPayload.serviceName="aiplatform.googleapis.com"
```
پنجره‌ی کوئری (Query pane) یک ویرایشگر است که در بالای صفحه‌ی Logs Explorer قرار دارد:
روی اجرای پرس‌وجو کلیک کنید.
یکی از ورودی‌های گزارش حسابرسی را انتخاب کنید و فیلدها را برای بررسی اطلاعات ثبت‌شده در گزارش گسترش دهید.
شما می‌توانید جزئیات مربوط به فراخوانی API ورتکس، شامل متد و مدلی که استفاده شده است را مشاهده کنید. همچنین می‌توانید هویت فراخوانی‌کننده و مجوزهای مجاز برای فراخوانی را مشاهده کنید.

۸. تعاملات با Gen AI را ثبت کنید

شما پارامترهای درخواست API یا داده‌های پاسخ را در گزارش‌های حسابرسی پیدا نمی‌کنید. با این حال، این اطلاعات می‌تواند برای عیب‌یابی برنامه و تجزیه و تحلیل گردش کار مهم باشد. در این مرحله، ما این شکاف را با اضافه کردن گزارش‌گیری برنامه پر می‌کنیم. گزارش‌گیری از بسته logging کلاسیک پایتون استفاده می‌کند. در حالی که در محیط تولید خود ممکن است از چارچوب گزارش‌گیری متفاوتی استفاده کنید، اصول یکسان هستند.

بسته logging پایتون نمی‌داند که باید وقایع را در Google Cloud بنویسد. این بسته از نوشتن در خروجی استاندارد (به طور پیش‌فرض stderr ) یا در یک فایل پشتیبانی می‌کند. با این حال، Cloud Run قابلیت ثبت اطلاعات چاپ شده در خروجی استاندارد و ارسال خودکار آن به Cloud Logging را دارد. برای افزودن قابلیت‌های ثبت وقایع به برنامه Gen AI خود، دستورالعمل‌های زیر را دنبال کنید.

به پنجره (یا برگه) «پوسته ابری» در مرورگر خود برگردید.
در ترمینال، main.py دوباره باز کنید:
```
cloudshell edit ~/codelab-o11y/main.py
```
تغییرات زیر را در کد برنامه اعمال کنید:
1. آخرین دستور import را پیدا کنید. باید خط ۵ باشد:
```
from vertexai.generative_models import GenerativeModel
```
  مکان نما را روی خط بعدی (خط 6) قرار دهید و بلوک کد زیر را در آنجا قرار دهید.
```
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)
```
2. کدی را که مدل را برای تولید محتوا فراخوانی می‌کند، پیدا کنید. باید خط 30 باشد:
```
response = model.generate_content(prompt)
```
  مکان‌نما را در ابتدای خط NEXT (خط ۳۱) قرار دهید و قطعه کد زیر را در آنجا قرار دهید.
```
    json_fields = {
         'animal': animal,
         'prompt': prompt,
         'response': response.to_dict(),
    }
    logger.debug('content is generated', extra={'json_fields': json_fields})
```
  نکته: این بلوک کد برای قرار گرفتن در متد fun_fact() تورفتگی دارد. اگر خطایی در تورفتگی وجود داشته باشد، ویرایشگر Cloud Shell خط منحنی قرمز رنگی را برای علامت‌گذاری ناحیه مشکل‌دار نشان می‌دهد. تورفتگی را به صورت دستی و با پیروی از سینتکس پایتون تنظیم کنید.
این تغییرات، گزارش‌گیری استاندارد پایتون را طوری پیکربندی می‌کنند که از یک قالب‌بندی سفارشی برای تولید JSON رشته‌ای که از دستورالعمل‌های قالب‌بندی ساختاریافته پیروی می‌کند، استفاده کند. گزارش‌گیری به گونه‌ای پیکربندی شده است که گزارش‌ها را در stdout چاپ کند، جایی که توسط عامل گزارش‌گیری Cloud Run جمع‌آوری شده و به صورت ناهمگام به Cloud Logging وارد می‌شود. گزارش‌ها پارامتر animal درخواست و اعلان و پاسخ مدل را ثبت می‌کنند. پس از چند ثانیه، ویرایشگر Cloud Shell تغییرات شما را به طور خودکار ذخیره می‌کند.

کد برنامه 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 نمایش داده شده را در یک تب یا پنجره جداگانه در مرورگر خود کپی کنید. روش دیگر، اجرای دستور زیر در ترمینال برای چاپ آدرس اینترنتی سرویس و کلیک بر روی آدرس اینترنتی نشان داده شده در حالی که کلید Ctrl را نگه داشته‌اید تا آدرس اینترنتی باز شود:
```
gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
```
وقتی URL باز می‌شود، ممکن است خطای ۵۰۰ دریافت کنید یا پیام زیر را ببینید:
```
Sorry, this is just a placeholder...
```
این یعنی سرویس‌ها هنوز استقرار خود را به پایان نرسانده اند. چند لحظه صبر کنید و صفحه را رفرش کنید. در پایان متنی را خواهید دید که با «دانستنی‌های جالب درباره سگ‌ها» شروع می‌شود و شامل ۱۰ حقیقت جالب درباره سگ‌ها است.

برای ایجاد گزارش‌های برنامه، URL سرویس را باز کنید. صفحه را رفرش کنید و در عین حال مقدار پارامتر ?animal= را تغییر دهید تا نتایج متفاوتی دریافت کنید.
برای مشاهده لاگ‌های برنامه، مراحل زیر را انجام دهید:

برای باز کردن صفحه کاوشگر گزارش‌ها در کنسول ابری، روی دکمه زیر کلیک کنید:
فیلتر زیر را در کادر Query (شماره ۲ در رابط Log explorer ) قرار دهید:
```
LOG_ID("run.googleapis.com%2Fstdout") AND
severity=DEBUG
```
روی اجرای پرس‌وجو کلیک کنید.

نتیجه‌ی پرس‌وجو، گزارش‌هایی با پاسخ سریع و هوش مصنوعی Vertex شامل رتبه‌بندی‌های ایمنی را نشان می‌دهد.

۹. تعاملات با هوش مصنوعی نسل جدید را بشمارید

Cloud Run معیارهای مدیریت‌شده‌ای را می‌نویسد که می‌توانند برای نظارت بر سرویس‌های مستقر استفاده شوند. معیارهای نظارت مدیریت‌شده توسط کاربر، کنترل بیشتری بر داده‌ها و فرکانس به‌روزرسانی معیار ارائه می‌دهند. برای پیاده‌سازی چنین معیاری، نیاز به نوشتن کدی است که داده‌ها را جمع‌آوری کرده و در Cloud Monitoring می‌نویسد. برای نحوه پیاده‌سازی آن با استفاده از OpenTelemetry SDK، به مرحله بعدی (اختیاری) مراجعه کنید.

این مرحله جایگزینی برای پیاده‌سازی معیار کاربر در کد - معیارهای مبتنی بر گزارش - را نشان می‌دهد. معیارهای مبتنی بر گزارش به شما امکان می‌دهند معیارهای نظارتی را از ورودی‌های گزارش که برنامه شما در Cloud Logging می‌نویسد، ایجاد کنید. ما از گزارش‌های برنامه که در مرحله قبل پیاده‌سازی کردیم، برای تعریف یک معیار مبتنی بر گزارش از نوع شمارنده استفاده خواهیم کرد. این معیار تعداد تماس‌های موفق با Vertex API را شمارش می‌کند.

به پنجره‌ی کاوشگر لاگ‌ها که در مرحله‌ی قبل استفاده کردیم، نگاه کنید. در زیر پنل کوئری، منوی کشویی Actions را پیدا کرده و روی آن کلیک کنید تا باز شود. برای یافتن این منو، به تصویر زیر مراجعه کنید:
در منوی باز شده، گزینه « ایجاد معیار» را انتخاب کنید تا پنل «ایجاد معیار مبتنی بر گزارش» باز شود.
برای پیکربندی یک معیار شمارنده جدید در پنل ایجاد معیار مبتنی بر گزارش ، این مراحل را دنبال کنید:
1. نوع متریک را تنظیم کنید: شمارنده را انتخاب کنید.
2. فیلدهای زیر را در بخش جزئیات تنظیم کنید:
  - نام معیار ثبت وقایع : نام را روی model_interaction_count تنظیم کنید. برخی محدودیت‌های نامگذاری اعمال می‌شود؛ برای جزئیات بیشتر به بخش «عیب‌یابی محدودیت‌های نامگذاری» مراجعه کنید.
  - توضیحات : توضیحی برای معیار وارد کنید. به عنوان مثال، Number of log entries capturing successful call to model inference.
  - واحدها : این قسمت را خالی بگذارید یا رقم 1 را وارد کنید.
3. مقادیر را در بخش انتخاب فیلتر رها کنید. توجه داشته باشید که فیلد فیلتر ساخت همان فیلتری را دارد که برای دیدن گزارش‌های برنامه استفاده کردیم.
4. (اختیاری) برچسبی اضافه کنید که به شمارش تعداد صداهای هر حیوان کمک کند. توجه: این برچسب پتانسیل افزایش شدید کاردینالیتی معیار را دارد و برای استفاده در تولید توصیه نمی‌شود:
  1. روی افزودن برچسب کلیک کنید.
  2. فیلدهای زیر را در بخش برچسب‌ها تنظیم کنید:
    - نام برچسب : نام را روی animal تنظیم کنید.
    - توضیحات : توضیحات برچسب را وارد کنید. برای مثال، Animal parameter .
    - نوع برچسب : STRING را انتخاب کنید.
    - نام فیلد : نوع jsonPayload.animal را وارد کنید.
    - عبارت منظم : آن را خالی بگذارید.
  3. کلیک کنید انجام شد
5. برای ایجاد معیار، روی «ایجاد معیار» کلیک کنید.

همچنین می‌توانید با استفاده از دستور gcloud logging metrics create CLI در gcloud یا با استفاده از google_logging_metric Terraform resource ، یک معیار مبتنی بر گزارش از صفحه معیارهای مبتنی بر گزارش ایجاد کنید.

برای تولید داده‌های معیار، URL سرویس را باز کنید. برای برقراری چندین فراخوانی به مدل، صفحه باز شده را چندین بار رفرش کنید. مانند قبل، سعی کنید از حیوانات مختلف در پارامتر استفاده کنید.

برای جستجوی داده‌های متریک مبتنی بر لاگ، عبارت PromQL را وارد کنید. برای وارد کردن یک عبارت PromQL، مراحل زیر را انجام دهید:

برای باز کردن صفحه مرورگر معیارها در کنسول ابری، روی دکمه زیر کلیک کنید:
در نوار ابزار پنل query-builder، دکمه‌ای که نام آن < > MQL یا < > PromQL است را انتخاب کنید. برای مشاهده محل دکمه، به تصویر زیر مراجعه کنید.
مطمئن شوید که PromQL در قسمت زبان (Language) انتخاب شده باشد. این قسمت در همان نوار ابزاری قرار دارد که به شما امکان قالب‌بندی کوئری (query) را می‌دهد.
پرس‌وجوی خود را در ویرایشگر پرس‌وجوها وارد کنید:
```
sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
```
برای اطلاعات بیشتر در مورد استفاده از PromQL، به PromQL در Cloud Monitoring مراجعه کنید.
روی اجرای پرس‌وجو کلیک کنید. نمودار خطی مشابه این تصویر را مشاهده خواهید کرد:

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

۱۰. (اختیاری) استفاده از Open Telemetry برای نظارت و ردیابی

همانطور که در مرحله قبل ذکر شد، می‌توان معیارها را با استفاده از OpenTelemetry (Otel) SDK پیاده‌سازی کرد. استفاده از OTel در معماری‌های میکروسرویس یک روش توصیه شده است. این مرحله موارد زیر را شرح می‌دهد:

مقداردهی اولیه اجزای OTel برای پشتیبانی از ردیابی و نظارت بر برنامه
پر کردن پیکربندی Otel با ابرداده منابع محیط Cloud Run
کاربرد فلاسک ابزار دقیق با قابلیت ردیابی خودکار
پیاده‌سازی یک معیار شمارنده برای نظارت بر تعدادی از فراخوانی‌های موفق مدل
مرتبط کردن ردیابی با لاگ‌های برنامه

معماری پیشنهادی برای سرویس‌های سطح محصول، استفاده از OTel collector برای جمع‌آوری و دریافت تمام داده‌های مشاهده‌پذیری برای یک یا چند سرویس است. کد موجود در این مرحله به دلیل سادگی از collector استفاده نمی‌کند. در عوض از OTel exportها استفاده می‌کند که داده‌ها را مستقیماً در Google Cloud می‌نویسند.

راه‌اندازی اجزای Otel برای ردیابی و نظارت بر معیارها

به پنجره (یا برگه) «پوسته ابری» در مرورگر خود برگردید.

در ترمینال، فایل requirements.txt را با لیست اضافی از وابستگی‌ها به‌روزرسانی کنید:

cat >> ~/codelab-o11y/requirements.txt << EOF
opentelemetry-api==1.24.0
opentelemetry-sdk==1.24.0
opentelemetry-exporter-otlp-proto-http==1.24.0
opentelemetry-instrumentation-flask==0.45b0
opentelemetry-instrumentation-requests==0.45b0
opentelemetry-exporter-gcp-trace==1.7.0
opentelemetry-exporter-gcp-monitoring==1.7.0a0   
EOF

یک فایل جدید setup_opentelemetry.py ایجاد کنید:
```
cloudshell edit ~/codelab-o11y/setup_opentelemetry.py
```
اکنون باید یک فایل خالی در پنجره ویرایشگر بالای ترمینال ظاهر شود.

کد زیر را کپی کرده و در فایل setup_opentelemetry.py باز شده قرار دهید:

import os

from opentelemetry import metrics
from opentelemetry import trace
from opentelemetry.exporter.cloud_monitoring import CloudMonitoringMetricsExporter
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.resourcedetector.gcp_resource_detector import GoogleCloudResourceDetector
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import get_aggregated_resources, Resource, CLOUD_ACCOUNT_ID, SERVICE_NAME
from opentelemetry.sdk.trace.export import BatchSpanProcessor

resource = get_aggregated_resources(
    [GoogleCloudResourceDetector(raise_on_error=True)]
)
resource = resource.merge(Resource.create(attributes={
    SERVICE_NAME: os.getenv("K_SERVICE"),
}))

meter_provider = MeterProvider(
    resource=resource,
    metric_readers=[
        PeriodicExportingMetricReader(
            CloudMonitoringMetricsExporter(), export_interval_millis=5000
        )
    ],
)
metrics.set_meter_provider(meter_provider)
meter = metrics.get_meter(__name__)

trace_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(CloudTraceSpanExporter(
    # send all resource attributes
    resource_regex=r".*"
))
trace_provider.add_span_processor(processor)
trace.set_tracer_provider(trace_provider)

def google_trace_id_format(trace_id: int) -> str:
    project_id = resource.attributes[CLOUD_ACCOUNT_ID]
    return f'projects/{project_id}/traces/{trace.format_trace_id(trace_id)}'

پس از چند ثانیه، ویرایشگر Cloud Shell کد شما را به طور خودکار ذخیره می‌کند.

کد برنامه ابزار دقیق با قابلیت ردیابی و نظارت با استفاده از OTel

در ترمینال، main.py دوباره باز کنید:
```
cloudshell edit ~/codelab-o11y/main.py
```
تغییرات زیر را در کد برنامه اعمال کنید:
1. قبل از خط import os (خط ۱)، کد زیر را وارد کنید (به خط خالی در انتها توجه کنید):
```
from setup_opentelemetry import google_trace_id_format
from opentelemetry import metrics, trace
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.instrumentation.flask import FlaskInstrumentor
```
2. پس از تعریف متد format() (خط 9)، کد زیر را وارد کنید (با رعایت تورفتگی):
```
        span = trace.get_current_span()
```
3. بعد از خط ۱۳ (حاوی "message": record.getMessage() ) کد زیر را (با رعایت تورفتگی) وارد کنید:
```
            "logging.googleapis.com/trace": google_trace_id_format(span.get_span_context().trace_id),
            "logging.googleapis.com/spanId": trace.format_span_id(span.get_span_context().span_id),
```
  این دو ویژگی اضافی به مرتبط کردن لاگ‌های برنامه و بازه‌های ردیابی OTel کمک می‌کنند.
4. بعد از خط app = Flask(__name__) ‎ (خط ۳۱) کد زیر را وارد کنید:
```
FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()
```
  این خطوط، تمام درخواست‌های ورودی و خروجی برنامه فلاسک ما را با ردیابی، ابزاربندی می‌کنند.
5. درست بعد از کد جدید اضافه شده (بعد از خط ۳۳) کد زیر را اضافه کنید:
```
meter = metrics.get_meter(__name__)
requests_counter = meter.create_counter(
    name="model_call_counter",
    description="number of model invocations",
    unit="1"
)
```
  این خطوط یک معیار جدید از نوع شمارنده با نام model_call_counter ایجاد کرده و آن را برای صادرات ثبت می‌کنند.
6. پس از فراخوانی logger.debug() (خط ۴۹)، کد زیر را وارد کنید:
```
    requests_counter.add(1, {'animal': animal})
```
  این تغییر، هر بار که برنامه با موفقیت Vertex API را برای تعامل با مدل Gemini فراخوانی کند، شمارنده را ۱ واحد افزایش می‌دهد.

کد برنامه 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 نمایش داده شده را در یک تب یا پنجره جداگانه در مرورگر خود کپی کنید. روش دیگر، اجرای دستور زیر در ترمینال برای چاپ آدرس اینترنتی سرویس و کلیک بر روی آدرس اینترنتی نشان داده شده در حالی که کلید Ctrl را نگه داشته‌اید تا آدرس اینترنتی باز شود:
```
gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
```
وقتی URL باز می‌شود، ممکن است خطای ۵۰۰ دریافت کنید یا پیام زیر را ببینید:
```
Sorry, this is just a placeholder...
```
این یعنی سرویس‌ها هنوز استقرار خود را به پایان نرسانده اند. چند لحظه صبر کنید و صفحه را رفرش کنید. در پایان متنی را خواهید دید که با «دانستنی‌های جالب درباره سگ‌ها» شروع می‌شود و شامل ۱۰ حقیقت جالب درباره سگ‌ها است.

برای تولید داده‌های تله‌متری، URL سرویس را باز کنید. صفحه را رفرش کنید و در عین حال مقدار پارامتر ?animal= را تغییر دهید تا نتایج متفاوتی دریافت کنید.

کاوش ردپاهای برنامه

برای باز کردن صفحه Trace explorer در کنسول Cloud، روی دکمه زیر کلیک کنید:
یکی از جدیدترین ردپاها را انتخاب کنید. قرار است ۵ یا ۶ دهانه مانند تصویر زیر ببینید.
دهانه‌ای را پیدا کنید که فراخوانی را تا کنترل‌کننده رویداد (متد fun_facts ) ردیابی می‌کند. این آخرین دهانه با نام / خواهد بود.
در پنل جزئیات ردیابی، Logs & events را انتخاب کنید. گزارش‌های برنامه‌ای را خواهید دید که با این span خاص مرتبط هستند. این ارتباط با استفاده از شناسه‌های trace و span در trace و log شناسایی می‌شود. قرار است گزارش برنامه‌ای که prompt را نوشته و پاسخ Vertex API را ببینید.

متریک شمارنده را بررسی کنید

برای باز کردن صفحه مرورگر معیارها در کنسول ابری، روی دکمه زیر کلیک کنید:
در نوار ابزار پنل query-builder، دکمه‌ای که نام آن < > MQL یا < > PromQL است را انتخاب کنید. برای مشاهده محل دکمه، به تصویر زیر مراجعه کنید.
مطمئن شوید که PromQL در قسمت زبان (Language) انتخاب شده باشد. این قسمت در همان نوار ابزاری قرار دارد که به شما امکان قالب‌بندی کوئری (query) را می‌دهد.

پرس‌وجوی خود را در ویرایشگر پرس‌وجوها وارد کنید:

sum(rate(workload_googleapis_com:model_call_counter{monitored_resource="generic_task"}[${__interval}]))

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

۱۱. (اختیاری) اطلاعات حساس مبهم‌سازی‌شده از لاگ‌ها

در مرحله 10، اطلاعات مربوط به تعامل برنامه با مدل Gemini را ثبت کردیم. این اطلاعات شامل نام حیوان، اعلان واقعی و پاسخ مدل بود. اگرچه ذخیره این اطلاعات در گزارش باید ایمن باشد، اما برای بسیاری از سناریوهای دیگر لزوماً صحیح نیست. اعلان ممکن است شامل برخی اطلاعات شخصی یا حساس باشد که کاربر نمی‌خواهد ذخیره شود. برای رفع این مشکل، می‌توانید داده‌های حساسی را که در Cloud Logging نوشته می‌شوند، مبهم‌سازی کنید. برای به حداقل رساندن تغییرات کد، راه حل زیر توصیه می‌شود.

یک تاپیک PubSub برای ذخیره ورودی‌های لاگ ایجاد کنید
یک مخزن لاگ ایجاد کنید که لاگ‌های دریافت‌شده را به تاپیک PubSub هدایت کند.
یک خط لوله Dataflow ایجاد کنید که گزارش‌های هدایت‌شده به موضوع PubSub را با دنبال کردن مراحل زیر تغییر دهد:
1. خواندن یک ورودی لاگ از مبحث PubSub
2. با استفاده از API بازرسی DLP، اطلاعات حساس مربوط به payload ورودی را بررسی کنید.
3. اطلاعات حساس موجود در پیلود را با استفاده از یکی از روش‌های ویرایش DLP ویرایش کنید.
4. ورودی لاگ مبهم‌سازی‌شده را در Cloud Logging بنویسید
خط لوله را مستقر کنید

۱۲. (اختیاری) تمیز کردن

برای جلوگیری از خطر متحمل شدن هزینه‌های مربوط به منابع و APIهای مورد استفاده در آزمایشگاه کد، توصیه می‌شود پس از اتمام آزمایشگاه، آن را پاکسازی کنید. ساده‌ترین راه برای حذف هزینه‌ها، حذف پروژه‌ای است که برای آزمایشگاه کد ایجاد کرده‌اید.

احتیاط : حذف یک پروژه اثرات زیر را دارد:

– همه چیز در پروژه حذف می‌شود . اگر از یک پروژه موجود برای وظایف موجود در این سند استفاده کرده‌اید، هنگام حذف آن، هر کار دیگری را که در پروژه انجام داده‌اید نیز حذف می‌کنید.
– شناسه‌های پروژه سفارشی از بین می‌روند . هنگام ایجاد این پروژه، ممکن است یک شناسه پروژه سفارشی ایجاد کرده باشید که می‌خواهید در آینده از آن استفاده کنید. برای حفظ URLهایی که از شناسه پروژه استفاده می‌کنند، مانند URL appspot.com، منابع انتخاب شده را در داخل پروژه به جای حذف کل پروژه حذف کنید.

اگر قصد دارید برنامه‌ای را که ایجاد کرده‌اید بررسی کنید، استفاده مجدد از پروژه می‌تواند در زمان شما صرفه‌جویی کند و به شما کمک کند از محدودیت‌های سهمیه پروژه فراتر نروید.

برای حذف پروژه، دستور delete project را در ترمینال اجرا کنید:

PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete ${PROJECT_ID} --quiet

حذف پروژه ابری شما، پرداخت هزینه برای تمام منابع و APIهای استفاده شده در آن پروژه را متوقف می‌کند. باید این پیام را ببینید که در آن 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.

(اختیاری) اگر با خطایی مواجه شدید، برای یافتن شناسه پروژه‌ای که در طول آزمایش استفاده کرده‌اید، به مرحله ۵ مراجعه کنید. آن را با دستور موجود در دستورالعمل اول جایگزین کنید. برای مثال، اگر شناسه پروژه شما lab-example-project باشد، دستور به صورت زیر خواهد بود:
```
gcloud projects delete lab-project-id-example --quiet
```

۱۳. تبریک

در این آزمایشگاه، شما یک برنامه Gen AI ایجاد کردید که از مدل Gemini برای پیش‌بینی استفاده می‌کند. و برنامه را با قابلیت‌های ضروری نظارت و ثبت وقایع تجهیز کردید. برنامه و تغییرات آن را از کد منبع به Cloud Run منتقل کردید. سپس از محصولات Google Cloud Observability برای ردیابی عملکرد برنامه استفاده کردید تا از قابلیت اطمینان برنامه اطمینان حاصل کنید.

اگر علاقه‌مند به شرکت در یک مطالعه تحقیقاتی تجربه کاربری (UX) برای بهبود محصولاتی که امروز با آنها کار کرده‌اید هستید، اینجا ثبت نام کنید .

در اینجا چند گزینه برای ادامه تحصیل شما وجود دارد:

Codelab نحوه استقرار برنامه چت مبتنی بر Gemini در Cloud Run
Codelab نحوه استفاده از فراخوانی تابع Gemini با Cloud Run
نحوه استفاده از API هوش ویدیویی Cloud Run Jobs برای پردازش صحنه به صحنه یک ویدیو
کارگاه آموزشی بر اساس تقاضا ، موتور کوبرنتیز گوگل (Google Kubernetes Engine) به صورت آنبورد
درباره پیکربندی شمارنده و معیارهای توزیع با استفاده از گزارش‌های برنامه بیشتر بدانید
نوشتن معیارهای OTLP با استفاده از یک محفظه کناری OpenTelemetry
اشاره به استفاده از Open Telemetry در Google Cloud