Начало работы с API Gemini в приложениях Swift

В этом руководстве показано, как получить доступ к API Gemini непосредственно из приложения Swift с помощью Google AI Swift SDK. Вы можете использовать этот SDK, если не хотите напрямую работать с REST API или серверным кодом (например, Python) для доступа к моделям Gemini в вашем приложении Swift.

В этом уроке вы узнаете, как сделать следующее:

• Настройте свой проект, включая ключ API
• Генерировать текст из текстового ввода
• Генерация текста из ввода текста и изображения (мультимодальный)
• Создавайте многоходовые беседы (чат)
• Используйте потоковую передачу для более быстрого взаимодействия

Кроме того, это руководство содержит разделы, посвященные расширенным вариантам использования (например, подсчету токенов ), а также параметрам управления генерацией контента .

Предварительные условия

В этом руководстве предполагается, что вы знакомы с использованием Xcode для разработки приложений Swift.

Чтобы завершить работу с этим руководством, убедитесь, что ваша среда разработки и приложение Swift соответствуют следующим требованиям:

• Xcode 15.0 или выше
• Ваше приложение Swift должно быть ориентировано на iOS 15 или более позднюю версию или macOS 12 или более позднюю версию.

Настройте свой проект

Прежде чем вызывать API Gemini, вам необходимо настроить проект Xcode, который включает в себя настройку ключа API, добавление пакета SDK в проект Xcode и инициализацию модели.

Настройте свой ключ API

Чтобы использовать API Gemini, вам понадобится ключ API. Если у вас его еще нет, создайте ключ в Google AI Studio.

Получить ключ API

Защитите свой ключ API

Настоятельно рекомендуется не проверять ключ API в вашей системе контроля версий. Один из альтернативных вариантов — сохранить его в файле GenerativeAI-Info.plist , а затем прочитать ключ API из файла .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
  }
}

Вы также можете просмотреть пример приложения , чтобы узнать, как хранить ключ API в файле .plist .

Во всех фрагментах этого руководства предполагается, что вы получаете доступ к своему ключу API из этого .plist -файла ресурса по требованию.

Добавьте пакет SDK в свой проект

Чтобы использовать Gemini API в своем собственном приложении Swift, добавьте в свое приложение пакет GoogleGenerativeAI :

1. В Xcode щелкните правой кнопкой мыши свой проект в навигаторе проекта.

2. Выберите «Добавить пакеты» в контекстном меню.

3. В диалоговом окне «Добавить пакеты» вставьте URL-адрес пакета в строку поиска:

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

4. Нажмите «Добавить пакет» . Xcode теперь добавит пакет GoogleGenerativeAI в ваш проект.

Инициализируйте генеративную модель

Прежде чем вы сможете выполнять какие-либо вызовы API, вам необходимо инициализировать генеративную модель.

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)

Реализация расширенных вариантов использования

Распространенные случаи использования, описанные в предыдущем разделе этого руководства, помогут вам освоиться с API 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 = 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 запросов в минуту (об/мин).