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

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

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

^‫۱ دو ارائه‌دهنده 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 در کدتان، کافی است مطمئن شوید که خدمات زیرینه را به‌درستی در کدتان تنظیم کرده‌اید.

تغییرات لازم برای تغییر نام تجاری «Vertex AI» به «Agent Platform»

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

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

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

• تغییر نام نمایشی میانای برنامه‌سازی کاربردی از «میانای برنامه‌سازی کاربردی Vertex AI» به «میانای برنامه‌سازی کاربردی پلاتفرم عامل». توجه داشته باشید که نام سرویس بدون تغییر باقی مانده است: aiplatform.googleapis.com.

• تغییر نام تجاری «Vertex AI Studio» به «Agent Studio».

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

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

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

  Swift

  ‫vertexai را به agentPlatform تغییر دهید.
  از کیت توسعه نرم‌افزار Firebase برای پلاتفرم‌های Apple نسخه ۱۲.۱۷.۰ و بالاتر دردسترس است.

  قبل‌از

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexai` syntax, the default location is `us-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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 تغییر دهید.
  از کیت توسعه نرم‌افزار Firebase AI Logic برای Android نسخه ۱۷.۱۵.۰ و بالاتر دردسترس است (Firebase Android BoM نسخه ۳۴.۱۷.۰ و بالاتر).

  قبل‌از

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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 تغییر دهید.
  از کیت توسعه نرم‌افزار Firebase AI Logic برای Android نسخه ۱۷.۱۵.۰ و بالاتر دردسترس است (Firebase Android BoM نسخه ۳۴.۱۷.۰ و بالاتر).

  قبل‌از

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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 تغییر دهید.
  از کیت توسعه نرم‌افزار Firebase JS نسخه ۱۲.۱۷.۰ و بالاتر دردسترس است.

  قبل‌از

  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-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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 تغییر دهید.
  از افزایه Firebase AI Logic برای Flutter نسخه ۳.۱۵.۰ و بالاتر دردسترس است (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-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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 تغییر دهید.
  از کیت توسعه نرم‌افزار Firebase برای Unity نسخه ۱۳.۱۵.۰ و بالاتر دردسترس است.

  قبل‌از

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `VertexAI` syntax, the default location is `us-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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"));
  
  // ...
  

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

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

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

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

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

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

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

• از تصادم نام بین واحد و کلاسی که باعث ایجاد مشکل در توزیع‌های باینری می‌شود اجتناب کنید.

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

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

تغییر نام پیمانه به FirebaseAILogic غیرمخرب است و در Firebase 12 با نسخه‌های قبلی سازگار است. بااین‌حال، در Firebase 13، این واحد قدیمی برداشته خواهد شد. پیش‌از به‌روزرسانی به Firebase 13، وابستگی‌ها و وارد کردن‌هایتان را انتقال دهید.

برای تغییر نام این واحد، هیچ تغییری الزامی نیست، اما توصیه می‌کنیم که موارد زیر را انجام دهید:

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

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

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

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

• Gemini Developer API (generativelanguage.googleapis.com)
• Firebase AI Logic میانای برنامه‌سازی کاربردی (firebasevertexai.googleapis.com)

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

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

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

3. برای شروع کار با Gemini Developer API، انتخاب کنید.

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

نحوه غیرفعال کردن میاناهای برنامه‌سازی کاربردی در پروژه 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 مدل‌های Flash Cyber

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

حتماً پرسشگان مربوط به تغییرات لازم هنگام منسوخ شدن یا ازکار افتادن (بازنشسته شدن) مدل‌ها را مرور کنید.

Gemini 2.5 مدل پایدار - تاریخ‌های خاموش شدن و جایگزین‌ها

• ‫Gemini 2.5 Pro،‏ Gemini 2.5 Flash، و Gemini 2.5 Flash‑Lite

  gemini-2.5-pro
gemini-2.5-flash
gemini-2.5-flash-lite
gemini-2.5-flash-image (با نام مستعار «نانو موز»)

  • برای مدل‌های با کاربرد عمومی، تاریخ خاموش شدن به ارائه‌دهنده انتخابی شما Gemini API بستگی دارد:

    • ‫Gemini Developer API (هوش مصنوعی Google): منسوخ شده است، اما تاریخ تعطیلی آن هنوز اعلام نشده است (فقط پروژه‌های فعال قبلی می‌توانند به استفاده از آن ادامه دهند)
    • ‫Agent Platform Gemini API (formerly Vertex AI): ۲۰ اکتبر ۲۰۲۶

  • برای مدل تولید تصویر (Nano Banana)، تاریخ تعطیلی صرف‌نظر از ارائه‌دهنده Gemini API انتخابی شما یکسان است: ۲ اکتبر ۲۰۲۶

  توجه داشته باشید که سایر مدل‌های «Nano Banana» و هرگونه مدل پایدار Gemini Live API 2.5 تحت تأثیر قرار نمی‌گیرند.

جایگزین: برای استفاده از یکی از مدل‌های جدید Gemini 3.x (مثل gemini-3.8-flash یا gemini-3.1-flash-image) انتقال دهید.

Imagen مدل پایدار - تاریخ‌های خاموش شدن و جایگزین‌ها

• همه مدل‌های Imagen از ۱۷ اوت ۲۰۲۶ خاموش خواهند شد (توجه داشته باشید که این تاریخ خاموش شدن از ۳۰ ژوئن ۲۰۲۶ تمدید شده است).

جایگزین: برنامه‌هایتان را به مدل‌های Gemini تصویر (مدل‌های «نانو بنانا») منتقل کنید.

Gemini 2.0 مدل پایدار - تاریخ‌های خاموش شدن و جایگزین‌ها

• ‫Gemini 2.0 Flash و Gemini 2.0 Flash‑Lite:

  ‫gemini-2.0-flash-001 (و نام مستعار به‌روزرسانی خودکار آن gemini-2.0-flash)
  ‫gemini-2.0-flash-lite-001 (و نام مستعار به‌روزرسانی خودکار آن gemini-2.0-flash-lite)

  • ۶ فوریه ۲۰۲۶: این مدل‌ها دیگر برای استفاده در پروژه‌هایی که قبلاً از مدل استفاده نکرده‌اند دردسترس نخواهند بود.

  • ‫۳۱ مارس ۲۰۲۶: این مدل‌ها خاموش خواهند شد.

  توجه داشته باشید که مدل‌های پایدار Gemini Live API 2.0 تحت تأثیر قرار نمی‌گیرند.

جایگزین: برای استفاده از یکی از مدل‌های جدید Gemini 3.x (مثل gemini-3.1-flash-lite) انتقال دهید.

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

• ‫Gemini 1.5 Pro مدل:

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

• ‫Gemini 1.5 Flash مدل:

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

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

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

جایگزین: برای استفاده از یکی از مدل‌های جدید Gemini 3.x (مثل gemini-3.1-flash-lite) انتقال دهید.

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

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

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

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

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

• با نزدیک شدن به تاریخ توقف:

  • ‫Google ایمیل‌هایی را به اعضای مناسب پروژه ارسال می‌کند.
  • ما یادآوری‌هایی درباره تعطیلی‌های آتی در کانال‌های مختلف منتشر می‌کنیم:
    • یادداشت‌های انتشار (مثال را ببینید)
    • برنمای‌های سطح صفحه، صفحه مدل‌های پشتیبانی‌شده، و پرسشگان مدل‌های منسوخ‌شده و خاموش‌شده

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

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

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

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

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

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

     توجه داشته باشید که برای جدیدترین مدل‌های Gemini 3.x، چندین پارامتر پشتیبانی نمی‌شود (به‌طور خاص، دما، K برتر، P برتر، جریمه بسامد، جریمه حضور، و تعداد نامزد).

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

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

به‌طور پیش‌فرض، 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»، تنظیم دقیق مدل، تولید جاسازی، و بازیابی معنایی

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

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

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

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

در سال ۲۰۲۴، مجموعه‌ای از کیت‌های توسعه نرم‌افزار کارخواه Firebase راه‌اندازی کردیم که می‌توانست از Agent Platform Gemini API (formerly Vertex AI) و همچنین دروازه پراکسی Firebase برای محافظت از آن API دربرابر سوءاستفاده و فعال کردن یکپارچه‌سازی با دیگر محصولات Firebase استفاده کند. ما محصولمان را «هوش مصنوعی Vertex در 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 برای برنامه‌ای که قبلاً منتشر شده است

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

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

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

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

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

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

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

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

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

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

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

با توجه به این تغییر، می‌توانید هر کلید API با نام 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) است را حذف نکنید.

کلید Gemini API را به پایگاه کد برنامه تلفن همراه یا وب اضافه نکنید

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

از «کلید میانای برنامه‌سازی کاربردی Firebase» به‌عنوان کلید میانای برنامه‌سازی کاربردی Gemini استفاده نکنید

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

کلید API شما در Firebase کلید API است که در فایل پیکربندی Firebase یا شیئی که به پایگاه کد برنامه خود اضافه می‌کنید فهرست شده است تا برنامه خود را به Firebase متصل کنید. اگر از کلید فقط با «میاناهای برنامه‌سازی کاربردی» مربوط به Firebase (مثل Firebase AI Logic) استفاده می‌کنید، قرار دادن کلید میانای برنامه‌سازی کاربردی Firebase در کدتان مشکلی ندارد. اطلاعات مهم درباره کلیدهای میانای برنامه‌سازی کاربردی Firebase را بیاموزید.

در پانل میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اطلاعات اعتباری کنسول Google Cloud، کلیدهای Firebase API به این شکل است:

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

نحوه ایمن نگه داشتن کلید میانای برنامه‌سازی کاربردی Gemini