教程: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(设备端)教程