بدء استخدام Gemini API في تطبيقات Swift

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

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

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

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

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

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

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

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

إعداد مشروعك

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

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

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

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

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

ننصحك بشدة بعدم التحقّق من مفتاح واجهة برمجة التطبيقات في نظام التحكّم في الإصدار. يمكنك بدلاً من ذلك تخزينه في ملف GenerativeAI-Info.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 في تطبيق Swift، أضِف حزمة GoogleGenerativeAI إلى تطبيقك:

1. في Xcode، انقر بزر الماوس الأيمن على مشروعك في أداة التنقل في المشروع.

2. انقر على إضافة حِزم من قائمة السياق.

3. في مربع الحوار إضافة حزم، الصِق عنوان URL للحزمة في شريط البحث:

   https://github.com/google/generative-ai-swift
   

4. انقر على إضافة حزمة. ستضيف Xcode الآن حزمة GoogleGenerativeAI إلى مشروعك.

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

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

1. استورِد وحدة "GoogleGenerativeAI":

   import GoogleGenerativeAI
   

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

   // Access your API key from your on-demand resource .plist file
   // (see "Set up your API key" above)
   let model = GenerativeModel(name: "MODEL_NAME", apiKey: APIKey.default)
   

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

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

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

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

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

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

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

import GoogleGenerativeAI

// For text-only input, use the gemini-pro model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro", 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-pro-vision)، لذلك يمكنك إدخال كل من النص والصور. تأكَّد من مراجعة متطلّبات الصورة للطلبات.

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

import GoogleGenerativeAI

// For text-and-image input (multimodal), use the gemini-pro-vision model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro-vision", 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-pro، وأهِّل المحادثة من خلال طلب الرقم startChat(). بعد ذلك، استخدِم sendMessage() لإرسال رسالة جديدة للمستخدم، ما يؤدي أيضًا إلى إلحاق الرسالة والردّ بسجلّ المحادثات.

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

• user: الدور الذي يقدّم الطلبات هذه القيمة هي القيمة التلقائية لاستدعاءات sendMessage.

• model: الدور الذي يقدّم الردود يمكن استخدام هذا الدور عند استدعاء "startChat()" مع "history" الحالي.

import GoogleGenerativeAI

let config = GenerationConfig(
  maxOutputTokens: 100
)

// For text-only input, use the gemini-pro model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  name: "gemini-pro",
  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

// For text-and-image input (multimodal), use the gemini-pro-vision model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro-vision", 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. يصف هذا القسم بعض حالات الاستخدام التي يمكن اعتبارها أكثر تقدمًا.

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

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

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

عند استخدام المطالبات الطويلة، قد يكون من المفيد حساب الرموز قبل إرسال أي محتوى إلى النموذج. توضِّح الأمثلة التالية كيفية استخدام علامة 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 = 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(
  name: "MODEL_NAME",
  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(
  name: "MODEL_NAME",
  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(
  name: "MODEL_NAME",
  apiKey: APIKey.default,
    safetySettings: [harassmentSafety, hateSpeechSafety]
)

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

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

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

• يوفّر Gemini خيارات لطلب زيادة الحدّ الأقصى للمعدّل. الحدّ الأقصى لمعدّل الزحف لطُرز Gemini Pro هو 60 طلبًا في الدقيقة (RPM).