GenAI Proofreading API

تتوفر واجهة برمجة التطبيقات هذه كإصدار تجريبي، ولا تخضع لأي اتفاقية مستوى خدمة أو سياسة إيقاف نهائي. قد يتم إجراء تغييرات على واجهة برمجة التطبيقات هذه تؤدي إلى إيقاف التوافق مع الإصدارات القديمة.

باستخدام واجهة برمجة التطبيقات GenAI Proofreading API من ML Kit، يمكنك مساعدة المستخدمين في التحقّق من الأخطاء النحوية والنحوية في أجزاء قصيرة من النص.

الإمكانات الرئيسية

• التدقيق في النص الذي تم إدخاله باستخدام لوحة المفاتيح أو الصوت
• ستعرض الطلبات اقتراحًا واحدًا على الأقل. إذا تم عرض عدة اقتراحات، سيتم ترتيب النتائج تنازليًا حسب مستوى الثقة.

أمثلة النتائج

الإدخال	نوع الإدخال	النتيجة
هذه رسالة قصيرة.	لوحة المفاتيح	هذه رسالة قصيرة.
المشروع مكتمل تقريبًا ولكن يجب مراجعته.	لوحة المفاتيح	المشروع على وشك الانتهاء ولكنّه بحاجة إلى مراجعة
يُرجى مقابلتي في مطعم الدب.	الصوت	يُرجى مقابلتي في البار.

البدء

ملاحظة: تتطلّب واجهة برمجة التطبيقات هذه المستوى 26 من واجهة برمجة تطبيقات Android أو مستوى أعلى.

للبدء باستخدام واجهة برمجة التطبيقات 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(). تقدّم هذه الطريقة الحالة النهائية لتوفّر الميزة على الجهاز أثناء التشغيل.

ملاحظة: قد تؤدي الاختلافات في الأجهزة على مستوى أنواع الأجهزة المختلفة إلى اختلافات في إصدارات النموذج الأساسي لجهاز Gemini Nano، وبالتالي في نتائج واجهة برمجة التطبيقات ML Kit GenAI API. يتم تطبيق محوِّلات LoRA للحدّ من الاختلافات.

المشاكل الشائعة في الإعداد

ملاحظة: لا تتوفّر واجهة برمجة التطبيقات هذه على الأجهزة التي تتضمّن مشغِّل تحميل تم فتح قفله.

تعتمد واجهات برمجة تطبيقات الذكاء الاصطناعي التوليدي من ML Kit على تطبيق Android AICore للوصول إلى Gemini Nano. عند الانتهاء من إعداد الجهاز (بما في ذلك إعادة الضبط) أو إعادة ضبط تطبيق AICore (مثل محو البيانات وإلغاء التثبيت ثم إعادة التثبيت)، قد لا يكون لدى تطبيق AICore الوقت الكافي لإنهاء عملية الإعداد (بما في ذلك تنزيل أحدث الإعدادات من الخادم). نتيجةً لذلك، قد لا تعمل واجهات برمجة تطبيقات الذكاء الاصطناعي التوليدي في ML Kit على النحو المتوقّع. في ما يلي رسائل الخطأ الشائعة التي قد تظهر لك أثناء عملية الإعداد وكيفية معالجتها:

مثال على رسالة خطأ	كيفية التعامل مع
تعذّر تشغيل AICore بسبب نوع الخطأ 4-CONNECTION_ERROR ورمز الخطأ 601-BINDING_FAILURE: تعذّر ربط خدمة AICore.	قد يحدث ذلك عند تثبيت التطبيق باستخدام واجهات برمجة التطبيقات ML Kit GenAI API بعد إعداد الجهاز مباشرةً أو عند إلغاء تثبيت AICore بعد تثبيت تطبيقك. من المفترض أن يؤدي تحديث تطبيق AICore ثم إعادة تثبيت تطبيقك إلى حلّ هذه المشكلة.
تعذّر تشغيل AICore بسبب الخطأ من النوع 3-PREPARATION_ERROR ورمز الخطأ 606-FEATURE_NOT_FOUND: الميزة ... غير متاحة.	قد يحدث ذلك عندما لا ينتهي AICore من تنزيل أحدث الإعدادات. يجب البقاء على اتصال بالشبكة والانتظار لبضع دقائق أو بضع ساعات. تجدر الإشارة إلى أنّه في حال فتح قفل أداة تحميل البرامج الثابتة للجهاز، ستظهر لك أيضًا رسالة الخطأ هذه، لأنّ واجهة برمجة التطبيقات هذه لا تتوافق مع الأجهزة التي تم فتح قفل أداة تحميل البرامج الثابتة فيها.
تعذّر تحميل AICore بسبب نوع الخطأ 1-DOWNLOAD_ERROR ورمز الخطأ 0-UNKNOWN: تعذّر تحميل الميزة ... بسبب الحالة 0 وخطأ esz: UNAVAILABLE: تعذّر حلّ مضيف ...	يُرجى البقاء على اتصال بالشبكة والانتظار بضع دقائق ثم إعادة المحاولة.

ملاحظة: على الرغم من أنّ عمليات إعادة الضبط المختلفة شائعة لدى المطوّرين، إلا أنّها أقل تكرارًا لدى المستخدمين. بالإضافة إلى ذلك، يمكن أن ترصد واجهة برمجة التطبيقات checkFeatureStatus() جميع حالات تعذُّر الإعداد هذه. احرص على استدعاء checkFeatureStatus() أولاً قبل عرض أي واجهة مستخدم ذات صلة، حتى لا تظهر هذه الأخطاء لمستخدمي تطبيقك بأي حال من الأحوال.