Swift uygulamalarında Gemini API'yi kullanmaya başlama

Bu eğiticide, Google AI Swift SDK'sını kullanarak Gemini API'ye doğrudan Swift uygulamanızdan nasıl erişileceği gösterilmektedir. Swift uygulamanızdaki Gemini modellerine erişmek için doğrudan REST API'leriyle veya sunucu tarafı kodla (Python gibi) çalışmak istemiyorsanız bu SDK'yı kullanabilirsiniz.

Bu eğiticide aşağıdakileri nasıl yapacağınızı öğreneceksiniz:

• API anahtarınız da dahil olmak üzere projenizi oluşturma
• Yalnızca metin girişlerinden metin oluşturma
• Metin ve resim girişlerinden metin oluşturma (çok modlu)
• Çok dönüşlü görüşmeler yapma (sohbet)
• Daha hızlı etkileşimler için akış özelliğini kullanın

Ayrıca bu eğitim, gelişmiş kullanım alanları (ör. jetonları sayma) ve içerik oluşturmayı denetleme seçenekleri hakkında bölümler içerir.

Ön koşullar

Bu eğiticiye başlamadan önce, Swift uygulamaları geliştirmek için Xcode konusunda bilgi sahibi olduğunuz varsayılmaktadır.

Bu eğiticiyi tamamlamak için geliştirme ortamınızın ve Swift uygulamanızın aşağıdaki gereksinimleri karşıladığından emin olun:

• Xcode 15.0 veya üstü
• Swift uygulamanız iOS 15 veya sonraki sürümleri ya da macOS 12 veya sonraki sürümleri hedeflemelidir.

Projenizi oluşturun

Gemini API'yi çağırmadan önce Xcode projenizi ayarlamanız gerekir. Bu aşamaya API anahtarınızı oluşturma, SDK paketini Xcode projenize ekleme ve model başlatma dahildir.

API anahtarınızı oluşturma

Gemini API'yi kullanmak için API anahtarı gerekir. Anahtarınız yoksa Google AI Studio'da bir anahtar oluşturun.

API anahtarı alma

API anahtarınızın güvenliğini sağlama

Sürüm kontrol sisteminizde bir API anahtarını kontrol etmemeniz kesinlikle önerilir. Alternatif bir seçenek de bunu bir GenerativeAI-Info.plist dosyasında depolamak ve ardından API anahtarını .plist dosyasından okumaktır. Bu .plist dosyasını uygulamanızın kök klasörüne yerleştirdiğinizden ve sürüm kontrolünden hariç tuttuğunuzdan emin olun.

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 anahtarınızı .plist dosyasında nasıl depolayacağınızı öğrenmek için örnek uygulamayı da inceleyebilirsiniz.

Bu eğitimdeki tüm snippet'ler, API anahtarınıza isteğe bağlı bu kaynak .plist dosyasından eriştiğinizi varsayar.

SDK paketini projenize ekleyin

Gemini API'yi kendi Swift uygulamanızda kullanmak için GoogleGenerativeAI paketini uygulamanıza ekleyin:

1. Xcode'da proje gezgininde projenizi sağ tıklayın.

2. İçerik menüsünden Paket Ekle'yi seçin.

3. Paket Ekle iletişim kutusundaki arama çubuğuna paket URL'sini yapıştırın:

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

4. Paket Ekle'yi tıklayın. Xcode şimdi projenize GoogleGenerativeAI paketini ekleyecektir.

Üretken modeli ilk kullanıma hazırlama

Herhangi bir API çağrısı yapmadan önce üretici modeli ilk kullanıma hazırlamanız gerekir.

1. GoogleGenerativeAI modülünü içe aktarma:

   import GoogleGenerativeAI
   

2. Üretken modeli ilk kullanıma hazırlayın:

   // 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)
   

Bir model belirtirken aşağıdakilere dikkat edin:

• Kullanım alanınıza özel bir model kullanın (örneğin, gemini-pro-vision çok modlu giriş içindir). Bu kılavuzda, her uygulamaya ilişkin talimatlarda, her kullanım alanı için önerilen model listelenmiştir.

Yaygın kullanım alanlarından yararlanın

Projeniz hazır olduğuna göre farklı kullanım alanları uygulamak için Gemini API'yi nasıl kullanabileceğinizi keşfedebilirsiniz:

• Yalnızca metin girişlerinden metin oluşturma
• Metin ve resim girişlerinden metin oluşturma (çok modlu)
• Çok dönüşlü görüşmeler yapma (sohbet)
• Daha hızlı etkileşimler için akış özelliğini kullanın

Yalnızca metin girişinden metin oluştur

İstem girişi yalnızca metin içeriyorsa metin çıkışı oluşturmak için generateContent yöntemiyle gemini-pro modelini kullanın:

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)
}

Metin ve resim girişinden metin oluşturma (çok modlu)

Gemini çok modlu bir model (gemini-pro-vision) sunar. Böylece hem metin hem de resim girebilirsiniz. İstemler için resim gereksinimlerini incelediğinizden emin olun.

İstem girişi hem metin hem de resimleri içerdiğinde metin çıkışı oluşturmak için generateContent yöntemiyle gemini-pro-vision modelini kullanın:

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)
}

Çok dönüşlü görüşmeler yapma (sohbet)

Gemini'ı kullanarak birden fazla dönüş için serbest biçimli konuşmalar oluşturabilirsiniz. SDK, görüşmenin durumunu yöneterek süreci basitleştirir. Böylece, generateContent'den farklı olarak sohbet geçmişini sizin saklamanız gerekmez.

Çok dönüşlü bir görüşme (ör. sohbet) oluşturmak için gemini-pro modelini kullanın ve startChat() yöntemini çağırarak sohbeti başlatın. Ardından, yeni bir kullanıcı mesajı göndermek için sendMessage() kullanın. Bu işlem, mesajı ve yanıtı da sohbet geçmişine ekler.

Bir görüşmedeki içerikle ilişkili role için iki olası seçenek vardır:

• user: İstemleri sağlayan rol. Bu değer, sendMessage çağrıları için varsayılan değerdir.

• model: Yanıtları sağlayan rol. Bu rol, mevcut history ile startChat() çağrılırken kullanılabilir.

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)
}

Daha hızlı etkileşimler için akış özelliğini kullanın

Varsayılan olarak model, tüm oluşturma işlemini tamamladıktan sonra bir yanıt döndürür. Tüm sonucu beklemeyip bunun yerine kısmi sonuçları işlemek için akışı kullanarak daha hızlı etkileşimler gerçekleştirebilirsiniz.

Aşağıdaki örnekte, metin ve resim giriş isteminden metin oluşturmak için generateContentStream yöntemiyle akışın nasıl uygulanacağı gösterilmektedir.

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)

Yalnızca metin girişi ve sohbet kullanım alanları için benzer bir yaklaşım kullanabilirsiniz.

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

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

Gelişmiş kullanım alanları

Bu eğiticinin önceki bölümünde açıklanan yaygın kullanım alanları, Gemini API'yi kullanmaya alışmanıza yardımcı olur. Bu bölümde, daha ileri düzey olarak değerlendirilebilecek bazı kullanım alanları açıklanmaktadır.

İşlev çağrısı

İşlev çağrısı, üretici modellerden yapılandırılmış veri çıkışları almanızı kolaylaştırır. Daha sonra bu çıkışları kullanarak diğer API'leri çağırabilir ve ilgili yanıt verilerini modele döndürebilirsiniz. Başka bir deyişle, işlev çağrısı, üretken modelleri harici sistemlere bağlamanıza yardımcı olarak oluşturulan içeriğin en güncel ve doğru bilgileri içermesini sağlar. İşlev çağrısı eğiticisinde daha fazla bilgi edinebilirsiniz.

Jetonları say

Uzun istemler kullanırken, modele içerik göndermeden önce jetonların sayılması yararlı olabilir. Aşağıdaki örneklerde countTokens() öğesinin çeşitli kullanım alanlarında nasıl kullanılacağı gösterilmektedir:

// 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)

İçerik oluşturmayı denetleme seçenekleri

Model parametrelerini yapılandırarak ve güvenlik ayarlarını kullanarak içerik oluşturmayı kontrol edebilirsiniz.

Model parametrelerini yapılandırma

Modele gönderdiğiniz her istem, modelin nasıl yanıt oluşturacağını kontrol eden parametre değerleri içerir. Model, farklı parametre değerleri için farklı sonuçlar oluşturabilir. Model parametreleri hakkında daha fazla bilgi edinin. Yapılandırma, model örneğinizin kullanım ömrü boyunca korunur.

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
)

Güvenlik ayarlarını kullan

Zararlı olarak değerlendirilebilecek yanıtlar alma olasılığını ayarlamak için güvenlik ayarlarını kullanabilirsiniz. Güvenlik ayarları, varsayılan olarak güvenli olmayan içerik olması orta ve/veya yüksek olasılıklı tüm içerikleri tüm boyutlarda engeller. Güvenlik ayarları hakkında daha fazla bilgi edinin.

Aşağıda, bir güvenlik ayarını nasıl belirleyeceğiniz açıklanmıştır:

// 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)
  ]
)

Birden fazla güvenlik ayarı da belirleyebilirsiniz:

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]
)

Sırada ne var?

• İstem tasarımı, dil modellerinden istenen yanıtı alan istemler oluşturma sürecidir. İyi yapılandırılmış istemler yazmak, bir dil modelinden doğru, yüksek kaliteli yanıtlar almanın önemli bir parçasıdır. İstem yazmayla ilgili en iyi uygulamalar hakkında bilgi edinin.

• Gemini, giriş türleri ve karmaşıklık, sohbet veya diğer iletişim dili görevlerine yönelik uygulamalar ve boyut kısıtlamaları gibi farklı kullanım alanlarının ihtiyaçlarını karşılamak için çeşitli model varyasyonları sunuyor. Kullanılabilir Gemini modelleri hakkında bilgi edinin.

• Gemini, hız sınırının artırılmasını isteme seçeneği sunar. Gemini Pro modelleri için hız sınırı dakikada 60 istektir (BGBG).