بدء استخدام Gemini API في تطبيقات Dart أو Flutter

يوضّح هذا الدليل التوجيهي كيفية الوصول إلى واجهة برمجة تطبيقات Gemini في تطبيق Dart أو Flutter باستخدام حزمة تطوير البرامج (SDK) الخاصة بالذكاء الاصطناعي من Google AI. يمكنك استخدام حزمة SDK هذه إذا كنت لا تريد استخدام واجهات برمجة تطبيقات REST مباشرةً للوصول إلى نماذج Gemini في تطبيقك.

في هذا البرنامج التعليمي، ستتعرّف على كيفية إجراء ما يلي:

• إعداد مشروعك، بما في ذلك مفتاح واجهة برمجة التطبيقات
• إنشاء نص من الإدخال النصي فقط
• إنشاء نص من إدخال النص والصور (متعدد الوسائط)
• إنشاء محادثات متعددة الأدوار (المحادثة)
• استخدام البث للتفاعل بشكل أسرع

بالإضافة إلى ذلك، يحتوي هذا البرنامج التعليمي على أقسام تتناول حالات الاستخدام المتقدّمة (مثل عمليات التضمين والرموز المميّزة للاحتساب)، بالإضافة إلى خيارات التحكّم في إنشاء المحتوى.

المتطلبات الأساسية

يفترض هذا البرنامج التعليمي أنك على دراية بإنشاء التطبيقات باستخدام Dart.

لإكمال هذا البرنامج التعليمي، تأكد من أن بيئة التطوير تفي بالمتطلبات التالية:

• Dart 3.2.0+

إعداد مشروعك

قبل استدعاء واجهة برمجة تطبيقات Gemini، عليك إعداد مشروعك، ويتضمّن ذلك إعداد مفتاح واجهة برمجة التطبيقات، وإضافة حزمة SDK إلى العناصر التابعة للنشر، وتهيئة النموذج.

إعداد مفتاح واجهة برمجة التطبيقات

لاستخدام Gemini API، يجب استخدام مفتاح واجهة برمجة التطبيقات. إذا لم يسبق لك إنشاء مفتاح، أنشئ مفتاحًا في Google AI Studio

الحصول على مفتاح واجهة برمجة التطبيقات

تأمين مفتاح واجهة برمجة التطبيقات

حافظ على أمان مفتاح واجهة برمجة التطبيقات. ننصحك بشدة بعدم عدم تضمين مفتاح واجهة برمجة التطبيقات مباشرةً في الرمز البرمجي لتطبيقك، أو التحقق من الملفات التي تحتوي على المفتاح في أنظمة التحكم في الإصدار. بدلاً من ذلك، عليك استخدام مخزن أسرار لمفتاح واجهة برمجة التطبيقات.

تفترض كل المقتطفات في هذا البرنامج التعليمي أنّك تصل إلى مفتاح واجهة برمجة التطبيقات كمتغير لبيئة المعالجة. إذا كنت تطوِّر تطبيق Flutter، يمكنك استخدام String.fromEnvironment وتمرير --dart-define=API_KEY=$API_KEY إلى flutter build أو flutter run للتجميع باستخدام مفتاح واجهة برمجة التطبيقات لأنّ بيئة العملية ستكون مختلفة عند تشغيل التطبيق.

تثبيت حزمة SDK

لاستخدام Gemini API في تطبيقك الخاص، عليك add حزمة google_generative_ai في تطبيق Dart أو Flutter:

dart pub add google_generative_ai

flutter pub add google_generative_ai

إعداد النموذج التوليدي

قبل أن تتمكن من إجراء أي طلبات بيانات من واجهة برمجة التطبيقات، عليك استيراد النموذج التوليدي وإعداده.

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 وعمليات التضمين.

إنشاء نص من الإدخال النصي فقط

عندما يتضمّن إدخال الطلب نصًا فقط، استخدِم نموذج 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. يصف هذا القسم بعض حالات الاستخدام التي يمكن اعتبارها أكثر تقدمًا.

استدعاء الدوال

يُسهّل استدعاء الدوال عليك الحصول على مخرجات البيانات المنظَّمة من النماذج التوليدية. ويمكنك بعد ذلك استخدام هذه المخرجات لطلب واجهات برمجة تطبيقات أخرى وعرض بيانات الاستجابة ذات الصلة للنموذج. بعبارة أخرى، يساعدك استدعاء الوظيفة على ربط النماذج التوليدية بالأنظمة الخارجية، بحيث يتضمن المحتوى الذي يتم إنشاؤه أحدث المعلومات ودقتها. يمكنك الاطّلاع على مزيد من المعلومات في البرنامج التعليمي الخاص باستدعاء الوظائف.

استخدام التضمينات

التضمين هو أسلوب يُستخدَم لتمثيل المعلومات كقائمة بأرقام النقاط العائمة في مصفوفة. باستخدام 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).