The Google AI Swift SDK is in public preview, which means its behavior and features could change in backward-incompatible ways. Preview releases should not be used in production.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

با Gemini API در برنامه های Swift شروع کنید

این آموزش نحوه دسترسی مستقیم به Gemini API را از برنامه Swift خود با استفاده از Google AI Swift SDK نشان می دهد. اگر نمی‌خواهید مستقیماً با APIهای REST یا کدهای سمت سرور (مانند پایتون) برای دسترسی به مدل‌های Gemini در برنامه سوئیفت خود کار کنید، می‌توانید از این SDK استفاده کنید.

در این آموزش، نحوه انجام کارهای زیر را خواهید آموخت:

پروژه خود را تنظیم کنید، از جمله کلید API
متن را از ورودی فقط متنی تولید کنید
تولید متن از ورودی متن و تصویر (چند وجهی)
ساخت مکالمات چند نوبتی (چت)
از پخش جریانی برای تعاملات سریعتر استفاده کنید

علاوه بر این، این آموزش شامل بخش هایی در مورد موارد استفاده پیشرفته (مانند شمارش توکن ها ) و همچنین گزینه هایی برای کنترل تولید محتوا است .

پیش نیازها

این آموزش فرض می کند که شما با استفاده از Xcode برای توسعه برنامه های Swift آشنا هستید.

برای تکمیل این آموزش، مطمئن شوید که محیط توسعه و برنامه Swift شما شرایط زیر را برآورده می کند:

Xcode 15.0 یا بالاتر
برنامه Swift شما باید iOS 15 یا بالاتر یا macOS 12 یا بالاتر را هدف قرار دهد.

پروژه خود را تنظیم کنید

قبل از فراخوانی Gemini API، باید پروژه Xcode خود را راه‌اندازی کنید، که شامل تنظیم کلید API، افزودن بسته SDK به پروژه Xcode و مقداردهی اولیه مدل است.

کلید API خود را تنظیم کنید

برای استفاده از Gemini API، به یک کلید API نیاز دارید. اگر قبلاً یکی ندارید، یک کلید در Google AI Studio ایجاد کنید.

یک کلید API دریافت کنید

کلید API خود را ایمن کنید

اکیداً توصیه می شود که یک کلید API را در سیستم کنترل نسخه خود بررسی نکنید . یکی از گزینه های جایگزین این است که آن را در یک فایل GenerativeAI-Info.plist ذخیره کنید و سپس کلید API را از فایل .plist بخوانید. مطمئن شوید که این فایل .plist را در پوشه ریشه برنامه خود قرار داده و آن را از کنترل نسخه حذف کنید.

برای مشاهده نحوه ذخیره و خواندن کلید API از یک فایل .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
  }
}

همچنین می‌توانید برنامه نمونه را مرور کنید تا یاد بگیرید چگونه کلید API خود را در یک فایل .plist . ذخیره کنید.

همه قطعه‌های این آموزش فرض می‌کنند که شما به کلید API خود از این فایل .plist منبع درخواستی دسترسی دارید.

بسته SDK را به پروژه خود اضافه کنید

برای استفاده از Gemini API در برنامه Swift خود، بسته GoogleGenerativeAI را به برنامه خود اضافه کنید:

در Xcode، روی پروژه خود در ناوبر پروژه کلیک راست کنید.
از منوی زمینه گزینه Add Packages را انتخاب کنید.
در گفتگوی Add Packages ، URL بسته را در نوار جستجو جای‌گذاری کنید:
```
https://github.com/google/generative-ai-swift
```
روی افزودن بسته کلیک کنید. Xcode اکنون بسته GoogleGenerativeAI را به پروژه شما اضافه می کند.

مدل مولد را راه اندازی کنید

قبل از اینکه بتوانید هر گونه تماس API را انجام دهید، باید مدل تولیدی را مقداردهی اولیه کنید.

ماژول GoogleGenerativeAI را وارد کنید:
```
import GoogleGenerativeAI
```

مدل مولد را راه اندازی کنید:

// 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 مراجعه کنید. محدودیت نرخ برای مدل‌های Gemini Pro 60 درخواست در دقیقه (RPM) است، و ما گزینه‌هایی برای درخواست افزایش محدودیت نرخ ارائه می‌دهیم.

موارد استفاده رایج را اجرا کنید

اکنون که پروژه شما راه اندازی شده است، می توانید با استفاده از 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 API راحت باشید. این بخش برخی از موارد استفاده را که ممکن است پیشرفته‌تر در نظر گرفته شوند، توضیح می‌دهد.

فراخوانی تابع

فراخوانی تابع، دریافت خروجی داده های ساختاریافته از مدل های تولیدی را برای شما آسان تر می کند. سپس می‌توانید از این خروجی‌ها برای فراخوانی 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 = 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) است.