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

بدء استخدام 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-beta4")

إذا كنت بحاجة إلى الحصول على الردود بتنسيق معيّن باستخدام Structured Output API، عليك ضبط KSP وإضافة تبعيات إضافية. لمعرفة التفاصيل، يُرجى الاطّلاع على إنشاء مخرجات منظَّمة.

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

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

أنشِئ عنصر 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()، بحيث يكون الطلب النصي سؤالاً أو أمرًا متعلقًا بالصورة. يمكنك تجميع ما يصل إلى 10 صور في الطلب نفسه.

Kotlin

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

جافا

GenerateContentResponse response = generativeModelFutures.generateContent(
    new GenerateContentRequest.Builder(
        new Content.Builder()
            .addPart(new ImagePart(bitmap1))
            .addPart(new ImagePart(bitmap2))
            .addPart(new TextPart("textPrompt"))
            .build())
    // 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.

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

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

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

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

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

بدء استخدام Prompt API تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

ضبط المشروع

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

Kotlin

جافا

Kotlin

جافا

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

Kotlin

جافا

Kotlin

جافا

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

Kotlin

جافا

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

Kotlin

جافا

Kotlin

جافا

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

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

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

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

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