ساختن برنامه‌های هوش مصنوعی با بوم‌سازگان Google

۱. قبل‌از شروع

توسعه نرم‌افزار تکامل یافته است. موفق‌ترین توسعه‌دهندگان فقط کد نمی‌نویسند؛ آن‌ها ابزارها و مأموران هوش مصنوعی را برای ساختن بهتر و سریع‌تر هماهنگ می‌کنند. بوم‌سازگان ابزارهای Google مجموعه جامعی را برای کل چرخه حیات ارائه می‌دهد: تولید واسط کاربر، نمونه‌سازی و استقرار برنامه، توسعه ویژگی هوش مصنوعی، و ادغام امن و مقیاس‌پذیر با پس‌بست. در این codelab، از Google Stitch برای طراحی واسط کاربر، از Google AI Studio برای vibe code و استقرار برنامه، و از Firebase برای توسعه ویژگی‌های هوش مصنوعی و ذخیره اطلاعات در یک پسایمن و مقیاس‌پذیر استفاده خواهید کرد.

برنامه‌ای که قرار است در این codelab بسازید Decide For Me نام دارد—یک دستیار تصمیم‌گیری برای افراد مردد که با انتخاب‌های زندگی (مانند جابجایی آپارتمان، تغییر شغل، یا انتخاب سرگرمی) مواجه هستند. کاربر دوراهی و اولویت‌هایش در زندگی را وارد می‌کند و برنامه بااستفاده از هوش مصنوعی به کاربر کمک می‌کند براساس آنچه ناامیدی بلندمدت را به‌حداقل می‌رساند تصمیم‌گیری کند. این برنامه همچنین اولین گام مشخص را به کاربر ارائه می‌دهد. نسخه نهایی برنامه‌تان باید مشابه این باشد:

نماگرفت برنامه «به‌جای من تصمیم بگیر» که میانای گپ و پانل اولویت‌ها را نشان می‌دهد

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

  • طراحی واسط‌های کاربر با Google Stitch.
  • کدنویسی حسی برنامه وب با Google AI Studio.
  • از Firebase برای توسعه ویژگی‌های هوش مصنوعی و ذخیره اطلاعات در فضای ابری استفاده کنید.
  • مستقر کردن برنامه وب در محیط تولید با Google AI Studio (با بهره‌گیری از Cloud Run).

۲. طراحی واسط کاربر با Stitch

  1. تصویر مدل (DecideForMeScreen.jpeg) را بارگیری کنید. آن را در پوشه محلی که بتوانید پیدایش کنید ذخیره کنید.
  2. به Stitch بروید، فیلد ورودی را پیدا کنید، و گزینه وب را انتخاب کنید. (برای این codelab، روی تجربه وب تمرکز خواهید کرد، اما می‌توانید از Stitch برای تولید صفحه‌های تلفن همراه نیز استفاده کنید.)
  3. تصویر مدل را بارگذاری کنید:
    1. روی + (دکمه افزودن) کلیک کنید.
    2. بارگذاری فایل‌ها را انتخاب کنید.
    3. تصویری را که در مرحله راه‌اندازی بارگیری کردید پیوست کنید (DecideForMeScreen.jpeg). این مدل دست‌کشیده به شما امکان می‌دهد قابلیت‌های چندحالتی Stitch را آزمایش کنید.
  4. پیام‌واره زیر را کپی کنید و در فیلد ورودی جای‌گذاری کنید:
    # General Guidance
    Create a modern, clean, and highly polished UI for a web application called
    "Decide For Me" - a hyper-rational decision assistant.
    
    CRITICAL: Replicate the exact layout, structure, and element placement shown in
    the hand-drawn mockup file DecideForMeScreen.jpeg. Do not add any extra menus,
    sidebars, buttons, or top/bottom navigation bars that are not explicitly drawn
    in the file. Stick strictly to the skeleton provided in the mockup.
    
    # Layout & Structure
    - Two-Column Split Screen:
      - Left Side (Main Chat Area): Takes up roughly 70-75% of the screen width. It
        should feel like a premium, focused workspace.
      - Right Side (Configuration Panel): A sidebar taking up 25-30% of the screen
        width with a distinct, subtle background color to separate it from the
        chat.
    
    # Right Panel: Configuration Screen
    - Header: Title it "My Priorities" with a clean, minimalist typography.
    - Content Card: A styled card containing a text box or paragraph area
      showcasing the user's priorities.
    - Interactions: Include a clear "Edit Priorities" button. When clicked, this
      area should visually toggle into an editable textarea or input field.
    
    # Left Panel: Chat & Dilemma Decision Screen
    - Chat History: A clean vertical flow of message bubbles.
      - The first message bubble must be aligned to the left (system message) and
        say: "Tell me your dilemma". Use a friendly, neutral background color for
        this bubble.
    - Bottom Input Area: Instead of a traditional single-line chat bar, create a
      unified, beautiful "Decision Submission" layout positioned at the bottom:
      - Dual Input Fields: Place two horizontal or cleanly stacked input fields.
        - Input 1 label: "Option A"
        - Input 2 label: "Option B"
      - Action Button: A prominent, styled "Go" action button to trigger the
        reasoning loop.
    
    # Theme & Aesthetic
    - Vibe: Hyper-rational, clean, trustworthy, and modern. Use a sophisticated
      color palette (e.g., deep slates, clean whites/grays, and a sharp accent
      color like a subtle indigo or teal for active states and buttons).
    - Spacing & Typography: Use generous whitespace, soft rounded corners
      (border-radius) for cards and buttons, and a highly legible sans-serif font.
    
  5. روی پیکان تولید در گوشه پایین فیلد ورودی کلیک کنید. Stitch صفحه و کل سیستم طراحی را تولید می‌کند، ازجمله پالت رنگ، گزینه‌های قلم، نمادنگاری، و حس کلی عناصر میانای کاربر:

میانای Stitch که سیستم طراحی و طراحی میانای کاربر «به‌جای من تصمیم بگیر» تولیدشده را نشان می‌دهد

۳. ساختن برنامه با Google AI Studio

  1. ایجاد پروژه Firebase:
    1. با همان «حساب Google» که برای Stitch استفاده کردید، به سیستم کنسول Firebase وارد شوید.
    2. برای ایجاد پروژه جدید، روی دکمه کلیک کنید و سپس نام پروژه را وارد کنید (برای مثال، Decider App).
    3. روی ادامه کلیک کنید.
    4. اگر درخواست شد، شرایط Firebase را مرور و قبول کنید، سپس روی ادامه کلیک کنید.
    5. (اختیاری) «کمک هوش مصنوعی» را در کنسول Firebase (به‌نام «Gemini در Firebase») فعال کنید.
    6. برای این codelab، به Google Analytics نیاز ندارید، بنابراین گزینه Google Analytics را خاموش کنید.
    7. روی ایجاد پروژه کلیک کنید، منتظر بمانید تا پروژه‌تان آماده شود، سپس روی ادامه دادن کلیک کنید.
  2. صفحه‌ای را که در Stitch ساخته‌اید به Google AI Studio صادر کنید:
    1. روی طرح تولیدشده در Stitch کلیک کنید.
    2. روی صادر کردن در گوشه بالا سمت چپ صفحه کلیک کنید.
    3. مطمئن شوید گزینه انتخاب‌شده Google AI Studio باشد.
    4. به فیلد شرح در پایین پیمایش کنید.
  3. پیام‌واره زیر را کپی کنید و آن را در فیلد شرح جای‌گذاری کنید. [FIREBASE_PROJECT_ID] را با شناسه پروژه واقعی از مرحله ۱ جایگزین کنید (اگر شناسه پروژه خود را به‌خاطر نمی‌آورید، می‌توانید آن را در «تنظیمات پروژه» پیدا کنید):
    # General Guidance
    Build the "Decide For Me" app: A hyper-rational decision assistant for
    chronically indecisive people facing life choices (moving apartments, changing
    careers, picking a hobby). The user enters a dilemma and their top priorities
    in life. The app will help with the decision. Follow the instructions below to
    build it:
    
    # UI Instructions
    Using the design artifacts exported from Stitch (the PNG image and HTML file),
    build a fully functional web application that accurately mirrors the design and
    layout.
    
    # App Architecture & Initialization Instructions
    - Initialize the latest Firebase JS SDK for client-side services. Use the
      Firebase project with ID [FIREBASE_PROJECT_ID].
    - Enable Firebase Authentication in this project using the Google provider.
      If a user is not logged in, show a clean, minimalist sign-in state. If the
      user is logged in, take them directly to the dilemma decision screen.
    - Initialize Firebase App Check in debug mode with the following code:
      `self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;`
      `initializeAppCheck(app, { /* App Check options */ });`
    
    
    # State & Database Management Instructions
    - User Priorities:
      - Once authenticated, pull the user's saved priorities from Firebase
        Firestore at the path: `users/{userId}`. Each document should contain one
        string field: 'priorities'.
      - Bind this data to the Right Panel ("My Priorities").
      - When the user clicks the "Edit" button, toggle the view to a textarea, with
        a 'save' button. When saved, write the updated string back to
        `users/{userId}`.
      - Make sure to implement and deploy strong Security Rules for Firestore.
    
    # UI Stream Update & Display Instructions
    - Once the user submits option A and option B in the dilemma decision screen,
      display both options as a single message on the user side of the chat. Then,
      display a sleek loading state in the main chat panel. Leave the app in this
      "loading" state and do nothing else, we will process both options and build
      the server-side thinking later.
    
  4. روی ساختن با Google AI Studio کلیک کنید. با این کار، Google AI Studio در برگه جدیدی باز می‌شود و فایل‌های طراحی و پیام‌واره شما به آن منتقل می‌شود:
    1. تأیید کنید که پیام‌واره به‌طور کامل منتقل شده باشد.
    2. اگر فقط بخشی از پیام‌واره را می‌بینید، کل پیام‌واره را دوباره جای‌گذاری کنید.
  5. روی ساختن کلیک کنید. ‫Google AI Studio شروع به تولید برنامه Decide For Me براساس پیام‌واره و طراحی میانای کاربر شما می‌کند:
    1. درحین تولید، طرح‌های میانای کاربر جایگزین را پیشنهاد می‌کند (این طرح‌ها را برای این codelab نادیده بگیرید، اما می‌توانید در آینده طرح‌های مختلفی را انتخاب کنید).
    2. وقتی از شما خواسته شد Firebase را فعال کنید، روی فعال کردن کلیک کنید.
  6. برنامه تولیدشده را بازرسی و درستی‌سنجی کنید:
    1. برنامه را در برگه پیش‌نمایش آزمایش کنید.
    2. برای مرور همه فایل‌ها و کدهای تولیدشده، به برگه کد بروید.
    3. ‫Google AI Studio همچنین یک پروژه Firebase ایجاد کرده، اصالت‌سنجی Firebase و Firestore را فعال کرده، و Firebase را در پایگاه کد شما پیکربندی کرده است. در مرحله بعدی این codelab، به این پروژه Firebase دسترسی پیدا می‌کنید و با آن کار می‌کنید.

۴. ثبت کردن کد تصدیق اشکال‌زدایی «بررسی برنامه»

وقتی Google AI Studio برنامه را تولید می‌کند، یک پروژه Firebase ایجاد می‌کند و برنامه شما را به آن متصل می‌کند. باید به این پروژه Firebase دسترسی پیدا کنید و محیط توسعه نرم‌افزار خود را با سرویس امنیتی مهمی به‌نام «بررسی برنامه Firebase» ثبت کنید.

دسترسی به پروژه Firebase

  1. شناسه پروژه Firebase ایجادشده توسط Google AI Studio را پیدا کنید:
    1. در Google AI Studio، به برگه کد بروید.
    2. فایل firebase-applet-config.json را باز کنید.
    3. مقدار فیلد projectId را کپی کنید.
  2. به کنسول Firebase بروید و بااستفاده از این شناسه، پروژه را جستجو کنید.

ثبت کردن کد اشکال‌زدایی

برنامه شما می‌تواند از بررسی برنامه Firebase برای محافظت از سرویس‌های پسین و مدل‌های هوش مصنوعی دربرابر سوءاستفاده استفاده کند. این کار با اطمینان از اینکه ترافیک ورودی فقط از برنامه‌های قانونی منشأ می‌گیرد انجام می‌شود.

چون برنامه‌تان در محیط پیش‌نمایش Google AI Studio اجرا می‌شود، از ارائه‌کننده اشکال‌زدایی «بررسی برنامه» (self.FIREBASE_APPCHECK_DEBUG_TOKEN = true) استفاده می‌کند. وقتی برنامه وب بار می‌شود، Firebase به‌طور خودکار یک کلید اشکال‌زدایی را به کنسول توسعه‌دهنده مرورگرتان ارسال می‌کند.

  1. توکن اشکال‌زدایی را پیدا کنید:
    1. در Google AI Studio، ابزارهای توسعه‌دهنده مرورگرتان را هنگام مشاهده پیش‌نمای برنامه باز کنید:
      • Chrome،‏ Edge، یا Firefox: کلید F12 را فشار دهید (یا در هرجایی از پیش‌نمایش کلیک راست کنید و بازرسی را انتخاب کنید)، سپس برگه کنسول را انتخاب کنید.
      • macOS: کلیدهای Cmd+Option+I را فشار دهید، سپس برگه کنسول را انتخاب کنید.
    2. در گزارش‌های کنسول، پیام اشکال‌زدایی «بررسی برنامه» را پیدا کنید:
      AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
      You will need to safelist it in the Firebase console for it to work.
      
    3. رشته کد را (بدون گیومه) کپی کنید.
  2. ثبت کردن کد اشکال‌زدایی:
    1. در کنسول Firebase، به امنیت > بررسی برنامه > برگه برنامه‌ها بروید.
    2. برنامه وب خود را در فهرست پیدا کنید، روی منوِ سه‌نقطه‌ای (⋮) کلیک کنید، و مدیریت کردن کدهای اشکال‌زدایی را انتخاب کنید.
    3. روی افزودن کد اشکال‌زدایی کلیک کنید، کد کپی‌شده را جای‌گذاری کنید، نامی مثل Google AI Studio Preview وارد کنید، و روی ذخیره کلیک کنید.
    نماگرفت از گزینه منو «مدیریت کردن کدهای اشکال‌زدایی» در کنسول Firebase

۵. آزمایش برنامه

اکنون که پروژه‌تان متصل شده است و کد تصحیح اشکال شما در «بررسی برنامه» ثبت شده است، ویژگی‌های پایه را آزمایش کنید: «اصالت‌سنجی» و Firestore.

  1. اصالت‌سنجی کاربر آزمایشی و اولویت‌های ذخیره:
    1. در پیش‌نمایش برنامه Decide For Me در Google AI Studio، صفحه اصالت‌سنجی را با ورود به سیستم «حساب Google» آزمایش کنید.
    2. اولویت‌های زندگی‌تان را بااستفاده از پانل سمت چپ (اولویت‌های من) ذخیره کنید.
  2. اصالت‌سنجی را در کنسول Firebase درستی‌سنجی کنید:
    1. به کنسول Firebase بروید و اصالت‌سنجی را باز کنید.
    2. مطمئن شوید «حساب Google» که برای اصالت‌سنجی در برنامه Decide For Me استفاده کرده‌اید در آنجا فهرست شده باشد:
    صفحه «اصالت‌سنجی» کنسول Firebase که «حساب Google» اصالت‌سنجی‌شده را نشان می‌دهد
  3. درستی‌سنجی کردن فضای ذخیره‌سازی داده Firestore:
    1. Firestore را در کنسول Firebase باز کنید.
    2. تأیید کنید که اولویت‌هایتان در سندی در مسیر users/{userId} ذخیره شده است:
    پایگاه داده Firestore در کنسول Firebase که اولویت‌های ذخیره‌شده در users/{userId} را نشان می‌دهد

‫۶. ساختن جریان «تصمیم‌گیرنده» هوشواره‌ای بااستفاده از Firebase

برنامه شما از هوش مصنوعی برای تقویت کنش‌های Decide For Me استفاده خواهد کرد. می‌توانید از Firebase برای ساختن این جریان «تصمیم‌گیرنده» هوشواره‌ای استفاده کنید.

راه‌اندازی Firebase AI Logic

  1. ‫Gemini Developer API را در Firebase AI Logic فعال کنید:
    1. Firebase AI Logic را در کنسول Firebase باز کنید، سپس روی شروع به کار کلیک کنید.
    2. Gemini Developer API را انتخاب کنید و دستورالعمل‌های موجود در کنسول را برای فعال کردن میانای برنامه‌سازی کاربردی دنبال کنید.
  2. پیکربندی تنظیمات Firebase AI Logic:
    1. به برگه تنظیمات بروید.
    2. گزینه اجرای حالت فقط الگو را به اجراشده تغییر دهید.
    3. گزینه اجرای حالت کاربران اصالت‌سنجی‌شده را به اجراشده تغییر دهید.

ایجاد کردن الگوی پیام‌واره سرور

در این codelab، از الگوهای پیام‌واره سرور برای تعاملاتتان با Gemini API ازطریق Firebase AI Logic استفاده خواهید کرد.

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

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

نحوه ایجاد و آزمایش کردن الگوی پیام‌واره سرور به این صورت است:

  1. الگوی پیام‌واره سرور را ایجاد کنید:
    1. به برگه الگوهای پیام‌واره بروید.
    2. روی ایجاد الگو کلیک کنید.
    3. الگوی خالی را انتخاب کنید.
    4. بااستفاده از اطلاعات زیر، اولین الگوی خود را ایجاد کنید:
      • نام الگو: Decider Flow
      • شناسه الگو: decider-flow
      • پیکربندی (frontmatter)
        model: "gemini-3.5-flash-lite"
        input:
          schema:
            priorities: "string, user's core priorities"
            optionA: "string, option A under consideration"
            optionB: "string, option B under consideration"
        output:
          format: json
          schema:
            verdict: string
            justification: string
            firstStep: string
        
      • پیام‌واره و دستورالعمل‌های سیستم (اختیاری)
        {role "system"}
        You are the Decider Agent, a multi-stage reasoning engine that
        combines the roles of an honest and polite behavioral economist, a
        long-term strategic forecaster, and an executive decision coach.
        Your job is to take a user's dilemma and their core priorities, run
        them through a rigorous, adversarial 3-phase thinking process, and
        output a highly analytical, reasoning-backed final verdict. You must be
        direct, sharp, and realistic. Do not give generic platitudes or claim
        that "both options are great." You must force a clear choice.
        
        {role "user"}
        # Context & Inputs
        You are analyzing a critical life decision for the user. Base your
        entire multi-phase reasoning flow strictly on these three specific
        inputs:
        - User's Core Priorities: {{priorities}}
        - Option A under consideration: {{optionA}}
        - Option B under consideration: {{optionB}}
        
        Execute your reasoning flow through the following three phases:
        
        # Phase 1: Cynical Breakdown (Input-Driven Analysis)
        Analyze {{optionA}} and {{optionB}} strictly through the lens of the
        user's explicit {{priorities}}. Do not evaluate them in a vacuum.
        - Identify the hidden flaws, compromises, and psychological costs
          embedded in both choices.
        - Pinpoint exactly how {{optionA}} could directly conflict with or
          undermine their {{priorities}}.
        - Pinpoint exactly how {{optionB}} could directly conflict with or
          undermine their {{priorities}}.
        - Uncover any cognitive biases (like status quo bias or loss aversion)
          the user might be falling for in either option.
        
        # Phase 2: Long-Term Regret Projection
        Project the user 5 years into the future. Apply the Regret Minimization
        Framework to both paths:
        - The {{optionA}} Timeline: Quantify the absolute worst-case, deep,
          structural 5-year regret of choosing this path. Focus heavily on
          failures of courage vs. failures of action based on their
          {{priorities}}.
        - The {{optionB}} Timeline: Quantify the matching 5-year regret for
          this path.
        - Contrast these two timelines. Which option carries the kind of regret
          that fundamentally breaks the user's {{priorities}}?
        
        # Phase 3: Final Recommendation & Action Step
        Synthesize the cynical critiques and long-term regret scores.
        Weigh them against the user's {{priorities}} to determine which
        choice minimizes long-term disappointment.
        - Verdict: You must declare either {{optionA}} or {{optionB}} as the
          definitive winner. No compromise, no "it depends," and no hybrid
          options.
        - Justification: Provide a sharp, reasoning-backed explanation showing why
          the losing option was eliminated based on the Phase 1 and Phase 2
          analysis.
        - First Step: Give one microscopic, low-friction task the user can
          execute within the next 15 minutes to commit to or move toward the
          chosen verdict.
        
        {} اضافی در اطراف {role "system"} و {role "user"} اضافه کنید تا دستورالعمل‌های سیستم و پیام‌واره خود را با نحو صحیح بنویسید: 9db2a4f2c5cf2ec7.png
      • ورودی آزمایشی
        {
          "priorities": "Be financially stable, have a good work-life balance where I can travel twice a year",
          "optionA": "Buy a house for 615000 British pounds with a mortgage of 2800 per month for the next 35 years",
          "optionB": "Keep renting for 2400 per month for the foreseeable"
        }
        
  2. روی ذخیره الگو کلیک کنید.
  3. الگو را آزمایش کنید:
    1. روی اجرای آزمایش پیام‌واره کلیک کنید.
    2. پاسخ آزمایشی را پیدا کنید و بررسی کنید که همه فیلدهایی را که در پیام‌واره مشخص کرده‌اید (verdict، justification، و firstStep) داشته باشد.
    3. اگر همه چیز با پاسخ موردانتظار مطابقت دارد، الگو را بااستفاده از نماد قفل در گوشه بالا سمت چپ الگو قفل کنید تا از پایداری نسخه اطمینان حاصل کنید و از تغییرات تصادفی جلوگیری کنید.

الگویتان آماده استفاده در برنامه‌تان است!

‫۷. استفاده از الگوی پیام‌واره «تصمیم‌گیرنده» در برنامه

برنامه وب خود را طوری تنظیم کنید که از این الگو استفاده کند:

  1. به برنامه‌تان در Google AI Studio برگردید.
  2. از عامل Google AI Studio بخواهید کنش Decide For Me را اجرا کند:
    1. پیام‌واره زیر را کپی کنید:
      Now let's implement the "Decide For Me" button action. When clicked, it
      should call the Firebase AI Logic SDK using a Template Generative Model.
      The prompt is stored in a prompt template with the id "decider-flow". When
      calling the API, pass the following variables as the input payload object:
      - priorities
      - optionA
      - optionB
      
      The API will return a JSON object. Handle the response asynchronously and
      extract:
      - verdict
      - justification
      - firstStep
      
      Once the data is received, update the UI state to append a new message to
      the chat array. Ensure it renders as a system chat bubble positioned on
      the left side of the chat screen, mapping these three fields clearly into
      the bubble's layout.
      
      Please provide the necessary front-end component state updates and the
      Firebase SDK call.
      
    2. پیام‌واره را در ورودی گپ Google AI Studio جای‌گذاری کنید و روی ارسال کلیک کنید.
  3. پیکربندی را تأیید کنید و دستیار تصمیم‌گیری را آزمایش کنید:
    1. صبر کنید تا Google AI Studio افزودن Firebase AI Logic به برنامه‌تان را تکمیل کند.
    2. به برگه کد بروید و مطمئن شوید کلید میانای API در فایل firebase-applet-config.json وجود دارد. اگر کلید Firebase API در فایل پیکربندی نیست، از Google AI Studio بخواهید آن را وارد کند.
    3. به برگه پیش‌نمایش بروید
    4. گزینه‌های الف و ب را ارسال کنید و تأیید کنید که هوش مصنوعی حکم تصمیم، توجیه، و گام اول را برمی‌گرداند.

برای مرجع، کد تولیدشده توسط Google AI Studio باید شبیه به این باشد:

const aiInstance = getAI(app);
const templateModel = getTemplateGenerativeModel(aiInstance);

const result = await templateModel.generateContent('decider-flow', {
  priorities: priorities,
  optionA: optA,
  optionB: optB
});

const rawText = result.response.text();

// Parse response text to extract fields
const cleaned = rawText.replace(/```json|```/g, '').trim();
const parsedData: { verdict?: string; justification?: string; firstStep?: string } = JSON.parse(cleaned);

const verdict = parsedData.verdict;
const justification = parsedData.justification;
const firstStep = parsedData.firstStep;

اشکال‌زدایی و نظارت بر درخواست‌ها

اگر برنامه‌تان با خطا مواجه می‌شود، نمی‌تواند پاسخ تولید کند، یا می‌خواهید ترافیک میانای برنامه‌سازی کاربردی را با جزئیات بررسی کنید، از ابزارهای نظارت و تجزیه‌وتحلیل داخلی Firebase AI Logic استفاده کنید:

  1. در کنسول Firebase، به برگه سرویس‌های هوش مصنوعی > منطق هوش مصنوعی > پایش هوش مصنوعی بروید.
  2. سنجه‌های کمی را در داشبورد بررسی کنید:
    • حجم و وضعیت درخواست: بررسی کنید که آیا درخواست‌های ورودی به پس‌بست می‌رسند و 200 OK را برمی‌گردانند یا با خطاهای کارخواه یا سرور ناموفق می‌شوند.
    • تأخیر: نمودار تأخیر را بررسی کنید تا زمان پاسخ سرتاسر را بررسی کنید.
    • تعداد داده‌واحد: بر میزان استفاده از داده‌واحد ورودی و خروجی در هر درخواست نظارت کنید.
  3. ردیابی‌های درخواست‌های فردی را برای اشکال‌زدایی عمیق بررسی کنید:روی یک ردیابی درخواست خاص در جدول ردیابی‌ها کلیک کنید تا بار مفید آن را بررسی کنید.
    • ورودی‌ها: تأیید کنید که متغیرها (priorities، optionA، و optionB) به‌درستی از برنامه کارخواه منتقل شده‌اند.
    • خروجی‌ها: نوشتار خامی را که مدل تولید کرده است مشاهده کنید تا بررسی کنید آیا JSON معتبر مطابق با طرح‌واره را برگردانده است یا نه.
    • جزئیات خطا: اگر درخواستی ناموفق بود، گزارش خطای ردیابی را برای دلایلی مانند کدهای نامعتبر «بررسی برنامه»، رد اصالت‌سنجی، محدودیت‌های سهمیه، یا خطاهای اعتبارسنجی پیام‌واره بررسی کنید.
  4. عیب‌یابی و حل کردن مشکلات Google AI Studio:
    • اگر خطایی در ردیابی شناسایی کردید (برای مثال، تجزیه پاسخ JSON با قالب نادرست یا پارامترهای مفقود)، پیام خطا یا پایه‌بار را کپی کنید.
    • به Google AI Studio برگردید و از دستیار بخواهید مشکل مربوطه را در کد برنامه برطرف کند.

‫۸. اختیاری: استقرار برنامه

اکنون که برنامه‌تان در حالت پیش‌نمایش کار می‌کند، آن را در تولید مستقر کنید.

برای محافظت از نقاط پایانی Firebase در تولید، یک ارائه‌دهنده گواهی تولید را برای استفاده با بررسی برنامه Firebase پیکربندی کنید (در این codelab، از reCAPTCHA نسخه ۳ استفاده خواهید کرد).

ابتدا باید برنامه‌تان را مستقر کنید تا نشانی وب دقیق آن را دریافت کنید و بتوانید دامنه خاص را در reCAPTCHA ثبت کنید، نه اینکه همه برنامه‌های ai.studio را مجاز کنید.

برنامه‌تان را مستقر کنید و reCAPTCHA را پیکربندی کنید:

  1. استقرار برنامه وب با Google AI Studio:
    1. در Google AI Studio، روی انتشار در نوار پیمایش بالا کلیک کنید.
    2. روی شروع به کار کلیک کنید، نام و شرح برنامه را مرور یا سفارشی‌سازی کنید، و روی انتشار برنامه کلیک کنید.
    3. منتظر بمانید تا Google AI Studio برنامه شما را بسازد و مستقر کند (معمولاً ۱ تا ۲ دقیقه).
    4. نشانی وب سفارشی زنده تولیدشده (برای مثال، https://decide-for-me-123.ai.studio) را کپی کنید و دامنه آن را یادداشت کنید (برای مثال، decide-for-me-123.ai.studio).
  2. ایجاد کلیدهای reCAPTCHA نسخه ۳ در Google reCAPTCHA:
    1. به کنسول سرپرست Google reCAPTCHA بروید.
    2. برچسبی (برای مثال، Decide For Me - Production) وارد کنید.
    3. نوع reCAPTCHA > reCAPTCHA نسخه ۳ (مبتنی بر امتیاز) را انتخاب کنید.
    4. در بخش دامنه‌ها، دامنه دقیق مستقرشده برنامه‌تان (برای مثال، decide-for-me-123.ai.studio، بدون https:// و هرگونه مسیر) یا دامنه سفارشی را (اگر قصد دارید از آن استفاده کنید) اضافه کنید.
    5. شرایط خدمات را بپذیرید و روی ارسال کلیک کنید.
    6. این برگه را باز نگه دارید: به کلید سایت (کلید کارخواه عمومی) و کلید مخفی (کلید سرور خصوصی) نیاز دارید.
  3. کلید خصوصی‌تان را در کنسول Firebase ثبت کنید:
    1. به بررسی برنامه در کنسول Firebase بروید.
    2. به برگه Apps (برنامه‌ها) بروید.
    3. برنامه وب خود را در فهرست پیدا کنید، روی آن کلیک کنید (یا روی منوِ سه‌نقطه‌ای ⋮ کلیک کنید)، و reCAPTCHA نسخه ۳ را انتخاب کنید.
    4. کلید محرمانه reCAPTCHA را در فیلد جای‌گذاری کنید و روی ذخیره کلیک کنید.
  4. پیکربندی برنامه کارخواه برای استفاده از ReCaptchaV3Provider:
    1. در Google AI Studio، به پانل گپ بروید و از دستیار بخواهید پیکربندی App Check شما را برای تولید به‌روز کند:
      Please update our Firebase App Check initialization to use
      ReCaptchaV3Provider with the reCAPTCHA site key "YOUR_RECAPTCHA_SITE_KEY",
      while retaining support for debug tokens in non-production environments.
      
    2. اگر کد را مستقیماً در برگه کد مرور می‌کنید، مطمئن شوید که مقداردهی اولیه «بررسی برنامه» شما با این ساختار مطابقت داشته باشد:
      import { initializeAppCheck, ReCaptchaV3Provider } from "firebase/app-check";
      
      const appCheck = initializeAppCheck(app, {
        provider: new ReCaptchaV3Provider("YOUR_RECAPTCHA_SITE_KEY"),
        isTokenAutoRefreshEnabled: true
      });
      
    3. پس‌از به‌روزرسانی کد، برنامه‌تان را در Google AI Studio بازانتشار کنید تا پیکربندی به‌روزشده «بررسی برنامه» به سایت فعال شما ارسال شود.
  5. ترافیک تولید را درستی‌سنجی کنید و «بررسی برنامه» را پایش کنید:
    1. نشانی وب برنامه فعال خود را در پنجره مرورگر ناشناس باز کنید، با Google وارد سیستم شوید، و ارسال یک دوراهی را آزمایش کنید.
    2. به بررسی برنامه در کنسول Firebase برگردید و برگه‌های میاناهای برنامه‌سازی کاربردی و پایش را بررسی کنید تا مطمئن شوید درخواست‌ها با موفقیت برای Firestore و Firebase AI Logic ثبت شده‌اند.

‫۹. نتیجه‌گیری

تبریک! برنامه مفیدی با ویژگی‌های هوش مصنوعی از ابتدا بااستفاده از ابزارهای Google Builder Stack ساخته‌اید. این تازه شروع کار است؛ کارهای بسیار بیشتری می‌توانید با ابزارهای Google انجام دهید. اکنون پروژه Firebase + Google Cloud دارید؛ همه سرویس‌های دردسترس را کاوش کنید!

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

برای ادامه سفر، به goo.gle/builders بروید تا آزمایشگاه بعدی را شروع کنید.

اگر ازقبل از Antigravity 2.0، پلاتفرم اختصاصی Google برای هماهنگ‌سازی چندین عامل خودکار به‌طور موازی، استفاده می‌کنید، می‌توانید به‌سرعت پروژه‌تان را از Google AI Studio صادر کنید و آن را به Antigravity وارد کنید تا به کار کردن روی آن به‌صورت محلی ادامه دهید. Antigravity دارای مهارت‌های عامل برای Firebase است که با یک کلیک قابل نصب است. این مهارت‌ها همچنین از توسعه تلفن همراه پشتیبانی می‌کنند که به شما کمک می‌کند درصورت تمایل این برنامه را در هر دو محیط Android و iOS تکرار کنید.