بدء استخدام Prompt API

توضّح هذه الصفحة كيفية إجراء ما يلي:

  • ضبط مشروعك لاستخدام Prompt API
  • تقديم إدخال نصّي فقط وتلقّي ردّ
  • تقديم إدخال صورة مع إدخال نصّي ذي صلة وتلقّي ردّ

لمزيد من التفاصيل حول Prompt API، يُرجى الاطّلاع على المستندات المرجعية للغة Kotlin ‏ (com.google.mlkit.genai.prompt) ولغة Java ‏ (com.google.mlkit.genai.prompt.java و com.google.mlkit.genai.prompt).

ضبط المشروع

أضِف حزمة تعلّم الآلة Prompt API كاعتمادية في إعداد build.gradle:

implementation("com.google.mlkit:genai-prompt:1.0.0-beta2")

تنفيذ النموذج التوليدي

لتنفيذ الرمز في مشروعك، اتّبِع الخطوات التالية:

  • أنشئ عنصر generativeModel:

    Kotlin

    // Get a GenerativeModel instance
val generativeModel = Generation.getClient()

    جافا

    // Get a GenerativeModel instance
GenerativeModelFutures generativeModelFutures = GenerativeModelFutures
    .from(Generation.INSTANCE.getClient());

  • تحقَّق مما إذا كان Gemini Nano AVAILABLE, DOWNLOADABLE أو UNAVAILABLE. بعد ذلك، نزِّل الميزة إذا كانت قابلة للتنزيل:

    Kotlin

    val status = generativeModel.checkStatus()
when (status) {
    FeatureStatus.UNAVAILABLE -> {
        // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
    }

    FeatureStatus.DOWNLOADABLE -> {
        // Gemini Nano can be downloaded on this device, but is not currently downloaded
        generativeModel.download().collect { status ->
            when (status) {
                is DownloadStatus.DownloadStarted ->
                    Log.d(TAG, "starting download for Gemini Nano")

                is DownloadStatus.DownloadProgress ->
                    Log.d(TAG, "Nano ${status.totalBytesDownloaded} bytes downloaded")

                DownloadStatus.DownloadCompleted -> {
                    Log.d(TAG, "Gemini Nano download complete")
                    modelDownloaded = true
                }

                is DownloadStatus.DownloadFailed -> {
                    Log.e(TAG, "Nano download failed ${status.e.message}")
                }
            }
        }
    }

    FeatureStatus.DOWNLOADING -> {
        // Gemini Nano currently being downloaded
    }

    FeatureStatus.AVAILABLE -> {
        // Gemini Nano currently downloaded and available to use on this device
    }
}

    جافا

    ListenableFuture<Integer> status = generativeModelFutures.checkStatus();
Futures.addCallback(generativeModelFutures.checkStatus(), new FutureCallback<>() {
    @Override
    public void onSuccess(Integer featureStatus) {
        switch (featureStatus) {
            case FeatureStatus.AVAILABLE - > {
                // Gemini Nano currently downloaded and available to use on this device
            }
            case FeatureStatus.UNAVAILABLE - > {
                // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
            }
            case FeatureStatus.DOWNLOADING - > {
                // Gemini Nano currently being downloaded
            }
            case FeatureStatus.DOWNLOADABLE - > {
                generativeModelFutures.download(new DownloadCallback() {
                    @Override
                    public void onDownloadStarted(long l) {
                        Log.d(TAG, "starting download for Gemini Nano");
                    }
                    @Override
                    public void onDownloadProgress(long l) {
                        Log.d(TAG, "Nano " + l + " bytes downloaded");
                    }
                    @Override
                    public void onDownloadCompleted() {
                        Log.d(TAG, "Gemini Nano download complete");
                    }
                    @Override
                    public void onDownloadFailed(@NonNull GenAiException e) {
                        Log.e(TAG, "Nano download failed: " + e.getMessage());
                    }
                });
            }
        }
    }
    @Override
    public void onFailure(@NonNull Throwable t) {
        // Failed to check status
    }
}, ContextCompat.getMainExecutor(context));

تقديم إدخال نصّي فقط

Kotlin

val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog.")

جافا

GenerateContentResponse response = generativeModelFutures.generateContent(
  new GenerateContentRequest.Builder(
    new TextPart("Write a 3 sentence story about a magical dog."))
  .build())
  .get();

بدلاً من ذلك، أضِف مَعلمات اختيارية:

Kotlin

val response = generativeModel.generateContent(
    generateContentRequest(
        TextPart("Write a 3 sentence story about a magical dog."),
    ) {
        // Optional parameters
        temperature = 0.2f
        topK = 10
        candidateCount = 3
    },
)

جافا

GenerateContentRequest.Builder requestBuilder =
        new GenerateContentRequest.Builder(
                new TextPart("Write a 3 sentence story about a magical dog."));
requestBuilder.setTemperature(.2f);
requestBuilder.setTopK(10);
requestBuilder.setCandidateCount(3);

GenerateContentResponse response =
        generativeModelFutures.generateContent(requestBuilder.build()).get();

لمزيد من المعلومات حول المَعلمات الاختيارية، يُرجى الاطّلاع على الإعدادات الاختيارية.

تقديم إدخال متعدّد الوسائط (صورة ونص)

يمكنك تجميع صورة وإدخال نصّي معًا في الدالة generateContentRequest()، مع أن يكون النصّ المطلوب سؤالاً أو أمرًا مرتبطًا بالصورة:

Kotlin

val response = generativeModel.generateContent(
    generateContentRequest(ImagePart(bitmap), TextPart(textPrompt)) {
        // optional parameters
        ...
    },
)

جافا

GenerateContentResponse response = generativeModelFutures.generateContent(
    new GenerateContentRequest.Builder(
        new ImagePart(bitmap),
        new TextPart("textPrompt"))
    // optional parameters
    .build())
.get();

معالجة نتيجة الاستنتاج

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

    • يستخدِم هذا الرمز الاستنتاج غير المتواصل، الذي يسترجِع النتيجة الكاملة من نموذج الذكاء الاصطناعي قبل عرض النتيجة:

    Kotlin

    // Call the AI model to generate content and store the complete
// in a new variable named 'response' once it's finished
val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog")

    جافا

    GenerateContentResponse response = generativeModelFutures.generateContent(
        new GenerateContentRequest.Builder(
                new TextPart("Write a 3 sentence story about a magical dog."))
                .build())
        .get();

    • توضّح المقتطفات التالية أمثلة على استخدام الاستنتاج المتواصل، الذي يسترجِع النتيجة على شكل أجزاء أثناء إنشائها:

    Kotlin

    // Streaming inference
var fullResponse = ""
generativeModel.generateContentStream("Write a 3 sentence story about a magical dog").collect { chunk ->
    val newChunkReceived = chunk.candidates[0].text
    print(newChunkReceived)
    fullResponse += newChunkReceived
}

    جافا

    // Streaming inference
StringBuilder fullResponse = new StringBuilder();
generativeModelFutures.generateContent(new GenerateContentRequest.Builder(
    (new TextPart("Write a 3 sentence story about a magical dog"))).build(),
        chunk -> {
            Log.d(TAG, chunk);
            fullResponse.append(chunk);
        });

لمزيد من المعلومات حول الاستنتاج المتواصل وغير المتواصل، يُرجى الاطّلاع على مقالة الاستنتاج المتواصل مقابل الاستنتاج غير المتواصل.

تحسين وقت الاستجابة

لتحسين وقت الاستجابة لطلب الاستنتاج الأول، يمكن لتطبيقك اختياريًا طلب warmup(). يؤدي ذلك إلى تحميل Gemini Nano في الذاكرة وتهيئة مكوّنات وقت التشغيل.

الإعدادات الاختيارية

كجزء من كل GenerateContentRequest، يمكنك ضبط المَعلمات الاختيارية التالية:

  • temperature : تتحكّم في درجة العشوائية في اختيار الرموز المميّزة.
  • seed : تتيح إنشاء نتائج ثابتة ومحدّدة.
  • topK : تتحكّم في العشوائية والتنوّع في النتائج.
  • candidateCount : تطلب عدد الردود الفريدة التي يتم عرضها. يُرجى العِلم أنّ العدد الدقيق للردود قد لا يكون هو نفسه candidateCount لأنّه تتم إزالة الردود المكرّرة تلقائيًا.
  • maxOutputTokens : تحدّد الحدّ الأقصى لعدد الرموز المميّزة التي يمكن إنشاؤها في الردّ.

لمزيد من الإرشادات حول ضبط الإعدادات الاختيارية، يُرجى الاطّلاع على GenerateContentRequest.

الميزات المتوافقة والقيود

  • يجب أن يكون الإدخال أقل من 4000 رمز مميّز (أو ما يقارب 3000 كلمة باللغة الإنجليزية). لمزيد من المعلومات، يُرجى الاطّلاع على المرجع countTokens.
  • يجب تجنُّب حالات الاستخدام التي تتطلّب إخراجًا طويلاً (أكثر من 256 رمزًا مميّزًا).
  • يفرض AICore حصة استنتاج لكلّ تطبيق. لمزيد من المعلومات، يُرجى الاطّلاع على الحصة لكلّ تطبيق.
  • تم التحقّق من اللغتَين التاليتَين في Prompt API:
    • الإنجليزية
    • الكورية

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

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

مثال على رسالة خطأ كيفية التعامل مع الخطأ
تعذّر تنفيذ AICore بسبب نوع الخطأ 4-CONNECTION_ERROR ورمز الخطأ 601-BINDING_FAILURE: تعذّر ربط خدمة AICore. قد يحدث ذلك عند تثبيت التطبيق باستخدام واجهات برمجة التطبيقات GenAI في حزمة تعلّم الآلة مباشرةً بعد إعداد الجهاز أو عند إلغاء تثبيت AICore بعد تثبيت تطبيقك. يجب أن يؤدي تحديث تطبيق AICore ثم إعادة تثبيت تطبيقك إلى حلّ المشكلة.
تعذّر تنفيذ AICore بسبب نوع الخطأ 3-PREPARATION_ERROR ورمز الخطأ 606-FEATURE_NOT_FOUND: الميزة ... غير متاحة. قد يحدث ذلك عندما لم ينتهِ AICore من تنزيل أحدث الإعدادات. عندما يكون الجهاز متصلاً بالإنترنت، يستغرق التحديث عادةً بضع دقائق إلى بضع ساعات. يمكن أن تؤدي إعادة تشغيل الجهاز إلى تسريع عملية التحديث.

ملاحظة: إذا كان برنامج إقلاع الجهاز غير مقفل، فسترى هذا الخطأ أيضًا، لأنّ واجهة برمجة التطبيقات هذه لا تتوافق مع الأجهزة التي تتضمّن برنامج إقلاع غير مقفل.
تعذّر تنفيذ AICore بسبب نوع الخطأ 1-DOWNLOAD_ERROR ورمز الخطأ 0-UNKNOWN: تعذّر تنفيذ الميزة ... بسبب حالة الخطأ 0 والخطأ esz: UNAVAILABLE: تعذّر حلّ المضيف ... يُرجى الحفاظ على الاتصال بالشبكة والانتظار بضع دقائق ثم إعادة المحاولة.