تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

واجهة برمجة التطبيقات GenAI Summarization API

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

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

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

توفّر واجهة برمجة التطبيقات GenAI Summarization API الإمكانات التالية:

تلخيص النص، الذي يتم تصنيفه على أنّه مقالة أو محادثة
تلخيص النتائج في نقطة واحدة أو نقطتَين أو ثلاث نقاط

البدء

أضِف واجهة برمجة التطبيقات summarization API من ML Kit كعنصر تابع في build.gradle إعداداتك.

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

بعد ذلك، نفِّذ الرمز في مشروعك:

أنشئ عنصر Summarizer.
نزِّل الميزة إذا كان بإمكانك تنزيلها.
أنشئ طلب تلخيص.
يمكنك إجراء الاستنتاج واسترداد النتيجة.

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 Summarization API استخدام اللغات الإنجليزية واليابانية والكورية، وهي محدّدة في SummarizerOptions.Language.

قد يختلف مدى توفّر إعدادات الميزة المحدّدة (المحدّدة باستخدامSummarizerOptions) حسب إعدادات الجهاز المحدّدة والطُرز التي تم تنزيلها على الجهاز.

إنّ الطريقة الأكثر موثوقية للمطوّرين للتأكّد من أنّ ميزة واجهة برمجة التطبيقات المقصودة متوفرة على جهاز يتضمّن SummarizerOptions المطلوبة هي استدعاء الأسلوب checkFeatureStatus(). تقدّم هذه الطريقة الحالة النهائية لتوفّر الميزة على الجهاز أثناء التشغيل.

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

تعتمد واجهات برمجة تطبيقات الذكاء الاصطناعي التوليدي من 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: تعذّر حلّ مضيف ...	يُرجى البقاء على اتصال بالشبكة والانتظار بضع دقائق ثم إعادة المحاولة.