۱. مقدمه
نمای کلی
ساخت و ساز با هوش مصنوعی امروز از کجا شروع میشود؟ با یک جرقه شروع میشود: ایدهای که ارزش نمونهسازی اولیه را دارد. حالت ساخت (Build Mode) استودیوی هوش مصنوعی گوگل، این جرقه را از طریق "کدنویسی ارتعاشی" به واقعیت تبدیل میکند. با بهرهگیری از مدلهای Gemini، میتوانید برنامههای وب فولاستک را کاملاً از طریق تولید کد محاورهای طراحی، آزمایش و مستقر کنید.
در این آزمایشگاه کد، شما Block Explorer ، یک بازی تعاملی مکانی که دادههای نقشهبرداری دنیای واقعی را با هوش مصنوعی مولد ترکیب میکند، خواهید ساخت. شما از AI Studio برای تولید برنامه و ادغام آن با پلتفرم نقشههای گوگل و رابط برنامهنویسی Gemini استفاده خواهید کرد. سپس یاد خواهید گرفت که چگونه برنامه نهایی را مستقیماً در Cloud Run مستقر کنید و آن را برای آزمایش دیگران در دسترس قرار دهید.
کاری که انجام خواهید داد
- از Google AI Studio برای نمونهسازی اولیه یک اپلیکیشن وب تعاملی نقشهبرداری مکانی و اطلاعات عمومی استفاده کنید.
- فعالسازی و ارائه خودکار کلید آزمایشی پلتفرم نقشههای گوگل مستقیماً در فضای کاری AI Studio.
- با استفاده از پرسشهای زبان طبیعی، کدگذاری جغرافیایی پویای آدرس، کشف مکانها و آزمونهای سوالات بیاهمیت تولید شده توسط هوش مصنوعی را پیادهسازی کنید.
- با ادغام Maps Grounding Lite، دقت آزمونهای اطلاعات عمومی را افزایش دهید.
- برنامه را در محیط پیشنمایش تعاملی (interactive preview sandbox) آزمایش و تکرار کنید.
- برنامه را مستقیماً از رابط کاربری Google AI Studio روی Cloud Run مستقر کنید.
آنچه یاد خواهید گرفت
- چگونه از حالت ساخت (Build mode) گوگل هوش مصنوعی استودیو (Google AI Studio) برای نمونهسازی سریع یک سرویس فولاستک (full-stack) با استفاده از زبان طبیعی استفاده کنیم.
- نحوه استفاده از API های پلتفرم نقشه های گوگل برای ساخت برنامه های کاربردی با داده های مکانی.
- چگونه میتوان سوالات LLM را با زمینه جغرافیایی-مکانی دنیای واقعی مرتبط کرد تا آزمونهای پویا و بینشهای محلی ایجاد شود.
- چگونه برنامه AI Studio خود را به عنوان یک کانتینر بدون سرور در Cloud Run مستقر کنید.
پیش نمایشی از این pp را در زیر مشاهده میکنید:
۲. پروژه خود را تنظیم کنید
قبل از راهاندازی AI Studio، وضعیت حساب کاربری، پیشنیازها و دسترسی به API خود را تأیید کنید.
اطلاعات حساب و سطح گوگل
- اگر از قبل حساب گوگل ندارید، یک حساب گوگل ایجاد کنید .
- نکته : در صورت امکان از یک حساب گوگل شخصی برای این آزمایشگاه استفاده کنید. حسابهای کاربری گروهی، شرکتی یا مدرسه ممکن است سیاستهایی را اعمال کنند که ویژگیهای آزمایشی یا ادغامهای ابری را غیرفعال کنند.
- جزئیات صورتحساب برای استقرار را بررسی کنید:
- سطح شروع گوگل کلود : امکان انتشار حداکثر دو برنامه کامل در یک منطقه منتخب را بدون هیچ هزینهای و بدون ایجاد یک حساب پرداخت کامل گوگل کلود فراهم میکند.
- استقرار استاندارد : به یک پروژه پولی موجود در گوگل کلود متصل میشود و محدودیتهای ذخیرهسازی، منابع CPU و APIها را افزایش میدهد.
نسخه آزمایشی پلتفرم نقشه گوگل (Google Maps)
برای سادهسازی نمونهسازی اولیه، Google AI Studio به صورت بومی با پلتفرم Google Maps ادغام میشود. این امر روشی بدون مشکل برای آزمایش و ساخت مستقیم با APIهای اصلی پلتفرم Google Maps (مانند Maps JavaScript API، Geocoding API، Places API و Routes API) در پروژه شما فراهم میکند. AI Studio به طور خودکار یک کلید آزمایشی پلتفرم Google Maps برای شما ایجاد میکند.
مزایای کلیدی کلید آزمایشی:
- بدون نیاز به کارت اعتباری یا تنظیمات صورتحساب : میتوانید بلافاصله و بدون پیکربندی حساب صورتحساب Google Cloud، نمونه اولیه را ایجاد و ارزیابی کنید.
- سهمیه سخاوتمندانه نمونهسازی اولیه : شامل حداکثر ۱۰۰ درخواست رایگان در روز برای هر API جهت آزمایش و تکرار.
- یکپارچهسازی یکپارچه : نیازی به مراجعه به پورتالهای خارجی یا کپی و پیست کردن اطلاعات کاربری ندارید. Google AI Studio به طور خودکار تشخیص میدهد که برنامه شما چه زمانی نیاز به یکپارچهسازی با پلتفرم Google Maps دارد و موارد را برای شما پیکربندی میکند.
۳. پوسته برنامه را در حالت ساخت AI Studio ایجاد کنید
شما با ایجاد پوسته برنامه با استفاده از Google AI Studio شروع خواهید کرد.
- به پنل برنامههای Google AI Studio بروید و روی New App کلیک کنید (یا تب Build را انتخاب کنید).
- در کادر ورودی اعلان، توضیحات اولیه برای برنامه جغرافیایی خود را وارد کنید. همچنین میتوانید روی تراشه کشف پلتفرم نقشههای گوگل در زیر پیشنهادات اعلان کلیک کنید:
Build a highly polished, responsive, split-screen application. This application should be called "Block Explorer". It is meant to be a geospatial exploration app. It will use Google Maps Platform.
Key Features & Functionality:
- Split-Screen Layout: On desktop, a 1/3-width left-side editorial control panel and a 2/3-width right-side full-height map.
- Include a search bar where users can type a location such as a city or neighborhood. Submitting should issue a Geocoding request to the Google Geocoding V4 API REST endpoint (https://geocode.googleapis.com/v4/geocode/address/). Then pan the map to the geocoded location.
- Interactive Google Map: Render the Map inside an interactive container allowing users to pan, drag, and zoom freely. Place customized markers representing the currently selected/geocoded location.
- Also include five buttons for presets the users can click on: Buenos Aires, Shibuya, Copacabana, Cologne, and Lima. Clicking on this should geocode the location and pan the map there.
- Make sure to also include a mechanism to clearly show error messages when they occur so users can easily troubleshoot.
- برای شروع فرآیند تولید برنامه، روی ساخت (Build) کلیک کنید.
AI Studio شروع به تولید کد برنامه میکند. اگر از شما خواسته شد که یک تم طراحی انتخاب کنید، هر سبکی را که ترجیح میدهید انتخاب کنید.
فعالسازی پلتفرم نقشههای گوگل و ارائه کلید آزمایشی
پلتفرم نقشههای گوگل، رابط برنامهنویسی کاربردی (API) مربوط به کدگذاری جغرافیایی (Geocoding API ) را ارائه میدهد که درخواستهای آدرس قابل خواندن توسط انسان (مانند «شیبویا» یا «بوئنوس آیرس») را به مختصات جغرافیایی (طول و عرض جغرافیایی) تبدیل میکند تا نقشهها را در مرکز قرار داده و نشانگرها را نمایش دهد.
وقتی شما یک درخواست با هدف مکانی ارسال میکنید (مانند درخواست نقشههای گوگل، مکانیاب فروشگاه یا کاوش محلی)، AI Studio به طور خودکار نیاز مکانی را تشخیص میدهد و در تهیه موارد کلیدی به شما کمک میکند:
- پرده فعالسازی درونزمینهای : یک کارت درونبرنامهای با عنوان «راهاندازی پلتفرم نقشههای گوگل» در نوبت مکالمه ظاهر میشود.
- پذیرش شرایط و فعالسازی :
- شرایط خدمات پروژه آزمایشی نقشهها (و در صورت درخواست، شرایط خدمات تکمیلی سطح مبتدی ) را بررسی و بپذیرید.
- روی فعال کردن نقشههای گوگل کلیک کنید.
- تأمین خودکار کلید و تزریق رمز : AI Studio به طور خودکار یک کلید آزمایشی پلتفرم نقشههای گوگل را در زیرساخت پروژه میزبانیشده گوگل (GHP) تهیه کرده و آن را مستقیماً تحت نام
GOOGLE_MAPS_PLATFORM_KEYبه رمزهای پروژه شما تزریق میکند. - پیشنمایش زنده فوری : پیشنمایش برنامه بلافاصله با یک نقشه گوگل تعاملی زنده و کاملاً کاربردی بهروزرسانی میشود.
با وارد کردن یک مکان جدید یا انتخاب یکی از دکمههای مکان از پیش تعیینشده، برنامه را در محیط پیشنمایش آزمایش کنید!
۴. با استفاده از Gemini API، بینشهای محلی را اضافه کنید
در مرحله بعد، شما API Gemini را برای ایجاد بینشهای غنی و بومیسازی شده در مورد مکانها هنگام کاوش کاربران در نقشه، ادغام خواهید کرد.
- در پنجره چت، پیام زیر را برای دستیار هوش مصنوعی ارسال کنید:
Now, let's bring in the AI using the Gemini API.
1. Once geocoding successfully identifies the City and State (e.g., "Miami, Florida"), trigger a call to the Gemini API (using the gemini-3.8-flash model).
2. Use the following prompt template for the AI:
"You are a local tour guide for [City, State]. Give me exactly 3 short, highly engaging, and unusual or surprising fun facts about this place. Keep each fact under 2 sentences. Format the response as a clean HTML unordered list (<ul>) so I can inject it directly."
3. Display these fun facts in a beautiful "Local Insights" banner on the bottom portion of the map screen. Add a subtle loading spinner while the AI is thinking.
4. Make sure to make this handling robust. If an API request fails, display a user-friendly error notification in the UI.
- در صفحه پیشنمایش تأیید کنید که انتخاب یا جستجوی یک مکان، حقایق سرگرمکننده پویای ایجاد شده توسط Gemini را نمایش میدهد.
باید ببینید که AI Studio برنامه را بهروزرسانی میکند و در نتیجه بخش «Local Insights» به پایین صفحه اضافه میشود.
۵. مسابقهی چیزهای بیاهمیت تولید شده توسط هوش مصنوعی را بسازید
اکنون که برنامه شما مختصات مکان و بینشهای محلی را بازیابی میکند، این قابلیتها را برای تولید آزمونهای تعاملی بر اساس مقصد انتخاب شده ترکیب کنید.
- ارسال پیام ایجاد آزمون به عامل:
Now let's build the actual game! We will have Gemini generate a 3-question quiz based on the real places we just got information about.
After the local insights are generated, show the user a button to "Test their local knowledge". Once clicked, offer them 3 options to choose from:
- Local cuisine
- Art and culture
- Local history
Once selected, generate a 3-question quiz based on the category and the place. The quiz should be multiple choice. Once the user submits the quiz show them their score and the correct answer.
- برای آزمایش مدیریت حالت، انتخاب پاسخ و نمایش امتیاز، آزمون ایجاد شده را در پنجره پیشنمایش اجرا کنید.
۶. ادغام نقشههای Grounding Lite
به طور پیشفرض، Gemini با استفاده از دانش حاصل از دادههای آموزشی خود، حقایق و آزمونها را تولید میکند. برای بهبود دقت و استفاده از دادههای مکانی بلادرنگ، Maps Grounding Lite را ادغام کنید. این سرویس Gemini را مستقیماً به دادههای زنده از پلتفرم Google Maps متصل میکند.
- دستور زیر را در AI Studio ارسال کنید:
Add a toggle to make the quiz more difficult. Call this "Hyperlocal mode". When enabled, use the Google Maps Grounding Lite service with the Gemini API to fetch more local data, making the quiz more difficult.
Add information for the user so they know that Hyperlocal Mode is more difficult and how it works.
- برای تأیید تولید آزمون مبتنی بر پایه، گزینهی حالت Hyperlocal را در پنجرهی پیشنمایش آزمایش کنید.
دانشجویان کارشناسی ارشد حقوق (LLM) میتوانند ساعات کاری خاص، باز بودنهای اخیر یا شناسههای دقیق مکانها را تصور کنند. Maps Grounding Lite پاسخها را با موجودیتها و اسناد واقعی Google Maps Places مرتبط میکند و به طور قابل توجهی دقت واقعی سوالات بیاهمیت را بهبود میبخشد.
۷. استقرار در Cloud Run
زمانی که نمونه اولیه شما کاملاً کاربردی شد، آن را مستقیماً از AI Studio به عنوان یک کانتینر عمومی بدون سرور در Cloud Run مستقر کنید.
- در گوشه سمت راست بالای Google AI Studio، روی دکمه Publish کلیک کنید تا ویزارد استقرار (deployment wizard) آغاز شود.
- برای پیکربندی پروژه Google Cloud خود، روی «شروع به کار» کلیک کنید.
- تأیید کنید که منوی کشویی target Google Cloud Project با پروژه استقرار مورد نظر شما مطابقت دارد.
- AI Studio به طور خودکار یک شناسه سرویس منحصر به فرد برای نمونه Cloud Run ایجاد میکند.
- روی انتشار برنامه کلیک کنید.
- ساخت کانتینر، ثبت نام و استقرار سرویس در پسزمینه اجرا میشود. این فرآیند معمولاً در عرض ۲ تا ۴ دقیقه تکمیل میشود.
- وقتی استقرار تمام شد، URL برنامه تولید شده را کپی کنید و لینک برنامه زنده را در یک برگه مرورگر مشاهده کنید!
۸. بررسی بهترین شیوههای امنیتی و تولید
هنگام انتقال این برنامه از یک نمونه اولیه به یک محیط عملیاتی، این ارکان امنیتی را در نظر داشته باشید:
۱. محدودیتهای کلید API نقشههای گوگل
هرگز کلیدهای API نقشههای گوگل در محیط عملیاتی را بدون محدودیت رها نکنید. در کنسول ابری گوگل :
- محدودیتهای API: کلید را طوری محدود کنید که فقط بتواند APIهای خاصی را فراخوانی کند (API جاوا اسکریپت نقشهها، API کدگذاری جغرافیایی، API مکانها).
- محدودیتهای برنامه: کلید را با استفاده از ارجاعدهندههای HTTP (مثلاً
https://yourgame.com/*) محدود کنید تا از استفاده غیرمجاز در سایتهای شخص ثالث جلوگیری شود.
۲. ایمنسازی کلید API جمینی
کلید API مربوط به Gemini هرگز نباید در جاوا اسکریپت سمت کلاینت نمایش داده شود.
- معماری تولید: یک سرویس بکاند سبک (مثلاً Cloud Run یا Cloud Functions) بسازید تا به عنوان یک پروکسی عمل کند. فرانتاند شما، بکاند شما (
/api/get-fun-facts) را فراخوانی میکند و بکاند با استفاده از یک متغیر محیطی (GEMINI_API_KEY) به طور ایمن با Google AI Studio ارتباط برقرار میکند.
۹. منابع را پاکسازی کنید
برای جلوگیری از هرگونه هزینه پیشبینی نشده یا پاکسازی منابع فضای کاری خود:
- در Google AI Studio، به صفحه برنامهها بروید.
- برنامه خود را در شبکه یا لیست پیدا کنید.
- برای حذف وضعیت برنامه و لغو انتشار سرویس از Cloud Run، روی نماد سطل زباله کلیک کنید.
- اگر با استفاده از یک پروژه استاندارد مستقر شدهاید و میخواهید تمام منابع را به طور کامل خاموش کنید، به تنظیمات پروژه کنسول گوگل کلود بروید و پروژه اصلی را حذف کنید.
۱۰. نتیجهگیری
تبریک! شما یک برنامه وب مکانی مبتنی بر هوش مصنوعی را از Google AI Studio طراحی، توسعه و مستقر کردهاید. شما با موفقیت از APIهای پلتفرم نقشههای گوگل برای ساخت یک بازی تعاملی، مبتنی بر دادههای دنیای واقعی، استفاده کردهاید.
برای دریافت نشان Completed Builder Journey به این لینک مراجعه کنید!
برای ادامه سفرتان، برای آزمایشگاه بعدی به goo.gle/builders بروید.