Google AI Studio چیست؟ آموزش ساخت پرامپت، دریافت کد و حفاظت از API Key
در این راهنمای عملی با Google AI Studio آشنا می‌شوید، یک Prompt قابل ارزیابی می‌سازید، تنظیمات مدل و Structured Output را آزمایش می‌کنید، کد JavaScript می‌گیرید و API Key را بدون افشای سمت کاربر به پروژه منتقل می‌کنید.
Google AI Studio محیطی تحت وب برای آزمایش مدل‌های Gemini، ساخت Prompt و مشاهده سریع نتیجه است. به جای اینکه از همان دقیقه اول یک Backend کامل بنویسید، می‌توانید دستور، نمونه ورودی، تنظیمات تولید و ابزارهای مدل را در یک فضای تعاملی امتحان کنید و وقتی رفتار به حد قابل قبول رسید، کد اولیه را برای زبان دلخواه بگیرید.
اما نمونه‌ای که در مرورگر جواب می‌دهد هنوز محصول آماده انتشار نیست. کیفیت باید با داده‌های واقعی سنجیده شود، خروجی باید قابل اعتبارسنجی باشد و API Key نباید داخل JavaScript مرورگر یا Repository قرار بگیرد. این راهنما دقیقاً این فاصله را پوشش می‌دهد: از اولین Prompt تا انتقال امن یک نمونه به برنامه واقعی.
Google AI Studio چیست و چه تفاوتی با Gemini دارد؟
Gemini نام خانواده مدل‌ها و تجربه‌های کاربری مرتبط است؛ Google AI Studio یک محیط توسعه برای آزمایش قابلیت‌های این مدل‌ها و Gemini API است. در AI Studio می‌توانید مکالمه چندمرحله‌ای بسازید، ورودی متن یا رسانه اضافه کنید، پارامترهای اجرا را تغییر دهید و قابلیت‌هایی مانند Structured Output، Function Calling، Code Execution و Grounding را برای سناریوی مناسب فعال کنید.
مزیت اصلی AI Studio سرعت بازخورد است. تغییر کوچک در System Instruction یا مثال‌ها را فوراً روی چند ورودی می‌بینید. محدودیت آن نیز همین سادگی است: یک نتیجه خوب، تضمین نمی‌کند همه ورودی‌ها درست پردازش شوند. برای تصمیم فنی باید مجموعه آزمون، معیار موفقیت و Budget داشته باشید.
| نیاز | بخش مناسب در AI Studio | خروجی قابل بررسی |
|---|---|---|
| آزمایش گفت‌وگو | Chat Prompt | پاسخ چندمرحله‌ای و حفظ Context |
| تنظیم رفتار ثابت | System Instruction | لحن، قالب و محدودیت پاسخ |
| خروجی قابل پردازش | Structured Output | JSON سازگار با Schema |
| اتصال به منطق برنامه | Function Calling | نام تابع و آرگومان‌های کنترل‌شده |
| انتقال نمونه به پروژه | Get code | نمونه درخواست SDK یا REST |
شروع کار با Google AI Studio
به نشانی رسمی AI Studio بروید و با حساب Google وارد شوید. اگر از حساب Workspace استفاده می‌کنید، مدیر سازمان می‌تواند دسترسی را محدود کند. پروژه‌ای جدا برای تمرین بسازید تا تنظیمات، سهمیه و کلیدهای آزمایشی با پروژه Production مخلوط نشوند.
- یک Chat Prompt تازه ایجاد کنید.
- مدلی را انتخاب کنید که برای نیاز شما مناسب است.
- System Instruction کوتاه و قابل سنجش بنویسید.
- سه ورودی عادی، مرزی و نامعتبر آماده کنید.
- نتیجه را بر اساس معیار مشخص ارزیابی کنید، نه صرفاً روان بودن متن.
اگر رابط یا نام گزینه‌ها در نسخه جدید تغییر کرده بود، از مستندات رسمی همان صفحه کمک بگیرید. مدل‌ها، سهمیه‌ها و قابلیت‌های آزمایشی ممکن است تغییر کنند؛ بنابراین نام مدل را بی‌دلیل در منطق اصلی برنامه Hard-code نکنید.
یک Prompt قابل ارزیابی چگونه نوشته می‌شود؟
Prompt حرفه‌ای فقط شرح خواسته نیست. باید نقش، ورودی، محدودیت، قالب خروجی و رفتار در حالت ابهام را روشن کند. برای مثال، در دسته‌بندی پیام پشتیبانی مشخص کنید چه برچسب‌هایی مجازند، مدل در صورت نبود اطلاعات چه کند و پاسخ چگونه توسط برنامه خوانده شود.
الگوی پیشنهادی برای System Instruction
- هدف: یک جمله درباره کاری که مدل باید انجام دهد.
- مرز: کارهایی که نباید انجام دهد یا اطلاعاتی که نباید حدس بزند.
- قالب: فیلدهای لازم، نوع داده و مقادیر مجاز.
- ابهام: خروجی مورد انتظار وقتی داده کافی نیست.
- کیفیت: معیارهایی مانند کامل بودن، استنادپذیری یا کوتاهی پاسخ.
به جای افزودن ده‌ها صفت کلی مثل «بسیار دقیق و عالی»، مثال‌های واقعی و ضدنمونه بدهید. سپس هر تغییر Prompt را با همان مجموعه آزمون اجرا کنید تا بدانید بهبود حاصل شده یا فقط خروجی متفاوت شده است.
سناریوی نمونه: دسته‌بندی درخواست پشتیبانی
فرض کنید برنامه باید پیام را در یکی از دسته‌های billing، technical یا account قرار دهد و میزان اطمینان را برگرداند. پاسخ آزاد برای Backend مناسب نیست؛ چون ممکن است توضیح اضافی، نام فیلد متفاوت یا JSON ناقص تولید شود. در این وضعیت Structured Output انتخاب بهتری است.
Structured Output را برای خروجی قابل اعتماد فعال کنید
در Run settings، Structured Output را فعال و Schema را تعریف کنید. Schema قرارداد داده را محدود می‌کند، اما صحت معنایی را تضمین نمی‌کند. مقدار confidence می‌تواند از نظر نوع معتبر باشد ولی از نظر واقعیت اشتباه باشد؛ بنابراین بازه عددی، مقادیر enum و کنترل سمت سرور همچنان ضروری‌اند.
{ "category": "technical", "confidence": 0.92, "needsHumanReview": false}برای ورودی‌های حساس یا مبهم، آستانه‌ای تعریف کنید که درخواست را به انسان برگرداند. مثلاً اگر confidence کمتر از مقدار مورد توافق بود یا پیام هم‌زمان چند مسئله داشت، needsHumanReview باید true شود. این تصمیم را صرفاً به متن مدل واگذار نکنید؛ Backend باید آن را کنترل کند.
تنظیمات مدل را هدفمند تغییر دهید
Run settings امکان تغییر پارامترهایی مانند دمای تولید و فعال کردن ابزارها را می‌دهد. برای استخراج داده و پاسخ‌های قراردادی، تنوع کمتر معمولاً آزمون‌پذیری را بهتر می‌کند. برای ایده‌پردازی می‌توان تنوع بیشتری پذیرفت. یک تنظیم واحد برای همه قابلیت‌ها مناسب نیست.
- هر بار فقط یک متغیر را تغییر دهید.
- نسخه Prompt، نام مدل و تنظیمات را کنار نتیجه ثبت کنید.
- ورودی‌های ثابت را برای مقایسه نگه دارید.
- خطا، زمان پاسخ و مصرف را همراه کیفیت بررسی کنید.
- قابلیت‌های ابزارمحور را فقط وقتی فعال کنید که کاربرد مشخص دارند.
Code Execution و Grounding سطح توانایی و ریسک را تغییر می‌دهند. داده محرمانه را بدون بررسی سیاست سازمانی وارد نکنید و نتیجه ابزار را حقیقت قطعی فرض نکنید. در محصول واقعی، لاگ قابل ممیزی و محدودیت دسترسی لازم است.
دریافت کد از AI Studio و انتقال به پروژه
پس از تثبیت نمونه، گزینه Get code را بزنید و زبان مناسب Backend را انتخاب کنید. کد تولیدشده نقطه شروع است، نه معماری نهایی. Timeout، Retry، مدیریت خطا، مشاهده‌پذیری، محدودیت اندازه ورودی و اعتبارسنجی خروجی را خودتان اضافه کنید.
نمونه زیر شکل کلی فراخوانی سمت سرور با SDK جاوااسکریپت را نشان می‌دهد. نام مدل را با مدل در دسترس پروژه خود تطبیق دهید و کلید را فقط از متغیر محیطی بخوانید:
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY}); const response = await ai.models.generateContent({ model: "YOUR_SUPPORTED_MODEL", contents: "پیام را دسته‌بندی کن: اتصال حساب من قطع می‌شود"}); console.log(response.text);در Production پاسخ را پیش از استفاده Parse و Validate کنید. اگر JSON نامعتبر یا فیلد خارج از enum بود، خطای کنترل‌شده برگردانید. متن ورودی کاربر را مستقیم داخل فرمان سیستم، Query پایگاه داده یا HTML قرار ندهید.
ساخت و نگهداری امن API Key
API Key یک Secret است و باید مانند رمز عبور با آن رفتار شود. آن را در Git، فایل عمومی، اسکرین‌شات آموزشی یا کد سمت مرورگر قرار ندهید. برنامه وب باید درخواست را به Backend خودتان بفرستد و Backend با کلید ذخیره‌شده در Environment یا Secret Manager به Gemini API متصل شود.
$env:GEMINI_API_KEY = "کلید را فقط در محیط محلی وارد کنید"node server.mjsRemove-Item Env:GEMINI_API_KEYاین نمونه فقط برای نشست موقت PowerShell است. در سرور واقعی از Secret Manager میزبان استفاده کنید، دسترسی را به سرویس لازم محدود کنید و Budget Alert بسازید. اگر کلید افشا شد، نخست کلید جایگزین را ایجاد و Deploy کنید، سپس کلید قدیمی را غیرفعال یا حذف و Usage را بررسی کنید.
Build mode و Secret سمت سرور
طبق مستندات رسمی، Build mode در AI Studio برای برنامه‌های جدید کلید Gemini را به‌صورت Secret در Runtime سمت سرور قرار می‌دهد و آن را وارد کد Client نمی‌کند. اگر پروژه را به شکل ZIP خارج می‌کنید، باید متغیر GEMINI_API_KEY را در محیط Hosting تنظیم کنید. قبل از Share یا Deploy، Network tab و Bundle نهایی را برای نبود Secret کنترل کنید.
هزینه، سهمیه و محدودیت‌ها را چگونه کنترل کنیم؟
واژه free در جست‌وجوها نباید باعث فرض رایگان بودن دائمی همه مدل‌ها و قابلیت‌ها شود. سهمیه و قیمت به مدل، Project و طرح فعال بستگی دارد و می‌تواند تغییر کند. صفحه رسمی Pricing و Dashboard مصرف را منبع تصمیم قرار دهید.
- برای محیط توسعه و Production پروژه جدا بسازید.
- سقف ورودی و خروجی را در Backend محدود کنید.
- درخواست تکراری را Cache کنید، اگر ماهیت داده اجازه می‌دهد.
- Timeout، Rate Limit و Retry با Backoff تعریف کنید.
- هزینه و خطا را بر اساس Feature ثبت کنید.
- برای انتشار عمومی App، سناریوی سوءاستفاده را آزمایش کنید.
اشتباه‌های رایج هنگام کار با AI Studio
اعتماد به یک پاسخ زیبا
روان بودن متن معیار صحت نیست. حداقل ده‌ها نمونه نماینده از داده واقعی بسازید و نتیجه را با پاسخ مورد انتظار مقایسه کنید. برای قابلیت حساس، بازبینی انسانی و Log قابل پیگیری در نظر بگیرید.
قرار دادن کلید در Frontend
Obfuscation و متغیر Build مانع استخراج Secret از مرورگر نمی‌شوند. کلید باید روی سرور بماند. اگر درخواست مستقیماً از Client ارسال شود، هر کاربر می‌تواند کلید یا الگوی دسترسی را از Bundle و Network مشاهده کند.
انتقال مستقیم کد نمونه به Production
کد Get code معمولاً برای نمایش سریع مسیر فراخوانی است. Validation، محدودیت ورودی، Telemetry، خطاهای سهمیه، سیاست نگهداری داده و تست بار را پیش از انتشار اضافه کنید.
فعال کردن همه ابزارها
هر Tool سطح حمله و هزینه را افزایش می‌دهد. Function Calling را با فهرست توابع محدود، Schema دقیق و مجوز سمت سرور پیاده کنید. هیچ آرگومان تولیدشده توسط مدل نباید بدون Validation عملیات مالی، حذف داده یا تغییر دسترسی انجام دهد.
چک‌لیست تبدیل Prompt به قابلیت واقعی
- هدف و معیار موفقیت را نوشته‌اید.
- ورودی‌های عادی، مرزی و نامعتبر دارید.
- System Instruction کوتاه و نسخه‌بندی‌شده است.
- خروجی ساختاریافته در Backend اعتبارسنجی می‌شود.
- API Key در Client و Git وجود ندارد.
- مدل و تنظیمات از Configuration خوانده می‌شوند.
- Timeout، Retry و Rate Limit تعریف شده‌اند.
- مصرف و خطا به تفکیک Feature ثبت می‌شود.
- برای نتیجه کم‌اطمینان مسیر بازبینی انسانی دارید.
- قبل از Deploy، Secret scanning و تست امنیت انجام می‌شود.
اگر قصد دارید خروجی AI Studio را در یک عامل برنامه‌نویسی توسعه دهید، مقاله ساخت AI Agent امن با Python را بخوانید. برای نمونه‌سازی سریع همراه با کنترل کیفیت نیز راهنمای وایب کدینگ امن و قابل انتشار مکمل مناسبی است.
جمع‌بندی
Google AI Studio بهترین استفاده را زمانی دارد که آن را آزمایشگاه Prompt بدانید: مسئله را کوچک کنید، رفتار را با نمونه‌های ثابت بسنجید، خروجی را ساختاریافته کنید و سپس کد را به Backend کنترل‌شده ببرید. API Key باید Secret سمت سرور بماند و کیفیت، هزینه و خطا باید قابل اندازه‌گیری باشند.
برای یادگیری پروژه‌محور هوش مصنوعی و تبدیل نمونه‌های آزمایشی به برنامه قابل انتشار، دوره‌ها و مسیرهای آموزشی خانه برنامه نویسان البرز را بررسی کنید.