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

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

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

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

ضبط إعدادات المشروع

أضِف ML Kit Prompt API كعنصر تابع في إعدادات build.gradle:

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

إذا كنت بحاجة إلى أن تكون الردود بتنسيق معيّن باستخدام 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));
  
  

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

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();

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

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()، مع العلم أنّ الطلب النصي يجب أن يكون سؤالاً أو أمرًا ذا صلة بالصورة. يمكنك تجميع صور ونصوص متعددة معًا في الطلب نفسه.

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.

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

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

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

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