<ph type="x-smartling-placeholder">
本教程演示了如何直接从 Google Cloud 控制台 使用 Android 版 Google AI 客户端 SDK 的 Android 应用。您可以使用 客户端 SDK(如果您不想直接使用 REST API 或服务器端代码) (如 Python),以便访问 Android 应用中的 Gemini 模型。
在本教程中,您将了解如何执行以下操作:
此外,本教程还包含一些有关高级用例(如 计算词元)以及 控制内容生成。
考虑在设备端访问 Gemini
通过本教程中介绍的适用于 Android 的客户端 SDK,您可以访问 在 Google 的服务器上运行的 Gemini Pro 模型。适用于涉及 处理敏感数据、提高离线可用性,或节省 使用常用用户流时,可以考虑访问 Gemini Nano 该类型在设备上运行。有关详情,请参阅 Android(设备端)教程。
前提条件
本教程假定您熟悉使用 Android Studio 开发 Android 应用
要完成本教程,请确保您的开发环境和 Android 应用满足以下要求:
- Android Studio(最新版本)
- 您的 Android 应用必须以 API 级别 21 或更高级别为目标平台。
设置项目
在调用 Gemini API 之前,您需要设置 Android 项目, 包括设置 API 密钥、将 SDK 依赖项添加到 Android 项目和初始化模型。
设置您的 API 密钥
如需使用 Gemini API,您需要 API 密钥。如果您还没有账号, 在 Google AI Studio 中创建密钥。
保护您的 API 密钥
强烈建议您不要将 API 密钥签入您的版本
控制系统而应将其存储在 local.properties
文件中
(位于项目的根目录中,但已从版本中排除
控件),然后使用
Android 版 Secrets Gradle 插件
以构建配置变量的形式读取 API 密钥。
Kotlin
// Access your API key as a Build Configuration variable
val apiKey = BuildConfig.apiKey
Java
// Access your API key as a Build Configuration variable
String apiKey = BuildConfig.apiKey;
本教程中的所有代码段都采用了这一最佳实践。此外,如果您
想要查看 Secrets Gradle 插件的实现,您可以查看
示例应用
或使用 Android Studio Iguana 的最新预览版
Gemini API 入门版模板
(其中包含 local.properties
文件,以帮助您开始使用)。
将 SDK 依赖项添加到项目中
在您的模块(应用级)Gradle 配置文件(如
<project>/<app-module>/build.gradle.kts
),请添加 适用于 Android 的 Google AI SDK:Kotlin
dependencies { // ... other androidx dependencies // add the dependency for the Google AI client SDK for Android implementation("com.google.ai.client.generativeai:generativeai:0.9.0") }
Java
对于 Java,您需要添加两个额外的库。
dependencies { // ... other androidx dependencies // add the dependency for the Google AI client SDK for Android implementation("com.google.ai.client.generativeai:generativeai:0.9.0") // Required for one-shot operations (to use `ListenableFuture` from Guava Android) implementation("com.google.guava:guava:31.0.1-android") // Required for streaming operations (to use `Publisher` from Reactive Streams) implementation("org.reactivestreams:reactive-streams:1.0.4") }
将您的 Android 项目与 Gradle 文件同步。
初始化生成模型
在进行任何 API 调用之前,您需要初始化生成模型:
Kotlin
val generativeModel = GenerativeModel(
// The Gemini 1.5 models are versatile and work with most use cases
modelName = "gemini-1.5-flash",
// Access your API key as a Build Configuration variable (see "Set up your API key" above)
apiKey = BuildConfig.apiKey
)
Java
对于 Java,您还需要初始化 GenerativeModelFutures
对象。
// Use a model that's applicable for your use case
// The Gemini 1.5 models are versatile and work with most use cases
GenerativeModel gm = new GenerativeModel(/* modelName */ "gemini-1.5-flash",
// Access your API key as a Build Configuration variable (see "Set up your API key" above)
/* apiKey */ BuildConfig.apiKey);
// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(gm);
指定模型时,请注意以下事项:
请使用您的用例专用的模型(例如
gemini-1.5-flash
适用于多模态输入)。在本指南中, 实现列出了每个用例的推荐模型。
实现常见使用场景
现在您的项目已设置完毕,您可以探索如何使用 Gemini API 来 实现不同的应用场景:
根据纯文本输入生成文本
如果输入的提示仅包含文本,请使用 Gemini 1.5 模型或
使用 generateContent
生成文本输出的 Gemini 1.0 Pro 模型:
Kotlin
请注意,generateContent()
是一个挂起函数,必须为
从协程作用域调用。如果您不熟悉协程,请先阅读以下内容:
Android 上的 Kotlin 协程。
val generativeModel = GenerativeModel(
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
modelName = "gemini-1.5-flash",
// Access your API key as a Build Configuration variable (see "Set up your API key" above)
apiKey = BuildConfig.apiKey
)
val prompt = "Write a story about a magic backpack."
val response = generativeModel.generateContent(prompt)
print(response.text)
Java
请注意,generateContent()
会返回 ListenableFuture
。如果
此 API,请参阅有关以下内容的 Android 文档:
使用 ListenableFuture
。
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
GenerativeModel gm = new GenerativeModel(/* modelName */ "gemini-1.5-flash",
// Access your API key as a Build Configuration variable (see "Set up your API key" above)
/* apiKey */ BuildConfig.apiKey);
GenerativeModelFutures model = GenerativeModelFutures.from(gm);
Content content = new Content.Builder()
.addText("Write a story about a magic backpack.")
.build();
Executor executor = // ...
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
@Override
public void onSuccess(GenerateContentResponse result) {
String resultText = result.getText();
System.out.println(resultText);
}
@Override
public void onFailure(Throwable t) {
t.printStackTrace();
}
}, executor);
根据文本和图片输入生成文本(多模态)
Gemini 提供各种可处理多模态输入的模型 (Gemini 1.5 模型),这样你就可以输入文字和图片。请务必 请参阅提示的图片要求。
如果输入的提示同时包含文本和图片,请使用符合以下条件的 Gemini 1.5 模型:
generateContent
,用于生成文本输出:
Kotlin
请注意,generateContent()
是一个挂起函数,必须为
从协程作用域调用。如果您不熟悉协程,请先阅读以下内容:
Android 上的 Kotlin 协程。
val generativeModel = GenerativeModel(
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
modelName = "gemini-1.5-flash",
// Access your API key as a Build Configuration variable (see "Set up your API key" above)
apiKey = BuildConfig.apiKey
)
val image1: Bitmap = // ...
val image2: Bitmap = // ...
val inputContent = content {
image(image1)
image(image2)
text("What's different between these pictures?")
}
val response = generativeModel.generateContent(inputContent)
print(response.text)
Java
请注意,generateContent()
会返回 ListenableFuture
。如果
此 API,请参阅有关以下内容的 Android 文档:
使用 ListenableFuture
。
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
GenerativeModel gm = new GenerativeModel(/* modelName */ "gemini-1.5-flash",
// Access your API key as a Build Configuration variable (see "Set up your API key" above)
/* apiKey */ BuildConfig.apiKey);
GenerativeModelFutures model = GenerativeModelFutures.from(gm);
Bitmap image1 = // ...
Bitmap image2 = // ...
Content content = new Content.Builder()
.addText("What's different between these pictures?")
.addImage(image1)
.addImage(image2)
.build();
Executor executor = // ...
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
@Override
public void onSuccess(GenerateContentResponse result) {
String resultText = result.getText();
System.out.println(resultText);
}
@Override
public void onFailure(Throwable t) {
t.printStackTrace();
}
}, executor);
建立多轮对话(聊天)
借助 Gemini,您可以跨多个回合构建自由形式的对话。通过
SDK 通过管理对话状态来简化流程,
使用 generateContent
,则无需存储对话记录
。
如需构建多轮对话(如聊天),请使用 Gemini 1.5 模型或
Gemini 1.0 Pro 模型,并通过调用 startChat()
来初始化对话。
然后,使用 sendMessage()
发送一条新的用户消息,此消息还将附加
消息和对聊天记录的响应。
与内容关联的 role
有两种可能的选项
对话:
user
:提供提示的角色。该值是sendMessage
次通话。model
:提供响应的角色。此角色可以在以下情况下使用: 使用现有的history
调用startChat()
。
Kotlin
请注意,generateContent()
是一个挂起函数,必须为
从协程作用域调用。如果您不熟悉协程,请先阅读以下内容:
Android 上的 Kotlin 协程。
val generativeModel = GenerativeModel(
// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
modelName = "gemini-1.5-flash",
// Access your API key as a Build Configuration variable (see "Set up your API key" above)
apiKey = BuildConfig.apiKey
)
val chat = generativeModel.startChat(
history = listOf(
content(role = "user") { text("Hello, I have 2 dogs in my house.") },
content(role = "model") { text("Great to meet you. What would you like to know?") }
)
)
chat.sendMessage("How many paws are in my house?")
Java
请注意,generateContent()
会返回 ListenableFuture
。如果
此 API,请参阅有关以下内容的 Android 文档:
使用 ListenableFuture
。
// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
GenerativeModel gm = new GenerativeModel(/* modelName */ "gemini-1.5-flash",
// Access your API key as a Build Configuration variable (see "Set up your API key" above)
/* apiKey */ BuildConfig.apiKey);
GenerativeModelFutures model = GenerativeModelFutures.from(gm);
// (optional) Create previous chat history for context
Content.Builder userContentBuilder = new Content.Builder();
userContentBuilder.setRole("user");
userContentBuilder.addText("Hello, I have 2 dogs in my house.");
Content userContent = userContentBuilder.build();
Content.Builder modelContentBuilder = new Content.Builder();
modelContentBuilder.setRole("model");
modelContentBuilder.addText("Great to meet you. What would you like to know?");
Content modelContent = userContentBuilder.build();
List<Content> history = Arrays.asList(userContent, modelContent);
// Initialize the chat
ChatFutures chat = model.startChat(history);
// Create a new user message
Content.Builder userMessageBuilder = new Content.Builder();
userMessageBuilder.setRole("user");
userMessageBuilder.addText("How many paws are in my house?");
Content userMessage = userMessageBuilder.build();
Executor executor = // ...
// Send the message
ListenableFuture<GenerateContentResponse> response = chat.sendMessage(userMessage);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
@Override
public void onSuccess(GenerateContentResponse result) {
String resultText = result.getText();
System.out.println(resultText);
}
@Override
public void onFailure(Throwable t) {
t.printStackTrace();
}
}, executor);
使用流式传输加快互动速度
默认情况下,模型会在完成整个生成过程后返回响应 过程。您无需等待整个会话,即可实现更快速的互动 结果,而改用流式传输来处理部分结果。
以下示例展示了如何使用
generateContentStream
,用于根据文本和图片输入提示生成文本。
Kotlin
请注意,generateContentStream()
是一个挂起函数,必须为
从协程作用域调用。如果您不熟悉协程,请先阅读以下内容:
Android 上的 Kotlin 协程。
val generativeModel = GenerativeModel(
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
modelName = "gemini-1.5-flash",
// Access your API key as a Build Configuration variable (see "Set up your API key" above)
apiKey = BuildConfig.apiKey
)
val image1: Bitmap = // ...
val image2: Bitmap = // ...
val inputContent = content {
image(image1)
image(image2)
text("What's the difference between these pictures?")
}
var fullResponse = ""
generativeModel.generateContentStream(inputContent).collect { chunk ->
print(chunk.text)
fullResponse += chunk.text
}
Java
此 SDK 中的 Java 流式传输方法会返回 Publisher
类型
来自 Reactive Streams,
库。
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
GenerativeModel gm = new GenerativeModel(/* modelName */ "gemini-1.5-flash",
// Access your API key as a Build Configuration variable (see "Set up your API key" above)
/* apiKey */ BuildConfig.apiKey);
GenerativeModelFutures model = GenerativeModelFutures.from(gm);
Bitmap image1 = // ...
Bitmap image2 = // ...
Content content = new Content.Builder()
.addText("What's different between these pictures?")
.addImage(image1)
.addImage(image2)
.build();
Publisher<GenerateContentResponse> streamingResponse =
model.generateContentStream(content);
StringBuilder outputContent = new StringBuilder();
streamingResponse.subscribe(new Subscriber<GenerateContentResponse>() {
@Override
public void onNext(GenerateContentResponse generateContentResponse) {
String chunk = generateContentResponse.getText();
outputContent.append(chunk);
}
@Override
public void onComplete() {
System.out.println(outputContent);
}
@Override
public void onError(Throwable t) {
t.printStackTrace();
}
@Override
public void onSubscribe(Subscription s) {
s.request(Long.MAX_VALUE);
}
});
对于纯文本输入和聊天用例,您可以使用类似的方法:
Kotlin
请注意,generateContentStream()
是一个挂起函数,必须为
从协程作用域调用。如果您不熟悉协程,请先阅读以下内容:
Android 上的 Kotlin 协程。
// Use streaming with text-only input
generativeModel.generateContentStream(inputContent).collect { chunk ->
print(chunk.text)
}
// Use streaming with multi-turn conversations (like chat)
val chat = generativeModel.startChat()
chat.sendMessageStream(inputContent).collect { chunk ->
print(chunk.text)
}
Java
此 SDK 中的 Java 流式传输方法会返回 Publisher
类型
来自 Reactive Streams,
库。
// Use streaming with text-only input
Publisher<GenerateContentResponse> streamingResponse =
model.generateContentStream(inputContent);
StringBuilder outputContent = new StringBuilder();
streamingResponse.subscribe(new Subscriber<GenerateContentResponse>() {
@Override
public void onNext(GenerateContentResponse generateContentResponse) {
String chunk = generateContentResponse.getText();
outputContent.append(chunk);
}
@Override
public void onComplete() {
System.out.println(outputContent);
}
@Override
public void onSubscribe(Subscription s) {
s.request(Long.MAX_VALUE);
}
// ... other methods omitted for brevity
});
// Use streaming with multi-turn conversations (like chat)
ChatFutures chat = model.startChat(history);
Publisher<GenerateContentResponse> streamingResponse =
chat.sendMessageStream(inputContent);
StringBuilder outputContent = new StringBuilder();
streamingResponse.subscribe(new Subscriber<GenerateContentResponse>() {
@Override
public void onNext(GenerateContentResponse generateContentResponse) {
String chunk = generateContentResponse.getText();
outputContent.append(chunk);
}
@Override
public void onComplete() {
System.out.println(outputContent);
}
@Override
public void onSubscribe(Subscription s) {
s.request(Long.MAX_VALUE);
}
// ... other methods omitted for brevity
});
实现高级用例
本教程上一部分中介绍的常见用例有助于 能够熟练使用 Gemini API。本部分介绍了一些 可能被视为更高级的用例。
调用函数
函数调用可让您更轻松地从 Google Cloud 控制台获取结构化数据输出 生成模型。然后,您可以使用这些输出来调用其他 API 并返回 将相关的响应数据提供给模型。换句话说,函数调用有助于 将生成模型连接到外部系统, 可提供最新、最准确的信息。 如需了解详情,请参阅 函数调用教程。
计算词元数量
在使用长提示时,在发送任何词元之前计算词元数量可能会有帮助
传递给模型。以下示例展示了如何使用 countTokens()
例如:
Kotlin
请注意,countTokens()
是一个挂起函数,必须为
从协程作用域调用。如果您不熟悉协程,请先阅读以下内容:
Android 上的 Kotlin 协程。
// For text-only input
val (totalTokens) = generativeModel.countTokens("Write a story about a magic backpack.")
// For text-and-image input (multi-modal)
val multiModalContent = content {
image(image1)
image(image2)
text("What's the difference between these pictures?")
}
val (totalTokens) = generativeModel.countTokens(multiModalContent)
// For multi-turn conversations (like chat)
val history = chat.history
val messageContent = content { text("This is the message I intend to send")}
val (totalTokens) = generativeModel.countTokens(*history.toTypedArray(), messageContent)
Java
请注意,countTokens()
会返回 ListenableFuture
。如果
此 API,请参阅有关以下内容的 Android 文档:
使用 ListenableFuture
。
Content text = new Content.Builder()
.addText("Write a story about a magic backpack.")
.build();
Executor executor = // ...
// For text-only input
ListenableFuture<CountTokensResponse> countTokensResponse = model.countTokens(text);
Futures.addCallback(countTokensResponse, new FutureCallback<CountTokensResponse>() {
@Override
public void onSuccess(CountTokensResponse result) {
int totalTokens = result.getTotalTokens();
System.out.println("TotalTokens = " + totalTokens);
}
@Override
public void onFailure(Throwable t) {
t.printStackTrace();
}
}, executor);
// For text-and-image input
Bitmap image1 = // ...
Bitmap image2 = // ...
Content multiModalContent = new Content.Builder()
.addImage(image1)
.addImage(image2)
.addText("What's different between these pictures?")
.build();
ListenableFuture<CountTokensResponse> countTokensResponse = model.countTokens(multiModalContent);
// For multi-turn conversations (like chat)
List<Content> history = chat.getChat().getHistory();
Content messageContent = new Content.Builder()
.addText("This is the message I intend to send")
.build();
Collections.addAll(history, messageContent);
ListenableFuture<CountTokensResponse> countTokensResponse = model.countTokens(history.toArray(new Content[0]));
用于控制内容生成的选项
您可以通过配置模型参数和使用 安全设置。
配置模型参数
您发送到模型的每个提示都包含参数值,用于控制 模型生成回答。对于不同的参数值,模型会生成不同的结果。详细了解 模型参数。
Kotlin
val config = generationConfig {
temperature = 0.9f
topK = 16
topP = 0.1f
maxOutputTokens = 200
stopSequences = listOf("red")
}
val generativeModel = GenerativeModel(
// The Gemini 1.5 models are versatile and work with most use cases
modelName = "gemini-1.5-flash",
apiKey = BuildConfig.apiKey,
generationConfig = config
)
Java
GenerationConfig.Builder configBuilder = new GenerationConfig.Builder();
configBuilder.temperature = 0.9f;
configBuilder.topK = 16;
configBuilder.topP = 0.1f;
configBuilder.maxOutputTokens = 200;
configBuilder.stopSequences = Arrays.asList("red");
GenerationConfig generationConfig = configBuilder.build();
// The Gemini 1.5 models are versatile and work with most use cases
GenerativeModel gm = new GenerativeModel(
"gemini-1.5-flash",
BuildConfig.apiKey,
generationConfig
);
GenerativeModelFutures model = GenerativeModelFutures.from(gm);
使用安全设置
你可以使用安全设置来调整收到符合以下要求的回答的可能性 可能会被视为有害的内容。默认情况下,安全设置会屏蔽带有“中等”标记的内容 和/或在所有维度上都属于不安全的内容的高概率。了解 详细了解安全设置。
设置一项安全设置的方法如下:
Kotlin
val generativeModel = GenerativeModel(
// The Gemini 1.5 models are versatile and work with most use cases
modelName = "gemini-1.5-flash",
apiKey = BuildConfig.apiKey,
safetySettings = listOf(
SafetySetting(HarmCategory.HARASSMENT, BlockThreshold.ONLY_HIGH)
)
)
Java
SafetySetting harassmentSafety = new SafetySetting(HarmCategory.HARASSMENT,
BlockThreshold.ONLY_HIGH);
// The Gemini 1.5 models are versatile and work with most use cases
GenerativeModel gm = new GenerativeModel(
"gemini-1.5-flash",
BuildConfig.apiKey,
null, // generation config is optional
Collections.singletonList(harassmentSafety)
);
GenerativeModelFutures model = GenerativeModelFutures.from(gm);
您还可以设定多项安全设置:
Kotlin
val harassmentSafety = SafetySetting(HarmCategory.HARASSMENT, BlockThreshold.ONLY_HIGH)
val hateSpeechSafety = SafetySetting(HarmCategory.HATE_SPEECH, BlockThreshold.MEDIUM_AND_ABOVE)
val generativeModel = GenerativeModel(
// The Gemini 1.5 models are versatile and work with most use cases
modelName = "gemini-1.5-flash",
apiKey = BuildConfig.apiKey,
safetySettings = listOf(harassmentSafety, hateSpeechSafety)
)
Java
SafetySetting harassmentSafety = new SafetySetting(HarmCategory.HARASSMENT,
BlockThreshold.ONLY_HIGH);
SafetySetting hateSpeechSafety = new SafetySetting(HarmCategory.HATE_SPEECH,
BlockThreshold.MEDIUM_AND_ABOVE);
// The Gemini 1.5 models are versatile and work with most use cases
GenerativeModel gm = new GenerativeModel(
"gemini-1.5-flash",
BuildConfig.apiKey,
null, // generation config is optional
Arrays.asList(harassmentSafety, hateSpeechSafety)
);
GenerativeModelFutures model = GenerativeModelFutures.from(gm);
后续步骤
提示设计是创建提示以从语言模型引出所需回复的过程。撰写结构合理的提示是 是确保语言模型做出准确、高质量响应的一部分。 了解提示撰写的最佳做法。
Gemini 提供多种模型变体,以满足不同使用情形的需求 例如输入类型和复杂性、聊天或其他 对话框语言任务和大小限制。 不妨了解可用的 Gemini 模型。
通过本教程中介绍的适用于 Android 的客户端 SDK,您可以访问 在 Google 的服务器上运行的 Gemini Pro 模型。适用于涉及 处理敏感数据、提高离线可用性,或节省 使用常用用户流时,可以考虑访问 Gemini Nano 该类型在设备上运行。有关详情,请参阅 Android(设备端)教程。