فراخوانی عملکرد با استفاده از Gemini API، تماس تابع با استفاده از Gemini API

iOS+ Android Web Flutter

مدل های مولد در حل بسیاری از مشکلات قدرتمند هستند. با این حال، آنها با محدودیت هایی مانند:

• آنها پس از آموزش منجمد می شوند و منجر به دانش قدیمی می شوند.
• آنها نمی توانند داده های خارجی را پرس و جو یا تغییر دهند.

فراخوانی تابع می تواند به شما در غلبه بر برخی از این محدودیت ها کمک کند. فراخوانی تابع گاهی اوقات به عنوان استفاده از ابزار نامیده می شود زیرا به مدل اجازه می دهد تا از ابزارهای خارجی مانند API ها و توابع برای تولید پاسخ نهایی خود استفاده کند.

می‌توانید در اسناد Google Cloud درباره فراخوانی تابع ، از جمله فهرست مفیدی از موارد استفاده برای فراخوانی تابع، اطلاعات بیشتری کسب کنید.

تماس تابع توسط Gemini 1.0 Pro، Gemini 1.5 Pro و Gemini 1.5 Flash پشتیبانی می شود.

این راهنما به شما نشان می‌دهد که چگونه می‌توانید یک تنظیم فراخوانی تابع شبیه به مثالی که در بخش اصلی بعدی این صفحه توضیح داده شد، پیاده‌سازی کنید. در سطح بالا، در اینجا مراحل تنظیم فراخوانی تابع در برنامه شما آمده است:

1. تابعی بنویسید که بتواند اطلاعاتی را که برای تولید پاسخ نهایی به مدل نیاز دارد ارائه دهد (مثلاً تابع می تواند یک API خارجی را فراخوانی کند).

2. یک اعلان تابع ایجاد کنید که تابع و پارامترهای آن را توصیف کند.

3. اعلان تابع را در زمان اولیه سازی مدل ارائه دهید تا مدل بداند در صورت نیاز چگونه می تواند از تابع استفاده کند.

4. برنامه خود را طوری تنظیم کنید که مدل بتواند اطلاعات مورد نیاز را برای فراخوانی عملکرد برنامه شما ارسال کند.

5. پاسخ تابع را به مدل برگردانید تا مدل بتواند پاسخ نهایی خود را ایجاد کند.

پرش به اجرای کد

نمای کلی یک مثال فراخوانی تابع

هنگامی که درخواستی را برای مدل ارسال می‌کنید، می‌توانید مجموعه‌ای از «ابزارها» (مانند توابع) را نیز به مدل ارائه دهید که می‌تواند برای تولید پاسخ نهایی خود از آنها استفاده کند. برای استفاده از این توابع و فراخوانی آنها ("تماس عملکرد")، مدل و برنامه شما باید اطلاعات را به یکدیگر منتقل کنند، بنابراین روش توصیه شده برای استفاده از فراخوانی تابع از طریق رابط چت چند نوبتی است. .

تصور کنید برنامه ای دارید که در آن کاربر می تواند پیامی مانند: What was the weather in Boston on October 17, 2024? .

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

ابتدا، یک تابع fetchWeather در برنامه خود می نویسید که با این API فرضی خارجی، که دارای ورودی و خروجی است، تعامل دارد:

پارامتر	تایپ کنید	مورد نیاز	توضیحات
ورودی
location	شیء	بله	نام شهر و ایالت آن که آب و هوا را برای آن بدست آورید. فقط شهرهای ایالات متحده پشتیبانی می شوند. همیشه باید یک شی تودرتو از city و state باشد.
date	رشته	بله	تاریخ واکشی آب و هوا (همیشه باید در قالب YYYY-MM-DD باشد).
خروجی
temperature	عدد صحیح	بله	دما (بر حسب فارنهایت)
chancePrecipitation	رشته	بله	احتمال بارندگی (به صورت درصد بیان می شود)
cloudConditions	رشته	بله	شرایط ابری (یکی از clear ، partlyCloudy ، mostlyCloudy ، cloudy )

هنگام راه اندازی مدل، به مدل می گویید که این تابع fetchWeather وجود دارد و چگونه می توان از آن برای پردازش درخواست های دریافتی در صورت نیاز استفاده کرد. این "اعلام عملکرد" ​​نامیده می شود. مدل به طور مستقیم تابع را فراخوانی نمی کند. در عوض، همانطور که مدل در حال پردازش درخواست ورودی است، تصمیم می گیرد که آیا تابع fetchWeather می تواند به آن کمک کند تا به درخواست پاسخ دهد یا خیر. اگر مدل تصمیم بگیرد که این تابع واقعاً می تواند مفید باشد، مدل داده های ساختاری ایجاد می کند که به برنامه شما کمک می کند تا تابع را فراخوانی کند .

دوباره به درخواست دریافتی نگاه کنید: What was the weather in Boston on October 17, 2024? . احتمالاً مدل تصمیم می‌گیرد که تابع fetchWeather می‌تواند به آن در تولید پاسخ کمک کند. این مدل به پارامترهای ورودی مورد نیاز برای fetchWeather نگاه می‌کند و سپس داده‌های ورودی ساخت‌یافته را برای تابعی که تقریباً شبیه این است تولید می‌کند:

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

مدل این داده های ورودی ساخت یافته را به برنامه شما ارسال می کند تا برنامه شما بتواند تابع fetchWeather را فراخوانی کند. وقتی برنامه شما شرایط آب و هوایی را از API دریافت می کند، اطلاعات را به مدل منتقل می کند. این اطلاعات آب و هوا به مدل اجازه می دهد تا پردازش نهایی خود را تکمیل کند و پاسخ خود را به درخواست اولیه What was the weather in Boston on October 17, 2024?

این مدل ممکن است پاسخ نهایی به زبان طبیعی را ارائه دهد، مانند: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

فراخوانی تابع را پیاده سازی کنید

iOS+ Android Web Flutter

قبل از شروع

اگر قبلاً این کار را نکرده‌اید، راهنمای شروع به کار برای Vertex AI in Firebase SDK را تکمیل کنید. مطمئن شوید که تمام کارهای زیر را انجام داده اید:

1. یک پروژه Firebase جدید یا موجود راه اندازی کنید، از جمله استفاده از طرح قیمت گذاری Blaze و فعال کردن API های مورد نیاز.

2. برنامه خود را به Firebase وصل کنید، از جمله ثبت برنامه خود و افزودن پیکربندی Firebase به برنامه خود.

3. SDK را اضافه کنید و سرویس Vertex AI و مدل تولیدی را در برنامه خود راه اندازی کنید.

بعد از اینکه برنامه خود را به Firebase متصل کردید، SDK را اضافه کردید و سرویس Vertex AI و مدل تولیدی را راه اندازی کردید، آماده فراخوانی Gemini API هستید.

مراحل باقی‌مانده در این راهنما به شما نشان می‌دهد که چگونه یک تنظیم فراخوانی تابع شبیه به گردش کار شرح داده شده در مثال فراخوانی اجمالی یک تابع را اجرا کنید (به بخش بالای این صفحه مراجعه کنید).

می توانید نمونه کد کامل را برای مثال فراخوانی این تابع در ادامه این صفحه مشاهده کنید.

مرحله 1 : تابع را بنویسید

تصور کنید برنامه ای دارید که در آن کاربر می تواند پیامی مانند: What was the weather in Boston on October 17, 2024? . مدل های Gemini ممکن است این اطلاعات آب و هوا را ندانند. با این حال، تصور کنید که یک API خدمات هواشناسی خارجی را می شناسید که می تواند آن را ارائه دهد. مثال در این راهنما بر این API خارجی فرضی تکیه دارد.

تابعی را در برنامه خود بنویسید که با API خارجی فرضی تعامل داشته باشد و اطلاعاتی را که برای ایجاد درخواست نهایی نیاز دارد در اختیار مدل قرار دهد. در این مثال آب و هوا، یک تابع fetchWeather خواهد بود که با این API خارجی فرضی تماس برقرار می کند.

توجه: برای فراخوانی یک API خارجی به توابعی که به مدل ارائه می‌کنید نیازی نیست. آنها همچنین می توانند کارهایی مانند ارائه فرمول هایی برای محاسبه یک مقدار، پرس و جو از پایگاه داده، بازگرداندن نتایج جستجو در اسناد و غیره انجام دهند.

مرحله 2 : یک اعلان تابع ایجاد کنید

اعلان تابعی را ایجاد کنید که بعداً به مدل ارائه خواهید کرد (مرحله بعدی این راهنما).

توجه: مثال این راهنما نشان می دهد که تنها یک اعلان تابع برای مدل ارائه می شود، اما می توانید حداکثر 128 اعلان تابع را برای مدل ارائه دهید تا از بین آنها یکی را انتخاب کند.

در بیانیه خود، تا حد امکان جزئیات بیشتری را در توضیحات مربوط به تابع و پارامترهای آن درج کنید.

مدل از اطلاعات موجود در اعلان تابع برای تعیین اینکه کدام تابع را انتخاب کند و چگونه مقادیر پارامتر را برای فراخوانی واقعی تابع ارائه کند، استفاده می کند. برای نحوه انتخاب مدل از میان توابع و همچنین نحوه کنترل آن انتخاب، رفتارها و گزینه های اضافی را در ادامه این صفحه ببینید.

در مورد طرحی که ارائه می کنید به موارد زیر توجه کنید:

• شما باید اعلان‌های تابع را در قالب طرحی ارائه دهید که با طرحواره OpenAPI سازگار باشد. Vertex AI پشتیبانی محدودی از طرح OpenAPI ارائه می دهد.

  • ویژگی های زیر پشتیبانی می شوند: type ، nullable ، required ، format ، description ، properties ، items ، enum .

  • ویژگی‌های زیر پشتیبانی نمی‌شوند : default ، optional ، maximum ، oneOf .

• به‌طور پیش‌فرض، برای Vertex AI in Firebase SDK، همه فیلدها ضروری در نظر گرفته می‌شوند مگر اینکه آنها را به‌عنوان اختیاری در آرایه optionalProperties مشخص کنید. برای این فیلدهای اختیاری، مدل می تواند فیلدها را پر کند یا آنها را رد کند. توجه داشته باشید که این برخلاف رفتار پیش‌فرض برای Vertex AI Gemini API است.

برای بهترین شیوه‌های مربوط به اعلامیه‌های عملکرد، از جمله نکاتی برای نام‌ها و توضیحات، به بهترین شیوه‌ها در اسناد Google Cloud مراجعه کنید.

در اینجا نحوه نوشتن یک اعلان تابع آورده شده است:

مرحله 3 : اعلان تابع را در طول اولیه سازی مدل ارائه دهید

توجه: هر دو Gemini 1.0 Pro و Gemini 1.5 Pro از فراخوانی عملکرد پشتیبانی می کنند. هنگام تصمیم گیری برای استفاده از کدام مدل، مطمئن شوید که سهمیه های هر مدل را مرور کنید.

حداکثر تعداد اعلان‌های تابعی که می‌توانید با درخواست ارائه کنید 128 است. برای اینکه چگونه مدل ممکن است از بین توابع انتخاب کند، و همچنین چگونه می‌توانید آن انتخاب را کنترل کنید (با استفاده از یک toolConfig برای تنظیم، به رفتارها و گزینه‌های دیگر در این صفحه مراجعه کنید. حالت فراخوانی تابع ).

نحوه انتخاب مدل Gemini و به صورت اختیاری مکان مناسب برای مورد استفاده و برنامه خود را بیاموزید.

مرحله 4 : تابع را برای فراخوانی API خارجی فراخوانی کنید

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

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

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

در این مثال، درخواست دریافتی حاوی این پیام بود What was the weather in Boston on October 17, 2024? . از این دستور، مدل پارامترهای ورودی مورد نیاز تابع fetchWeather را استنباط کرد (یعنی city ، state و date ).

مرحله 5 : خروجی تابع را در اختیار مدل قرار دهید تا پاسخ نهایی را ایجاد کند

پس از اینکه تابع fetchWeather اطلاعات آب و هوا را برگرداند، برنامه شما باید آن را به مدل ارسال کند.

سپس، مدل پردازش نهایی خود را انجام می دهد و یک پاسخ نهایی به زبان طبیعی را ایجاد می کند: On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

رفتارها و گزینه های اضافی

در اینجا برخی از رفتارهای اضافی برای فراخوانی تابع وجود دارد که باید آنها را در کد خود جای دهید و گزینه هایی که می توانید کنترل کنید.

ممکن است مدل بخواهد دوباره یک تابع یا تابع دیگری را فراخوانی کند.

اگر پاسخ از یک فراخوانی تابع برای مدل برای ایجاد پاسخ نهایی کافی نباشد، آنگاه ممکن است مدل درخواست یک فراخوانی تابع اضافی یا درخواست فراخوانی به یک تابع کاملاً متفاوت کند. مورد دوم تنها در صورتی می تواند اتفاق بیفتد که شما بیش از یک تابع به مدل در لیست اعلان تابع خود ارائه دهید.

برنامه شما باید شرایطی را در نظر بگیرد که مدل ممکن است برای فراخوانی عملکرد اضافی درخواست کند.

ممکن است مدل بخواهد چند تابع را همزمان فراخوانی کند.

شما می توانید تا 128 تابع را در لیست اعلان عملکرد خود به مدل ارائه دهید. با توجه به این موضوع، مدل ممکن است تصمیم بگیرد که چندین تابع برای کمک به تولید پاسخ نهایی خود مورد نیاز است. و ممکن است تصمیم بگیرد که برخی از این توابع را همزمان فراخوانی کند - این فراخوانی تابع موازی نامیده می شود.

برنامه شما باید شرایطی را در نظر بگیرد که مدل ممکن است چندین عملکرد را همزمان بخواهد و برنامه شما باید همه پاسخ‌ها را از توابع به مدل ارائه دهد.

فراخوانی عملکرد موازی توسط Gemini 1.5 Pro و Gemini 1.5 Flash پشتیبانی می شود.

شما می توانید کنترل کنید که چگونه و آیا مدل می تواند درخواست فراخوانی توابع را داشته باشد.

شما می توانید محدودیت هایی را در مورد اینکه مدل چگونه و آیا باید از اعلان های تابع ارائه شده استفاده کند، قرار دهید. این را تنظیم حالت فراخوانی تابع می نامند. در اینجا چند نمونه آورده شده است:

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

• اگر چند اعلان تابع ارائه می کنید، می توانید مدل را به استفاده از زیرمجموعه ای از توابع ارائه شده محدود کنید.

شما این محدودیت ها (یا حالت ها) را با افزودن یک پیکربندی ابزار ( toolConfig ) به همراه اعلانات و اعلان های تابع پیاده سازی می کنید. در پیکربندی ابزار، می توانید یکی از حالت های زیر را مشخص کنید. مفیدترین حالت ANY است.

حالت	توضیحات
AUTO	رفتار مدل پیش فرض مدل تصمیم می گیرد که از فراخوانی تابع یا پاسخ زبان طبیعی استفاده کند.
ANY	مدل باید از فراخوانی تابع استفاده کند ("فراخوانی تابع اجباری"). برای محدود کردن مدل به زیرمجموعه ای از توابع، نام تابع مجاز را در allowedFunctionNames مشخص کنید.
NONE	مدل نباید از فراخوانی تابع استفاده کند. این رفتار معادل یک درخواست مدل بدون هیچ گونه اعلان تابع مرتبط است.

حالت تماس تابعی توسط Gemini 1.5 Pro و Gemini 1.5 Flash پشتیبانی می شود.

چه کار دیگری می توانید انجام دهید؟

سایر قابلیت های Gemini API را امتحان کنید

• مکالمات چند نوبتی (چت) بسازید.
• متن را از اعلان‌های فقط متنی ایجاد کنید.
• متن را از اعلان‌های چندوجهی (شامل متن، تصاویر، PDF، ویدئو و صدا) تولید کنید.

یاد بگیرید چگونه تولید محتوا را کنترل کنید

• طراحی سریع، از جمله بهترین شیوه‌ها، استراتژی‌ها و درخواست‌های نمونه را درک کنید .
• پارامترهای مدل مانند دما و حداکثر نشانه های خروجی را پیکربندی کنید .
• از تنظیمات ایمنی برای تنظیم احتمال دریافت پاسخ هایی که ممکن است مضر تلقی شوند استفاده کنید .

همچنین می‌توانید با استفاده از Vertex AI Studio دستورات و پیکربندی‌های مدل را آزمایش کنید.

در مورد مدل های جمینی بیشتر بدانید

در مورد مدل های موجود برای موارد استفاده مختلف و سهمیه ها و قیمت آنها اطلاعات کسب کنید.

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