チュートリアル: Gemini API のスタートガイド


このチュートリアルでは、Android 用 Google AI クライアント SDK を使用して、Android アプリから Gemini API に直接アクセスする方法について説明します。Android アプリで Gemini モデルにアクセスするために REST API やサーバーサイド コード(Python など)を直接操作したくない場合は、このクライアント SDK を使用できます。

このチュートリアルでは、次の方法について学びます。

さらに、このチュートリアルには、高度なユースケース(トークンのカウントなど)と、コンテンツ生成の制御のオプションに関するセクションも含まれています。

デバイス上で Gemini へのアクセスを検討してください

このチュートリアルで説明する Android 用クライアント SDK を使用すると、Google のサーバーで実行される Genmini Pro モデルにアクセスできます。機密データの処理、オフラインでの可用性、または頻繁に使用されるユーザーフローの費用削減を含むユースケースでは、デバイス上で実行される Gemini Nano へのアクセスを検討することをおすすめします。詳細については、Android(オンデバイス)チュートリアルをご覧ください。

前提条件

このチュートリアルは、Android Studio を使用した Android アプリの開発に精通していることを前提としています。

このチュートリアルを完了するには、開発環境と Android アプリが次の要件を満たしていることを確認してください。

  • Android Studio(最新バージョン)
  • Android アプリは API レベル 21 以降を対象にする必要があります。

プロジェクトを設定する

Gemini API を呼び出す前に、Android プロジェクトをセットアップする必要があります。これには、API キーのセットアップ、Android プロジェクトへの SDK 依存関係の追加、モデルの初期化が含まれます。

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 プラグインの実装を確認する場合は、この SDK のサンプルアプリを参照するか、Gemini API Starter テンプレート(使用を開始するための local.properties ファイルが含まれています)を含む Android Studio Iguana の最新プレビューを使用できます。

SDK の依存関係をプロジェクトに追加する

  1. モジュール(アプリレベル)の Gradle 構成ファイル(<project>/<app-module>/build.gradle.kts など)に、Google AI SDK for Android の依存関係を追加します。

    Kotlin

    dependencies {
      // ... other androidx dependencies
    
      // add the dependency for the Google AI client SDK for Android
      implementation("com.google.ai.client.generativeai:generativeai:0.6.0")
    }
    

    Java

    Java の場合は、ライブラリを 2 つ追加する必要があります。

    dependencies {
        // ... other androidx dependencies
    
        // add the dependency for the Google AI client SDK for Android
        implementation("com.google.ai.client.generativeai:generativeai:0.6.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-pro-vision はマルチモーダル入力に使用します)。このガイドでは、各実装の手順に、各ユースケースで推奨されるモデルを示します。

一般的なユースケースの実装

プロジェクトを設定したら、Gemini API を使用してさまざまなユースケースを実装してみましょう。

テキストのみの入力からテキストを生成する

プロンプト入力にテキストのみが含まれる場合は、generateContent を指定して Gemini 1.5 モデルまたは Gemini 1.0 Pro モデルを使用し、テキスト出力を生成します。

Kotlin

generateContent() は suspend 関数であり、コルーチン スコープから呼び出す必要があります。コルーチンに慣れていない場合は、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.0 Pro Vision)が用意されています。プロンプトの画像の要件を確認してください。

プロンプト入力にテキストと画像の両方が含まれている場合は、generateContent を指定して Gemini 1.5 モデルまたは Gemini 1.0 Pro Vision モデルを使用して、テキスト出力を生成します。

Kotlin

generateContent() は suspend 関数であり、コルーチン スコープから呼び出す必要があります。コルーチンに慣れていない場合は、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 モデルまたは Genmini 1.0 Pro モデルを使用し、startChat() を呼び出してチャットを初期化します。次に、sendMessage() を使用して新しいユーザー メッセージを送信します。これにより、メッセージとレスポンスもチャット履歴に追加されます。

会話のコンテンツに関連付けられた role には、次の 2 つのオプションがあります。

  • user: プロンプトを提供するロール。この値は、sendMessage 呼び出しのデフォルトです。

  • model: レスポンスを提供するロール。このロールは、既存の historystartChat() を呼び出すときに使用できます。

Kotlin

generateContent() は suspend 関数であり、コルーチン スコープから呼び出す必要があります。コルーチンに慣れていない場合は、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 userMessage = new Content.Builder()
    .setRole("user")
    .addText("How many paws are in my house?")
    .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() は suspend 関数であり、コルーチン スコープから呼び出す必要があります。コルーチンに慣れていない場合は、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);

final String[] fullResponse = {""};

streamingResponse.subscribe(new Subscriber<GenerateContentResponse>() {
    @Override
    public void onNext(GenerateContentResponse generateContentResponse) {
        String chunk = generateContentResponse.getText();
        fullResponse[0] += chunk;
    }

    @Override
    public void onComplete() {
        System.out.println(fullResponse[0]);
    }

    @Override
    public void onError(Throwable t) {
        t.printStackTrace();
    }

    @Override
    public void onSubscribe(Subscription s) { }
});

テキストのみの入力とチャットのユースケースにも、同様のアプローチを使用できます。

Kotlin

generateContentStream() は suspend 関数であり、コルーチン スコープから呼び出す必要があります。コルーチンに慣れていない場合は、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);

final String[] fullResponse = {""};

streamingResponse.subscribe(new Subscriber<GenerateContentResponse>() {
    @Override
    public void onNext(GenerateContentResponse generateContentResponse) {
        String chunk = generateContentResponse.getText();
        fullResponse[0] += chunk;
    }

    @Override
    public void onComplete() {
        System.out.println(fullResponse[0]);
    }

    // ... other methods omitted for brevity
});
// Use streaming with multi-turn conversations (like chat)
ChatFutures chat = model.startChat(history);

Publisher<GenerateContentResponse> streamingResponse =
    chat.sendMessageStream(inputContent);

final String[] fullResponse = {""};

streamingResponse.subscribe(new Subscriber<GenerateContentResponse>() {
    @Override
    public void onNext(GenerateContentResponse generateContentResponse) {
        String chunk = generateContentResponse.getText();
        fullResponse[0] += chunk;
    }

    @Override
    public void onComplete() {
        System.out.println(fullResponse[0]);
    }

    // ... other methods omitted for brevity
});

高度なユースケースの実装

このチュートリアルの前のセクションで説明した一般的なユースケースを習得することで、Gemini API を使いやすくなります。このセクションでは、より高度とみなされるユースケースについて説明します。

関数呼び出し

関数呼び出しを使用すると、生成モデルから構造化データ出力を簡単に取得できます。これらの出力を使用して他の API を呼び出し、関連するレスポンス データをモデルに返すことができます。つまり、関数呼び出しを使用すると、生成モデルを外部システムに接続できるため、生成されるコンテンツに最新かつ正確な情報が含まれるようになります。詳細については、関数呼び出しのチュートリアルをご覧ください。

トークンをカウントする

長いプロンプトを使用する場合は、コンテンツをモデルに送信する前にトークンをカウントすると便利な場合があります。次の例は、さまざまなユースケースで countTokens() を使用する方法を示しています。

Kotlin

countTokens() は suspend 関数であり、コルーチン スコープから呼び出す必要があります。コルーチンに慣れていない場合は、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);

安全性設定を使用する

安全性設定を使用して、有害とみなされる可能性のあるレスポンスを受け取る可能性を調整できます。デフォルトでは、安全性設定により、すべての次元において安全でないコンテンツである可能性が高いコンテンツが中程度または高い確率でブロックされます。詳しくは、安全性設定をご覧ください。

安全性に関する設定を 1 つ設定する方法は次のとおりです。

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 モデルをご確認ください。

  • Gemini には、レート制限の引き上げをリクエストするオプションが用意されています。Genmini Pro モデルのレート制限は 60 リクエスト/分(RPM)です。

  • このチュートリアルで説明する Android 用クライアント SDK を使用すると、Google のサーバーで実行される Genmini Pro モデルにアクセスできます。機密データの処理、オフラインでの可用性、または頻繁に使用されるユーザーフローの費用削減を含むユースケースでは、デバイス上で実行される Gemini Nano へのアクセスを検討することをおすすめします。詳細については、Android(オンデバイス)チュートリアルをご覧ください。