GenAI Proofreading API

이 API는 베타 버전으로 제공되며 SLA 또는 지원 중단 정책이 적용되지 않습니다. 이 API는 이전 버전과의 호환성을 중단하는 방식으로 변경될 수 있습니다.

ML Kit의 GenAI Proofreading API를 사용하면 사용자가 짧은 텍스트의 문법과 맞춤법을 확인하도록 지원할 수 있습니다.

주요 기능

• 키보드 또는 음성을 통해 입력된 텍스트의 교정
• 요청 시 하나 이상의 추천이 반환됩니다. 추천이 여러 개 반환되면 결과가 신뢰도에 따라 내림차순으로 정렬됩니다.

결과 예시

입력	입력 유형	출력
this is a short msg	키보드	짧은 메시지입니다.
프로젝트가 거의 완료되었지만 검토가 필요합니다.	키보드	프로젝트가 거의 완료되었지만 검토가 필요함
곰 앞에서 만나요.	음성	바에서 만나요.

시작하기

참고: 이 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()

자바

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가 있는 기기에서 의도한 API 기능이 지원되는지 확인하는 가장 안정적인 방법은 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: Feature ... is not available 오류로 실패했습니다.	이는 AICore가 최신 구성 다운로드를 완료하지 않은 경우 발생할 수 있습니다. 네트워크 연결을 유지하고 몇 분에서 몇 시간 정도 기다립니다. 기기의 부트로더가 잠금 해제된 경우에도 이 오류가 표시됩니다. 이 API는 부트로더가 잠금 해제된 기기를 지원하지 않습니다.
AICore가 오류 유형 1-DOWNLOAD_ERROR 및 오류 코드 0-UNKNOWN으로 실패했습니다. 기능 ... 실패 상태 0 및 오류 esz: UNAVAILABLE: 호스트를 확인할 수 없음 ...	네트워크 연결을 유지하고 몇 분 정도 기다린 후 다시 시도합니다.

참고: 다양한 재설정은 개발자에게는 일반적이지만 사용자에게는 훨씬 드뭅니다. 또한 이러한 모든 설정 실패 사례는 checkFeatureStatus() API에서 포착할 수 있습니다. 관련 UI를 표시하기 전에 먼저 checkFeatureStatus()를 호출하여 앱 사용자가 어떤 경우에도 이러한 오류를 보지 않도록 하세요.