برنامج تعليمي: بدء استخدام Gemini API

Python Node.js الويب الإيقاف انتقال لعبة Dart (Flutter) Android Swift

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

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

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

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

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

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

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

• Dart 3.2.0 أو أحدث

إعداد مشروعك

قبل طلب Gemini API، عليك إعداد مشروعك، بما في ذلك: إعداد مفتاح واجهة برمجة التطبيقات وإضافة حزمة 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 '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);
  }

  // The Gemini 1.5 models are versatile and work with most use cases
  final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
}

عند تحديد نموذج، يُرجى مراعاة ما يلي:

• استخدِم نموذجًا مخصَّصًا لحالة الاستخدام (مثل gemini-1.5-flash). مخصص للإدخال متعدد الوسائط). في هذا الدليل، ستشمل التعليمات الخاصة بكل قائمة التنفيذ النموذج الموصى به لكل حالة استخدام.

تنفيذ حالات الاستخدام الشائعة

بعد الانتهاء من إعداد مشروعك، يمكنك الآن استخدام Gemini API من أجل تنفيذ حالات استخدام مختلفة:

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

يوفّر لك قسم "حالات الاستخدام المتقدّمة" معلومات حول Gemini API. والتضمين.

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

عندما يتضمّن الإدخال المخصّص نصًا فقط، يُرجى استخدام نموذج Gemini 1.5 أو نموذج Gemini 1.0 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);
  }
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
  final content = [Content.text('Write a story about a magic backpack.')];
  final response = await model.generateContent(content);
  print(response.text);
}

إنشاء نص من إدخال النص والصورة (متعدد الوسائط)

يوفّر Gemini نماذج مختلفة يمكنها التعامل مع الإدخالات المتعدّدة الوسائط (نموذج Gemini 1.5) لتتمكن من إدخال النصَين والصور. تأكد من مراجعة متطلبات الصور في الطلبات:

عندما يتضمّن الإدخال في الطلب نصًا وصورًا معًا، يجب استخدام نموذج Gemini 1.5 باستخدام الطريقة 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);
  }
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  final model = GenerativeModel(model: 'gemini-1.5-flash', 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 1.5 أو نموذج Gemini 1.0 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);
  }
  // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
  final model = GenerativeModel(
      model: 'gemini-1.5-flash',
      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 يصف هذا القسم بعض حالات الاستخدام التي يمكن اعتبارها أكثر تقدمًا.

استدعاء الدالة

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

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

التضمين هو أسلوب يُستخدَم لتمثيل المعلومات. كقائمة بأرقام النقاط العائمة في مصفوفة. باستخدام 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(
  // The Gemini 1.5 models are versatile and work with most use cases
  model: 'gemini-1.5-flash',
  apiKey: apiKey,
  generationConfig: generationConfig,
);

استخدام إعدادات الأمان

يمكنك استخدام إعدادات الأمان لضبط احتمالية تلقّي ردود ضارًا. تحظر إعدادات الأمان المحتوى باستخدام الوسيط و/أو احتمالية عالية لكونه محتوى غير آمن بجميع السمات. التعلّم مزيد من المعلومات حول إعدادات الأمان

إليك كيفية ضبط إعداد أمان واحد:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high)
];
final model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  model: 'gemini-1.5-flash',
  apiKey: apiKey,
  safetySettings: safetySettings,
);

يمكنك أيضًا ضبط أكثر من إعداد أمان واحد:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high),
  SafetySetting(HarmCategory.hateSpeech, HarmBlockThreshold.high),
];

الخطوات التالية

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

• يقدّم Gemini صيغًا متعدّدة للنماذج لتلبية احتياجات الاستخدام المختلفة. مثل أنواع الإدخال ودرجة التعقيد أو عمليات التنفيذ المتعلقة بالدردشة أو غير ذلك ومهام لغة مربع الحوار وقيود الحجم. مزيد من المعلومات حول طُرز Gemini المتاحة