开始在 Swift 应用中使用 Gemini API

本教程演示了如何使用 Google AI Swift SDK 直接从 Swift 应用访问 Gemini API。如果您不想直接使用 REST API 或服务器端代码（如 Python）来访问 Swift 应用中的 Gemini 模型，则可以使用此 SDK。

在本教程中，您将了解如何执行以下操作：

• 设置您的项目，包括您的 API 密钥
• 从纯文本输入生成文本
• 从文字和图片输入生成文本（多模态）
• 发起多轮对话（聊天）
• 使用流式传输提高互动速度

此外，本教程还包含一些高级用例（例如令牌计数）以及控制内容生成的选项。

前提条件

本教程假定您熟悉如何使用 Xcode 开发 Swift 应用。

如需完成本教程，请确保您的开发环境和 Swift 应用满足以下要求：

• Xcode 15.0 或更高版本
• 您的 Swift 应用必须以 iOS 15 或更高版本或者 macOS 12 或更高版本为目标平台。

设置项目

在调用 Gemini API 之前，您需要设置 Xcode 项目，其中包括设置 API 密钥、将 SDK 软件包添加到 Xcode 项目以及初始化模型。

设置您的 API 密钥

您需要 API 密钥才能使用 Gemini API。如果您还没有密钥，请在 Google AI Studio 中创建密钥。

获取 API 密钥

保护您的 API 密钥

强烈建议您不要将 API 密钥签入版本控制系统。一种替代方法是将其存储在 GenerativeAI-Info.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 文件中。

本教程中的所有代码段均假定您从此按需资源 .plist 文件访问 API 密钥。

将 SDK 软件包添加到您的项目中

如需在您自己的 Swift 应用中使用 Gemini API，请将 GoogleGenerativeAI 软件包添加到您的应用中：

1. 在 Xcode 的项目导航器中，右键点击您的项目。

2. 从上下文菜单中选择添加软件包。

3. 在 Add Packages 对话框中，将软件包网址粘贴到搜索栏：

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

4. 点击 Add Package（添加软件包）。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：提供响应的角色。使用现有 history 调用 startChat() 时，可以使用此角色。

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。本部分介绍了一些可能被视为更高级的用例。

计算词元数

使用长提示时，在将任何内容发送到模型之前统计令牌数可能很有用。以下示例展示了如何针对各种用例使用 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 提供了用于请求提高速率限制的选项。Genmini Pro 型号的速率限制为每分钟 60 个请求。