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

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

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

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

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

جدول زیر دردسترس بودن ویژگی‌هایی را که معمولاً درباره آن‌ها سؤال می‌شود برای دو ارائه‌دهنده «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 Agent Platform» (یا «Agent Platform») تغییر داد. در بوم‌سازگان Firebase، به این سرویس «Agent Platform Gemini API» می‌گوییم.

برای 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 تغییر دهید.

  • نحو 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 تغییر دهید.
  دردسترس از افزونه 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-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 تغییر دهید.
  از کیت توسعه نرم‌افزار Firebase برای Unity نسخه ۱۳.۱۵.۰ به بالا دردسترس است.

  قبل‌از

  // ...
  
  // 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"));
  
  // ...
  

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

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

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

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

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

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

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

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

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

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

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

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 مدل‌های 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 (با نام مستعار «Nano Banana»)

  • برای مدل‌های استفاده عمومی، تاریخ توقف به ارائه‌دهنده 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 (مثل gemini-4-argon، gemini-3.8-flash، یا gemini-3.1-flash-image) انتقال دهید.

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

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

جایگزین: برنامه‌هایتان را برای استفاده از Gemini مدل‌های Image (مدل‌های «Nano Banana») انتقال دهید.

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 4.x و Gemini 3.x، چند پارامتر پشتیبانی نمی‌شود (به‌ویژه دما، top-K،‏ top-P، جریمه تکرار، جریمه حضور، و تعداد نامزدها).

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

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

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

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

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

نحوه کاهش تأخیر و استفاده زیاد از نشان

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

‫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»
• ریزتنظیم کردن مدل
• تولید جاسازی‌ها
• بازیابی معنایی

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

درک تغییر نام از «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 برای برنامه‌ای که قبلاً منتشر شده است

برای نسخه‌های برنامه‌ای که 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 Integrity یا 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 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 به‌طور هم‌زمان ارتقا یافته است. به‌جای استفاده از کلید 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 اکنون مجوز Gemini Developer API را بااستفاده از حساب سرویس تحت‌مدیریت Google‏ (P4SA) که به‌طور خودکار برای شما در پروژه Firebase شما فراهم می‌کنیم مدیریت می‌کند:
Firebase AI Logic Service Agent (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 Developer API به کلید میانای برنامه‌سازی کاربردی Gemini نیاز ندارید، و نباید کلید میانای برنامه‌سازی کاربردی Gemini را به پایگاه کد برنامه‌تان اضافه کنید.

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

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

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

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

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

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