به طور خودکار برنامه وب Node.js Genkit AI مولد را از Version Control تا Cloud Run اجرا کنید

1. بررسی اجمالی

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

در این آزمایشگاه، شما یک برنامه وب می نویسید و Cloud Run را پیکربندی می کنید تا زمانی که تغییری در کد منبع برنامه شما ایجاد می شود، برنامه شما به طور خودکار اجرا شود. سپس برنامه خود را تغییر داده و دوباره آن را مستقر می کنید.

آنچه خواهید آموخت

  • با Cloud Shell Editor یک برنامه وب بنویسید
  • کد برنامه خود را در GitHub ذخیره کنید
  • به طور خودکار برنامه خود را در Cloud Run مستقر کنید
  • با استفاده از Genkit هوش مصنوعی مولد را به برنامه خود اضافه کنید
  • دستورات LLM را با استفاده از کتابخانه dotprompt مدیریت کنید

2. پیش نیازها

  1. اگر قبلاً یک حساب Google ندارید، باید یک حساب Google ایجاد کنید .
    • از حساب شخصی به جای حساب کاری یا مدرسه استفاده کنید. حساب‌های محل کار و مدرسه ممکن است محدودیت‌هایی داشته باشند که شما را از فعال کردن APIهای مورد نیاز برای این آزمایشگاه باز می‌دارد.
  2. اگر قبلاً یک حساب GitHub ندارید، باید یک حساب GitHub ایجاد کنید

3. راه اندازی پروژه

  1. به Google Cloud Console وارد شوید.
  2. صورتحساب را در کنسول Cloud فعال کنید .
    • تکمیل این آزمایشگاه باید کمتر از 1 دلار آمریکا در منابع Cloud هزینه داشته باشد.
    • برای جلوگیری از هزینه های بیشتر، می توانید مراحل انتهای این آزمایشگاه را برای حذف منابع دنبال کنید.
    • کاربران جدید واجد شرایط استفاده از نسخه آزمایشی رایگان 300 دلاری هستند.
    • در رویداد Gen AI for Devs شرکت می کنید؟ اعتبار 1 دلاری ممکن است در دسترس باشد.
  3. یک پروژه جدید ایجاد کنید یا استفاده مجدد از یک پروژه موجود را انتخاب کنید.

4. Cloud Shell Editor را باز کنید

  1. به Cloud Shell Editor بروید
  2. اگر ترمینال در پایین صفحه ظاهر نشد، آن را باز کنید:
    • روی منوی همبرگر کلیک کنید نماد منوی همبرگر
    • روی ترمینال کلیک کنید
    • روی New Terminal کلیک کنید ترمینال جدید را در Cloud Shell Editor باز کنید
  3. در ترمینال، پروژه خود را با این دستور تنظیم کنید:
    • قالب:
      gcloud config set project [PROJECT_ID]
    • مثال:
      gcloud config set project lab-project-id-example
    • اگر نمی توانید شناسه پروژه خود را به خاطر بسپارید:
      • می توانید تمام شناسه های پروژه خود را با موارد زیر فهرست کنید:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      شناسه پروژه را در ترمینال Cloud Shell Editor تنظیم کنید
  4. اگر از شما خواسته شد که مجوز دهید، برای ادامه روی تأیید کلیک کنید. برای تأیید Cloud Shell کلیک کنید
  5. شما باید این پیام را ببینید:
    Updated property [core/project].
    اگر یک WARNING مشاهده کردید و از شما پرسیده شد Do you want to continue (Y/N)? ، پس احتمالاً شناسه پروژه را اشتباه وارد کرده اید. N را فشار دهید، Enter فشار دهید و دوباره دستور gcloud config set project را اجرا کنید.

5. API ها را فعال کنید

در ترمینال، API ها را فعال کنید:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com

تکمیل این دستور ممکن است چند دقیقه طول بکشد، اما در نهایت باید یک پیام موفقیت آمیز مشابه این پیام تولید کند: 

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. Git را پیکربندی کنید

  1. ایمیل کاربر git جهانی خود را تنظیم کنید:
    git config --global user.email "you@example.com"
  2. نام کاربری git جهانی خود را تنظیم کنید:
    git config --global user.name "Your Name"
  3. شاخه پیش‌فرض global git خود را روی main قرار دهید:
    git config --global init.defaultBranch main

7. کد خود را بنویسید

برای نوشتن برنامه در Node.js:

  1. به فهرست اصلی بروید:
    cd ~
  2. پوشه codelab-genai را ایجاد کنید:
    mkdir codelab-genai
  3. به دایرکتوری codelab-genai بروید:
    cd codelab-genai
  4. یک فایل index.js ایجاد کنید:
    touch index.js
  5. فایل package.json را ایجاد کنید:
    npm init es6 -y
  6. express به عنوان یک وابستگی اضافه کنید
    npm install express
  7. برای جلوگیری از ارتکاب node_modules فایل .gitignore را اضافه کنید
    echo node_modules/ >> .gitignore
  8. فایل index.js را در Cloud Shell Editor باز کنید:
    cloudshell edit index.js
    اکنون باید یک فایل خالی در قسمت بالای صفحه ظاهر شود. اینجا جایی است که می توانید این فایل index.js را ویرایش کنید. نشان دهید که کد در قسمت بالای صفحه نمایش داده می شود
  9. کد زیر را کپی کرده و در فایل باز شده index.js قرار دهید:
    import express from 'express';

const app = express();
app.get('/', async (req, res) => {
    res.send('Hello world!');
});

const port = process.env.PORT || 8080;
app.listen(port, () => {
    console.log(`codelab-genai: listening on port ${port}`);
});
    پس از چند ثانیه، Cloud Shell Editor کد شما را به صورت خودکار ذخیره می کند. این کد به درخواست های http با "سلام جهان!" ما پاسخ می دهد. احوالپرسی.

کد اولیه برنامه شما به پایان رسیده و آماده ذخیره در نسخه کنترل است.

8. یک مخزن ایجاد کنید

  1. به ترمینال Cloud Shell در پایین صفحه خود بازگردید.
  2. مطمئن شوید که هنوز در دایرکتوری صحیح هستید:
    cd ~/codelab-genai
  3. مخزن git خود را راه اندازی کنید
    git init -b main
  4. وارد GitHub CLI شوید
    gh auth login
    Enter فشار دهید تا گزینه های پیش فرض را بپذیرید و دستورالعمل های موجود در ابزار GitHub CLI را دنبال کنید، از جمله:
    1. به چه حسابی می خواهید وارد شوید؟ GitHub.com
    2. پروتکل ترجیحی شما برای عملیات Git در این میزبان چیست؟ HTTPS
    3. Git را با اعتبار GitHub خود تأیید کنید؟ Y (اگر این مورد نشان داده نشد از آن بگذرید.)
    4. چگونه می خواهید GitHub CLI را احراز هویت کنید؟ Login with a web browser
    5. کد یکبار مصرف خود را کپی کنید
    6. https://github.com/login/device را باز کنید
    7. کد یکبار مصرف خود را جایگذاری کنید
    8. روی Authorize github کلیک کنید
    9. ورود خود را کامل کنید
  5. تایید کنید که وارد سیستم شده اید:
    gh api user -q ".login"
    اگر با موفقیت وارد سیستم شده اید، این باید نام کاربری GitHub شما را خروجی کند.
  6. یک متغیر GITHUB_USERNAME ایجاد کنید
    GITHUB_USERNAME=$(gh api user -q ".login")
  7. تأیید کنید که متغیر محیطی را ایجاد کرده اید:
    echo ${GITHUB_USERNAME}
    اگر متغیر را با موفقیت ایجاد کرده اید، باید نام کاربری GitHub شما را خروجی کند.
  8. یک مخزن خالی GitHub با نام codelab-genai ایجاد کنید:
    gh repo create codelab-genai --private
    اگر خطا را دریافت کردید:
    GraphQL: Name already exists on this account (createRepository)
    سپس شما از قبل یک مخزن به نام codelab-genai دارید. برای ادامه این آموزش دو گزینه دارید:
  9. مخزن codelab-genai را به عنوان origin راه دور اضافه کنید:
    git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai

9. کد خود را به اشتراک بگذارید

  1. تأیید کنید که در دایرکتوری صحیح هستید:
    cd ~/codelab-genai
  2. تمام فایل های موجود در فهرست فعلی را به این commit اضافه کنید:
    git add .
  3. اولین commit را ایجاد کنید:
    git commit -m "add http server"
  4. commit خود را به شاخه main مخزن origin فشار دهید:
    git push -u origin main

می‌توانید این دستور را اجرا کنید و از URL حاصل بازدید کنید تا کد برنامه خود را در GitHub مشاهده کنید: 

echo -e "\n\nTo see your code, visit this URL:\n \
    https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/index.js \n\n"

10. استقرار خودکار را تنظیم کنید

  1. برگه Cloud Shell Editor را باز بگذارید. بعداً به این برگه باز خواهیم گشت.
  2. در یک تب جدید، از صفحه Cloud Run دیدن کنید
  3. Google Cloud Project صحیح را در کنسول انتخاب کنید کشویی پروژه Google Cloud Console
  4. روی CONNECT REPO کلیک کنید
  5. روی SET UP WITH CLOUD BUILD کلیک کنید
    1. GitHub را به عنوان ارائه دهنده مخزن انتخاب کنید
      • اگر به حساب GitHub خود در مرورگر وارد نشده اید، با اطلاعات کاربری خود وارد شوید.
    2. روی Authenticate و سپس Continue کلیک کنید.
    3. پس از ورود به سیستم، پیامی را در صفحه Cloud Run مشاهده خواهید کرد مبنی بر اینکه برنامه GitHub در هیچ یک از مخازن شما نصب نشده است.
    4. روی دکمه INSTALL GOOGLE CLOUD BUILD کلیک کنید.
      • در صفحه راه اندازی نصب، فقط مخازن را انتخاب کنید و مخزن codelab-genai را که از طریق CLI ایجاد کرده اید انتخاب کنید.
      • بر روی Install کلیک کنید
      • توجه: اگر تعداد زیادی مخزن GitHub دارید، بارگیری آن ممکن است چند دقیقه طول بکشد.
    5. your-user-name/codelab-genai به عنوان مخزن انتخاب کنید
      • اگر مخزن موجود نیست، روی پیوند Manage Connected Repositories کلیک کنید.
    6. شعبه را به عنوان ^main$ ترک کنید
    7. روی Go، Node.js، Python، Java، NET Core، Ruby یا PHP از طریق بسته‌های ساخت Google Cloud کلیک کنید.
      • فیلدهای دیگر ( Build context directory ، Entrypoint و Function target ) را به همان شکلی که هستند رها کنید.
    8. روی ذخیره کلیک کنید
  6. به سمت پایین اسکرول کنید تا به Authentication بروید
  7. روی اجازه دادن به فراخوان‌های احراز هویت نشده کلیک کنید
  8. روی CREATE کلیک کنید

پس از اتمام ساخت (که چند دقیقه طول می کشد)، این دستور را اجرا کنید و برای مشاهده برنامه در حال اجرا خود، به 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"

11. کد خود را تغییر دهید

به Cloud Shell Editor برگردید

اگر هنوز Cloud Shell Editor را باز دارید، می توانید از این مراحل صرف نظر کنید.

  1. به Cloud Shell Editor بروید
  2. اگر ترمینال در پایین صفحه ظاهر نشد، آن را باز کنید:
    • روی منوی همبرگر کلیک کنید نماد منوی همبرگر
    • روی ترمینال کلیک کنید
    • روی New Terminal کلیک کنید ترمینال جدید را در Cloud Shell Editor باز کنید
  3. در ترمینال، پروژه خود را با این دستور تنظیم کنید:
    • قالب:
      gcloud config set project [PROJECT_ID]
    • مثال:
      gcloud config set project lab-project-id-example
    • اگر نمی توانید شناسه پروژه خود را به خاطر بسپارید:
      • می توانید تمام شناسه های پروژه خود را با موارد زیر فهرست کنید:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      شناسه پروژه را در ترمینال Cloud Shell Editor تنظیم کنید
  4. اگر از شما خواسته شد که مجوز دهید، برای ادامه روی تأیید کلیک کنید. برای تأیید Cloud Shell کلیک کنید
  5. شما باید این پیام را ببینید:
    Updated property [core/project].
    اگر یک WARNING مشاهده کردید و از شما پرسیده شد Do you want to continue (Y/N)? ، پس احتمالاً شناسه پروژه را اشتباه وارد کرده اید. N را فشار دهید، Enter فشار دهید و دوباره دستور gcloud config set project را اجرا کنید.

Vertex AI را به برنامه خود اضافه کنید

  1. به ترمینال Cloud Shell در پایین صفحه خود بازگردید.
  2. مطمئن شوید که هنوز در دایرکتوری صحیح هستید:
    cd ~/codelab-genai
  3. Node.js Genkit SDK را نصب کنید:
    npm install @genkit-ai/ai
  4. Node.js Genkit SDK را برای Vertex AI نصب کنید:
    npm install @genkit-ai/vertexai
  5. Node.js Google Auth SDK را نصب کنید:
    npm install google-auth-library
  6. index.js دوباره در ویرایشگر پوسته ابری باز کنید
    cloudshell edit ~/codelab-genai/index.js
  7. کد موجود در فایل index.js خود را با:
    import express from 'express';
const app = express();

import { generate } from '@genkit-ai/ai';
import { gemini15Flash, vertexAI } from '@genkit-ai/vertexai';

import { GoogleAuth } from 'google-auth-library';
const auth = new GoogleAuth();

app.get('/', async (req, res) => {
    const project = await auth.getProjectId();

    const animal = req.query.animal || 'dog';
    const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
    const result = await generate({
        plugins: [
            vertexAI({ projectId: project, location: 'us-central1' }),
        ],
        model: gemini15Flash,
        prompt,
    });
    const html = result.text;
    res.send(html);
});

const port = process.env.PORT || 8080;
app.listen(port, () => {
    console.log(`codelab-genai: listening on port ${port}`);
});

12. استقرار مجدد

  1. مطمئن شوید که هنوز در دایرکتوری صحیح در Cloud Shell هستید:
    cd ~/codelab-genai
  2. این دستورات را اجرا کنید تا نسخه جدیدی از برنامه خود را به مخزن git محلی خود اختصاص دهید:
    git add .
git commit -m "add latest changes"
  3. تغییرات را به GitHub فشار دهید:
    git push
  4. پس از اتمام ساخت، این دستور را اجرا کنید و از برنامه مستقر شده خود بازدید کنید:
    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

13. (اختیاری) استفاده از Vertex AI خود را بررسی کنید

مانند سایر سرویس‌های Google Cloud، می‌توانید عملیات Vertex AI را بررسی کنید . گزارش های حسابرسی به شما کمک می کند به سؤالات «چه کسی، کجا و چه زمانی انجام داد؟» پاسخ دهید. گزارش های حسابرسی اداری برای Vertex AI به طور پیش فرض فعال هستند. برای بررسی درخواست‌ها برای تولید محتوا، باید برای فعال کردن گزارش‌های حسابرسی دسترسی به داده‌ها :

  1. در کنسول Google Cloud، به صفحه Audit Logs بروید:

    اگر از نوار جستجو برای یافتن این صفحه استفاده می کنید، نتیجه ای را انتخاب کنید که زیر عنوان آن IAM & Admin است.
  2. مطمئن شوید که پروژه Google Cloud موجود جایی است که برنامه Cloud Run خود را در آن ایجاد می کنید.
  3. در جدول پیکربندی گزارش های حسابرسی داده دسترسی ، Vertex AI API از ستون Service پیدا کنید.
  4. در برگه Log Types ، انواع گزارش حسابرسی دسترسی به داده ها را Admin read و Data read انتخاب کنید.
  5. روی ذخیره کلیک کنید.

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

  1. به برنامه مستقر شده خود برگردید و صفحه را بازخوانی کنید تا گزارش فعال شود.
  2. در کنسول Google Cloud، به صفحه Log Explorer بروید:

  3. در پنجره پرس و جو تایپ کنید:
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
protoPayload.serviceName="aiplatform.googleapis.com"
  4. روی Run query کلیک کنید.

گزارش‌های حسابرسی استفاده از Vertex AI API را نشان می‌دهند، اما به شما اجازه نمی‌دهند داده‌های مربوط به حجم کاری مانند درخواست‌ها یا جزئیات پاسخ را مشاهده کنید.

14. (اختیاری) قابلیت مشاهده بار کاری هوش مصنوعی خود را افزایش دهید

گزارش‌های حسابرسی اطلاعات مربوط به حجم کاری را دریافت نمی‌کنند. به منظور افزایش قابلیت مشاهده بارهای کاری خود، باید به صراحت این اطلاعات را ثبت کنید. برای این کار می توانید از چارچوب لاگ مورد علاقه خود استفاده کنید. مراحل زیر نحوه انجام آن را با استفاده از مکانیزم ثبت‌نام Node.js نشان می‌دهد.

  1. index.js دوباره در ویرایشگر پوسته ابری باز کنید
    cloudshell edit ~/codelab-genai/index.js
  2. پس از فراخوانی برای await generativeModel.generateContent(prompt) (خط 19) خط زیر را اضافه کنید:
        console.log(JSON.stringify({
        severity: 'DEBUG',
        message: 'Content is generated',
        prompt: prompt,
        response: resp.response,
    }));
    این کد در stdout اطلاعات مربوط به محتوای تولید شده را با استفاده از فرمت ثبت ساختار یافته می نویسد. یک عامل ورود به سیستم در Cloud Run خروجی چاپ شده در stdout را می گیرد و این قالب را در Cloud Logging می نویسد .
  3. دوباره Cloud Shell را باز کنید و دستور زیر را تایپ کنید تا مطمئن شوید که در دایرکتوری صحیح قرار دارید:
    cd ~/codelab-genai
  4. تغییرات را انجام دهید:
    git commit -am "observe generated content"
  5. تغییرات را به GitHub فشار دهید تا استقرار مجدد نسخه اصلاح شده را آغاز کنید:
    git push

پس از استقرار نسخه جدید، می توانید اطلاعات اشکال زدایی را در مورد تماس های Vertex AI مشاهده کنید.

برای مشاهده لاگ های برنامه خود به صورت زیر عمل کنید:

  1. در کنسول Google Cloud، به صفحه Log Explorer بروید:

  2. در پنجره پرس و جو تایپ کنید:
    LOG_ID("run.googleapis.com%2Fstdout")
severity=DEBUG
  3. روی Run query کلیک کنید.

نتیجه پرس و جو گزارش هایی را با پاسخ سریع و Vertex AI از جمله "رتبه بندی ایمنی" نشان می دهد که می تواند برای نظارت بر اقدامات ایمنی استفاده شود.

15. (اختیاری) پاکسازی کنید

در حالی که Cloud Run زمانی که از سرویس استفاده نمی‌شود شارژ نمی‌شود، ممکن است همچنان برای ذخیره تصویر ظرف در Artifact Registry هزینه دریافت کنید. برای جلوگیری از تحمیل هزینه، می توانید پروژه Cloud خود را حذف کنید. با حذف پروژه Cloud، صورت‌حساب تمام منابع مورد استفاده در آن پروژه متوقف می‌شود.

در صورت تمایل پروژه را حذف کنید:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

همچنین ممکن است بخواهید منابع غیر ضروری را از دیسک پوسته ابری خود حذف کنید. شما می توانید:

  1. دایرکتوری پروژه codelab را حذف کنید: 
    rm -rf ~/codelab-genai
  2. هشدار! این عمل قابل واگرد نیست! اگر می‌خواهید همه چیز را در Cloud Shell خود حذف کنید تا فضا آزاد شود، می‌توانید کل فهرست اصلی خود را حذف کنید . مراقب باشید هر چیزی که می خواهید نگه دارید در جای دیگری ذخیره شود. 
    sudo rm -rf $HOME

16. تبریک می گویم

در این آزمایشگاه، یک برنامه وب نوشتید و Cloud Run را پیکربندی کردید تا زمانی که تغییری در کد منبع برنامه شما ایجاد شد، برنامه شما به طور خودکار اجرا شود. سپس برنامه خود را تغییر دادید و دوباره آن را مستقر کردید.

اگر از این آزمایشگاه لذت بردید، می‌توانید دوباره آن را در یک زبان یا چارچوب کدنویسی دیگر امتحان کنید:

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

در اینجا چند گزینه برای ادامه یادگیری وجود دارد: