GenAI Proofreading API

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

您可以使用 ML Kit 的 GenAI Proofreading API，協助使用者檢查短文本中的文法和拼字。

主要功能

• 校正透過鍵盤或語音輸入的文字
• 要求會傳回至少一個建議。如果系統傳回多項建議，結果會依信心程度由高至低排序。

搜尋結果範例

輸入功率	輸入類型	輸出內容
這是簡短訊息	鍵盤	這是一則簡短訊息
專案已接近完成，但仍需審查	鍵盤	專案已完成，但需要審查
請在熊旁邊等我，	語音	請到酒吧與我會面。

開始使用

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

如要開始使用 GenAI Proofreading API，請將這個依附元件新增至專案的建構檔案。

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

接著，設定並取得具有特定語言和輸入類型設定的 Proofreader 用戶端。檢查並確認裝置上是否有必要的模型功能 (如有需要，請觸發下載作業)。在 ProofreadingRequest 中提交要分析的文字，執行校對推論，最後處理返回的建議，以便修正文字。

Kotlin

val textToProofread = "The praject is compleet but needs too be reviewd"

// Define task with required input and output format
val options = ProofreaderOptions.builder(context)
    // InputType can be KEYBOARD or VOICE. VOICE indicates that
    // the user generated text based on audio input.
    .setInputType(ProofreaderOptions.InputType.KEYBOARD)
    // Refer to ProofreaderOptions.Language for available
    // languages
    .setLanguage(ProofreaderOptions.Language.ENGLISH)
    .build()
val proofreader = Proofreading.getClient(options)

suspend fun prepareAndStartProofread() {
    // Check feature availability, status will be one of the
    // following: UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
    val featureStatus = proofreader.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.
        proofreader.downloadFeature(object : DownloadCallback {
            override fun onDownloadStarted(bytesToDownload: Long) { }

            override fun onDownloadFailed(e: GenAiException) { }

            override fun onDownloadProgress(
                totalBytesDownloaded: Long
            ) {}

            override fun onDownloadCompleted() {
                startProofreadingRequest(textToProofread, proofreader)
            }
        })
    } 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
        // very quickly. However, if Gemini Nano is not already
        // downloaded, the download process may take longer.
        startProofreadingRequest(textToProofread, proofreader)
    } else if (featureStatus == FeatureStatus.AVAILABLE) {
        startProofreadingRequest(textToProofread, proofreader)
    }
}

suspend fun startProofreadingRequest(
    text: String, proofreader: Proofreader
) {
    // Create task request
    val proofreadingRequest =
        ProofreadingRequest.builder(text).build()

    // Start proofreading request with non-streaming response
    // More than 1 result may be returned. If multiple suggestions
    // are returned, results will be sorted by descending confidence.
    val proofreadingResults =
        proofreader.runInference(proofreadingRequest).await().results

    // You can also start a streaming request
    // proofreader.runInference(proofreadingRequest) { newText ->
    //     // show new text in UI
    // }
}

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

Java

String textToProofread = "The praject is compleet but needs too be reviewd";

// Define task with required input and output format
ProofreaderOptions proofreaderOptions = 
    ProofreaderOptions
        .builder(context)
        // InputType can be KEYBOARD or VOICE. VOICE indicates that the
        // user generated text based on audio input.
        .setInputType(ProofreaderOptions.InputType.KEYBOARD)
        // Refer to ProofreaderOptions.Language for available languages
        .setLanguage(ProofreaderOptions.Language.ENGLISH)
        .build();
Proofreader proofreader = Proofreading.getClient(proofreaderOptions);

void prepareAndStartProofread(Context context) throws ExecutionException,
        InterruptedException {
    // Check feature availability, status will be one of the following:
    // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
    try {
        int featureStatus = proofreader.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.
            proofreader.downloadFeature(new DownloadCallback() {
                @Override
                public void onDownloadCompleted() {
                    startProofreadingRequest(textToProofread, proofreader);
                }

                @Override
                public void onDownloadFailed(GenAiException e) {
                }

                @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
            // very quickly. However, if Gemini Nano is not already
            // downloaded, the download process may take longer.
            startProofreadingRequest(textToProofread, proofreader);
        } else if (featureStatus == FeatureStatus.AVAILABLE) {
            startProofreadingRequest(textToProofread, proofreader);
        }
    } catch (ExecutionException | InterruptedException e) {
        e.printStackTrace();
    }
}

void startProofreadingRequest(String text, Proofreader proofreader) {
    // Create task request
    ProofreadingRequest proofreadingRequest = ProofreadingRequest
            .builder(text).build();

    try {
        // Start proofreading request with non-streaming response
        // More than 1 result may be returned. If multiple suggestions are
        // returned, results will be sorted by descending confidence.
        proofreader.runInference(proofreadingRequest).get().getResults();

        // You can also start a streaming request
        // proofreader.runInference(proofreadingRequest, newText -> {
        //     // Show new text in UI
        // });
    } catch (ExecutionException | InterruptedException e) {
        e.printStackTrace();
    }
}

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

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

當模型掌握更多關於使用者輸入文字方式 (鍵盤或語音) 的資訊時，就能更準確地預測可能出現的錯誤類型。鍵盤輸入的文字較容易出現鄰近鍵的拼寫錯誤，而語音輸入的文字較容易出現同音字拼寫錯誤。

支援的功能和限制

校對功能支援下列語言：英文、日文、法文、德文、義大利文、西班牙文和韓文，這些語言在 ProofreaderOptions.Language 中定義。輸入內容不得超過 256 個符記。

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

開發人員如要確保裝置支援指定 API 功能，並使用要求的 ProofreaderOptions，最可靠的方法是呼叫 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，這樣應用程式使用者在任何情況下都不會看到這些錯誤。