فراخوانی تابع، دریافت خروجی داده های ساختاریافته از مدل های تولیدی را برای شما آسان تر می کند. سپس می توانید از این خروجی ها برای فراخوانی API های دیگر و برگرداندن داده های پاسخ مربوطه به مدل استفاده کنید. به عبارت دیگر، فراخوانی تابع به شما کمک می کند تا مدل های تولیدی را به سیستم های خارجی متصل کنید تا محتوای تولید شده شامل به روزترین و دقیق ترین اطلاعات باشد.
می توانید مدل های Gemini را با توضیحاتی در مورد عملکردها ارائه دهید. اینها توابعی هستند که شما به زبان برنامه خود می نویسید (یعنی توابع Google Cloud نیستند). مدل ممکن است از شما بخواهد که یک تابع را فراخوانی کنید و نتیجه را برای کمک به مدل در رسیدگی به درخواست شما ارسال کنید.
اگر قبلاً این کار را نکردهاید، برای کسب اطلاعات بیشتر ، مقدمه فراخوانی تابع را بررسی کنید.
API مثال برای کنترل روشنایی
تصور کنید یک سیستم کنترل روشنایی اولیه با یک رابط برنامه نویسی کاربردی (API) دارید و می خواهید به کاربران اجازه دهید تا از طریق درخواست های متنی ساده، چراغ ها را کنترل کنند. میتوانید از ویژگی فراخوانی تابع برای تفسیر درخواستهای تغییر نور از سوی کاربران و ترجمه آنها به فراخوانهای API برای تنظیم مقادیر نور استفاده کنید. این سیستم کنترل روشنایی فرضی به شما امکان می دهد روشنایی نور و دمای رنگ آن را کنترل کنید که به عنوان دو پارامتر جداگانه تعریف می شود:
پارامتر | تایپ کنید | مورد نیاز | توضیحات |
---|---|---|---|
brightness | شماره | بله | سطح نور از 0 تا 100. صفر خاموش است و 100 روشنایی کامل است. |
colorTemperature | رشته | بله | دمای رنگ دستگاه نور که می تواند daylight ، cool یا warm باشد. |
برای سادگی، این سیستم نورپردازی خیالی تنها یک نور دارد، بنابراین کاربر مجبور نیست اتاق یا مکان را مشخص کند. در اینجا نمونه ای از درخواست JSON است که می توانید برای تغییر سطح نور با استفاده از دمای رنگ نور روز به API کنترل روشنایی ارسال کنید:
{
"brightness": "50",
"colorTemperature": "daylight"
}
این آموزش به شما نشان میدهد که چگونه یک Function Call را برای Gemini API تنظیم کنید تا درخواستهای روشنایی کاربران را تفسیر کند و آنها را به تنظیمات API برای کنترل مقدار روشنایی و دمای رنگ نور تنظیم کنید.
قبل از شروع: پروژه و کلید API خود را تنظیم کنید
قبل از فراخوانی Gemini API، باید پروژه خود را راه اندازی کرده و کلید API خود را پیکربندی کنید.
کلید API خود را دریافت و ایمن کنید
برای فراخوانی Gemini API به یک کلید API نیاز دارید. اگر قبلاً یکی ندارید، یک کلید در Google AI Studio ایجاد کنید.
اکیداً توصیه می شود که یک کلید API را در سیستم کنترل نسخه خود بررسی نکنید .
شما باید کلید API خود را در یک فروشگاه محرمانه مانند Google Cloud Secret Manager ذخیره کنید.
این آموزش فرض می کند که شما به کلید API خود به عنوان یک متغیر محیط فرآیند دسترسی دارید. اگر در حال توسعه یک برنامه Flutter هستید، می توانید از String.fromEnvironment
استفاده کنید و --dart-define=API_KEY=$API_KEY
برای flutter build
یا flutter run
برای کامپایل با کلید API ارسال کنید زیرا محیط فرآیند هنگام اجرای برنامه متفاوت خواهد بود. .
بسته SDK را وارد کنید و کلید API خود را پیکربندی کنید
برای استفاده از Gemini API در برنامه خود، باید بسته google_generative_ai
را به برنامه Dart یا Flutter خود add
:
دارت
dart pub add google_generative_ai
بال زدن
flutter pub add google_generative_ai
یک تابع API را تعریف کنید
تابعی ایجاد کنید که درخواست API را ایجاد کند. این تابع باید در کد برنامه شما تعریف شود، اما می تواند خدمات یا API های خارج از برنامه شما را فراخوانی کند. Gemini API این تابع را مستقیماً فراخوانی نمی کند، بنابراین می توانید نحوه و زمان اجرای این تابع را از طریق کد برنامه خود کنترل کنید. برای اهداف نمایشی، این آموزش یک تابع API ساختگی را تعریف می کند که فقط مقادیر روشنایی درخواستی را برمی گرداند:
Future<Map<String, Object?>> setLightValues(
Map<String, Object?> arguments,
) async =>
// This mock API returns the requested lighting values
{
'brightness': arguments['brightness'],
'colorTemperature': arguments['colorTemp'],
};
ایجاد اعلان عملکرد
اعلان تابعی را ایجاد کنید که به مدل مولد منتقل می کنید. هنگامی که یک تابع را برای استفاده توسط مدل اعلام می کنید، باید تا حد امکان جزئیات بیشتری را در توضیحات تابع و پارامتر بگنجانید. مدل مولد از این اطلاعات برای تعیین اینکه کدام تابع را انتخاب کند و چگونه مقادیر پارامترهای فراخوانی تابع را ارائه کند، استفاده می کند. کد زیر نحوه اعلام عملکرد کنترل روشنایی را نشان می دهد:
final lightControlTool = FunctionDeclaration(
'setLightValues',
'Set the brightness and color temperature of a room light.',
Schema(SchemaType.object, properties: {
'brightness': Schema(SchemaType.number,
description: 'Light level from 0 to 100. '
'Zero is off and 100 is full brightness.'),
'colorTemperature': Schema(SchemaType.string,
description: 'Color temperature of the light fixture, '
'which can be `daylight`, `cool` or `warm`.'),
}, requiredProperties: [
'brightness',
'colorTemperature'
]));
توابع را در طول اولیه سازی مدل اعلام کنید
هنگامی که می خواهید از فراخوانی تابع با یک مدل استفاده کنید، باید اعلان های تابع خود را هنگام مقداردهی اولیه شی مدل ارائه دهید. شما با تنظیم پارامتر tools
مدل، توابع را اعلام می کنید. Dart SDK همچنین از اعلام توابع به عنوان آرگومان برای generateContent
یا generateContentStream
APIها پشتیبانی می کند.
final model = GenerativeModel(
model: 'gemini-1.5-flash',
apiKey: apiKey,
// Specify the function declaration.
tools: [
Tool(functionDeclarations: [lightControlTool])
],
);
یک فراخوانی تابع ایجاد کنید
هنگامی که مدل را با اعلان های تابع خود مقداردهی اولیه کردید، می توانید مدل را با تابع تعریف شده درخواست کنید. شما باید از فراخوانی تابع با استفاده از درخواست چت ( sendMessage()
) استفاده کنید، زیرا فراخوانی تابع عموماً از داشتن متن درخواست ها و پاسخ های قبلی سود می برد.
final chat = model.startChat(); final prompt =
'Dim the lights so the room feels cozy and warm.';
// Send the message to the generative model.
var response = await chat.sendMessage(Content.text(prompt));
final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
final functionCall = functionCalls.first;
final result = switch (functionCall.name) {
// Forward arguments to the hypothetical API.
'setLightValues' => await setLightValues(functionCall.args),
// Throw an exception if the model attempted to call a function that was
// not declared.
_ => throw UnimplementedError(
'Function not implemented: ${functionCall.name}')
};
// Send the response to the model so that it can use the result to generate
// text for the user.
response = await chat
.sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
print(text);
}
،فراخوانی تابع، دریافت خروجی داده های ساختاریافته از مدل های تولیدی را برای شما آسان تر می کند. سپس می توانید از این خروجی ها برای فراخوانی API های دیگر و برگرداندن داده های پاسخ مربوطه به مدل استفاده کنید. به عبارت دیگر، فراخوانی تابع به شما کمک می کند تا مدل های تولیدی را به سیستم های خارجی متصل کنید تا محتوای تولید شده شامل به روزترین و دقیق ترین اطلاعات باشد.
می توانید مدل های Gemini را با توضیحاتی در مورد عملکردها ارائه دهید. اینها توابعی هستند که شما به زبان برنامه خود می نویسید (یعنی توابع Google Cloud نیستند). مدل ممکن است از شما بخواهد که یک تابع را فراخوانی کنید و نتیجه را برای کمک به مدل در رسیدگی به درخواست شما ارسال کنید.
اگر قبلاً این کار را نکردهاید، برای کسب اطلاعات بیشتر ، مقدمه فراخوانی تابع را بررسی کنید.
API مثال برای کنترل روشنایی
تصور کنید یک سیستم کنترل روشنایی اولیه با یک رابط برنامه نویسی کاربردی (API) دارید و می خواهید به کاربران اجازه دهید تا از طریق درخواست های متنی ساده، چراغ ها را کنترل کنند. میتوانید از ویژگی فراخوانی تابع برای تفسیر درخواستهای تغییر نور از سوی کاربران و ترجمه آنها به فراخوانهای API برای تنظیم مقادیر نور استفاده کنید. این سیستم کنترل روشنایی فرضی به شما امکان می دهد روشنایی نور و دمای رنگ آن را کنترل کنید که به عنوان دو پارامتر جداگانه تعریف می شود:
پارامتر | تایپ کنید | مورد نیاز | توضیحات |
---|---|---|---|
brightness | شماره | بله | سطح نور از 0 تا 100. صفر خاموش است و 100 روشنایی کامل است. |
colorTemperature | رشته | بله | دمای رنگ دستگاه نور که می تواند daylight ، cool یا warm باشد. |
برای سادگی، این سیستم نورپردازی خیالی تنها یک نور دارد، بنابراین کاربر مجبور نیست اتاق یا مکان را مشخص کند. در اینجا نمونه ای از درخواست JSON است که می توانید برای تغییر سطح نور با استفاده از دمای رنگ نور روز به API کنترل روشنایی ارسال کنید:
{
"brightness": "50",
"colorTemperature": "daylight"
}
این آموزش به شما نشان میدهد که چگونه یک Function Call را برای Gemini API تنظیم کنید تا درخواستهای روشنایی کاربران را تفسیر کند و آنها را به تنظیمات API برای کنترل مقدار روشنایی و دمای رنگ نور تنظیم کنید.
قبل از شروع: پروژه و کلید API خود را تنظیم کنید
قبل از تماس با Gemini API ، باید پروژه خود را تنظیم کرده و کلید API خود را پیکربندی کنید.
کلید API خود را دریافت و ایمن کنید
برای تماس با API Gemini به یک کلید API نیاز دارید. اگر قبلاً یکی از آنها را ندارید ، در استودیوی Google AI یک کلید ایجاد کنید.
به شدت توصیه می شود که یک کلید API را در سیستم کنترل نسخه خود بررسی نکنید .
شما باید کلید API خود را در یک فروشگاه اسرار مانند Google Cloud Secret Manager ذخیره کنید.
این آموزش فرض می کند که شما به عنوان یک متغیر محیط فرآیند به کلید API خود دسترسی پیدا می کنید. اگر در حال تهیه یک برنامه Flutter هستید ، می توانید از String.fromEnvironment
و عبور-- --dart-define=API_KEY=$API_KEY
برای flutter build
یا flutter run
برای کامپایل کردن با کلید API استفاده کنید زیرا محیط فرآیند هنگام اجرای برنامه متفاوت خواهد بود. .
بسته SDK را وارد کرده و کلید API خود را پیکربندی کنید
برای استفاده از API Gemini در برنامه خود ، باید بسته google_generative_ai
را به برنامه DART یا Flutter خود add
:
دارت
dart pub add google_generative_ai
بال زدن
flutter pub add google_generative_ai
یک عملکرد API را تعریف کنید
تابعی را ایجاد کنید که درخواست API را ایجاد کند. این عملکرد باید در کد برنامه شما تعریف شود ، اما می تواند با خدمات یا API در خارج از برنامه شما تماس بگیرد. API Gemini این عملکرد را مستقیماً فراخوانی نمی کند ، بنابراین می توانید نحوه و زمان اجرای این عملکرد را از طریق کد برنامه خود کنترل کنید. برای اهداف تظاهرات ، این آموزش یک تابع API مسخره را تعریف می کند که فقط مقادیر روشنایی درخواستی را برمی گرداند:
Future<Map<String, Object?>> setLightValues(
Map<String, Object?> arguments,
) async =>
// This mock API returns the requested lighting values
{
'brightness': arguments['brightness'],
'colorTemperature': arguments['colorTemp'],
};
اعلامیه های عملکردی ایجاد کنید
اعلامیه عملکردی را ایجاد کنید که به مدل تولیدی منتقل می شوید. هنگامی که یک تابع را برای استفاده توسط مدل اعلام می کنید ، باید تا حد امکان در توضیحات عملکرد و پارامتر جزئیات را درج کنید. مدل تولیدی از این اطلاعات استفاده می کند تا مشخص شود کدام عملکرد را انتخاب می کند و چگونه می توان مقادیر پارامترهای موجود در تماس عملکرد را ارائه داد. کد زیر نحوه اعلام عملکرد کنترل روشنایی را نشان می دهد:
final lightControlTool = FunctionDeclaration(
'setLightValues',
'Set the brightness and color temperature of a room light.',
Schema(SchemaType.object, properties: {
'brightness': Schema(SchemaType.number,
description: 'Light level from 0 to 100. '
'Zero is off and 100 is full brightness.'),
'colorTemperature': Schema(SchemaType.string,
description: 'Color temperature of the light fixture, '
'which can be `daylight`, `cool` or `warm`.'),
}, requiredProperties: [
'brightness',
'colorTemperature'
]));
در طول اولیه سازی مدل توابع را اعلام کنید
هنگامی که می خواهید از عملکرد فراخوانی با یک مدل استفاده کنید ، باید هنگام تنظیم شیء مدل ، اعلامیه های عملکرد خود را ارائه دهید. شما با تنظیم پارامتر tools
Model ، توابع را اعلام می کنید. DART SDK همچنین از اعلام توابع به عنوان آرگومان به API های generateContent
یا generateContentStream
پشتیبانی می کند.
final model = GenerativeModel(
model: 'gemini-1.5-flash',
apiKey: apiKey,
// Specify the function declaration.
tools: [
Tool(functionDeclarations: [lightControlTool])
],
);
یک تماس عملکردی ایجاد کنید
هنگامی که مدل را با اعلامیه های عملکرد خود تنظیم کردید ، می توانید مدل را با عملکرد تعریف شده فوری کنید. شما باید از عملکرد فراخوانی با استفاده از گپ زدن ( sendMessage()
) استفاده کنید ، زیرا عملکرد فراخوانی به طور کلی از داشتن متن و پاسخ های قبلی سود می برد.
final chat = model.startChat(); final prompt =
'Dim the lights so the room feels cozy and warm.';
// Send the message to the generative model.
var response = await chat.sendMessage(Content.text(prompt));
final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
final functionCall = functionCalls.first;
final result = switch (functionCall.name) {
// Forward arguments to the hypothetical API.
'setLightValues' => await setLightValues(functionCall.args),
// Throw an exception if the model attempted to call a function that was
// not declared.
_ => throw UnimplementedError(
'Function not implemented: ${functionCall.name}')
};
// Send the response to the model so that it can use the result to generate
// text for the user.
response = await chat
.sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
print(text);
}