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

Python Node.js الويب REST Go 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 المتاحة