関数呼び出しのチュートリアル

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

Gemini モデルに関数の説明を提供できます。これらは、アプリの言語で記述する関数です（Google Cloud Functions ではありません）。モデルがクエリの処理に役立つ関数を呼び出して結果を返すよう求める場合があります。

まだご覧になっていない場合は、関数呼び出しの概要で学習するできます。

照明制御用の API の例

基本的な照明制御システムとアプリケーションプログラミングインターフェース（API）を使用していて、ユーザーがシンプルなテキストリクエスト。関数呼び出し機能を使用してライティングを解釈できる API 呼び出しに変換して照明を設定する API 呼び出しに変換し、使用できます。この架空の照明制御システムを使用して、明るさと色温度です parameters:

パラメータ	タイプ	必須 / 省略可	説明
`brightness`	数値	あり	明るさレベル（0～100）。ゼロがオフで、100 が最大の明るさです。
`colorTemperature`	文字列	あり	照明器具の色温度（`daylight`、`cool`、`warm` のいずれか）。

わかりやすくするために、この架空の照明システムにはライトが 1 つしかなく、ユーザーは部屋や場所を指定する必要はありません。照明制御 API に送信して、昼光色温度を使用して照明レベルを 50% に変更する JSON リクエストの例を次に示します。

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

このチュートリアルでは、Gemini API の関数呼び出しを設定して、ユーザーの照明リクエストを解釈し、API 設定にマッピングして明るさと色温度の値に基づいて変化します

始める前に: プロジェクトと API キーを設定する

Gemini API を呼び出す前に、プロジェクトを設定して API キーを構成する必要があります。

開いて、プロジェクトと API キーの設定方法を表示

API キーを取得して保護する

Gemini API を呼び出すには API キーが必要です。キーをまだ作成していない場合は、Google AI Studio でキーを作成します。

API キーを取得する

API キーをバージョン管理システムにチェックインしないことを強くおすすめします。

API キーは、次の場所にある local.properties ファイルに保管する必要があります。ルートディレクトリに配置し、このファイルをバージョン管理から除外します。対象本番環境のデプロイでは、 Android 用 Secrets Gradle プラグイン API キーをビルド構成変数として読み取ることができます。

// Access your API key as a Build Configuration variable
val apiKey = BuildConfig.apiKey

このチュートリアルのすべてのスニペットで、このベストプラクティスが活用されています。また、Secrets Gradle プラグインの実装を確認するには、この SDK のサンプルアプリを確認するか、Gemini API Starter テンプレート（開始に必要な local.properties ファイルを含む）が用意されている Android Studio の最新プレビュー版を使用します。

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

アプリケーション開発環境で、次の操作を行います。

モジュール（アプリケーションレベル）の Gradle 構成ファイルに、次の内容を含めます。 Google AI SDK for Android の依存関係を追加します。

Kotlin

// add to <project>/<app-module>/build.gradle.kts
dependencies {
  // ... other androidx dependencies

  // add the dependency for the Google AI client SDK for Android
  implementation("com.google.ai.client.generativeai:generativeai:0.7.0")
}

Java

// add to <project>/<app-module>/build.gradle
dependencies {
  // ... other androidx dependencies

  // add the dependency for the Google AI client SDK for Android
  implementation("com.google.ai.client.generativeai:generativeai:0.7.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 関数を定義する

API リクエストを行う関数を作成します。この関数を定義する必要があります。コード内で使用できますが、外部からサービスや API を呼び出すことはできます。説明します。Gemini API は、この関数を直接呼び出しません。そのため、この機能をアプリケーションで実行する方法とタイミングを制御できます。できます。このチュートリアルではデモ用に、次のサンプルを処理するモック API 関数を定義します。リクエストされた照明の値を返すだけです。

suspend fun setLightValues(
    brightness: Int,
    colorTemp: String
): JSONObject {
    // This mock API returns the requested lighting values
    return JSONObject().apply {
        put("brightness", brightness)
        put("colorTemperature", colorTemp)
    }
}

関数宣言を作成する

生成モデルに渡す関数宣言を作成します。モデルで使用する関数を宣言する場合は、関数とパラメータの説明にできるだけ多くの詳細を含める必要があります。生成モデルこの情報を基に、どの機能を選択するのか、またどのような機能を指定する必要があります。次のコードは、照明コントロール関数を宣言します。

val lightControlTool = defineFunction(
  name = "setLightValues",
  description = "Set the brightness and color temperature of a room light.",
  Schema.int("brightness", "Light level from 0 to 100. Zero is off and 100" +
    " is full brightness."),
  Schema.str("colorTemperature", "Color temperature of the light fixture" +
    " which can be `daylight`, `cool` or `warm`.")
) { brightness, colorTemp ->
    // Call the function you declared above
    setLightValues(brightness.toInt(), colorTemp)
}

モデルの初期化時に関数を宣言する

モデルで関数呼び出しを使用する場合は、モデルオブジェクトを初期化するときに関数宣言を指定する必要があります。関数を宣言するには、モデルの tools パラメータを設定します。

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",

    // Access your API key as a Build Configuration variable
    apiKey = BuildConfig.apiKey,

    // Specify the function declaration.
    tools = listOf(Tool(listOf(lightControlTool)))
)

関数呼び出しを生成する

関数宣言でモデルを初期化したら、プロンプトを使用して、モデルを定義します。通常、関数呼び出しでは、以前のプロンプトとレスポンスのコンテキストが役立つため、チャットプロンプト（sendMessage()）を使用した関数呼び出しを使用する必要があります。

val chat = generativeModel.startChat()

val prompt = "Dim the lights so the room feels cozy and warm."

// Send the message to the generative model
var response = chat.sendMessage(prompt)

// Check if the model responded with a function call
response.functionCall?.let { functionCall ->
  // Try to retrieve the stored lambda from the model's tools and
  // throw an exception if the returned function was not declared
  val matchedFunction = generativeModel.tools?.flatMap { it.functionDeclarations }
      ?.first { it.name == functionCall.name }
      ?: throw InvalidStateException("Function not found: ${functionCall.name}")

  // Call the lambda retrieved above
  val apiResponse: JSONObject = matchedFunction.execute(functionCall)

  // Send the API response back to the generative model
  // so that it generates a text response that can be displayed to the user
  response = chat.sendMessage(
    content(role = "function") {
        part(FunctionResponsePart(functionCall.name, apiResponse))
    }
  )
}

// Whenever the model responds with text, show it in the UI
response.text?.let { modelResponse ->
    println(modelResponse)
}