انخفاض في سعر Gemini 1.5 Flash، وضبط أذونات الوصول لجميع المطوّرين وغير ذلك مزيد من المعلومات

تمت ترجمة هذه الصفحة بواسطة 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 المتاحة