شروع کار با Prompt API

این صفحه نحوه انجام موارد زیر را شرح می‌دهد:

• پروژه خود را برای استفاده از Prompt API پیکربندی کنید
• فقط ورودی متنی ارائه دهید و پاسخ دریافت کنید
• یک ورودی تصویر به همراه ورودی متن مرتبط ارائه دهید و پاسخ دریافت کنید

برای جزئیات بیشتر در مورد API مربوط به Prompt، به مستندات مرجع برای 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 باشند.

پیکربندی پروژه

توجه: این API به اندروید API سطح ۲۶ یا بالاتر نیاز دارد.

API مربوط به ML Kit Prompt را به عنوان یک وابستگی در پیکربندی build.gradle خود اضافه کنید:

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

پیاده‌سازی مدل مولد

برای پیاده‌سازی کد در پروژه خود، مراحل زیر را دنبال کنید:

• یک شیء generativeModel ایجاد کنید:

  کاتلین

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

  جاوا

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

• بررسی کنید که آیا جمینی نانو AVAILABLE, DOWNLOADABLE یا UNAVAILABLE است. سپس، در صورت قابل دانلود بودن، ویژگی را دانلود کنید:

  کاتلین

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

نتیجه استنتاج فرآیند

• استنتاج را اجرا کنید و نتیجه را بازیابی کنید. می‌توانید انتخاب کنید که منتظر نتیجه کامل باشید یا پاسخ را همزمان با تولید آن، چه برای درخواست‌های فقط متنی و چه برای درخواست‌های چندوجهی، پخش کنید.

  • این از استنتاج غیر جریانی استفاده می‌کند که قبل از بازگرداندن نتیجه، کل نتیجه را از مدل هوش مصنوعی بازیابی می‌کند:

  کاتلین

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

  • قطعه کدهای زیر نمونه‌هایی از استفاده از استنتاج جریانی هستند که نتیجه را به صورت تکه تکه و همزمان با تولید بازیابی می‌کنند:

  کاتلین

  // 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 مراجعه کنید.

ویژگی‌ها و محدودیت‌های پشتیبانی‌شده

• ورودی باید کمتر از ۴۰۰۰ توکن (یا تقریباً ۳۰۰۰ کلمه انگلیسی) باشد. برای اطلاعات بیشتر، به مرجع countTokens مراجعه کنید.
• از مواردی که نیاز به خروجی طولانی (بیش از ۲۵۶ توکن) دارند، باید اجتناب شود.
• AICore سهمیه استنتاج را برای هر برنامه اعمال می‌کند. برای اطلاعات بیشتر، به سهمیه هر برنامه مراجعه کنید.
• زبان‌های زیر برای Prompt API اعتبارسنجی شده‌اند:
  • انگلیسی
  • کره ای

توجه: ما در حال اعتبارسنجی زبان‌های بیشتری هستیم. شما را تشویق می‌کنیم که زبان‌های دیگر را آزمایش کنید تا ببینید آیا استانداردهای کیفی شما را برآورده می‌کنند یا خیر، و نظرات خود را در مورد زبان‌های دیگری که به آنها علاقه دارید با ما در میان بگذارید.

مشکلات رایج در راه‌اندازی

توجه: این API در دستگاه‌هایی با بوت لودر آنلاک شده پشتیبانی نمی‌شود.

رابط‌های برنامه‌نویسی کاربردی ML Kit GenAI برای دسترسی به Gemini Nano به برنامه Android AICore متکی هستند. هنگامی که یک دستگاه تازه راه‌اندازی شده (شامل تنظیم مجدد) یا برنامه AICore تازه تنظیم مجدد شده است (مثلاً پاک کردن داده‌ها، حذف نصب و سپس نصب مجدد)، ممکن است برنامه AICore زمان کافی برای تکمیل مقداردهی اولیه (از جمله دانلود آخرین پیکربندی‌ها از سرور) نداشته باشد. در نتیجه، رابط‌های برنامه‌نویسی کاربردی ML Kit GenAI ممکن است آنطور که انتظار می‌رود عمل نکنند. در اینجا پیام‌های خطای راه‌اندازی رایجی که ممکن است مشاهده کنید و نحوه مدیریت آنها آمده است:

مثال پیام خطا	نحوه رسیدگی
AICore با خطای نوع ۴-CONNECTION_ERROR و کد خطای ۶۰۱-BINDING_FAILURE ناموفق بود: سرویس AICore نتوانست اتصال برقرار کند.	این مشکل می‌تواند زمانی رخ دهد که شما برنامه را با استفاده از APIهای ML Kit GenAI بلافاصله پس از راه‌اندازی دستگاه نصب می‌کنید یا زمانی که AICore پس از نصب برنامه شما حذف نصب می‌شود. به‌روزرسانی برنامه AICore و سپس نصب مجدد برنامه باید این مشکل را برطرف کند.
AICore با خطای نوع ۳-PREPARATION_ERROR و کد خطای ۶۰۶-FEATURE_NOT_FOUND ناموفق بود: ویژگی ... در دسترس نیست.	این اتفاق ممکن است زمانی رخ دهد که AICore دانلود آخرین تنظیمات را تمام نکرده باشد. وقتی دستگاه به اینترنت متصل است، معمولاً چند دقیقه تا چند ساعت طول می‌کشد تا به‌روزرسانی شود. راه‌اندازی مجدد دستگاه می‌تواند سرعت به‌روزرسانی را افزایش دهد. توجه داشته باشید که اگر بوت لودر دستگاه آنلاک شده باشد، این خطا را نیز مشاهده خواهید کرد - این API از دستگاه‌هایی با بوت لودر آنلاک شده پشتیبانی نمی‌کند.
AICore با خطای نوع ۱-DOWNLOAD_ERROR و کد خطا ۰-UNKNOWN شکست خورد: ویژگی ... با وضعیت خرابی ۰ و خطای esz شکست خورد: UNAVAILABLE: قادر به حل مشکل میزبان نیست ...	اتصال شبکه را حفظ کنید، چند دقیقه صبر کنید و دوباره امتحان کنید.

نکته: اگرچه تنظیم مجدد‌های مختلف برای توسعه‌دهندگان رایج است، اما برای کاربران بسیار کمتر اتفاق می‌افتد. همچنین، همه این موارد شکست راه‌اندازی را می‌توان توسط APIهای checkFeatureStatus() یا checkStatus() دریافت کرد. قبل از نمایش هرگونه رابط کاربری مرتبط، حتماً ابتدا checkFeatureStatus() یا checkStatus() را فراخوانی کنید تا کاربران برنامه شما در هیچ موردی این خطاها را نبینند.