پرسشگان و عیب‌یابی

تفاوت‌های بین استفاده از Gemini Developer API و Agent Platform Gemini API (formerly Vertex AI)

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

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

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

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

نحوه استفاده از Gemini Developer API و Agent Platform Gemini API (formerly Vertex AI)

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

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

میاناهای برنامه‌سازی کاربردی موردنیاز و نحوه فعال کردن آن‌ها

برای استفاده از کیت‌های توسعه نرم‌افزار Firebase AI Logic با Agent Platform Gemini API (formerly Vertex AI)، پروژه شما باید دو میانای برنامه‌سازی کاربردی زیر را فعال داشته باشد:

• Agent Platform API (aiplatform.googleapis.com)
• Firebase AI Logic API (firebasevertexai.googleapis.com)

می‌توانید این API-ها را بااستفاده از یکی از گزینه‌های زیر فعال کنید:

• گزینه ۱ (توصیه‌شده): میاناهای برنامه‌سازی کاربردی را با چند کلیک در کنسول Firebase فعال کنید:

  1. در کنسول Firebase، به صفحه سرویس‌های هوش مصنوعی > Firebase AI Logic بروید.

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

  3. برای شروع به کار با Agent Platform Gemini API (formerly Vertex AI)، انتخاب کنید.

     با این کار، گردش کار راهنمایی‌شده‌ای راه‌اندازی می‌شود که این دو میانای برنامه‌سازی کاربردی را برای شما فعال می‌کند. Firebase همچنین یک حساب سرویس تحت مدیریت Google‏ (P4SA) برای مجاز کردن استفاده از Gemini API فراهم می‌کند و Firebase AI Logic API را به فهرست مجاز برای کلید Firebase API شما اضافه می‌کند.

• گزینه ۲ (دستی؛ توصیه نمی‌شود): میاناهای برنامه‌سازی کاربردی را در کنسول Google Cloud فعال کنید:

  1. روی هر پیوند میانای برنامه‌سازی کاربردی در بالای این ورودی پرسشگان کلیک کنید، سپس روی فعال کردن در صفحه هر میانای برنامه‌سازی کاربردی کلیک کنید.

  2. میانای برنامه‌سازی کاربردی Firebase AI Logic را به فهرست مجاز کلید میانای برنامه‌سازی کاربردی Firebase اضافه کنید.

نحوه غیرفعال کردن میاناهای برنامه‌سازی کاربردی در پروژه Firebase

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

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

اجازه‌های لازم برای استفاده از Firebase AI Logic

مدل‌های پشتیبانی‌شده هنگام استفاده از Firebase AI Logic

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

• Firebase AI Logic از مدل‌های زیر پشتیبانی می‌کند:

  • Gemini Developer API

    • بیشتر مدل‌های بنیادی Gemini

  • Agent Platform Gemini API (formerly Vertex AI)

    • بیشتر مدل‌های بنیادی Gemini

• Firebase AI Logic از مدل‌های زیر پشتیبانی نمی‌کند (صرف‌نظر از ارائه‌دهنده Gemini API انتخابی شما):

  • مدل‌های تنظیم‌شده

  • مدل‌های جاسازی، مدل‌های Veo، مدل‌های Lyria، مدل‌های رباتیک، مدل‌های استفاده از رایانه، Gemini مدل‌های Omni، یا Gemini مدل‌های Cyber

نحوه تنظیم حد نرخ به‌ازای هر کاربر

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

اگر می‌خواهید حد نرخ هر کاربر را تنظیم کنید، باید تنظیمات سهمیه را برای Firebase AI Logic API تنظیم کنید.

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

نحوه کاهش تأخیر و مصرف بالای نمانه

اگر با تأخیر زیاد یا مصرف بالای نمانه مواجه هستید، احتمالاً به‌دلیل پیکربندی سطح تفکر برای مدلی است که استفاده می‌کنید.

Gemini 3 و مدل‌های جدیدتر همیشه از «فرایند تفکر» داخلی استفاده می‌کنند که توانایی‌های استدلال و برنامه‌ریزی چندمرحله‌ای آن‌ها را به‌طور قابل‌توجهی بهبود می‌بخشد، و آن‌ها را برای تکالیف پیچیده مانند کدنویسی، ریاضیات پیشرفته، و تجزیه‌وتحلیل داده‌ها بسیار مؤثر می‌کند.

بااین‌حال، بسته به تکلیف، همیشه به سطوح بالاتر اندیشیدن نیاز نیست، و می‌توانید مدل را برای استفاده از سطح پایین‌تر اندیشیدن پیکربندی کنید. سطح تفکر پایین‌تر به کاهش تأخیر و مصرف کد کمک می‌کند. برای اینکه بتوانید تصمیم بگیرید که مدل چقدر به قابلیت تفکر نیاز دارد، مقایسه دشواری تکالیف را مرور کنید.

توجه داشته باشید که برای اکثر مدل‌های Gemini 3 و جدیدتر، سطح اندیشیدن پیش‌فرض روی HIGH تنظیم شده است.

الزامات نوع MIME برای درخواست‌های چندحالته (مانند ورودی‌های تصویر، PDF، ویدیو، و صدا)

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

• mimeType فایل. یک استثنا را در زیر ببینید.

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

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

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

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

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

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

در اینجا اطلاعات تکمیلی مختص پلاتفرم درباره این ویژگی ارائه شده است:

• برای Android:

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

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

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

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

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

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

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

ویژگی‌های پیشرفته‌ای که هنوز هنگام استفاده از Firebase AI Logic دردسترس نیستند: زمینه‌سازی با «جستجوی تصویر Google»، تنظیم دقیق مدل، تولید جاسازی‌ها، و بازیابی معنایی

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

• پایه‌مندسازی با «جستجوی Google Image»
• تنظیم دقیق مدل
• تولید جاسازی‌ها
• بازیابی معنایی

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

استفاده از داده‌ها برای آموزش مدل‌ها

حاکمیت داده و هوش مصنوعی مسئولانه را ببینید.

مدل‌های منسوخ‌شده یا تعطیل‌شده (بازنشسته) - فهرست و جایگزین‌ها

وقتی Google نسخه مدل پایداری را منتشر می‌کند، تلاش می‌کنیم آن را حداقل ۱۲ ماه قبل‌از اینکه مدل را خاموش (بازنشسته) کنیم دردسترس نگه داریم.

بااین‌حال، به موارد زیر توجه داشته باشید:

• برای Agent Platform Gemini API (formerly Vertex AI)، برخی‌از مدل‌های پایدار فقط دردسترس بودن کوتاه‌مدت دارند، یعنی ممکن است ۴۵ روز پس‌از انتشار مدل جایگزین غیرفعال (بازنشسته) شوند.

• برای Gemini Developer API، گاهی‌اوقات به‌جای خاموش کردن یک مدل، سرویس به‌طور خودکار درخواست را به مدل جدیدتری هدایت می‌کند. درخواست‌های ارسال‌شده به مدل جدیدتر با نرخ‌های مدل جدیدتر صورت‌حساب می‌شود.

• چند هفته قبل‌از تاریخ توقف، پروژه‌هایی که قبلاً از مدل استفاده نکرده‌اند، از شروع استفاده از آن منع خواهند شد.

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

مدل‌های استفاده عمومی

^{۱ برای Agent Platform Gemini API (formerly Vertex AI)، این یک «مدل دردسترس بودن کوتاه‌مدت» است. الگوهای نام‌گذاری و نسخه‌بندی مدل را ببینید.}

^{همه مدل‌های استفاده عمومی زیر نیز خاموش شده‌اند: gemini-1.0-pro، gemini-1.0-pro-001، gemini-1.0-pro-002، gemini-1.0-pro-vision، gemini-1.0-pro-vision-001 gemini-1.5-flash-001، gemini-1.5-flash، gemini-1.5-flash-002، gemini-1.5-pro-001، gemini-1.5-pro، gemini-1.5-pro-002}

مدل‌های تولیدکننده تصویر (Nano Banana و Imagen)

صدا - مدل‌های Live API

تغییرات لازم هنگام منسوخ شدن یا خاموش شدن (بازنشسته شدن) مدل‌ها

تاریخ توقف مدل را از کجا می‌توان پیدا کرد؟

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

• Google ایمیل‌هایی به اعضای پروژه مربوطه ارسال می‌کند.

• ما اطلاعیه‌ها و یادآوری‌هایی درباره تعطیلی‌های آتی در کانال‌های مختلف منتشر می‌کنیم:

  • یادداشت‌های انتشار (نمونه را ببینید)
  • برنماهای سطح صفحه در اسناد، صفحه مدل‌های پشتیبانی‌شده، و پرسشگان مدل‌های منسوخ‌شده و تعطیل‌شده

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

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

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

   همچنین مدل‌های جایگزین توصیه‌شده را در پرسشگان مدل‌های منسوخ‌شده و خاموش‌شده ارائه می‌دهیم.

2. نام مدل مورداستفاده برنامه‌تان را به‌روز کنید.

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

3. بررسی کنید که آیا لازم است کدی را به‌روز کنید.

   معمولاً نیازی نیست کدی را که مدل را فراخوانی می‌کند اصلاح کنید. در اینجا چند استثنا آورده شده است:

   • پارامترهای نمونه‌برداری پشتیبانی‌نشده: در جدیدترین مدل‌های Gemini 4.x و Gemini 3.x، چند پارامتر پشتیبانی نمی‌شود (به‌ویژه دما، top-K،‏ top-P، جریمه تکرار، جریمه حضور، و تعداد نامزدها).

   • سطح اندیشیدن درمقابل بودجه اندیشیدن: از مدل‌های Gemini 3.x به‌بعد، باید به‌جای thinkingBudget از thinkingLevel استفاده کنید (اما thinkingBudget همچنان برای سازگاری با نسخه‌های قدیمی پشتیبانی می‌شود). اما از مدل‌های Gemini 4.x، thinkingBudget پشتیبانی نمی‌شود. درباره تفکر بیشتر بدانید.

   • آزمایش با مقدار سطح تفکر: وقتی به نسل جدیدی ارتقا می‌دهید (برای مثال، از ۲.۵ به ۳.۸) و می‌خواهید مطمئن شوید که عملکرد و رفتار یکسانی (برای مثال، ازنظر تأخیر) دریافت می‌کنید، توصیه می‌کنیم مقدار سطح تفکر را روی مقدار پایین‌تری تنظیم کنید. درباره تفکر بیشتر بدانید.

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

تغییرات لازم برای بازسازی نمانام «Vertex AI» به «پلاتفرم عامل»

در اواسط سال ۲۰۲۶، Google Cloud نمانام «Vertex AI» را به «Gemini Enterprise Agent Platform» (یا «Agent Platform») تغییر داد. در بوم‌سازگان Firebase، ما به این سرویس با عنوان «Agent Platform Gemini API» اشاره می‌کنیم.

برای Google Cloud، این بازسازی نمانام شامل موارد زیر بود. توجه داشته باشید که تغییرات دیگری هم وجود داشت، اما برای Firebase AI Logic قابل‌اعمال نیستند.

• بازسازی نمانام محصول از «Vertex AI» به «Gemini Enterprise Agent Platform» (یا «Agent Platform»)، که شامل نشانی‌های وب جدید برای کنسول Google Cloud و اسناد است.

• تغییر دادن نام نمایشی میانای برنامه‌سازی کاربردی از «Vertex AI API» به «Agent Platform API». توجه داشته باشید که نام سرویس تغییر نکرده است: aiplatform.googleapis.com.

• Rebranding "Vertex AI Studio" to "Agent Studio".

• هیچ تغییری در قابلیت‌های میاناهای برنامه‌سازی کاربردی زیربنایی یا مدل‌های پشتیبانی‌شده ایجاد نشده است.

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

• نحو مقداردهی اولیه جدید برای سرویس پس‌زمینه «Gemini API»:

  Swift

  vertexAI را به agentPlatform تغییر دهید.

  • نحو agentPlatform از نسخه ۱۲.۱۷.۰ به بالای کیت توسعه نرم‌افزار دردسترس است.
  • نحو vertexAI در نسخه ۱۳.۰.۰ کیت توسعه نرم‌افزار برداشته شد.

  قبل

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  let ai = FirebaseAI.firebaseAI(backend: .vertexAI(location: "LOCATION"))
  
  // ...
  

  بعد

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the `agentPlatform` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  let ai = FirebaseAI.firebaseAI(backend: .agentPlatform(location: "LOCATION"))
  
  // ...
  

  Kotlin

  vertexAI را به agentPlatform تغییر دهید.

  • نحو agentPlatform از نسخه ۱۷.۱۵.۰ به بالای کیت توسعه نرم‌افزار و نسخه ۳۴.۱۷.۰ به بالای Firebase Android BoM دردسترس است.
  • نحو vertexAI در نسخه ۱۸٫۰٫۰ کیت توسعه نرم‌افزار و نسخه ۳۵٫۰٫۰ BoM برداشته شد.

  قبل

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  val ai = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "LOCATION"))
  
  // ...
  

  بعد

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the `agentPlatform` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  val ai = Firebase.ai(backend = GenerativeBackend.agentPlatform(location = "LOCATION"))
  
  // ...
  

  Java

  vertexAI را به agentPlatform تغییر دهید.

  • نحو agentPlatform از نسخه ۱۷.۱۵.۰ به بالای کیت توسعه نرم‌افزار و نسخه ۳۴.۱۷.۰ به بالای Firebase Android BoM دردسترس است.
  • نحو vertexAI در نسخه ۱۸٫۰٫۰ کیت توسعه نرم‌افزار و نسخه ۳۵٫۰٫۰ BoM برداشته شد.

  قبل

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.vertexAI("LOCATION"));
  
  // ...
  

  بعد

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the `agentPlatform` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.agentPlatform("LOCATION"));
  
  // ...
  

  Web

  VertexAIBackend را به AgentPlatformBackend تغییر دهید.

  • نحو AgentPlatformBackend از نسخه ۱۲.۱۷.۰+ کیت توسعه نرم‌افزار Firebase JS دردسترس است.
  • نحو VertexAIBackend در نسخه ۱۳.۰.۰ کیت توسعه نرم‌افزار برداشته شد.

  قبل

  import { getAI, getGenerativeModel, VertexAIBackend } from "firebase/ai";
  
  // ...
  
  // Initialize FirebaseApp
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `VertexAIBackend` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  const ai = getAI(firebaseApp, { backend: new VertexAIBackend('LOCATION') });
  
  // ...
  

  بعد

  import { getAI, getGenerativeModel, AgentPlatformBackend } from "firebase/ai";
  
  // ...
  
  // Initialize FirebaseApp
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the `AgentPlatformBackend` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  const ai = getAI(firebaseApp, { backend: new AgentPlatformBackend('LOCATION') });
  
  // ...
  

  Dart

  vertexAI را به agentPlatform تغییر دهید.

  • نحو agentPlatform از نسخه ۳.۱۵.۰ به بالای افزونه و نسخه ۴.۱۸.۰ به بالای Firebase Flutter BoM دردسترس است.
  • نحو vertexAI در نسخه ۵٫۰٫۰ افزونه و نسخه ۵٫۰٫۰+‏ Firebase Flutter BoM برداشته شد.

  قبل

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  final ai = await FirebaseAI.vertexAI(location: 'LOCATION');
  
  // ...
  

  بعد

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the `agentPlatform` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  final ai = await FirebaseAI.agentPlatform(location: 'LOCATION');
  
  // ...
  

  Unity

  VertexAI را به AgentPlatform تغییر دهید.

  • نحو AgentPlatform از کیت توسعه نرم‌افزار Firebase برای Unity نسخه ۱۳.۱۵.۰ به بالا دردسترس است.
  • نحو VertexAI در نسخه ۱۴.۰.۰ کیت توسعه نرم‌افزار برداشته شد.

  قبل

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `VertexAI` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "LOCATION"));
  
  // ...
  

  بعد

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
  // For the `AgentPlatform` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform(location: "LOCATION"));
  
  // ...
  

• مکان پیش‌فرض جدید برای دسترسی به مدل هنگام استفاده از نحو مقداردهی اولیه جدید:

  هنگام استفاده از نحو مقداردهی اولیه جدید «Agent Platform»، مکان به‌طور پیش‌فرض روی global تنظیم می‌شود.

  این تغییر به این دلیل ایجاد شده است که تقریباً همه مدل‌های Gemini در global پشتیبانی می‌شوند و Google Cloud دیگر از مکان us-central1 برای نسخه‌های جدید اکثر مدل‌های Gemini پشتیبانی نمی‌کند.

برای برنامه‌های Swift - تغییرات لازم برای انتقال از FirebaseAI به FirebaseAILogic

برای برنامه‌های پلاتفرم Apple، از کیت توسعه نرم‌افزار Firebase نسخه ۱۲.۵.۰، Firebase AI Logic تحت واحد FirebaseAILogic توزیع می‌شود. در نسخه ۱۳.۰.۰ کیت توسعه نرم‌افزار، واحد FirebaseAI برداشته شد.

چرا این تغییر را ایجاد کردیم؟

ما قبلاً این سرویس را تحت واحد FirebaseAI توزیع می‌کردیم. اما به‌دلایل زیر باید نام آن را به FirebaseAILogic تغییر می‌دادیم:

• Avoid a name collision between module and class that causes issues in binary distributions.

• ما را قادر می‌سازد تا از ماکروهای Swift برای توسعه ویژگی‌های آینده استفاده کنیم.

اگر به نسخه ۱۲.۵.۰+ یا ۱۳.۰.۰+ ارتقا می‌دهید، چه کاری باید انجام دهید؟

در Firebase 12 (با شروع از نسخه 12.5.0+)، تغییر نام ماژول به FirebaseAILogic غیرمخرب و سازگار با نسخه قدیمی است، بنابراین این تغییرات در Firebase 12 توصیه می‌شود. بااین‌حال، در کیت توسعه نرم‌افزار Firebase نسخه ۱۳.۰.۰، واحد قدیمی FirebaseAI برداشته شده است، بنابراین این تغییرات هنگام ارتقا به Firebase 13 الزامی است.

1. هنگام انتخاب وابستگی‌های Swift PM،‏ FirebaseAILogic را (به‌جای FirebaseAI) انتخاب کنید.

2. عبارت‌های وارد کردن را به FirebaseAILogic (به‌جای FirebaseAI) تغییر دهید.

آشنایی با تغییر نام از «Vertex AI in Firebase» به «Firebase AI Logic»

در سال ۲۰۲۴، مجموعه‌ای از کیت‌های توسعه نرم‌افزار کارخواه Firebase را راه‌اندازی کردیم که می‌توانستند از Agent Platform Gemini API (formerly Vertex AI) و همچنین درگاه پراکسی Firebase برای محافظت از آن میانای برنامه‌سازی کاربردی دربرابر سوءاستفاده و فعال کردن ادغام با سایر محصولات Firebase استفاده کنند. ما محصولمان را «Vertex AI در Firebase» نامیدیم و این نام محصول به‌درستی موارد استفاده دردسترس محصولمان را در آن زمان توصیف می‌کرد.

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

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

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

اجرای App Check الزامی برای همه نسخه‌های برنامه

App Check باید برای همه نسخه‌های برنامه‌تان که از Firebase AI Logic استفاده می‌کنند اجرا شود.

بسیار مهم است که App Check در اسرع وقت اجرا شود — به‌ویژه قبل‌از اینکه برنامه‌تان را به سیستم کنترل کد منبع دردسترس عموم بسپارید، برنامه‌تان را هم‌رسانی کنید، یا برنامه‌تان را دردسترس عموم قرار دهید.

اگر App Check را فوراً در پایگاه کد برنامه‌تان پیاده‌سازی کنید، همه نسخه‌های برنامه‌تان می‌توانند کدهای معتبر App Check ارسال کنند. درخواستی که توکن معتبر ارسال نکند، درستی‌سنجی‌نشده درنظر گرفته می‌شود و وقتی App Check اجرا شود، مسدود خواهد شد.

اگر قبلاً نسخه‌ای از برنامه‌تان را برای کاربران نهایی منتشر کرده‌اید که فاقد App Check است، به پرسشگان درباره نحوه پیاده‌سازی و اعمال App Check برای برنامه‌ای که قبلاً منتشر شده است مراجعه کنید.

به‌تأخیر انداختن اجرای خودکار App Check برای Firebase AI Logic

از ۲ نوامبر ۲۰۲۶، Firebase به‌طور خودکار Firebase App Check را برای Firebase AI Logic در پروژه Firebase شما اعمال خواهد کرد (اگر قبلاً اعمال نشده باشد).

وقتی App Check اجرا شود، هر درخواستی به Firebase AI Logic بدون یک کد معتبر App Check مسدود خواهد شد. این شامل نسخه‌های منتشرشده برنامه که ارائه‌دهنده گواهی تولید در آن‌ها پیاده‌سازی نشده است می‌شود.

اگر نسخه‌هایی از برنامه را منتشر کرده‌اید که App Check در آن‌ها پیاده‌سازی نشده است، می‌توانید اجرای خودکار App Check را برای Firebase AI Logic موقتاً به‌تأخیر بیندازید. بااین‌حال، پیش‌از ۲۱ ژانویه ۲۰۲۷، بسیار مهم است که برای پیاده‌سازی و اعمال App Check برای برنامه‌هایی که قبلاً منتشر کرده‌اید تلاش کنید.

در اینجا نحوه به‌تأخیر انداختن اجرای خودکار App Check برای Firebase AI Logic آورده شده است:

1. در کنسول Firebase، به برگه امنیت > بررسی برنامه > میاناهای برنامه‌سازی کاربردی بروید.

2. ردیف Firebase AI Logic را پیدا کنید.

3. در انتهای ردیف، انتخابگر تاریخ اجرا می‌شود: را با نماد editویرایش آن پیدا کنید.

4. تاریخی را که می‌خواهید App Check به‌طور خودکار برای Firebase AI Logic اجرا شود انتخاب کنید.

   آخرین تاریخ ممکن ۲۱ ژانویه ۲۰۲۷ است. پس‌از آن تاریخ، نمی‌توانید اجرای خودکار App Check را برای Firebase AI Logic به‌تأخیر بیندازید.

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

نحوه پیاده‌سازی و اعمال App Check برای برنامه‌ای که قبلاً منتشر شده است

برای نسخه‌های برنامه‌ای که App Check در آن‌ها پیاده‌سازی نشده است، درخواست‌های ارسال‌شده به Firebase AI Logic از آن نسخه‌ها فاقد توکن‌های App Check معتبر هستند و تأییدنشده درنظر گرفته می‌شوند. وقتی App Check برای Firebase AI Logic اجرا شود، این درخواست‌ها مسدود خواهند شد.

دستورالعمل‌های زیر به شما کمک می‌کند برنامه‌تان را انتقال دهید تا بتوانید App Check را به‌گونه‌ای اجرا کنید که از اختلال در سرویس برای برنامه‌ای که قبلاً منتشر شده است و App Check ندارد جلوگیری شود.

1. به‌تأخیر انداختن اجرای خودکار App Check برای Firebase AI Logic:

   1. در کنسول Firebase، به برگه امنیت > بررسی برنامه > میاناهای برنامه‌سازی کاربردی بروید.

   2. ردیف Firebase AI Logic را پیدا کنید.

   3. در انتهای ردیف، انتخابگر تاریخ اجرا می‌شود: را با نماد editویرایش آن پیدا کنید.

   4. تاریخی را که می‌خواهید App Check به‌طور خودکار برای Firebase AI Logic اجرا شود انتخاب کنید.

      آخرین تاریخ ممکن ۲۱ ژانویه ۲۰۲۷ است. پس‌از آن تاریخ، نمی‌توانید اجرای خودکار App Check را برای Firebase AI Logic به‌تأخیر بیندازید.

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

2. در اسرع وقت، ارائه‌دهنده گواهی تولید را در برنامه‌تان پیاده‌سازی کنید.

   • پلاتفرم‌های Apple: DeviceCheck یا App Attest یا reCAPTCHA Enterprise
   • Android: Play Integrity یا reCAPTCHA Enterprise
   • وب: reCAPTCHA Enterprise
   • Flutter: از همه ارائه‌دهندگان بالا، ازجمله reCAPTCHA Enterprise پشتیبانی می‌کند
   • Unity: از همه ارائه‌دهندگان بالا پشتیبانی می‌کند (پشتیبانی از reCAPTCHA Enterprise به‌زودی ارائه می‌شود)

3. درخواست‌های برنامه‌تان را پایش کنید تا به شما کمک کند تصمیم بگیرید چه زمانی برای اجرای App Check ایمن است.

   برای مثال، اگر تقریباً همه درخواست‌های اخیر ازسوی کارخواه‌های درستی‌سنجی‌شده باشد، باید اجرای App Check را مدنظر قرار دهید.

4. App Check را برای Firebase AI Logic اعمال کنید.

5. برای توسعه محلی وقتی App Check اعمال می‌شود، می‌توانید App Check ارائه‌کننده اشکال‌زدایی را راه‌اندازی کنید و همچنان App Check را برای Firebase AI Logic اعمال کنید.

آشنایی با ارتقاهای امنیتی (اواسط ۲۰۲۶) برای Gemini Developer API و Firebase AI Logic

در گذشته، Gemini Developer API برای مجاز کردن استفاده از Gemini Developer API (generativelanguage.googleapis.com) به کلیدهای میانای برنامه‌سازی کاربردی Gemini استاندارد متکی بود. اگر Firebase AI Logic را فعال کرده بودید و انتخاب کرده بودید که از Gemini Developer API استفاده کنید، Firebase کلید میانای برنامه‌سازی کاربردی Gemini را برای شما ایجاد می‌کرد که به Gemini Developer API محدود بود. این کلید Gemini Developer API key (auto created by Firebase) نام داشت.

از اواسط سال ۲۰۲۶، Gemini Developer API به جایگزین ایمن‌تری به‌نام «کلیدهای مجوز (auth)» (که درواقع حساب‌های سرویس هستند) ارتقا می‌یابد. Firebase AI Logic هم‌زمان ارتقا یافته است. به‌جای استفاده از کلید میانای برنامه‌سازی کاربردی Gemini استاندارد، Firebase AI Logic اکنون مجوزدهی برای Gemini Developer API را بااستفاده از حساب سرویس تحت مدیریت Google (P4SA) که به‌طور خودکار برای شما فراهم می‌کنیم انجام می‌دهد:
Firebase AI Logic Service Agent (service-PROJECT_ID@gcp-sa-firebasevertexai.iam.gserviceaccount.com)

برای پروژه‌های موجود و جدید، اگر ازطریق Firebase AI Logic به Gemini Developer API دسترسی پیدا کنید، برای بهره‌مندی از این ارتقاهای امنیتی از اواسط سال ۲۰۲۶، نیازی به انجام هیچ اقدامی ازسوی شما نیست.

نحوه انتقال کلید میانای API Gemini به «کلید مجوز (auth)»

برای پروژه‌های موجود و جدید، اگر ازطریق Firebase AI Logic به Gemini Developer API دسترسی پیدا کنید، لازم نیست برای بهره‌مندی از ارتقاهای امنیتی از اواسط ۲۰۲۶ اقدامی انجام دهید (ازجمله انتقال به «کلید مجوز (auth)»).

ازطرف توسعه‌دهندگان ما، Firebase AI Logic به‌طور خودکار همه تغییرات امنیتی لازم را برای تطبیق انتقال Gemini Developer API به «کلیدهای مجوز (auth)» الزامی انجام می‌دهد.

از اواسط سال ۲۰۲۶، Firebase AI Logic دیگر کلیدهای میانای برنامه‌سازی کاربردی Gemini استاندارد را ارائه نمی‌دهد یا از آن‌ها استفاده نمی‌کند. درعوض، Firebase AI Logic اکنون بااستفاده از حساب سرویس تحت مدیریت Google (P4SA) که به‌طور خودکار در پروژه Firebase شما برایتان فراهم می‌کنیم، مجوز Gemini Developer API را مدیریت می‌کند:
Firebase AI Logic Service Agent (service-PROJECT_ID@gcp-sa-firebasevertexai.iam.gserviceaccount.com)

با توجه به این تغییر، می‌توانید هر کلید میانای برنامه‌سازی کاربردی را که نام Gemini Developer API key (auto created by Firebase) دارد مرور و حذف کنید. می‌توانید این کلید را در کنسول Google Cloud حذف کنید. پیش‌از حذف کلید، موارد زیر را مرور کنید:

• این کلید میانای API Gemini را Firebase فقط برای استفاده با Firebase AI Logic ایجاد کرده است، بنابراین حذف آن باید ایمن باشد. بااین‌حال، قبل‌از حذف این کلید، باید همچنان بررسی کنید تا مطمئن شوید که به‌اشتباه از این کلید با ابزارهای دیگری که می‌توانند دسترسی به Gemini Developer API را فراهم کنند، مانند کیت‌های توسعه نرم‌افزار سرور GenAI یا Genkit، استفاده نکرده باشید. در اینجا نحوه بررسی میزان استفاده آمده است:
  1. در کنسول Google Cloud، به صفحه Gemini Developer API بروید، سپس روی مدیریت کلیک کنید.
  2. در برگه سنجه‌ها، در منو کرکره‌ای اعتبارنامه‌ها، کلید با نام Gemini Developer API key (auto created by Firebase) را انتخاب کنید.
  3. اگر نمودارهای نمایش‌داده‌شده از اوایل ژوئیه ۲۰۲۶ (زمانی که Firebase AI Logic استفاده از این کلیدهای میانای API را متوقف کرد) هیچ استفاده‌ای را نشان نمی‌دهند، می‌توانید کلید را با خیال راحت حذف کنید.
     بااین‌حال، اگر نمودارها استفاده را نشان می‌دهند، پس از کلید با ابزار دیگری استفاده می‌کنید و باید نام کلید را تغییر دهید تا مشخص شود که با آن ابزار استفاده می‌شود (و نه با Firebase AI Logic).
• مطمئن شوید که هیچ کلید میانای API دیگری را که نام آن حاوی بخش (auto created by Firebase) است حذف نمی‌کنید.