نحوه استقرار یک وب‌سایت رابط کاربری مولد (Generative UI) در Cloud Run

۱. مقدمه

نمای کلی

در این آزمایشگاه، شما وب‌سایتی را خواهید ساخت و مستقر خواهید کرد که محتوای آن توسط مدل‌های زبان بزرگ گوگل Gemini به صورت آنی تولید می‌شود. این وب‌سایت یک ناوبری ساده به سبک «ماجراجویی خود را انتخاب کنید» برای کاوش در موضوعات خواهد بود، که در آن هر کلیک، صفحه جدیدی با لینک‌های جدید بر اساس انتخاب شما ایجاد می‌کند. شما این وب‌سایت را با Node.js و Fastify خواهید ساخت، از Vertex AI SDK برای فراخوانی Gemini استفاده خواهید کرد، آن را به عنوان یک سرویس امن و آماده برای تولید در Cloud Run مستقر خواهید کرد و با استفاده از Identity-Aware Proxy (IAP) آن را ایمن خواهید کرد.

کاری که انجام خواهید داد

  • یک برنامه Node.js Fastify ایجاد کنید که از Vertex AI استفاده کند.
  • برنامه را از منبع و بدون Dockerfile روی Cloud Run مستقر کنید.
  • با استفاده از پروکسی آگاه از هویت (IAP)، نقطه پایانی Cloud Run را ایمن کنید.

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

  • نحوه استفاده از Vertex AI SDK برای Node.js برای تولید محتوا.
  • نحوه‌ی استقرار یک برنامه‌ی Node.js در Cloud Run.
  • چگونه یک برنامه Cloud Run را با IAP ایمن کنیم.

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

  1. اگر از قبل حساب گوگل ندارید، باید یک حساب گوگل ایجاد کنید .
    • به جای حساب کاری یا تحصیلی از یک حساب شخصی استفاده کنید. حساب‌های کاری و تحصیلی ممکن است محدودیت‌هایی داشته باشند که مانع از فعال کردن APIهای مورد نیاز برای این آزمایشگاه توسط شما شود.
  2. وارد کنسول ابری گوگل شوید.
  3. فعال کردن پرداخت در کنسول ابری
    • تکمیل این آزمایشگاه باید کمتر از ۱ دلار آمریکا از طریق منابع ابری هزینه داشته باشد.
    • شما می‌توانید مراحل انتهای این آزمایش را برای حذف منابع دنبال کنید تا از هزینه‌های بیشتر جلوگیری شود.
    • کاربران جدید واجد شرایط استفاده از دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
  4. یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید.
    • اگر در مورد سهمیه پروژه خطایی مشاهده کردید، از یک پروژه موجود دوباره استفاده کنید یا یک پروژه موجود را حذف کنید تا یک پروژه جدید ایجاد شود.

۳. ویرایشگر Cloud Shell را باز کنید

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

۴. فعال کردن APIها

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

gcloud services enable \
  run.googleapis.com \
  aiplatform.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iap.googleapis.com

اگر از شما خواسته شد که مجوز دهید، برای ادامه روی تأیید کلیک کنید. برای تأیید Cloud Shell کلیک کنید

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

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

۵. پروژه Node.js خود را آماده کنید

  1. پوشه‌ای به نام gen-ui-on-cloudrun ایجاد کنید تا کد منبع برای استقرار در آن ذخیره شود: 
    mkdir gen-ui-on-cloudrun && cd gen-ui-on-cloudrun
  2. یک پروژه Node.js را مقداردهی اولیه کنید: 
    npm init -y
  3. پروژه را طوری پیکربندی کنید که از ماژول‌های ES استفاده کند و با اجرای این دستورات، یک اسکریپت شروع تعریف کنید: 
    npm pkg set type="module"
  4. برای وب سرور، fastify و برای Vertex AI SDK، @google/genai را نصب کنید: 
    npm install fastify @google/genai

۶. کد برنامه را ایجاد کنید

  1. یک فایل index.ts جدید برای کد منبع برنامه ایجاد و باز کنید:
    cloudshell edit ~/gen-ui-on-cloudrun/index.ts
    دستور cloudshell edit فایل index.ts را در ویرایشگر بالای ترمینال باز می‌کند.
  2. کد منبع سرور رابط کاربری مولد زیر را در فایل index.ts اضافه کنید: 
    import fastifyLib from 'fastify';
import { GoogleGenAI } from '@google/genai';

const fastify = fastifyLib({ logger: true });

const ai = new GoogleGenAI({
    vertexai: true,
    project: process.env.GOOGLE_CLOUD_PROJECT,
    location: process.env.GOOGLE_CLOUD_LOCATION || 'europe-west1',
});

const SYSTEM_INSTRUCTION = `The user should have submitted an html page and the id of the element just clicked.
Given the next page description, create a new webpage with a link back to "Start Over" (the / route), a brief overview of the topic, and a list of clickable link elements related to the page.
When an element is clicked, the webpage should link to the base route / with the nextPageDescription as a query string parameter.
All information needed to generate the next page should be included in the nextPageDescription without additional context.
Each nextPageDescription should be less than 1500 characters.

Example:
If the current HTML page is for a small pet store, it might include a link to an "About" page.
The href for the about page link should be /?nextPageDescription=about%20page%20for%20small%20pet%20store%20website

All responses should be valid HTML without markdown backticks.`;

interface QueryParams {
    nextPageDescription?: string;
}

fastify.get<{ Querystring: QueryParams }>('/', async (request, reply) => {
    const {
        nextPageDescription = 'A web page with interesting fun facts where I can select a fact to learn more about that topic.'
    } = request.query;

    try {
        const response = await ai.models.generateContent({
            model: 'gemini-2.5-flash',
            contents: nextPageDescription,
            config: {
                systemInstruction: SYSTEM_INSTRUCTION,
                temperature: 0.9,
            }
        });

        reply.type('text/html; charset=utf-8').send(response.text);
    } catch (error: any) {
        request.log.error(error);
        reply.status(500).send('An error occurred calling the AI.');
    }
});

const start = async () => {
    try {
        await fastify.listen({ port: Number(process.env.PORT) || 8080, host: '0.0.0.0' });
    } catch (err) {
        fastify.log.error(err);
        process.exit(1);
    }
};

start();

این کد یک وب سرور راه‌اندازی می‌کند که به درخواست‌های HTTP GET در مسیر ریشه ( / ) گوش می‌دهد. هنگامی که یک درخواست دریافت می‌شود، از پارامتر پرس‌وجوی nextPageDescription (یا یک مقدار پیش‌فرض) به عنوان اعلانی برای مدل Gemini 2.5 Flash از طریق Vertex AI استفاده می‌کند. این مدل توسط SYSTEM_INSTRUCTION دستور داده می‌شود تا یک صفحه HTML حاوی لینک‌ها را برگرداند، که در آن هر لینک شامل یک nextPageDescription برای تولید صفحه بعدی است.

۷. ایجاد حساب کاربری سرویس

برای تأیید اعتبار با API هوش مصنوعی Vertex، به یک حساب کاربری برای سرویس Cloud Run خود نیاز دارید.

  1. یک حساب کاربری سرویس با نام gen-navigator-sa ایجاد کنید: 
    gcloud iam service-accounts create gen-navigator-sa --display-name="Generative Navigator Service Account"
  2. به حساب کاربری سرویس، مجوز استفاده از Vertex AI را بدهید: 
    gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
    --member="serviceAccount:gen-navigator-sa@$GOOGLE_CLOUD_PROJECT.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

۸. استقرار در Cloud Run

اکنون برنامه را مستقیماً از کد منبع، بدون نیاز به Dockerfile، روی Cloud Run مستقر کنید.

  1. برای نصب برنامه، دستور gcloud را اجرا کنید:
    cd ~/gen-ui-on-cloudrun
gcloud beta run deploy generative-web-navigator \
    --source . \
    --no-build \
    --base-image=nodejs24 \
    --command="node" \
    --args="index.ts" \
    --region=europe-west1 \
    --no-allow-unauthenticated \
    --iap \
    --service-account="gen-navigator-sa@$GOOGLE_CLOUD_PROJECT.iam.gserviceaccount.com" \
    --set-env-vars GOOGLE_CLOUD_PROJECT="$GOOGLE_CLOUD_PROJECT",GOOGLE_CLOUD_LOCATION="europe-west1"
    ما در اینجا از چند پرچم مهم استفاده می‌کنیم:
    • --source . --no-build --base-image=nodejs24 : این به Cloud Run می‌گوید که کد منبع را از دایرکتوری فعلی مستقر کند، مرحله ساخت را رد کند و برنامه را با استفاده از یک تصویر پایه از پیش ساخته شده Node.js 24 اجرا کند.
    • --no-allow-unauthenticated : این تضمین می‌کند که فقط کاربران احراز هویت شده می‌توانند به سرویس دسترسی داشته باشند.
    • --iap : این گزینه، پروکسی آگاه از هویت (IAP) را قادر می‌سازد تا دسترسی به برنامه شما را مدیریت کند. IAP به شما امکان می‌دهد دسترسی را بر اساس هویت و زمینه کاربر، به جای فقط آدرس‌های IP، کنترل کنید.
  2. بعد از چند دقیقه، پیامی مانند زیر خواهید دید: 
    Service [generative-web-navigator] revision [generative-web-navigator-12345-abc] has been deployed and is serving 100 percent of traffic.

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

۹. پیکربندی دسترسی IAP

وقتی IAP را در Cloud Run فعال می‌کنید، IAP تمام درخواست‌ها را رهگیری می‌کند و از کاربران می‌خواهد قبل از دسترسی به سرویس شما، احراز هویت و مجوز بگیرند. برای اینکه این قابلیت کار کند، باید دو مجوز اعطا کنید:

  • به سرویس IAP اجازه دهید تا سرویس Cloud Run شما را فراخوانی کند.
  • به خودتان (یا سایر کاربران/گروه‌ها) اجازه دهید از طریق IAP به برنامه دسترسی داشته باشند.
  1. شماره پروژه خود را که برای شناسایی نماینده خدمات IAP لازم است، دریافت کنید: 
    export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)")
  2. به عامل سرویس IAP، نقش roles/run.invoker را در سرویس Cloud Run خود اعطا کنید. این به IAP اجازه می‌دهد تا پس از احراز هویت و اعطای مجوز به کاربر، سرویس شما را فراخوانی کند. 
    gcloud run services add-iam-policy-binding generative-web-navigator \
    --region=europe-west1 \
    --member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com" \
    --role="roles/run.invoker"
  3. به حساب کاربری خود، نقش roles/iap.httpsResourceAccessor را اعطا کنید. این به شما امکان می‌دهد به منابع HTTPS امن‌شده با IAP دسترسی داشته باشید. 
    gcloud beta iap web add-iam-policy-binding \
    --resource-type=cloud-run \
    --region=europe-west1 \
    --service=generative-web-navigator \
    --member="user:$(gcloud config get-value account)" \
    --role="roles/iap.httpsResourceAccessor"

۱۰. برنامه را آزمایش کنید

  1. آدرس اینترنتی سرویس مستقر شده خود را دریافت کنید: 
    gcloud run services describe generative-web-navigator --format='value(status.url)' --region=europe-west1
  2. آدرس اینترنتی (URL) را کپی کرده و در مرورگر وب خود باز کنید. از آنجا که این سرویس با IAP ایمن شده است، اگر قبلاً وارد سیستم نشده‌اید، از شما خواسته می‌شود با حساب گوگل خود وارد شوید. پس از تأیید اعتبار، باید اولین صفحه تولید شده خودکار را مشاهده کنید.
  3. روی هر لینکی کلیک کنید تا به صفحه جدیدی هدایت شوید که توسط هوش مصنوعی و بر اساس لینکی که روی آن کلیک کرده‌اید، ایجاد می‌شود!

شما موفق شدید! شما با موفقیت یک وب‌سایت رابط کاربری مولد را در Cloud Run مستقر کرده و آن را با استفاده از IAP ایمن کرده‌اید.

۱۱. نتیجه‌گیری

تبریک! شما با موفقیت یک وب‌سایت رابط کاربری مولد را با استفاده از Cloud Run، Vertex AI و IAP مستقر و ایمن کردید.

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

اگر می‌خواهید آنچه را که ایجاد کرده‌اید پاک کنید، می‌توانید پروژه ابری خود را حذف کنید تا از هزینه‌های اضافی جلوگیری شود.

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

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

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

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