GenAI Proofreading API

使用 ML Kit 的 GenAI 校對 API，協助使用者檢查短文的文法和拼字。

主要功能

  • 校對透過鍵盤或語音輸入的文字
  • 要求會傳回至少一項建議。如果系統傳回多項建議，結果會依信賴度降序排序。

搜尋結果範例

輸入功率

輸入類型

輸出內容

this is a short msg

鍵盤

這是簡短訊息

專案即將完成，但需要審查

鍵盤

專案即將完成，但需要審查

Please meat me at the bear,

語音

請在酒吧等我。

開始使用

如要開始使用 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 指定) 的可用性可能因特定裝置的設定，以及已下載至裝置的模型而異。

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

常見設定問題

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 ... 保持網路連線，稍待幾分鐘後再試一次。