این آموزش نحوه دسترسی به Gemini API برای برنامه Dart یا Flutter خود را با استفاده از Google AI Dart SDK نشان می دهد. اگر نمی‌خواهید برای دسترسی به مدل‌های Gemini در برنامه خود مستقیماً با REST API کار کنید، می‌توانید از این SDK استفاده کنید.
در این آموزش، نحوه انجام کارهای زیر را خواهید آموخت:
- پروژه خود را تنظیم کنید، از جمله کلید API
- متن را از ورودی فقط متنی تولید کنید
- تولید متن از ورودی متن و تصویر (چند وجهی)
- ایجاد مکالمات چند نوبتی (چت)
- برای تعامل سریعتر از پخش جریانی استفاده کنید
علاوه بر این، این آموزش شامل بخش هایی در مورد موارد استفاده پیشرفته (مانند جاسازی ها و شمارش نشانه ها ) و همچنین گزینه هایی برای کنترل تولید محتوا است .
پیش نیازها
این آموزش فرض می کند که شما با ساخت برنامه های کاربردی با دارت آشنا هستید.
برای تکمیل این آموزش، مطمئن شوید که محیط توسعه شما شرایط زیر را دارد:
- دارت 3.2.0+
پروژه خود را تنظیم کنید
قبل از فراخوانی Gemini API، باید پروژه خود را راه‌اندازی کنید، که شامل تنظیم کلید API، افزودن SDK به وابستگی‌های میخانه و تنظیم اولیه مدل می‌شود.
کلید API خود را تنظیم کنید
برای استفاده از Gemini API، به یک کلید API نیاز دارید. اگر قبلاً یکی ندارید، یک کلید در Google AI Studio ایجاد کنید.
کلید API خود را ایمن کنید
کلید API خود را ایمن نگه دارید. ما قویاً توصیه می‌کنیم که کلید API را مستقیماً در کد خود وارد نکنید ، یا فایل‌هایی را که حاوی کلید هستند را در سیستم‌های کنترل نسخه بررسی کنید. درعوض، باید از یک فروشگاه مخفی برای کلید API خود استفاده کنید.
همه قطعه‌های موجود در این آموزش فرض می‌کنند که شما به کلید API خود به عنوان یک متغیر محیط فرآیند دسترسی دارید. اگر در حال توسعه یک برنامه Flutter هستید، می توانید از String.fromEnvironment استفاده کنید و --dart-define=API_KEY=$API_KEY برای flutter build یا flutter run برای کامپایل با کلید API ارسال کنید زیرا محیط فرآیند هنگام اجرای برنامه متفاوت خواهد بود. .
بسته SDK را نصب کنید
برای استفاده از Gemini API در برنامه خود، باید بسته google_generative_ai را به برنامه Dart یا Flutter خود add :
دارت
dart pub add google_generative_ai
بال بال زدن
flutter pub add google_generative_ai
مدل مولد را راه اندازی کنید
قبل از اینکه بتوانید هر گونه تماس API را برقرار کنید، باید مدل تولیدی را وارد و مقداردهی اولیه کنید.
import 'package:google_generative_ai/google_generative_ai.dart';
// Access your API key as an environment variable (see "Set up your API key" above)
final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
print('No \$API_KEY environment variable');
exit(1);
}
final model = GenerativeModel(model: 'MODEL_NAME', apiKey: apiKey);
هنگام تعیین مدل به موارد زیر توجه کنید:
از مدلی استفاده کنید که مخصوص مورد استفاده شما باشد (مثلاً
gemini-pro-visionبرای ورودی چندوجهی است). در این راهنما، دستورالعمل‌های هر پیاده‌سازی، مدل پیشنهادی را برای هر مورد استفاده فهرست می‌کند.
موارد استفاده رایج را اجرا کنید
اکنون که پروژه شما راه اندازی شده است، می توانید با استفاده از Gemini API برای پیاده سازی موارد استفاده مختلف، کاوش کنید:
- متن را از ورودی فقط متنی تولید کنید
- تولید متن از ورودی متن و تصویر (چند وجهی)
- ساخت مکالمات چند نوبتی (چت)
- برای تعامل سریعتر از پخش جریانی استفاده کنید
در بخش موارد استفاده پیشرفته، می‌توانید اطلاعاتی درباره Gemini API و جاسازی‌ها پیدا کنید.
متن را از ورودی فقط متنی تولید کنید
هنگامی که ورودی سریع فقط متن را شامل می شود، از مدل gemini-pro با روش generateContent برای تولید خروجی متن استفاده کنید:
import 'dart:io';
import 'package:google_generative_ai/google_generative_ai.dart';
void main() async {
// Access your API key as an environment variable (see "Set up your API key" above)
final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
print('No \$API_KEY environment variable');
exit(1);
}
// For text-only input, use the gemini-pro model
final model = GenerativeModel(model: 'gemini-pro', apiKey: apiKey);
final content = [Content.text('Write a story about a magic backpack.')];
final response = await model.generateContent(content);
print(response.text);
}
تولید متن از ورودی متن و تصویر (چند وجهی)
Gemini یک مدل چندوجهی ( gemini-pro-vision ) ارائه می‌کند، بنابراین می‌توانید هم متن و هم تصاویر را وارد کنید. حتماً شرایط مورد نیاز تصویر را برای ورودی بررسی کنید.
هنگامی که ورودی سریع شامل متن و تصویر می شود، از مدل gemini-pro-vision با متد generateContent برای تولید خروجی متن استفاده کنید:
import 'dart:io';
import 'package:google_generative_ai/google_generative_ai.dart';
void main() async {
// Access your API key as an environment variable (see "Set up your API key" above)
final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
print('No \$API_KEY environment variable');
exit(1);
}
// For text-and-image input (multimodal), use the gemini-pro-vision model
final model = GenerativeModel(model: 'gemini-pro-vision', apiKey: apiKey);
final (firstImage, secondImage) = await (
File('image0.jpg').readAsBytes(),
File('image1.jpg').readAsBytes()
).wait;
final prompt = TextPart("What's different between these pictures?");
final imageParts = [
DataPart('image/jpeg', firstImage),
DataPart('image/jpeg', secondImage),
];
final response = await model.generateContent([
Content.multi([prompt, ...imageParts])
]);
print(response.text);
}
ساخت مکالمات چند نوبتی (چت)
با استفاده از Gemini، می توانید مکالمات آزاد را در چندین نوبت ایجاد کنید. SDK با مدیریت وضعیت مکالمه، فرآیند را ساده می‌کند، بنابراین برخلاف generateContent ، مجبور نیستید تاریخچه مکالمه را خودتان ذخیره کنید.
برای ایجاد یک مکالمه چند نوبتی (مانند چت)، از مدل gemini-pro استفاده کنید و با فراخوانی startChat() چت را مقداردهی اولیه کنید. سپس از sendMessage() برای ارسال یک پیام کاربر جدید استفاده کنید که پیام و پاسخ را نیز به تاریخچه چت اضافه می کند.
دو گزینه ممکن برای role مرتبط با محتوا در یک مکالمه وجود دارد:
user: نقشی که دستورات را ارائه می دهد. این مقدار پیش‌فرض برای تماس‌هایsendMessageاست و اگر نقش دیگری ارسال شود، تابع یک استثنا ایجاد می‌کند.model: نقشی که پاسخ ها را ارائه می دهد. این نقش هنگام فراخوانیstartChat()باhistoryموجود قابل استفاده است.
import 'dart:io';
import 'package:google_generative_ai/google_generative_ai.dart';
Future<void> main() async {
// Access your API key as an environment variable (see "Set up your API key" above)
final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
print('No \$API_KEY environment variable');
exit(1);
}
// For text-only input, use the gemini-pro model
final model = GenerativeModel(
model: 'gemini-pro',
apiKey: apiKey,
generationConfig: GenerationConfig(maxOutputTokens: 100));
// Initialize the chat
final chat = model.startChat(history: [
Content.text('Hello, I have 2 dogs in my house.'),
Content.model([TextPart('Great to meet you. What would you like to know?')])
]);
var content = Content.text('How many paws are in my house?');
var response = await chat.sendMessage(content);
print(response.text);
}
برای تعامل سریعتر از پخش جریانی استفاده کنید
به‌طور پیش‌فرض، مدل پس از تکمیل کل فرآیند تولید، پاسخی را برمی‌گرداند. شما می توانید با منتظر ماندن برای کل نتیجه به تعاملات سریع تری برسید و در عوض از استریم برای مدیریت نتایج جزئی استفاده کنید.
مثال زیر نحوه پیاده‌سازی استریم را با متد generateContentStream برای تولید متن از اعلان ورودی متن و تصویر نشان می‌دهد.
// ...
final response = model.generateContentStream([
Content.multi([prompt, ...imageParts])
]);
await for (final chunk in response) {
print(chunk.text);
}
// ...
می‌توانید از رویکرد مشابهی برای موارد استفاده از چت و ورودی متنی استفاده کنید.
// Use streaming with text-only input
final response = model.generateContentStream(content);
// Use streaming with multi-turn conversations (like chat)
final response = chat.sendMessageStream(content);
موارد استفاده پیشرفته را اجرا کنید
موارد استفاده متداول شرح داده شده در بخش قبلی این آموزش به شما کمک می کند تا با استفاده از Gemini API راحت باشید. این بخش برخی از موارد استفاده را که ممکن است پیشرفته‌تر در نظر گرفته شوند، توضیح می‌دهد.
فراخوانی تابع
فراخوانی تابع، دریافت خروجی داده های ساختاریافته از مدل های تولیدی را برای شما آسان تر می کند. سپس می توانید از این خروجی ها برای فراخوانی API های دیگر و برگرداندن داده های پاسخ مربوطه به مدل استفاده کنید. به عبارت دیگر، فراخوانی تابع به شما کمک می کند تا مدل های تولیدی را به سیستم های خارجی متصل کنید تا محتوای تولید شده شامل به روزترین و دقیق ترین اطلاعات باشد. در آموزش فراخوانی تابع بیشتر بیاموزید.
از جاسازی ها استفاده کنید
جاسازی تکنیکی است که برای نمایش اطلاعات به عنوان لیستی از اعداد ممیز شناور در یک آرایه استفاده می شود. با Gemini، می‌توانید متن (کلمات، جملات و بلوک‌های متن) را به شکل برداری نمایش دهید، که مقایسه و تضاد جاسازی‌ها را آسان‌تر می‌کند. برای مثال، دو متنی که موضوع یا احساسات مشابهی دارند باید دارای تعبیه‌های مشابهی باشند که از طریق تکنیک‌های مقایسه ریاضی مانند شباهت کسینوس قابل شناسایی است.
از مدل embedding-001 با روش embedContent (یا روش batchEmbedContent ) برای ایجاد جاسازی استفاده کنید. مثال زیر یک جاسازی برای یک رشته ایجاد می کند:
final model = GenerativeModel(model: 'embedding-001', apiKey: apiKey);
final content = Content.text('The quick brown fox jumps over the lazy dog.');
final result = await model.embedContent(content);
print(result.embedding.values);
توکن ها را بشمار
هنگام استفاده از اعلان های طولانی، ممکن است شمارش نشانه ها قبل از ارسال هر محتوایی به مدل مفید باشد. مثال های زیر نحوه استفاده از countTokens() برای موارد استفاده مختلف نشان می دهد:
// For text-only input
final tokenCount = await model.countTokens(Content.text(prompt));
print('Token count: ${tokenCount.totalTokens}');
// For text-and-image input (multimodal)
final tokenCount = await model.countTokens([
Content.multi([prompt, ...imageParts])
]);
print('Token count: ${tokenCount.totalTokens}');
// For multi-turn conversations (like chat)
final prompt = Content.text(message);
final allContent = [...chat.history, prompt];
final tokenCount = await model.countTokens(allContent);
print('Token count: ${tokenCount.totalTokens}');
گزینه هایی برای کنترل تولید محتوا
شما می توانید تولید محتوا را با پیکربندی پارامترهای مدل و با استفاده از تنظیمات ایمنی کنترل کنید.
توجه داشته باشید که انتقال generationConfig یا safetySettings به یک روش درخواست مدل (مانند generateContent ) به طور کامل شی پیکربندی با همان نام ارسال شده در getGenerativeModel را لغو می کند.
پیکربندی پارامترهای مدل
هر اعلانی که به مدل ارسال می کنید شامل مقادیر پارامتری است که نحوه تولید پاسخ مدل را کنترل می کند. مدل می تواند نتایج متفاوتی را برای مقادیر پارامترهای مختلف ایجاد کند. درباره پارامترهای مدل بیشتر بدانید. پیکربندی برای تمام طول عمر نمونه مدل شما حفظ می شود.
final generationConfig = GenerationConfig(
stopSequences: ["red"],
maxOutputTokens: 200,
temperature: 0.9,
topP: 0.1,
topK: 16,
);
final model = GenerativeModel(
model: 'MODEL_NAME',
apiKey: apiKey,
generationConfig: generationConfig,
);
از تنظیمات ایمنی استفاده کنید
می توانید از تنظیمات ایمنی برای تنظیم احتمال دریافت پاسخ هایی که ممکن است مضر تلقی شوند استفاده کنید. به‌طور پیش‌فرض، تنظیمات ایمنی محتوایی را با احتمال متوسط و/یا زیاد ناامن بودن محتوا در همه ابعاد مسدود می‌کند. درباره تنظیمات ایمنی بیشتر بیاموزید.
در اینجا نحوه تنظیم یک تنظیم ایمنی آورده شده است:
final safetySettings = [
SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high)
];
final model = GenerativeModel(
model: 'MODEL_NAME',
apiKey: apiKey,
safetySettings: safetySettings,
);
همچنین می توانید بیش از یک تنظیم ایمنی را تنظیم کنید:
final safetySettings = [
SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high),
SafetySetting(HarmCategory.hateSpeech, HarmBlockThreshold.high),
];
بعدش چیه
طراحی سریع فرآیند ایجاد اعلان‌هایی است که پاسخ دلخواه را از مدل‌های زبانی به دست می‌آورد. نوشتن اعلان‌های ساختاریافته بخش ضروری برای اطمینان از پاسخ‌های دقیق و با کیفیت بالا از یک مدل زبان است. درباره بهترین شیوه ها برای نوشتن سریع بیاموزید.
Gemini چندین مدل مختلف را برای برآوردن نیازهای موارد استفاده مختلف، مانند انواع ورودی و پیچیدگی، پیاده سازی برای چت یا سایر وظایف زبان گفتگو، و محدودیت های اندازه ارائه می دهد. با مدل های موجود Gemini آشنا شوید.
Gemini گزینه هایی را برای درخواست افزایش محدودیت نرخ ارائه می دهد. محدودیت نرخ برای مدل های Gemini Pro 60 درخواست در دقیقه (RPM) است.