Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

開始使用 Prompt API

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

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

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

設定專案

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

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

如要使用 Structured Output API 取得特定格式的回覆，請設定 KSP 並新增其他依附元件。詳情請參閱「生成結構化輸出內容」。

實作生成式模型

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

建立 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() 函式中，將多張圖片和文字輸入內容組合在一起，文字提示詞則是與圖片相關的問題或指令。在同一要求中，最多可組合 10 張圖片。

Kotlin

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

Java

GenerateContentResponse response = generativeModelFutures.generateContent(
    new GenerateContentRequest.Builder(
        new Content.Builder()
            .addPart(new ImagePart(bitmap1))
            .addPart(new ImagePart(bitmap2))
            .addPart(new TextPart("textPrompt"))
            .build())
    // 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 參考資料。
請避免需要長輸出內容 (超過 4,000 個詞元) 的用途。
AICore 會對每個應用程式強制執行推論配額。詳情請參閱「每個應用程式的配額」。

常見設定問題

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 失敗，錯誤類型 1-DOWNLOAD_ERROR，錯誤代碼 0-UNKNOWN：功能 ... 失敗，失敗狀態 0，錯誤 esz：UNAVAILABLE：無法解析主機 ...	請保持網路連線，稍候幾分鐘再重試。

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

設定專案

實作生成式模型

Kotlin

Java

Kotlin

Java

提供純文字輸入

Kotlin

Java

Kotlin

Java

提供多模態 (圖片和文字) 輸入

Kotlin

Java

處理推論結果

Kotlin

Java

Kotlin

Java

延遲時間最佳化

選用設定

支援的功能和限制

常見設定問題

開始使用 Prompt API