תחילת השימוש ב-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 של ML Kit כתלות בהגדרות של 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()
  

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

הזנת קלט של טקסט בלבד

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(), כשההנחיה בטקסט היא שאלה או פקודה שקשורה לתמונה. אפשר לאגד עד 10 תמונות באותה בקשה.

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

עיבוד תוצאת ההסקה

• מריצים את ההסקה ומאחזרים את התוצאה. אתם יכולים לבחור אם לחכות לתוצאה המלאה או להזרים את התשובה בזמן שהיא נוצרת, גם בפרומפטים של טקסט בלבד וגם בפרומפטים מולטי-מודאליים.

  • הדוגמה הזו משתמשת בהסקה ללא סטרימינג, שמאחזרת את כל התוצאה ממודל ה-AI לפני שהיא מחזירה את התוצאה:

  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.
• מומלץ להימנע מתרחישים לדוגמה שדורשים פלט ארוך (יותר מ-4,000 טוקנים).
• ‫AICore אוכף מכסת הסקה לכל אפליקציה. מידע נוסף זמין בקטע מכסה לכל אפליקציה.

בעיות נפוצות בהגדרה

ממשקי ה-API של ML Kit GenAI מסתמכים על אפליקציית Android AICore כדי לגשת ל-Gemini Nano. כשמגדירים מכשיר חדש (כולל איפוס) או מאפסים את אפליקציית AICore (למשל, מנקים את הנתונים, מסירים את האפליקציה ומתקינים אותה מחדש), יכול להיות שלאפליקציית AICore לא יהיה מספיק זמן לסיים את תהליך ההפעלה (כולל הורדת ההגדרות העדכניות מהשרת). כתוצאה מכך, יכול להיות שממשקי ה-API של ML Kit GenAI לא יפעלו כמו שצריך. ריכזנו כאן את הודעות השגיאה הנפוצות שמופיעות במהלך ההגדרה, והסברנו איך לטפל בהן: