تتوفّر الآن نافذة Gemini 1.5 Pro 2M للسياق وإمكانيات تنفيذ الرموز وGemma 2. مزيد من المعلومات

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

يفترض هذا البرنامج التعليمي أنك على دراية باستخدام Xcode لتطوير تطبيقات Swift.

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

Xcode 15.0 أو إصدار أحدث
يجب أن يستهدف تطبيق Swift نظام التشغيل iOS 15 أو الإصدارات الأحدث أو نظام التشغيل macOS 12 أو الإصدارات الأحدث.

إعداد مشروعك

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

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

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

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

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

ننصحك بشدة بعدم التحقّق من مفتاح واجهة برمجة التطبيقات في نظام التحكّم في الإصدار. ويمكنك بدلاً من ذلك تخزينها في ملف GenerativeAI-Info.plist ثم قراءة مفتاح واجهة برمجة التطبيقات من ملف .plist. احرص على وضع ملف .plist هذا في المجلد الجذر لتطبيقك واستبعاده من عنصر التحكّم في الإصدار.

التوسيع لعرض كيفية تخزين مفتاح واجهة برمجة التطبيقات وقراءته من ملف .plist

enum APIKey {
  // Fetch the API key from `GenerativeAI-Info.plist`
  static var `default`: String {
    guard let filePath = Bundle.main.path(forResource: "GenerativeAI-Info", ofType: "plist")
    else {
      fatalError("Couldn't find file 'GenerativeAI-Info.plist'.")
    }
    let plist = NSDictionary(contentsOfFile: filePath)
    guard let value = plist?.object(forKey: "API_KEY") as? String else {
      fatalError("Couldn't find key 'API_KEY' in 'GenerativeAI-Info.plist'.")
    }
    if value.starts(with: "_") {
      fatalError(
        "Follow the instructions at https://ai.google.dev/tutorials/setup to get an API key."
      )
    }
    return value
  }
}

يمكنك أيضًا مراجعة نموذج التطبيق للتعرّف على كيفية تخزين مفتاح واجهة برمجة التطبيقات في ملف .plist.

تفترض كل المقتطفات في هذا البرنامج التعليمي أنك تحاول الوصول إلى مفتاح واجهة برمجة التطبيقات من ملف .plist هذا للمورد عند الطلب.

إضافة حزمة SDK إلى مشروعك

لاستخدام Gemini API في تطبيق Swift، أضِف حزمة GoogleGenerativeAI إلى تطبيقك:

في Xcode، انقر بزر الماوس الأيمن على مشروعك في أداة التنقّل في المشروع.
اختَر إضافة حِزم من قائمة السياق.
في مربّع الحوار إضافة حِزم، الصِق عنوان URL للحزمة في شريط البحث:
```
https://github.com/google/generative-ai-swift
```
انقر على إضافة حزمة. سيضيف Xcode الآن حزمة GoogleGenerativeAI إلى مشروعك.

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

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

استيراد الوحدة النمطية GoogleGenerativeAI:
```
import GoogleGenerativeAI
```

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

// Access your API key from your on-demand resource .plist file
// (see "Set up your API key" above)
// The Gemini 1.5 models are versatile and work with most use cases
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

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

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

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

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

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

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

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

إذا كان إدخال الطلب يتضمّن نصًا فقط، استخدِم نموذج Gemini 1.5 أو نموذج Gemini 1.0 Pro مع generateContent لإنشاء محتوى نصي:

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let prompt = "Write a story about a magic backpack."
let response = try await model.generateContent(prompt)
if let text = response.text {
  print(text)
}

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

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

عندما يتضمّن إدخال الطلب نصًا وصورًا، استخدِم نموذج Gemini 1.5 مع طريقة generateContent لإنشاء إخراج نصي:

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let image1 = UIImage(...)
let image2 = UIImage(...)

let prompt = "What's different between these pictures?"

let response = try await model.generateContent(prompt, image1, image2)
if let text = response.text {
  print(text)
}

إنشاء محادثات متعددة الأدوار (الدردشة)

باستخدام Gemini، يمكنك إجراء محادثات حرة بين مختلف الأدوار. وتعمل حزمة تطوير البرامج (SDK) على تبسيط العملية من خلال إدارة حالة المحادثة، وبذلك لن تحتاج إلى تخزين سجلّ المحادثات بنفسك، على عكس generateContent.

لبدء محادثة متعددة الأدوار (مثل المحادثة)، يمكنك استخدام نموذج Gemini 1.5 أو نموذج Gemini 1.0 Pro، وبدء المحادثة من خلال الاتصال بالرقم startChat(). بعد ذلك، استخدِم sendMessage() لإرسال رسالة جديدة للمستخدم، وسيؤدي ذلك أيضًا إلى إلحاق الرسالة والرد إلى سجلّ المحادثات.

هناك خياران محتملان لـ role المرتبطين بالمحتوى في المحادثة:

user: الدور الذي يقدّم الطلبات هذه القيمة هي القيمة التلقائية لمكالمات sendMessage.
model: الدور الذي يقدّم الردود يمكن استخدام هذا الدور عند استدعاء startChat() باستخدام history الحالية.

import GoogleGenerativeAI

let config = GenerationConfig(
  maxOutputTokens: 100
)

// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  generationConfig: config
)

let history = [
  ModelContent(role: "user", parts: "Hello, I have 2 dogs in my house."),
  ModelContent(role: "model", parts: "Great to meet you. What would you like to know?"),
]

// Initialize the chat
let chat = model.startChat(history: history)
let response = try await chat.sendMessage("How many paws are in my house?")
if let text = response.text {
  print(text)
}

استخدام البث المباشر للتفاعلات بشكل أسرع

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

يوضّح المثال التالي كيفية تنفيذ البث باستخدام طريقة generateContentStream لإنشاء نص من طلب إدخال نص وصورة.

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let image1 = UIImage(named: "")!
let image2 = UIImage(named: "")!

let prompt = "What's different between these pictures?"
var fullResponse = ""
let contentStream = model.generateContentStream(prompt, image1, image2)
for try await chunk in contentStream {
  if let text = chunk.text {
    print(text)
    fullResponse += text
  }
}
print(fullResponse)

يمكنك استخدام أسلوب مماثل لحالات استخدام إدخال النص فقط والدردشة.

// Use streaming with text-only input
let contentStream = model.generateContentStream(prompt)

// Use streaming with multi-turn conversations (like chat)
let responseStream = chat.sendMessageStream(message)

تنفيذ حالات الاستخدام المتقدّمة

تساعدك حالات الاستخدام الشائعة الموضّحة في القسم السابق من هذا الدليل التوجيهي في إتقان استخدام Gemini API. يصف هذا القسم بعض حالات الاستخدام التي يمكن اعتبارها أكثر تقدمًا.

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

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

عدد الرموز المميّزة

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

// For text-only input
let response = try await model.countTokens("Why is the sky blue?")
print(response.totalTokens)

// For text-and-image input (multi-modal)
let response = try await model.countTokens(prompt, image1, image2)
print(response.totalTokens)

// For multi-turn conversations (like chat)
let chat = model.startChat()
let history = chat.history
let message = try ModelContent(role: "user", "Why is the sky blue?")
let contents = history + [message]
let response = try await model.countTokens(contents)
print(response.totalTokens)

خيارات التحكّم في إنشاء المحتوى

يمكنك التحكّم في عملية إنشاء المحتوى من خلال ضبط مَعلَمات النماذج واستخدام إعدادات الأمان.

ضبط مَعلمات النموذج

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

let config = GenerationConfig(
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
  maxOutputTokens: 200,
  stopSequences: ["red"]
)

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  generationConfig: config
)

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

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

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

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  safetySettings: [
    SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
  ]
)

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

let harassmentSafety = SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
let hateSpeechSafety = SafetySetting(harmCategory: .hateSpeech, threshold: .blockMediumAndAbove)

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
    safetySettings: [harassmentSafety, hateSpeechSafety]
)

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

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