本頁面由 Cloud Translation API 翻譯而成。

開始使用 Prompt API

本頁面說明如何執行下列操作：

設定專案以使用 Prompt API
提供純文字輸入內容並接收回覆
提供圖片輸入內容和相關文字輸入內容，然後接收回覆

如要進一步瞭解 Prompt API，請參閱 Kotlin (com.google.mlkit.genai.prompt) 和 Java (com.google.mlkit.genai.prompt.java、com.google.mlkit.genai.prompt) 的參考說明文件。

[選用] 使用 Gemma 3n 模型測試提示

實作前，建議先在 AI Studio 中使用 Gemma 3n E4B 模型測試提示。Gemma 3n 的輸出內容與 nano-v3 的輸出內容非常相似。

設定專案

在 build.gradle 設定中，將 ML Kit Prompt API 新增為依附元件：

implementation("com.google.mlkit:genai-prompt:1.0.0-alpha1")

實作生成模型

如要在專案中導入程式碼，請按照下列步驟操作：

建立 generativeModel 物件：

Kotlin

// Get a GenerativeModel instance
val generativeModel = Generation.getClient()

Java

// Get a GenerativeModel instance
GenerativeModelFutures generativeModelFutures = GenerativeModelFutures
    .from(Generation.INSTANCE.getClient());

確認 Gemini Nano 是否為 AVAILABLE,、DOWNLOADABLE 或 UNAVAILABLE。然後，如果可下載，請下載該功能：

Kotlin

val status = generativeModel.checkStatus()
when (status) {
    FeatureStatus.UNAVAILABLE -> {
        // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
    }

    FeatureStatus.DOWNLOADABLE -> {
        // Gemini Nano can be downloaded on this device, but is not currently downloaded
        generativeModel.download().collect { status ->
            when (status) {
                is DownloadStatus.DownloadStarted ->
                    Log.d(TAG, "starting download for Gemini Nano")

                is DownloadStatus.DownloadProgress ->
                    Log.d(TAG, "Nano ${status.totalBytesDownloaded} bytes downloaded")

                DownloadStatus.DownloadCompleted -> {
                    Log.d(TAG, "Gemini Nano download complete")
                    modelDownloaded = true
                }

                is DownloadStatus.DownloadFailed -> {
                    Log.e(TAG, "Nano download failed ${status.e.message}")
                }
            }
        }
    }

    FeatureStatus.DOWNLOADING -> {
        // Gemini Nano currently being downloaded
    }

    FeatureStatus.AVAILABLE -> {
        // Gemini Nano currently downloaded and available to use on this device
    }
}

Java

ListenableFuture<Integer> status = generativeModelFutures.checkStatus();
Futures.addCallback(generativeModelFutures.checkStatus(), new FutureCallback<>() {
    @Override
    public void onSuccess(Integer featureStatus) {
        switch (featureStatus) {
            case FeatureStatus.AVAILABLE - > {
                // Gemini Nano currently downloaded and available to use on this device
            }
            case FeatureStatus.UNAVAILABLE - > {
                // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
            }
            case FeatureStatus.DOWNLOADING - > {
                // Gemini Nano currently being downloaded
            }
            case FeatureStatus.DOWNLOADABLE - > {
                generativeModelFutures.download(new DownloadCallback() {
                    @Override
                    public void onDownloadStarted(long l) {
                        Log.d(TAG, "starting download for Gemini Nano");
                    }
                    @Override
                    public void onDownloadProgress(long l) {
                        Log.d(TAG, "Nano " + l + " bytes downloaded");
                    }
                    @Override
                    public void onDownloadCompleted() {
                        Log.d(TAG, "Gemini Nano download complete");
                    }
                    @Override
                    public void onDownloadFailed(@NonNull GenAiException e) {
                        Log.e(TAG, "Nano download failed: " + e.getMessage());
                    }
                });
            }
        }
    }
    @Override
    public void onFailure(@NonNull Throwable t) {
        // Failed to check status
    }
}, ContextCompat.getMainExecutor(context));

提供純文字輸入內容

Kotlin

val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog.")

Java

GenerateContentResponse response = generativeModelFutures.generateContent(
  new GenerateContentRequest.Builder(
    new TextPart("Write a 3 sentence story about a magical dog."))
  .build())
  .get();

或者，也可以新增選用參數：

Kotlin

val response = generativeModel.generateContent(
    generateContentRequest(
        TextPart("Write a 3 sentence story about a magical dog."),
    ) {
        // Optional parameters
        temperature = 0.2f
        topK = 10
        candidateCount = 3
    },
)

Java

GenerateContentRequest.Builder requestBuilder =
        new GenerateContentRequest.Builder(
                new TextPart("Write a 3 sentence story about a magical dog."));
requestBuilder.setTemperature(.2f);
requestBuilder.setTopK(10);
requestBuilder.setCandidateCount(3);

GenerateContentResponse response =
        generativeModelFutures.generateContent(requestBuilder.build()).get();

如要進一步瞭解選用參數，請參閱「選用設定」。

提供多模態 (圖像和文字) 輸入內容

在 generateContentRequest() 函式中，將圖片和文字輸入內容一併封裝，文字提示詞是與圖片相關的問題或指令：

Kotlin

val response = generativeModel.generateContent(
    generateContentRequest(ImagePart(bitmap), TextPart(textPrompt)) {
        // optional parameters
        ...
    },
)

Java

GenerateContentResponse response = generativeModelFutures.generateContent(
    new GenerateContentRequest.Builder(
        new ImagePart(bitmap),
        new TextPart("textPrompt"))
    // optional parameters
    .build())
.get();

處理推論結果

執行推論並擷取結果。您可以選擇等待完整結果，也可以在生成純文字和多模態提示的回覆時，串流傳送回覆。

這會使用非串流推論，從 AI 模型擷取完整結果，然後傳回結果：

Kotlin

// Call the AI model to generate content and store the complete
// in a new variable named 'response' once it's finished
val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog")

Java

GenerateContentResponse response = generativeModelFutures.generateContent(
        new GenerateContentRequest.Builder(
                new TextPart("Write a 3 sentence story about a magical dog."))
                .build())
        .get();

以下程式碼片段是串流推論的範例，可擷取生成結果的區塊：

Kotlin

// Streaming inference
var fullResponse = ""
generativeModel.generateContentStream("Write a 3 sentence story about a magical dog").collect { chunk ->
    val newChunkReceived = chunk.candidates[0].text
    print(newChunkReceived)
    fullResponse += newChunkReceived
}

Java

// Streaming inference
StringBuilder fullResponse = new StringBuilder();
generativeModelFutures.generateContent(new GenerateContentRequest.Builder(
    (new TextPart("Write a 3 sentence story about a magical dog"))).build(),
        chunk -> {
            Log.d(TAG, chunk);
            fullResponse.append(chunk);
        });

如要進一步瞭解串流和非串流推論，請參閱「串流與非串流」。

延遲時間最佳化

為盡量減少第一次推論呼叫的延遲時間，應用程式可以選擇呼叫 warmup()。這會將 Gemini Nano 載入記憶體，並初始化執行階段元件。

選用設定

在每個 GenerateContentRequest 中，您可以設定下列選用參數：

temperature：決定選取詞元時的隨機程度。
seed：啟用這項設定後，系統會產生穩定且確定的結果。
topK：控管結果的隨機性和多樣性。
candidateCount：要求傳回不重複的回覆數量。請注意，由於系統會自動移除重複的回覆，因此回覆的確切數量可能與 candidateCount 不同。
maxOutputTokens：定義回覆中可生成的詞元數量上限。

如需設定選用設定的更多指引，請參閱 GenerateContentRequest。

支援的功能和限制

輸入內容不得超過 4,000 個權杖 (或約 3,000 個英文字)。詳情請參閱 countTokens 參考資料。
請避免需要長輸出內容 (超過 256 個權杖) 的用途。
AICore 會對每個應用程式強制執行推論配額。詳情請參閱「每個應用程式的配額」。
下列語言已通過 Prompt API 驗證：
- 英文
- 韓文

常見設定問題

ML Kit GenAI API 會透過 Android AICore 應用程式存取 Gemini Nano。如果裝置剛完成設定 (包括重設)，或是 AICore 應用程式剛重設 (例如清除資料、解除安裝後重新安裝)，AICore 應用程式可能沒有足夠時間完成初始化 (包括從伺服器下載最新設定)。因此 ML Kit GenAI API 可能無法正常運作。以下是您可能會看到的常見設定錯誤訊息及處理方式：

錯誤訊息範例	如何處理
AICore 發生錯誤，錯誤類型為 4-CONNECTION_ERROR，錯誤代碼為 601-BINDING_FAILURE：AICore 服務繫結失敗。	如果裝置設定完成後，您立即使用 ML Kit GenAI API 安裝應用程式，或是應用程式安裝完成後解除安裝 AICore，就可能發生這種情況。更新 AICore 應用程式，然後重新安裝應用程式，應該就能修正問題。
AICore 失敗，錯誤類型為 3-PREPARATION_ERROR，錯誤代碼為 606-FEATURE_NOT_FOUND：功能「...」無法使用。	如果 AICore 尚未完成下載最新設定，就可能發生這種情況。裝置連上網際網路後，通常會在幾分鐘到幾小時內完成更新。重新啟動裝置可加快更新速度。請注意，如果裝置的系統啟動載入程式處於解鎖狀態，您也會看到這項錯誤訊息，因為這項 API 不支援系統啟動載入程式處於解鎖狀態的裝置。
AICore failed with error type 1-DOWNLOAD_ERROR and error code 0-UNKNOWN: Feature ... failed with failure status 0 and error esz: UNAVAILABLE: Unable to resolve host ...	保持網路連線，稍待幾分鐘後再試一次。

開始使用 Prompt API 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

[選用] 使用 Gemma 3n 模型測試提示

設定專案

實作生成模型

Kotlin

Java

Kotlin

Java

提供純文字輸入內容

Kotlin

Java

Kotlin

Java

提供多模態 (圖像和文字) 輸入內容

Kotlin

Java

處理推論結果

Kotlin

Java

Kotlin

Java

延遲時間最佳化

選用設定

支援的功能和限制

常見設定問題

開始使用 Prompt API