سوالات متداول و عیب یابی

این صفحه پاسخ به سوالات متداول (FAQs) و اطلاعات عیب‌یابی در مورد رابط برنامه‌نویسی Gemini و کیت‌های توسعه نرم‌افزار Firebase AI Logic را ارائه می‌دهد.

Firebase AI Logic و SDK های کلاینت آن قبلاً " Vertex AI in Firebase " نامیده می‌شدند. در ماه مه 2025، ما خدمات خود را به Firebase AI Logic تغییر نام دادیم و بسته‌بندی مجدد کردیم تا خدمات و ویژگی‌های توسعه‌یافته خود را بهتر منعکس کنیم - برای مثال، اکنون از API توسعه‌دهنده Gemini پشتیبانی می‌کنیم!

داشبوردهای وضعیت

• منطق هوش مصنوعی فایربیس

• رابط برنامه‌نویسی کاربردی (API) توسعه‌دهندگان جمینی

• رابط برنامه‌نویسی کاربردی Vertex AI Gemini ( Vertex Gemini API و Vertex Imagen API )

سوالات متداول عمومی

چرا نام از « Vertex AI in Firebase » به « Firebase AI Logic » تغییر کرد؟

در سال ۲۰۲۴، ما مجموعه‌ای از SDKهای کلاینت فایربیس را راه‌اندازی کردیم که می‌توانستند از API مربوط به Vertex AI Gemini و همچنین یک دروازه پروکسی فایربیس برای محافظت از آن API در برابر سوءاستفاده و فعال کردن ادغام با سایر محصولات فایربیس استفاده کنند. ما محصول خود را "Vertex AI in Firebase" نامیدیم و این نام محصول به طور دقیق موارد استفاده موجود محصول ما را در آن زمان توصیف می‌کرد.

از آن زمان، ما قابلیت‌های محصول خود را گسترش داده‌ایم. برای مثال، از ماه مه ۲۰۲۵، ما اکنون پشتیبانی از رابط برنامه‌نویسی نرم‌افزار Gemini Developer را ارائه می‌دهیم، از جمله امکان محافظت از رابط برنامه‌نویسی نرم‌افزار Gemini Developer در برابر سوءاستفاده با استفاده از ادغام ما با Firebase App Check .

در نتیجه، نام «Vertex AI in Firebase» دیگر به طور دقیق نشان‌دهنده‌ی دامنه‌ی گسترش‌یافته‌ی محصول ما نیست. بنابراین، نام جدید - Firebase AI Logic - مجموعه‌ی ویژگی‌های در حال تکامل ما را بهتر منعکس می‌کند و به ما اجازه می‌دهد تا در آینده به گسترش پیشنهادات خود ادامه دهیم!

برای اطمینان از دریافت آخرین ویژگی‌های Firebase AI Logic (و در صورت تمایل شروع به استفاده از Gemini Developer API ) راهنمای مهاجرت را بررسی کنید.

چه تفاوت‌هایی بین استفاده از رابط برنامه‌نویسی نرم‌افزار Gemini Developer و رابط برنامه‌نویسی نرم‌افزار Vertex AI Gemini وجود دارد؟

جدول زیر تفاوت‌های مهم بین دو ارائه‌دهنده‌ی « Gemini API » را به‌طور کلی، صرف‌نظر از نحوه‌ی دسترسی شما، فهرست می‌کند:

	رابط برنامه‌نویسی کاربردی (API) توسعه‌دهندگان جمینی	Vertex AI Gemini API
قیمت‌گذاری	هم در طرح قیمت‌گذاری رایگان Spark و هم در طرح قیمت‌گذاری پرداخت در محل Blaze ^1 موجود است	همیشه به طرح قیمت‌گذاری Blaze ^1 که به صورت پرداخت در محل است نیاز دارد (در صورت استفاده با Firebase AI Logic )
محدودیت‌های نرخ (سهمیه)	محدودیت‌های صریح نرخ	از سهمیه اشتراکی پویا (DSQ) استفاده می‌کند که همه کاربران آن مدل در آن منطقه آن را به اشتراک می‌گذارند. توان عملیاتی تأمین‌شده (PT) در دسترس است.
مشخص کردن مکان دسترسی به مدل	توسط API پشتیبانی نمی‌شود	پشتیبانی شده توسط API
پشتیبانی از آدرس‌های اینترنتی Cloud Storage	توسط API ^2 پشتیبانی نمی‌شود	فایل‌های عمومی و فایل‌های محافظت‌شده توسط Firebase Security Rules
پشتیبانی از URL های یوتیوب و URL های مرورگر	فقط آدرس‌های اینترنتی یوتیوب	آدرس‌های اینترنتی یوتیوب و آدرس‌های اینترنتی مرورگر

^۱ دو ارائه‌دهنده‌ی API قیمت‌گذاری پرداخت به ازای استفاده‌ی متفاوتی دارند (برای اطلاعات بیشتر به مستندات مربوطه مراجعه کنید).

^۲- فایل API مربوط به Gemini Developer API از طریق کیت‌های توسعه نرم‌افزار Firebase AI Logic پشتیبانی نمی‌شود.

جدول زیر فهرستی از ویژگی‌های متداول مورد پرسش برای دو ارائه‌دهنده‌ی « Gemini API » را نشان می‌دهد. این جدول به‌طور خاص هنگام استفاده از SDKهای کلاینت Firebase AI Logic اعمال می‌شود.

ویژگی	رابط برنامه‌نویسی کاربردی (API) توسعه‌دهندگان جمینی	Vertex AI Gemini API
پشتیبانی از مدل‌های Gemini	پشتیبانی شده	پشتیبانی شده
پشتیبانی از مدل‌های Imagen	پشتیبانی شده	پشتیبانی شده
پشتیبانی از مدل‌های Veo	هنوز پشتیبانی نشده	هنوز پشتیبانی نشده
پشتیبانی از Gemini Live API	پشتیبانی شده	پشتیبانی شده
ادغام با Firebase App Check	پشتیبانی شده	پشتیبانی شده
سازگار با Firebase Remote Config	پشتیبانی شده	پشتیبانی شده
پشتیبانی از نظارت هوش مصنوعی در کنسول Firebase	پشتیبانی شده	پشتیبانی شده

توجه: هنگام استفاده از Firebase AI Logic ، قابلیت‌های زیر هنوز پشتیبانی نمی‌شوند : ذخیره‌سازی زمینه، تنظیم دقیق مدل، تولید جاسازی‌ها، بازیابی معنایی، صدای بومی برای Live API و برخی از ویژگی‌های پیشرفته مدل‌های Imagen .

آیا می‌توانم هم از رابط برنامه‌نویسی توسعه‌دهنده Gemini و هم از رابط برنامه‌نویسی Vertex AI Gemini استفاده کنم؟

بله، شما می‌توانید هر دو ارائه‌دهنده‌ی « Gemini API » را در پروژه‌ی Firebase خود فعال داشته باشید و از هر دو API در خود برنامه استفاده کنید.

برای جابجایی بین ارائه‌دهندگان API در کد خود، فقط مطمئن شوید که سرویس backend را به طور مناسب در کد خود تنظیم کرده‌اید .

مهم: اگر پروژه شما در طرح قیمت‌گذاری Blaze با پرداخت در محل (pay-as-you-go) قرار دارد (که برای استفاده از Vertex AI Gemini API و چندین محصول دیگر در اکوسیستم Firebase و Google Cloud لازم است)، توجه داشته باشید که همه فراخوانی‌ها به Gemini Developer API به صورت پرداخت در محل هستند.

API های مورد نیاز چیستند؟ و چگونه آنها را فعال کنم؟

برای مشاهده محتوای خاص ارائه دهنده، ارائه دهنده API Gemini خود را انتخاب کنید API توسعه‌دهندگان Gemini، Vertex AI، API Gemini

برای استفاده از کیت‌های توسعه نرم‌افزار (SDK) فایربیس هوش مصنوعی لاجیک (Firebase AI Logic) با رابط برنامه‌نویسی نرم‌افزار (API) توسعه‌دهنده جمینی (Gemini Developer API )، پروژه شما باید دو رابط برنامه‌نویسی نرم‌افزار (API) زیر را فعال داشته باشد:

• رابط برنامه‌نویسی کاربردی (API) توسعه‌دهنده Gemini ( generativelanguage.googleapis.com )
• رابط برنامه‌نویسی کاربردی منطق هوش مصنوعی فایربیس ( firebasevertexai.googleapis.com )

شما باید این دو API را با استفاده از کنسول Firebase فعال کنید:

1. در کنسول Firebase ، به صفحه منطق هوش مصنوعی فایربیس بروید.

2. روی شروع به کار کلیک کنید.

3. برای شروع کار با رابط برنامه‌نویسی کاربردی (API) توسعه‌دهنده Gemini ، این گزینه را انتخاب کنید.

   این یک گردش کار هدایت‌شده را راه‌اندازی می‌کند که دو API را برای شما فعال می‌کند. کنسول همچنین یک کلید API Gemini ایجاد می‌کند و API مربوط به Firebase AI Logic را به لیست مجوزهای کلید API Firebase شما اضافه می‌کند.

کدام مدل‌ها را می‌توان با SDK های Firebase AI Logic استفاده کرد؟

فهرست مدل‌های پشتیبانی‌شده را ببینید. ما مرتباً قابلیت‌های جدیدی به SDKها اضافه می‌کنیم، بنابراین برای به‌روزرسانی‌ها (و همچنین در یادداشت‌های انتشار، وبلاگ‌ها و پست‌های اجتماعی) به این بخش سوالات متداول مراجعه کنید.

• رابط برنامه‌نویسی کاربردی (API) توسعه‌دهندگان جمینی

  • هر دو مدل فونداسیون Gemini و Imagen .

    توجه داشته باشید که رابط برنامه‌نویسی نرم‌افزار Gemini Developer (صرف نظر از نحوه دسترسی به آن) فقط از مدل‌های پایدار خاص Imagen پشتیبانی می‌کند.

• Vertex AI Gemini API

  • هر دو مدل فونداسیون Gemini و Imagen .

• صرف نظر از ارائه دهنده API Gemini انتخابی شما

  • منطق هوش مصنوعی فایربیس از موارد زیر پشتیبانی نمی‌کند :

    • مدل‌های Gemini غیر پایه (مانند مدل‌های PaLM، مدل‌های تنظیم‌شده یا مدل‌های مبتنی بر Gemma).

    • مدل‌های قدیمی‌تر ایمیجن یا imagen-3.0-capability-001 .

وقتی مدل‌ها بازنشسته می‌شوند چه باید کرد؟

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

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

تاریخ بازنشستگی یک مدل را از کجا پیدا کنیم؟

در اینجا چند روش برای یافتن تاریخ بازنشستگی یک مدل آورده شده است:

• در زمان انتشار : ما تاریخ بازنشستگی مورد انتظار هر مدل را در چندین جای مستندات ارائه دهنده API Gemini و همچنین در مستندات Firebase فهرست کرده‌ایم (به صفحه مدل‌های پشتیبانی شده مراجعه کنید).

• با نزدیک شدن به تاریخ بازنشستگی : ما ایمیل‌هایی را برای اعضای مربوطه در پروژه ارسال می‌کنیم و در یادداشت‌های انتشار و سایر کانال‌ها، یادآوری‌هایی را در مورد هرگونه بازنشستگی قریب‌الوقوع منتشر می‌کنیم (به عنوان مثال، یادآوری تاریخ بازنشستگی برای مدل‌های پایدار Gemini 1.5 و 1.0).

اگر مدلی که استفاده می‌کنید در شرف بازنشستگی باشد، چه باید کرد؟

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

2. نام مدل مورد استفاده برنامه خود را قبل از تاریخ انقضا به‌روزرسانی کنید؛ در غیر این صورت، هرگونه درخواست به آن مدل با خطای ۴۰۴ مواجه خواهد شد.

   • شما نام مدل را هنگام مقداردهی اولیه، هنگام ایجاد یک نمونه GenerativeModel ، LiveModel یا ImagenModel تنظیم می‌کنید. حتماً توصیه‌های مهم زیر در مورد استفاده از Firebase Remote Config را مرور کنید.

   • هنگام استفاده از Firebase AI Logic ، معمولاً نیازی به تغییر هیچ یک از کدهایی که در واقع مدل را فراخوانی می‌کنند، ندارید.

3. برنامه خود را آزمایش کنید تا مطمئن شوید که پاسخ‌ها همچنان مطابق انتظار هستند.

از آنجا که درخواست‌ها برای مدل‌های از رده خارج شده با شکست مواجه می‌شوند، اکیداً توصیه می‌کنیم که مدل و نسخه مدل را در کدبیس برنامه خود به صورت hard code وارد نکنید . در عوض، Firebase Remote Config برای کنترل مدل و نسخه مدل مورد استفاده در برنامه خود تنظیم و استفاده کنید .

با Remote Config ، می‌توانید به صورت پویا و از راه دور ، مدل و نسخه مدل مورد استفاده برنامه خود را بدون انتشار نسخه جدیدی از برنامه خود تغییر دهید. هر نسخه از قبل منتشر شده برنامه شما (که برای استفاده از Remote Config پیکربندی شده است) بلافاصله شروع به استفاده از مدل و نام مدل جدید خواهد کرد.

تاریخ‌های بازنشستگی مدل‌های پایدار Gemini 1.5 و 1.0

• مدل‌های Gemini 1.5 Pro :

  • gemini-1.5-pro-002 (و gemini-1.5-pro ): 24 سپتامبر 2025
  • gemini-1.5-pro-001 : 24 مه 2025

• مدل‌های Gemini 1.5 Flash :

  • gemini-1.5-flash-002 (و gemini-1.5-flash ): 24 سپتامبر 2025
  • gemini-1.5-flash-001 : ۲۴ مه ۲۰۲۵

• مدل‌های Gemini 1.0 Pro Vision : ۲۱ آوریل ۲۰۲۵ (قبلاً برای ۹ آوریل ۲۰۲۵ برنامه‌ریزی شده بود)

• مدل‌های Gemini 1.0 Pro : ۲۱ آوریل ۲۰۲۵ (قبلاً برای ۹ آوریل ۲۰۲۵ برنامه‌ریزی شده بود)

چگونه می‌توانم برای هر کاربر محدودیت نرخ تعیین کنم؟

به طور پیش‌فرض، Firebase AI Logic محدودیت درخواست برای هر کاربر را ۱۰۰ درخواست در دقیقه (RPM) تعیین می‌کند.

اگر می‌خواهید محدودیت نرخ هر کاربر را تنظیم کنید، باید تنظیمات سهمیه را برای API منطق هوش مصنوعی فایربیس تنظیم کنید.

درباره سهمیه API Firebase AI Logic بیشتر بدانید. در آن صفحه، همچنین می‌توانید نحوه مشاهده و ویرایش سهمیه خود را بیاموزید.

برای استفاده از SDK های Firebase AI Logic به چه مجوزهایی ممکن است نیاز باشد؟

اکشن	مجوزهای مورد نیاز IAM	نقش(های) IAM که به طور پیش‌فرض شامل مجوزهای مورد نیاز هستند
ارتقاء صورتحساب به طرح قیمت‌گذاری پرداخت در حین استفاده (Blaze)	firebase.billingPlans.update resourcemanager.projects.createBillingAssignment resourcemanager.projects.deleteBillingAssignment	مالک
فعال کردن APIها در پروژه	serviceusage.services.enable	ویرایشگر مالک
ایجاد برنامه فایربیس	firebase.clients.create	مدیر فایربیس ویرایشگر مالک

آیا Firebase AI Logic از داده‌های من برای آموزش مدل‌ها استفاده می‌کند؟

به بخش «مدیریت داده‌ها و هوش مصنوعی مسئولانه» مراجعه کنید.

آیا نوع MIME در درخواست‌های چندوجهی من (مانند تصاویر، فایل‌های PDF، ویدیو و ورودی صدا) الزامی است؟

بله، در هر درخواست چندوجهی، شما همیشه باید موارد زیر را ارائه دهید:

• نوع فایل mimeType است. به یک استثنا در زیر مراجعه کنید.

• فایل. می‌توانید فایل را به صورت داده درون‌خطی ارائه دهید یا فایل را با استفاده از URL آن ارائه دهید.

در مورد انواع فایل‌های ورودی پشتیبانی‌شده، نحوه‌ی تعیین نوع MIME و دو گزینه برای ارائه‌ی فایل در فایل‌های ورودی پشتیبانی‌شده و الزامات، اطلاعات کسب کنید.

استثنا در گنجاندن نوع MIME در درخواست شما

یک استثنا در ارائه نوع MIME، ورودی‌های تصویر درون‌خطی برای درخواست‌های برنامه‌های بومی پلتفرم اندروید و اپل است.

کیت‌های توسعه نرم‌افزار Firebase AI Logic برای پلتفرم‌های اندروید و اپل، روشی ساده و سازگار با پلتفرم را برای مدیریت تصاویر در درخواست‌ها ارائه می‌دهند - همه تصاویر (صرف نظر از فرمت آنها) قبل از ارسال به سرور، در سمت کلاینت با کیفیت ۸۰٪ به JPEG تبدیل می‌شوند. این بدان معناست که وقتی تصاویر را به عنوان داده‌های درون‌خطی با استفاده از کیت‌های توسعه نرم‌افزار پلتفرم‌های اندروید و اپل ارائه می‌دهید، نیازی به مشخص کردن نوع MIME در درخواست ندارید .

این روش ساده‌سازی‌شده در مستندات Firebase AI Logic در مثال‌هایی برای ارسال تصاویر کدگذاری‌شده با base64 در درخواست‌ها نشان داده شده است.

در اینجا اطلاعات اضافی مربوط به پلتفرم در مورد این ویژگی آمده است:

• برای اندروید :

  • شما می‌توانید از روش ساده‌شده برای مدیریت انواع تصاویر بومی پلتفرم ( Bitmap ) در اعلان‌های چندوجهی که حاوی تصاویر به عنوان داده‌های درون‌خطی هستند، بهره ببرید (به مثال مراجعه کنید).

  • برای کنترل بیشتر بر فرمت‌ها و تبدیل‌های تصویر، می‌توانید تصاویر را به عنوان InlineDataPart ارائه دهید و نوع MIME خاص را نیز ارائه دهید. برای مثال:

    content { inlineData(/* PNG as byte array */, "image/png") }

• برای پلتفرم‌های اپل :

  • شما می‌توانید از روش ساده‌شده برای مدیریت انواع تصاویر بومی پلتفرم ( UIImage ، NSImage ، CIImage و CGImage ) در اعلان‌های چندوجهی که حاوی تصاویر به عنوان داده‌های درون‌خطی هستند، بهره ببرید (به مثال مراجعه کنید).

  • برای کنترل بیشتر بر فرمت‌ها و تبدیل‌های تصویر، می‌توانید تصاویر را به عنوان InlineDataPart ارائه دهید و نوع MIME خاص را نیز ارائه دهید. برای مثال:

    InlineDataPart(data: Data(/* PNG Data */), mimeType: "image/png")

آیا این ویژگی‌ها هنگام استفاده از منطق هوش مصنوعی فایربیس در دسترس هستند؟ ذخیره‌سازی متن، تنظیم دقیق مدل، تولید جاسازی‌ها، بازیابی معنایی و صدای بومی؟

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

• ذخیره سازی متن
• تنظیم دقیق یک مدل
• تولید جاسازی‌ها
• بازیابی معنایی
• صدای بومی برای Live API

اگر می‌خواهید این موارد را به عنوان درخواست ویژگی اضافه کنید یا به یک درخواست ویژگی موجود رأی دهید، به Firebase UserVoice مراجعه کنید.

سوالات متداول در مورد کلید API جمینی

این سوالات متداول فقط در صورتی قابل استفاده هستند که از رابط برنامه‌نویسی کاربردی (API) توسعه‌دهندگان Gemini استفاده کنید.

کلید API جمینی چیست؟

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

«کلید API Gemini » فقط به معنای کلید API است که API توسعه‌دهنده Gemini را در فهرست مجاز API خود دارد.

توجه: رابط برنامه‌نویسی کاربردی توسعه‌دهنده Gemini گاهی اوقات در کنسول Google Cloud «رابط برنامه‌نویسی کاربردی زبان مولد» نامیده می‌شود.

وقتی در کنسول Firebase مراحل راه‌اندازی Firebase AI Logic را طی می‌کنید، یک کلید API مربوط به Gemini ایجاد می‌کنیم که فقط به Gemini Developer API محدود می‌شود و سرویس پروکسی Firebase AI Logic را برای استفاده از این کلید API تنظیم می‌کنیم. این کلید API مربوط به Gemini که توسط Firebase تولید شده است، در صفحه اعتبارنامه‌های کنسول Google Cloud ، کلید API مربوط به Gemini Developer (که به طور خودکار توسط Firebase ایجاد شده است) نامگذاری شده است.

درباره محدودیت‌های API برای کلیدهای API بیشتر بدانید.

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

آیا باید کلید API مربوط به Gemini خود را به کدبیس برنامه موبایل یا وب خود اضافه کنم؟

هنگام استفاده از SDK های Firebase AI Logic ، کلید API مربوط به Gemini خود را به کدبیس برنامه خود اضافه نکنید .

در واقع، هنگام توسعه با SDK های Firebase AI Logic ، شما مستقیماً با کلید API Gemini خود تعامل ندارید. در عوض، سرویس پروکسی Firebase AI Logic ما به صورت داخلی کلید API Gemini را در هر درخواست به API توسعه‌دهنده Gemini - کاملاً در backend - لحاظ می‌کند.

به محض اینکه توسعه‌ی جدی برنامه‌ی خود را آغاز کردید، بسیار مهم است که آن را با Firebase App Check ادغام کنید تا فقط درخواست‌های برنامه‌ی اصلی و دستگاه‌های تأیید شده به backend ارسال شوند.

چگونه می‌توانم کلید API مربوط به Gemini را که برای فراخوانی API توسعه‌دهندگان Gemini استفاده می‌شود، تغییر دهم؟

هنگام استفاده از کیت‌های توسعه نرم‌افزار Firebase AI Logic ، بعید است که نیاز به تغییر کلید API Gemini خود داشته باشید. با این حال، در اینجا دو مورد وجود دارد که ممکن است نیاز به تغییر داشته باشید:

• اگر تصادفاً کلید را گم کرده‌اید و می‌خواهید آن را با یک کلید امن جدید جایگزین کنید.

• اگر تصادفاً کلید را حذف کردید. توجه داشته باشید که می‌توانید کلید را ظرف 30 روز پس از حذف، بازیابی کنید .

در اینجا نحوه تغییر کلید API Gemini که توسط SDK های Firebase AI Logic استفاده می شود، آورده شده است:

1. اگر کلید API Gemini تولید شده توسط Firebase شما هنوز وجود دارد، آن را حذف کنید.

   شما می‌توانید این کلید API را در پنل APIs & Services > Credentials کنسول Google Cloud حذف کنید. نام آن به صورت زیر است:
   کلید API توسعه‌دهنده Gemini (به‌طور خودکار توسط Firebase ایجاد شده است) .

2. در همان صفحه از کنسول Google Cloud ، یک کلید API جدید ایجاد کنید. پیشنهاد می‌کنیم نام آن را چیزی شبیه به این بگذارید:
   کلید API توسعه‌دهنده Gemini برای Firebase .

3. به این کلید API جدید، محدودیت‌های API را اضافه کنید و فقط Generated Language API را انتخاب کنید.
   «رابط برنامه‌نویسی کاربردی زبان مولد» (Generative Language API) چیزی است که گاهی اوقات در کنسول Google Cloud به رابط برنامه‌نویسی کاربردی توسعه‌دهندگان Gemini گفته می‌شود.

   هیچ محدودیتی برای برنامه اعمال نکنید ؛ در غیر این صورت سرویس پروکسی Firebase AI Logic آنطور که انتظار می‌رود کار نخواهد کرد.

4. دستور زیر را اجرا کنید تا این کلید جدید به عنوان کلید API Gemini که سرویس پروکسی Firebase AI Logic باید از آن استفاده کند، تنظیم شود.

   PROJECT_ID="PROJECT_ID"
   GENERATIVE_LANGUAGE_API_KEY="DEVELOPER_CREATED_GEMINI_API_KEY"
   curl \
     -X PATCH \
     -H "x-goog-user-project: ${PROJECT_ID}" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://firebasevertexai.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global/config" \
     -d "{\"generativeLanguageConfig\": {\"apiKey\": \"${GENERATIVE_LANGUAGE_API_KEY}\"}}"
   

   درباره gcloud CLI اطلاعات کسب کنید.

مطمئن شوید که این کلید API جدید Gemini را به کدبیس برنامه خود اضافه نمی‌کنید . درباره نحوه ایمن نگه داشتن کلید API Gemini خود بیشتر بدانید.

توجه: همیشه می‌توانید برای سوالات و راهنمایی هنگام کار با کلیدهای API با پشتیبانی Firebase تماس بگیرید .

آیا می‌توانم از «کلید API فایربیس» خود به عنوان کلید API جمینی استفاده کنم؟

خیر — شما نباید از «کلید API فایربیس» خود به عنوان کلید API جمینی استفاده کنید. اکیداً توصیه می‌کنیم که API توسعه‌دهنده جمینی را به لیست مجاز کلید API فایربیس خود اضافه نکنید .

کلید API فایربیس شما، کلید API است که در فایل پیکربندی فایربیس یا شیء‌ای که برای اتصال برنامه خود به فایربیس به کدبیس برنامه خود اضافه می‌کنید، فهرست شده است. وقتی از این کلید فقط با APIهای مرتبط با فایربیس (مانند منطق هوش مصنوعی فایربیس ) استفاده می‌کنید، اشکالی ندارد که کلید API فایربیس خود را در کد خود وارد کنید. اطلاعات مهم در مورد کلیدهای API فایربیس را بیاموزید .

در پنل APIs & Services > Credentials کنسول Google Cloud ، کلیدهای API فایربیس به این شکل هستند:

از آنجا که برای کار کردن APIهای مرتبط با Firebase، باید کلید API فایربیس خود را به کدبیس برنامه‌تان اضافه کنید، و از آنجا که API توسعه‌دهنده Gemini از طریق کلید API مجاز است، اکیداً توصیه می‌کنیم که API توسعه‌دهنده Gemini (که در کنسول Google Cloud با نام "API Generative Language" شناخته می‌شود) را به لیست مجاز API برای کلید API فایربیس خود اضافه نکنید . در این صورت، API توسعه‌دهنده Gemini را در معرض سوءاستفاده احتمالی قرار می‌دهید.

چگونه کلید API Gemini خود را ایمن نگه دارم؟

این سوالات متداول، برخی از بهترین شیوه‌های توصیه‌شده برای ایمن نگه‌داشتن کلید API Gemini شما را شرح می‌دهد.

اگر مستقیماً از طریق برنامه تلفن همراه یا وب خود، رابط برنامه‌نویسی کاربردی توسعه‌دهندگان Gemini را فراخوانی می‌کنید:

• از SDK های کلاینت Firebase AI Logic استفاده کنید.
• کلید API مربوط به Gemini خود را به کدبیس برنامه‌تان اضافه نکنید .

Firebase AI Logic یک سرویس پروکسی ارائه می‌دهد که به صورت داخلی کلید API Gemini شما را در هر درخواست به Gemini Developer API - کاملاً در backend - قرار می‌دهد.

علاوه بر این، موارد زیر را اکیداً توصیه می‌کنیم:

• به محض اینکه توسعه‌ی جدی برنامه‌ی خود را آغاز کردید، آن را با Firebase App Check ادغام کنید تا از منابع backend و همچنین APIهای مورد استفاده برای دسترسی به مدل‌های مولد محافظت کنید.

• کلید API Gemini تولید شده توسط Firebase را خارج از Firebase AI Logic دوباره استفاده نکنید . اگر برای مورد استفاده دیگری به کلید API Gemini نیاز دارید، یک کلید جداگانه ایجاد کنید.

• به طور کلی، شما نباید کلید API Gemini تولید شده توسط Firebase را تغییر دهید. این کلید در کنسول Google Cloud با نام کلید API توسعه‌دهنده Gemini (که به طور خودکار توسط Firebase ایجاد شده است) نامگذاری شده است.

  • هیچ API اضافی را به لیست مجاز API برای کلید API Gemini تولید شده توسط Firebase خود اضافه نکنید . در لیست مجاز API، کلید API Gemini شما فقط باید API توسعه‌دهنده Gemini (که در کنسول Google Cloud "API Generative Language" نامیده می‌شود) را داشته باشد.

  • هیچ محدودیتی برای برنامه اعمال نکنید ؛ در غیر این صورت سرویس پروکسی Firebase AI Logic آنطور که انتظار می‌رود کار نخواهد کرد.

کلید API جمینی من لو رفته است. چه کاری باید انجام دهم؟

اگر کلید API Gemini شما لو رفته است، دستورالعمل‌ها را برای تغییر کلید API Gemini که برای فراخوانی API توسعه‌دهندگان Gemini استفاده می‌شود، دنبال کنید.

همچنین، بهترین شیوه‌های توصیه‌شده برای ایمن نگه‌داشتن کلید API Gemini خود را مرور کنید.

عیب‌یابی خطاها

چگونه این خطای ۴۰۴ را برطرف کنم؟ Firebase AI Logic genai config not found

اگر در حال تلاش برای استفاده از API توسعه‌دهنده Gemini هستید و خطای ۴۰۴ با مضمون Firebase AI Logic genai config not found » دریافت می‌کنید، معمولاً به این معنی است که پروژه Firebase شما کلید API معتبر Gemini برای استفاده با SDKهای کلاینت Firebase AI Logic ندارد.

در اینجا محتمل‌ترین علل این خطا آورده شده است:

• شما هنوز پروژه Firebase خود را برای Gemini Developer API تنظیم نکرده‌اید.

  چه باید کرد:
  در کنسول Firebase ، به صفحه Firebase AI Logic بروید. روی Get started کلیک کنید و سپس Gemini Developer API را انتخاب کنید. API را فعال کنید و کنسول پروژه شما را برای Gemini Developer API تنظیم می‌کند. پس از تکمیل گردش کار، دوباره درخواست خود را امتحان کنید.

• اگر اخیراً مراحل راه‌اندازی Firebase AI Logic را در کنسول Firebase طی کرده‌اید، ممکن است کلید API Gemini شما هنوز برای همه سرویس‌های backend مورد نیاز در همه مناطق در دسترس نباشد.

  چه باید کرد:
  چند دقیقه صبر کنید و سپس دوباره درخواست خود را امتحان کنید.

• ممکن است کلید API مربوط به Gemini شما از پروژه Firebase حذف شده باشد.

  چه باید کرد:
  بیاموزید که چگونه کلید API Gemini مورد استفاده توسط Firebase AI Logic را تغییر دهید .

چگونه می‌توانم این خطای ۴۰۰ را برطرف کنم؟ Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

اگر می‌خواهید یک درخواست چندوجهی با آدرس اینترنتی Cloud Storage for Firebase ارسال کنید، ممکن است با خطای ۴۰۰ زیر مواجه شوید:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

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

در اینجا راه حلی برای رفع مشکل پروژه شما و ارائه صحیح این سرویس ایجنت‌ها ارائه شده است تا بتوانید آدرس‌های اینترنتی Cloud Storage for Firebase در درخواست‌های چندوجهی خود بگنجانید. شما باید مالک پروژه باشید و فقط باید این مجموعه وظایف را یک بار برای پروژه خود انجام دهید.

1. با استفاده از gcloud CLI به آن دسترسی پیدا کنید و احراز هویت کنید.
   ساده‌ترین راه برای انجام این کار از طریق Cloud Shell است. برای اطلاعات بیشتر به مستندات Google Cloud مراجعه کنید.

2. در صورت درخواست، دستورالعمل‌های نمایش داده شده در ترمینال را دنبال کنید تا gcloud CLI روی پروژه Firebase شما اجرا شود.

   شما به شناسه پروژه Firebase خود نیاز دارید که می‌توانید آن را در بالای پروژه در کنسول Firebase پیدا کنید.

3. با اجرای دستور زیر، عوامل سرویس مورد نیاز را در پروژه خود فراهم کنید:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
   

4. چند دقیقه صبر کنید تا از آماده‌سازی سرویس‌ها مطمئن شوید و سپس دوباره درخواست چندوجهی خود را که شامل آدرس اینترنتی Cloud Storage for Firebase است، ارسال کنید.

اگر بعد از چند دقیقه انتظار هنوز این خطا را دریافت می‌کنید، با پشتیبانی Firebase تماس بگیرید.

چگونه می‌توانم این خطای ۴۰۰ را برطرف کنم؟ API key not valid. Please pass a valid API key.

اگر خطای ۴۰۰ دریافت کردید که می‌گوید API key not valid. Please pass a valid API key. معمولاً به این معنی است که کلید API در فایل/شیء پیکربندی Firebase شما وجود ندارد یا برای استفاده با برنامه و/یا پروژه Firebase شما تنظیم نشده است.

بررسی کنید که کلید API فهرست‌شده در فایل/شیء پیکربندی Firebase شما با کلید API برنامه‌تان مطابقت داشته باشد. می‌توانید تمام کلیدهای API خود را در پنل APIها و خدمات > اعتبارنامه‌ها در کنسول Google Cloud مشاهده کنید.

اگر متوجه شدید که آنها مطابقت ندارند، یک فایل/شیء پیکربندی Firebase جدید دریافت کنید و سپس آن را که در برنامه شما است جایگزین کنید . فایل/شیء پیکربندی جدید باید حاوی یک کلید API معتبر برای برنامه و پروژه Firebase شما باشد.

چگونه می‌توانم این خطای ۴۰۳ را برطرف کنم؟ Requests to this API firebasevertexai.googleapis.com ... are blocked.

اگر خطای ۴۰۳ با مضمون « Requests to this API firebasevertexai.googleapis.com ... are blocked. دریافت کردید، معمولاً به این معنی است که کلید API در پیکربندی Firebase در برنامه شما دارای محدودیت‌هایی است که مانع از فراخوانی API مورد نیاز می‌شود.

برای رفع این مشکل، باید محدودیت‌های کلید API خود را در کنسول Google Cloud به‌روزرسانی کنید تا API مورد نیاز را شامل شود. برای Firebase AI Logic ، باید مطمئن شوید که API مربوط به Firebase AI Logic ( firebasevertexai.googleapis.com ) در فهرست APIهای انتخاب‌شده‌ای که می‌توان با استفاده از کلید API فراخوانی کرد، گنجانده شده است.

این مراحل را دنبال کنید:

1. در کنسول Google Cloud ، پنل APIs & Services > Credentials را باز کنید.

2. کلید API که برنامه شما برای استفاده از آن پیکربندی شده است را انتخاب کنید (برای مثال، "کلید iOS" برای یک برنامه iOS).

3. در صفحه ویرایش کلید API ، بخش محدودیت‌های API را پیدا کنید.

4. مطمئن شوید که گزینه Restrict key انتخاب شده باشد. اگر اینطور نیست، کلید شما بدون محدودیت است و احتمالاً این منبع خطا نیست.

   توجه: اگر کلید API بدون محدودیت دارید، اکیداً توصیه می‌کنیم که «محدودیت‌های API» را روی کلید API فایربیس خود اعمال کنید.

5. در منوی کشویی Selected APIs ، عبارت Firebase AI Logic API را جستجو و انتخاب کنید تا به لیست APIهای انتخابی که می‌توان با استفاده از کلید API فراخوانی کرد، اضافه شود.

6. روی ذخیره کلیک کنید.

   اعمال تغییرات ممکن است تا پنج دقیقه طول بکشد.

توجه: APIهای مرتبط با Firebase فقط از کلیدهای API برای شناسایی پروژه یا برنامه Firebase استفاده می‌کنند، نه برای مجوز فراخوانی API (مانند برخی دیگر از APIها). مجوزدهی برای APIهای مرتبط با Firebase جدا از کلید API انجام می‌شود، یا از طریق مجوزهای Google Cloud IAM، Firebase Security Rules یا Firebase App Check . درباره کلیدهای API Firebase بیشتر بدانید.

چگونه می‌توانم این خطای ۴۰۳ را برطرف کنم؟ PERMISSION_DENIED: The caller does not have permission.

اگر خطای ۴۰۳ با متن PERMISSION_DENIED: The caller does not have permission. دریافت کردید، معمولاً به این معنی است که کلید API موجود در فایل/شیء پیکربندی Firebase شما متعلق به یک پروژه Firebase متفاوت است.

بررسی کنید که کلید API فهرست‌شده در فایل/شیء پیکربندی Firebase شما با کلید API برنامه‌تان مطابقت داشته باشد. می‌توانید تمام کلیدهای API خود را در پنل APIها و خدمات > اعتبارنامه‌ها در کنسول Google Cloud مشاهده کنید.

اگر متوجه شدید که آنها مطابقت ندارند، یک فایل/شیء پیکربندی Firebase جدید دریافت کنید و سپس آن را که در برنامه شما است جایگزین کنید . فایل/شیء پیکربندی جدید باید حاوی یک کلید API معتبر برای برنامه و پروژه Firebase شما باشد.

چگونه می‌توانم خطای ۴۰۴ که می‌گوید مدلی با عنوان « was not found or your project does not have access to it » را برطرف کنم؟

برای مثال: " Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-2.5-flash-image-preview was not found or your project does not have access to it. Please ensure you are using a valid model version. "

چند دلیل مختلف وجود دارد که چرا ممکن است با چنین خطایی مواجه شوید.

• نام مدل نامعتبر

  • علت : نام مدلی که ارائه داده‌اید، نام مدل معتبری نیست.

  • راه حل : نام مدل و نسخه مدل خود را با لیست تمام مدل‌های پشتیبانی شده و موجود مقایسه کنید. حتماً بخش‌ها و ترتیب آنها را در نام مدل بررسی کنید. برای مثال، نام مدل "نانو موز" gemini-2.5-flash-image-preview است ، نه gemini-2.5-flash-preview-image-generation .

• مکان نامعتبر است (فقط در صورت استفاده از ارائه دهنده API Vertex AI Gemini و یک مدل پیش نمایش قابل اجرا است)

  • علت : شما از یک نسخه پیش‌نمایش مدل (مثلاً gemini-2.5-flash-image-preview ) استفاده می‌کنید و موقعیت global را مشخص نکرده‌اید.

    اگر از API مربوط به Vertex AI Gemini استفاده می‌کنید، تمام مدل‌های پیش‌نمایش Gemini 2.5 و بالاتر که پس از ژوئن 2025 منتشر شده‌اند، فقط در مکان global (از جمله نسخه پیش‌نمایش "nano banana") در دسترس هستند. با این حال، از آنجایی که Firebase AI Logic به طور پیش‌فرض روی برای موقعیت مکانی us-central1 ، هنگام استفاده از این مدل‌های پیش‌نمایش ، باید هنگام مقداردهی اولیه سرویس backend API Vertex AI Gemini در کد خود، موقعیت مکانی global را صریحاً مشخص کنید.

  • راه حل : هنگام مقداردهی اولیه سرویس Vertex AI Gemini API ، مکان را global مشخص کنید. درباره نحوه تعیین مکان برای دسترسی به مدل (از جمله قطعه کدها) بیشتر بیاموزید.

• مکان نامعتبر است (فقط در صورت استفاده از ارائه دهنده API Vertex AI Gemini قابل اجرا است)

  • دلیل : شما از مدلی استفاده می‌کنید که در مکانی که می‌خواهید به آن دسترسی پیدا کنید، پشتیبانی نمی‌شود.

    اگر از API مربوط به Vertex AI Gemini استفاده می‌کنید، برخی از مدل‌ها فقط در مکان‌های خاصی در دسترس هستند . برای مثال (اما نه به طور کامل):

    • مدل‌های Imagen در موقعیت global پشتیبانی نمی‌شوند .
    • مدل‌های Gemini Live API (مانند gemini-2.0-flash-live-preview-04-09 ) فقط در ... پشتیبانی می‌شوند. مکان us-central1 .
    • مدل‌های Gemini 2.5 (مانند gemini-2.5-pro ) فقط در بازارهای global ، ایالات متحده و برخی از بازارهای اروپایی (و گاهی اوقات در سایر نقاط، اگر پروژه شما گزینه‌های ویژه‌ای داشته باشد) موجود هستند.

  • راه حل : هنگام مقداردهی اولیه سرویس Vertex AI Gemini API ، مطمئن شوید که یک مکان پشتیبانی شده برای مدلی که استفاده می‌کنید، مشخص کرده‌اید. درباره نحوه تعیین مکان دسترسی به مدل (از جمله قطعه کدها) و مکان‌های پشتیبانی شده برای مدل‌ها بیشتر بیاموزید.

    توجه داشته باشید که Firebase AI Logic به صورت پیش‌فرض روی مکان us-central1 .

درباره تجربه خود با Firebase AI Logic بازخورد دهید