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

توضّح هذه الصفحة كيفية تنفيذ ما يلي:

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

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

[اختياري] اختبار الطلب باستخدام نموذج Gemma 3n

قبل التنفيذ، ننصحك باختبار طلبك في AI Studio باستخدام نموذج Gemma 3n E4B. من المتوقّع أن تكون نتائج Gemma 3n مشابهة جدًا لنتائج nano-v3.

إعداد المشروع

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

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

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

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

  • أنشئ عنصر generativeModel:

    Kotlin

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

    Java

    // 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
    }
}

    Java

    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.")

Java

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
    },
)

Java

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
        ...
    },
)

Java

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")

    Java

    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
}

    Java

    // 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.

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

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

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

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

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

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