教程：Gemini API 使用入门

<ph type="x-smartling-placeholder"></ph>


本教程演示了如何直接从 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 密钥

强烈建议您不要将 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 依赖项添加到项目中

  1. 在您的模块（应用级）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")
}

  2. 将您的 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（设备端）教程。

。