“依托 Google 搜索进行接地”功能现已推出！了解详情

此页面由 Cloud Translation API 翻译。

教程：Gemini API 使用入门

本教程演示了如何直接从 Google Cloud 控制台使用 Google AI Swift SDK 的 Swift 应用。如果不需要直接使用 REST API 或服务器端代码（如 Python） Gemini 模型。

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

设置您的项目，包括您的 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 文件，然后从 .plist 读取 API 密钥文件。请务必将此 .plist 文件放在应用的根文件夹中，将其从版本控制中排除

展开即可查看如何在 .plist 文件中存储和读取 API 密钥

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 软件包添加到您的项目中

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

在 Xcode 中的项目导航器中，右键点击您的项目。
从上下文菜单中选择添加软件包。
在 Add Packages 对话框中，将软件包网址粘贴到搜索栏中：
```
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)
// The Gemini 1.5 models are versatile and work with most use cases
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

指定模型时，请注意以下事项：

请使用您的用例专用的模型（例如 gemini-1.5-flash 适用于多模态输入）。在本指南中，实现列出了每个用例的推荐模型。

注意：如需详细了解可用模型，包括功能和速率限制，请参阅 Gemini 模型。我们提供请求提高速率限制的选项默认还不够。

实现常见使用场景

现在您的项目已设置完毕，您可以探索如何使用 Gemini API 来实现不同的应用场景：

根据纯文本输入生成文本
根据文本和图片输入生成文本（多模态）
建立多轮对话（聊天）
使用流式传输加快互动速度

根据纯文本输入生成文本

如果输入的提示仅包含文本，请使用 Gemini 1.5 模型或使用 generateContent 生成文本输出的 Gemini 1.0 Pro 模型：

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", 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 1.5 模型），这样你就可以同时输入和图片。请务必查看提示的图片要求。

如果输入的提示同时包含文本和图片，请使用 Gemini 1.5 模型使用 generateContent 方法生成文本输出：

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", 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 1.5 模型或 Gemini 1.0 Pro 模型，并通过调用 startChat() 来初始化对话。然后，使用 sendMessage() 发送一条新的用户消息，此消息还将附加消息和对聊天记录的响应。

与内容关联的 role 有两种可能的选项对话：

user：提供提示的角色。该值是 sendMessage 次通话。
model：提供响应的角色。此角色可以在以下情况下使用：使用现有的 history 调用 startChat()。

。

import GoogleGenerativeAI

let config = GenerationConfig(
  maxOutputTokens: 100
)

// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  name: "gemini-1.5-flash",
  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

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", 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。本部分介绍了一些可能被视为更高级的用例。

调用函数

函数调用可让您更轻松地从 Google Cloud 控制台获取结构化数据输出生成模型。然后，您可以使用这些输出来调用其他 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 = try 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(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  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(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  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(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
    safetySettings: [harassmentSafety, hateSpeechSafety]
)

后续步骤

提示设计是创建提示以从语言模型引出所需回复的过程。撰写结构合理的提示是是确保语言模型做出准确、高质量响应的一部分。了解提示撰写的最佳做法。
Gemini 提供多种模型变体，以满足不同使用情形的需求例如输入类型和复杂性、聊天或其他对话框语言任务和大小限制。不妨了解可用的 Gemini 模型。