GenAI Summarization API

這個 API 目前仍在測試階段，不適用任何服務水準協議或廢止政策。這個 API 可能會變更，導致回溯相容性中斷。

您可以使用 ML Kit 的 GenAI 摘要 API，自動產生文章和對話的摘要，並以項目符號清單的形式呈現。這有助於使用者瞭解大量文字。

摘要功能可透過裝置端生成式 AI 技術發揮效益，因為這項技術可解決資料隱私和成本效率方面的疑慮。應用程式經常會處理個人聊天、電子郵件、記事和提醒事項等機密資訊，因此在裝置上處理這些資訊，對於使用者隱私權而言十分重要。此外，摘要作業 (尤其是含有長篇幅內容或大量項目的摘要作業) 可能需要大量的處理效能。在裝置上處理這類內容，可減少伺服器負載並降低放送費用，同時保護使用者資料的隱私權。

主要功能

GenAI 摘要 API 涵蓋下列功能：

• 摘要文字，分類為文章或對話。
• 以一、二或三個項目符號輸出摘要。

開始使用

注意： 此 API 需要 Android API 級別 26 以上。

在 build.gradle 設定中新增 ML Kit 摘要 API 做為依附元件。

implementation("com.google.mlkit:genai-summarization:1.0.0-beta1")

接著，請在專案中實作程式碼：

1. 建立 Summarizer 物件。
2. 下載功能 (如果可下載的話)。
3. 建立摘要要求。
4. 執行推論並擷取結果。

Kotlin

val articleToSummarize = "Announcing a set of on-device GenAI APIs..."

// Define task with required input type, output type, and language
val summarizerOptions = SummarizerOptions.builder(context)
    .setInputType(InputType.ARTICLE)
    .setOutputType(OutputType.ONE_BULLET)
    .setLanguage(Language.ENGLISH)
    .build()
val summarizer = Summarization.getClient(summarizerOptions)

suspend fun prepareAndStartSummarization() {
    // Check feature availability. Status will be one of the following:
    // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
    val featureStatus = summarizer.checkFeatureStatus().await()

    if (featureStatus == FeatureStatus.DOWNLOADABLE) {
        // Download feature if necessary. If downloadFeature is not called,
        // the first inference request will also trigger the feature to be
        // downloaded if it's not already downloaded.
        summarizer.downloadFeature(object : DownloadCallback {
            override fun onDownloadStarted(bytesToDownload: Long) { }

            override fun onDownloadFailed(e: GenAiException) { }

            override fun onDownloadProgress(totalBytesDownloaded: Long) {}

            override fun onDownloadCompleted() {
                startSummarizationRequest(articleToSummarize, summarizer)
            }
        })
    } else if (featureStatus == FeatureStatus.DOWNLOADING) {
        // Inference request will automatically run once feature is
        // downloaded. If Gemini Nano is already downloaded on the device,
        // the feature-specific LoRA adapter model will be downloaded
        // quickly. However, if Gemini Nano is not already downloaded, the
        // download process may take longer.
        startSummarizationRequest(articleToSummarize, summarizer)
    } else if (featureStatus == FeatureStatus.AVAILABLE) {
        startSummarizationRequest(articleToSummarize, summarizer)
    }
}

fun startSummarizationRequest(text: String, summarizer: Summarizer) {
    // Create task request
    val summarizationRequest = SummarizationRequest.builder(text).build()

    // Start summarization request with streaming response
    summarizer.runInference(summarizationRequest) { newText ->
        // Show new text in UI
    }

    // You can also get a non-streaming response from the request
    // val summarizationResult = summarizer.runInference(
    //     summarizationRequest).get().summary
}

// Be sure to release the resource when no longer needed
// For example, on viewModel.onCleared() or activity.onDestroy()
summarizer.close()

Java

String articleToSummarize = "Announcing: a set of on-device GenAI AI APIs.";

// Define task with required input type, output type, and language
SummarizerOptions summarizerOptions = 
    SummarizerOptions.builder(context)
        .setInputType(SummarizerOptions.InputType.ARTICLE)
        .setOutputType(SummarizerOptions.OutputType.ONE_BULLET)
        .setLanguage(SummarizerOptions.Language.ENGLISH)
        .build();
Summarizer summarizer = Summarization.getClient(summarizerOptions);

void prepareAndStartSummarization()
        throws ExecutionException, InterruptedException {
    // Check feature availability. Status will be one of the following:
    // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
    try {
        int featureStatus = summarizer.checkFeatureStatus().get();
        if (featureStatus == FeatureStatus.DOWNLOADABLE) {
            // Download feature if necessary.
            // If downloadFeature is not called, the first inference request
            // will also trigger the feature to be downloaded if it's not
            // already downloaded.
            summarizer.downloadFeature(new DownloadCallback() {
                @Override
                public void onDownloadCompleted() {
                    startSummarizationRequest(articleToSummarize, summarizer);
                }

                @Override
                public void onDownloadFailed(GenAiException e) { /* handle error */ }

                @Override
                public void onDownloadProgress(long totalBytesDownloaded) {}

                @Override
                public void onDownloadStarted(long bytesDownloaded) {}
            });
        } else if (featureStatus == FeatureStatus.DOWNLOADING) {
            // Inference request will automatically run once feature is
            // downloaded. If Gemini Nano is already downloaded on the
            // device, the feature-specific LoRA adapter model will be
            // downloaded quickly. However, if Gemini Nano is not already
            // downloaded, the download process may take longer.
            startSummarizationRequest(articleToSummarize, summarizer);
        } else if (featureStatus == FeatureStatus.AVAILABLE) {
            startSummarizationRequest(articleToSummarize, summarizer);
        }
    } catch (ExecutionException | InterruptedException e) {
        e.printStackTrace();
    }
}

void startSummarizationRequest(String text, Summarizer summarizer) {
    // Create task request
    SummarizationRequest summarizationRequest =
        SummarizationRequest.builder(text).build();

    // Start summarization request with streaming response
    summarizer.runInference(summarizationRequest, newText -> {
        // Show new text in UI
    });

    // You can also get a non-streaming response from the request
    // ListenableFuture<SummarizationResult> summarizationResult
    //         = summarizer.runInference(summarizationRequest);
    // String summary = summarizationResult.get().getSummary();
}

// Be sure to release the resource when no longer needed
// For example, on viewModel.onCleared() or activity.onDestroy()
summarizer.close();

模型如何處理不同的輸入類型

當文字輸入內容指定為 InputType.CONVERSATION 時，模型會預期輸入內容採用下列格式：

<name>: <message>
<name2>: <message2>
<name>: <message3>
<name3>: <message4>

這有助於模型進一步瞭解對話和互動，進而產生更準確的摘要。

支援的功能和限制

輸入內容的符號數不得超過 4,000 個 (或約 3,000 個英文單字)。如果輸入內容超過 4000 個符記，請考慮下列選項：

• 優先摘要前 4000 個符記。測試結果顯示，這項做法通常可為較長的輸入內容產生良好結果。建議您呼叫 setLongInputAutoTruncationEnabled 來啟用自動截斷功能，這樣系統就會自動截斷多餘的輸入內容。
• 將輸入內容區隔為 4000 個符記的群組，然後個別匯總。
• 請考慮採用更適合大量輸入內容的雲端解決方案。

對於 InputType.ARTICLE，輸入內容也必須超過 400 個半形字元，且文章至少要有 300 個字元，模型才能發揮最佳效能。

GenAI 摘要 API 支援英文、日文和韓文，並在 SummarizerOptions.Language 中定義。

特定功能設定 (由 SummarizerOptions 指定) 是否可用，可能會因特定裝置的設定和已下載至裝置的型號而異。

開發人員如要確保裝置支援指定 API 功能，並提供所要求的 SummarizerOptions，最可靠的方法就是呼叫 checkFeatureStatus() 方法。這個方法會在執行階段提供裝置上功能可用性的確切狀態。

注意： 不同裝置類型的硬體可能有所差異，因此 Gemini Nano 基本模型版本也會有所不同，進而影響 ML Kit GenAI API 的輸出結果。我們會套用 LoRA 轉接器來減輕差異。

常見的設定問題

注意： 裝置的解鎖式引導程序不支援此 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 失敗，錯誤類型為 1-DOWNLOAD_ERROR，錯誤代碼為 0-UNKNOWN：功能 ... 失敗，失敗狀態為 0，錯誤 esz：UNAVAILABLE：無法解析主機 ...	保持網路連線，稍待幾分鐘後再重試。

注意： 雖然各種重設作業對開發人員來說很常見，但對使用者來說則較為罕見。此外，所有設定失敗的情況都會由 checkFeatureStatus() API 偵測到。請務必先呼叫 checkFeatureStatus()，再顯示任何相關 UI，這樣應用程式使用者在任何情況下都不會看到這些錯誤。