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.

Halaman ini diterjemahkan oleh Cloud Translation API.

Mulai menggunakan Gemini API di aplikasi Swift

Tutorial ini menunjukkan cara mengakses Gemini API langsung dari aplikasi Swift menggunakan Google AI Swift SDK. Anda dapat menggunakan SDK ini jika tidak ingin bekerja langsung dengan REST API atau kode sisi server (seperti Python) untuk mengakses model Gemini di aplikasi Swift.

Dalam tutorial ini, Anda akan mempelajari cara melakukan hal berikut:

Menyiapkan project Anda, termasuk kunci API
Membuat teks dari input khusus teks
Membuat teks dari input teks dan gambar (multimodal)
Membuat percakapan multi-giliran (chat)
Menggunakan streaming untuk interaksi yang lebih cepat

Selain itu, tutorial ini berisi bagian tentang kasus penggunaan lanjutan (seperti token penghitungan) serta opsi untuk mengontrol pembuatan konten.

Prasyarat

Tutorial ini mengasumsikan bahwa Anda sudah terbiasa menggunakan Xcode untuk mengembangkan aplikasi Swift.

Untuk menyelesaikan tutorial ini, pastikan lingkungan pengembangan dan aplikasi Swift Anda memenuhi persyaratan berikut:

Xcode 15.0 atau yang lebih tinggi
Aplikasi Swift Anda harus menargetkan iOS 15 atau yang lebih tinggi, atau macOS 12 atau yang lebih tinggi.

Menyiapkan project

Sebelum memanggil Gemini API, Anda perlu menyiapkan project Xcode, yang mencakup penyiapan kunci API, menambahkan paket SDK ke project Xcode, dan menginisialisasi model.

Menyiapkan kunci API

Untuk menggunakan Gemini API, Anda memerlukan kunci API. Jika Anda belum memilikinya, buat kunci di Google AI Studio.

Mendapatkan kunci API

Mengamankan kunci API Anda

Sebaiknya Anda tidak melakukan check in kunci API ke dalam sistem kontrol versi Anda. Salah satu opsi alternatifnya adalah menyimpannya dalam file GenerativeAI-Info.plist, lalu membaca kunci API dari file .plist. Pastikan untuk menempatkan file .plist ini dalam folder root aplikasi Anda dan kecualikan dari kontrol versi.

Luaskan untuk melihat cara menyimpan dan membaca kunci API dari file .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
  }
}

Anda juga dapat meninjau aplikasi contoh untuk mempelajari cara menyimpan kunci API dalam file .plist.

Semua cuplikan dalam tutorial ini mengasumsikan bahwa Anda mengakses kunci API dari file .plist resource on demand ini.

Menambahkan paket SDK ke project

Untuk menggunakan Gemini API di aplikasi Swift Anda sendiri, tambahkan paket GoogleGenerativeAI ke aplikasi Anda:

Di Xcode, klik kanan pada project Anda di navigator project.
Pilih Add Packages dari menu konteks.
Dalam dialog Add Packages, tempel URL paket di kotak penelusuran:
```
https://github.com/google/generative-ai-swift
```
Klik Add Package. Xcode sekarang akan menambahkan paket GoogleGenerativeAI ke project Anda.

Menginisialisasi Model Generatif

Sebelum dapat melakukan panggilan API, Anda perlu menginisialisasi Model Generatif.

Impor modul GoogleGenerativeAI:
```
import GoogleGenerativeAI
```

Inisialisasi Model Generatif:

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

Saat menetapkan model, perhatikan hal-hal berikut:

Gunakan model yang spesifik untuk kasus penggunaan Anda (misalnya, gemini-pro-vision untuk input multimodal). Dalam panduan ini, petunjuk untuk setiap penerapan mencantumkan model yang direkomendasikan untuk setiap kasus penggunaan.

Catatan: Untuk mengetahui informasi mendetail tentang model yang tersedia, termasuk kemampuan dan batas kapasitas, lihat model Gemini. Batas kapasitas untuk model Gemini Pro adalah 60 permintaan per menit (RPM), dan kami menawarkan opsi untuk meminta peningkatan batas kapasitas.

Menerapkan kasus penggunaan umum

Setelah project siap, Anda dapat menjelajah menggunakan Gemini API untuk menerapkan berbagai kasus penggunaan:

Membuat teks dari input khusus teks
Membuat teks dari input teks dan gambar (multimodal)
Membuat percakapan multi-giliran (chat)
Menggunakan streaming untuk interaksi yang lebih cepat

Membuat teks dari input khusus teks

Jika input perintah hanya menyertakan teks, gunakan model gemini-pro dengan metode generateContent untuk menghasilkan output teks:

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

Membuat teks dari input teks dan gambar (multimodal)

Gemini menyediakan model multimodal (gemini-pro-vision), sehingga Anda dapat memasukkan teks dan gambar. Pastikan Anda meninjau persyaratan gambar untuk perintah.

Saat input perintah menyertakan teks dan gambar, gunakan model gemini-pro-vision dengan metode generateContent untuk menghasilkan output teks:

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

Membuat percakapan multi-giliran (chat)

Dengan Gemini, Anda dapat membuat percakapan berformat bebas di berbagai kesempatan. SDK menyederhanakan proses dengan mengelola status percakapan, sehingga tidak seperti generateContent, Anda tidak perlu menyimpan sendiri histori percakapan sendiri.

Untuk membuat percakapan multi-giliran (seperti chat), gunakan model gemini-pro, dan lakukan inisialisasi chat dengan memanggil startChat(). Kemudian, gunakan sendMessage() untuk mengirim pesan pengguna baru, yang juga akan menambahkan pesan dan respons ke histori chat.

Ada dua kemungkinan opsi untuk role yang dikaitkan dengan konten dalam percakapan:

user: peran yang menyediakan dialog. Nilai ini merupakan default untuk panggilan sendMessage.
model: peran yang memberikan respons. Peran ini dapat digunakan saat memanggil startChat() dengan history yang ada.

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

Menggunakan streaming untuk interaksi yang lebih cepat

Secara default, model akan menampilkan respons setelah menyelesaikan seluruh proses pembuatan. Anda dapat mencapai interaksi yang lebih cepat dengan tidak menunggu seluruh hasil, dan sebagai gantinya menggunakan streaming untuk menangani hasil parsial.

Contoh berikut menunjukkan cara mengimplementasikan streaming dengan metode generateContentStream untuk menghasilkan teks dari permintaan input teks dan gambar.

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)

Anda dapat menggunakan pendekatan serupa untuk kasus penggunaan chat dan input khusus teks.

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

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

Menerapkan kasus penggunaan lanjutan

Kasus penggunaan umum yang dijelaskan di bagian tutorial sebelumnya membantu Anda merasa nyaman dalam menggunakan Gemini API. Bagian ini menjelaskan beberapa kasus penggunaan yang mungkin dianggap lebih lanjut.

Hitung token

Saat menggunakan perintah panjang, sebaiknya hitung token sebelum mengirim konten apa pun ke model. Contoh berikut menunjukkan cara menggunakan countTokens() untuk berbagai kasus penggunaan:

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

Opsi untuk mengontrol pembuatan konten

Anda dapat mengontrol pembuatan konten dengan mengonfigurasi parameter model dan dengan menggunakan setelan keamanan.

Mengonfigurasi parameter model

Setiap prompt yang Anda kirim ke model menyertakan parameter value yang mengontrol cara model menghasilkan respons. Model ini dapat memberikan hasil yang berbeda untuk parameter value yang berbeda. Pelajari Parameter model lebih lanjut. Konfigurasi dipertahankan selama masa pakai instance model Anda.

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
)

Gunakan setelan keamanan

Anda dapat menggunakan setelan keamanan untuk menyesuaikan kemungkinan mendapatkan respons yang mungkin dianggap berbahaya. Secara default, setelan keamanan memblokir konten yang memiliki kemungkinan sedang dan/atau tinggi sebagai konten yang tidak aman di semua dimensi. Pelajari Setelan keamanan lebih lanjut.

Berikut cara menetapkan satu setelan keamanan:

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

Anda juga dapat menetapkan lebih dari satu setelan keamanan:

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

Langkah selanjutnya

Desain prompt adalah proses pembuatan prompt yang mendapatkan respons yang diinginkan dari model bahasa. Menulis dialog yang terstruktur dengan baik adalah bagian penting untuk memastikan respons yang akurat dan berkualitas tinggi dari model bahasa. Pelajari praktik terbaik untuk penulisan perintah.
Gemini menawarkan beberapa variasi model untuk memenuhi kebutuhan berbagai kasus penggunaan, seperti jenis input dan kompleksitas, implementasi untuk chat atau tugas bahasa dialog lainnya, dan batasan ukuran. Pelajari model Gemini yang tersedia.
Gemini menawarkan opsi untuk meminta peningkatan batas kapasitas. Batas kapasitas untuk model Gemini Pro adalah 60 permintaan per menit (RPM).