教學課程：開始使用 Gemini API


本教學課程示範如何直接透過 使用 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 金鑰。如果您沒有帳戶 建立金鑰

取得 API 金鑰

確保 API 金鑰安全

強烈建議您「不要」在版本中檢查 API 金鑰 控制系統請改為將其儲存在 local.properties 檔案中 (位於專案的根目錄中，但從版本中排除 控制)，然後使用 Secrets Gradle 外掛程式 Android 版 將 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 Starter 範本 (其中包含 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 模型或 接著，您就能呼叫 startChat() 來初始化 Gemini 1.0 Pro 模型。 接著，使用 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);

使用串流加快互動速度

根據預設，模型會在完成整個生成程序後傳回回應 上傳資料集之後，您可以運用 AutoML 自動完成部分資料準備工作您不必等待整個 並改用串流處理部分結果

以下範例顯示如何利用 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 類型 在回應式訊息串中 資源庫。

// 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 類型 在回應式訊息串中 資源庫。

// 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本節將說明 可能有更進階的用途

函式呼叫

函式呼叫可讓您輕鬆取得結構化資料輸出內容 生成式模型您可以運用這些輸出內容呼叫其他 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 (裝置端) 教學課程。

，瞭解如何調查及移除這項存取權。