יצירת פלט מובנה

אם אתם צריכים לנתח תשובות מ-Gemini Nano לפורמטים מסוימים, כמו JSON, לצורך עיבוד נוסף, השתמשו ב-Structured Output API עם גישה ישירה למודל.

באמצעות Structured Output API, אתם מגדירים את מבנה הפלט של היעד באמצעות מחלקות והערות ב-Kotlin. הגישה הישירה למודל מחזירה תשובה בצורת אובייקט Kotlin.

יצירת פלט מובנה שימושית במיוחד למשימות כמו:

  • חילוץ ישויות: חילוץ שדות מובְנים (לדוגמה, שם האירוע, תאריך, מיקום) מטקסט לא מובְנה.
  • סיווג: סיווג של טקסט הקלט לקטגוריות מוגדרות מראש.
  • סדרתיות של נתונים: המרת קלט לא מובנה של משתמשים לפורמט שמתאים לאחסון במסד נתונים או לקריאות ל-API.

דרישות מוקדמות

כדי לוודא שה-Structured Output API זמין במכשיר, משתמשים ב-API של isStructuredOutputFeatureAvailable(). ה-API מחזיר את הערך true אם Structured Output API זמין במכשיר, ואת הערך false אם לא.

suspend fun isStructuredOutputFeatureAvailable(): Boolean

ל-Structured Output API יש גם את הדרישות הבאות:

  • רמת API‏ 26 ומעלה ב-Android‏ (minSdk 26)
  • פלאגין KSP בגרסה 2.3.6 ואילך

מגבלות

ל-Structured Output API יש את המגבלות הבאות:

  • פועל רק ב-Kotlin.
  • יכול להיות ש-ProGuard יפריע לניתוח של המחלקה עם ההערות. אם מופיעות שגיאות בניתוח, מוסיפים את המחלקה עם ההערות לכללי השמירה כדי להחריג אותן מ-ProGuard, לדוגמה:
# Keep classes used by structured output for deserialization for release builds.
-keep class com.google.mlkit.genai.demo.kotlin.Plant { *; }

הגדרת הפרויקט

כדי להתחיל להשתמש ב-Structured Output API:

  1. מוסיפים את התלות com.google.mlkit:genai-prompt בקובץ build.gradle.kts (או build.gradle) ברמת האפליקציה, אם עדיין לא עשיתם את זה.

  2. מוסיפים את הפלאגין של KSP לקובץ build.gradle.kts ברמת הפרויקט. צריך להשתמש בגרסה של פלאגין KSP שתואמת לגרסת Kotlin. אנחנו ממליצים על גרסת KSP‏ 2.3.6 ואילך.

    dependencies {
        ...
        classpath "com.google.devtools.ksp:com.google.devtools.ksp.gradle.plugin:2.3.6"
    }
    
  3. מוסיפים את יחסי התלות של המהדר המובנה לקובץ build.gradle.kts ברמת האפליקציה:

    dependencies {
        ...
        ksp("com.google.mlkit:genai-schema-compiler:1.0.0-alpha1")
    }
    

הגדרת מבנה הפלט

מגדירים את מבנה הנתונים שהמודל אמור להחזיר באמצעות מחלקות נתונים של Kotlin. יש שתי הערות עיקריות להגדרת מבנה הפלט:

  • משתמשים בהערה @Generable כדי להגדיר את המחלקה כיעד לפלט מובנה.
  • משתמשים בהערות @Guide במאפייני הכיתה כדי לספק תיאורים ומגבלות שמנחים את הפלט של המודל.

בדוגמה הבאה מוגדר מבנה לחילוץ מידע על צמחים:

import com.google.mlkit.genai.schema.annotations.Generable
import com.google.mlkit.genai.schema.annotations.Guide

@Generable
data class PlantList(
    @Guide(description = "The list of plants found", minItems = 1, maxItems = 5)
    val plants: List<Plant>
)

@Generable("Information about a plant species")
data class Plant(
    @Guide(description = "The common name of the plant")
    val commonName: String,
    
    @Guide(description = "The full latin scientific name of the plant")
    val scientificName: String,
    
    @Guide(
        description = "The maximum height of the plant in centimeters.",
        minimum = 1.0,
        maximum = 10000.0
    )
    val maxHeightCm: Int,
    
    @Guide(description = "Whether the plant is poisonous or not")
    val isPoisonous: Boolean?,
    
    @Guide(
        description = "The primary continent where this plant is native to",
        enumValues = ["Africa", "Antarctica", "Asia", "Australia", "Europe", "North America", "South America"]
    )
    val nativeContinent: String
)

סוגים ואילוצים נתמכים

אלה הסוגים שנתמכים במחלקה עם הערות @Generable, יחד עם האילוצים המתאימים של @Guide:

סוג תיאור אילוצים נתמכים של @Guide
String לטקסט. description, enumValues
Double / Float למספרים בשיטת נקודה צפה. description,‏ minimum,‏ maximum
Int / Long למספרים שלמים. description,‏ minimum,‏ maximum
Boolean לערכים של נכון/לא נכון. description
List<T> לרשימות של סוגים נתמכים או מחלקות @Generable בתצוגת עץ. description,‏ minItems,‏ maxItems
List<String> לרשימות של ערכי String. ‫description, ‏enumValues, ‏minItems, ‏maxItems
כיתה אחת (@Generable) לאובייקטים מובְנים בתצוגת עץ. description

יצירת תוכן מובנה

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

// 1. Initialize your GenerativeModel as usual
val generativeModel = Generation.getClient()

// 2. Prepare the prompt text
val promptText = "List some common plants found in California."
val baseRequest = GenerateContentRequest.Builder(TextPart(promptText)).build()

// 3. Create the typed request, specifying the target class (e.g., PlantList)
val typedRequest = generateTypedContentRequest(
    generateContentRequest = baseRequest,
    outputClass = PlantList::class
)

// 4. Run the inference
try {
    val typedResponse = generativeModel.generateContent(typedRequest)
    
    // 5. Access the parsed object
    // The response candidates contain the parsed object of type T (PlantList in this case)
    val plantList: PlantList? = typedResponse.candidates.firstOrNull()?.response
    
    if (plantList != null) {
        // Process the structured data
        for (plant in plantList.plants) {
            Log.d("StructuredOutput", "Found plant: ${plant.commonName} (${plant.scientificName})")
        }
    } else {
        Log.e("StructuredOutput", "Failed to parse response into the desired structure.")
        
        // Inspect finish reason for details
        val finishReason = typedResponse.candidates.firstOrNull()?.finishReason
        Log.d("StructuredOutput", "Finish reason: $finishReason")
    }
} catch (e: GenAiException) {
    // Handle API errors
    when (e.errorCode) {
        GenAiException.STRUCTURED_OUTPUT_INVALID_CLASS -> {
            Log.e("StructuredOutput", "The class structure is not supported.")
        }
        GenAiException.STRUCTURED_OUTPUT_INVALID_VALUE -> {
            Log.e("StructuredOutput", "The model generated values that violate the schema constraints.")
        }
        else -> {
            Log.e("StructuredOutput", "API error: ${e.message}")
        }
    }
}

טיפול בסיבות לסיום ובשגיאות

כשמשתמשים ב-Structured Output API, צריך לטפל בחריגות פוטנציאליות שה-API זורק ולבדוק את המאפיין finishReason במועמדים לתגובה אם התגובה המנותחת היא null.

ערכי finishReason

המאפיין finishReason יכול לכלול את אחד מהערכים הבאים:

  • ‫TypedFinishReason.STOP: המודל סיים ליצור את הפלט בהצלחה והפלט תואם לסכימה.
  • ‫TypedFinishReason.MAX_TOKENS: המודל הפסיק כי הוא הגיע למגבלת האסימונים. יכול להיות שהפלט לא יהיה מלא.
  • ‫TypedFinishReason.PARSE_CLASS_ERROR: המודל סיים ליצור את התשובה, אבל אי אפשר היה לנתח את ה-JSON שנוצר למחלקת Kotlin המטורגטת.
  • ‫TypedFinishReason.STRUCTURE_NOT_ANNOTATED: במחלקת היעד או במחלקות המקוננות שלה חסרה ההערה הנדרשת @Generable.
  • ‫TypedFinishReason.STRUCTURE_VALUES_INVALID: הערכים שנוצרו הפרו את האילוצים שהוגדרו בהערות @Guide (לדוגמה, ערך מחוץ לטווח, גודל רשימה מחוץ לגבולות).
  • TypedFinishReason.OTHER: תהליך היצירה הופסק מסיבות אחרות.

חריגים

יכול להיות שה-Structured Output API יחזיר את השגיאה GenAiException עם קודי השגיאה הבאים:

  • ‫GenAiException.STRUCTURED_OUTPUT_INVALID_CLASS (-104): המבנה של המחלקה עם ההערות לא תקין או מכיל סוגים שלא נתמכים. בדרך כלל זו שגיאת הגדרה בזמן הפיתוח. בודקים את ההגדרה של מחלקת הנתונים @Generable כדי לוודא שכל סוגי המאפיינים נתמכים ושאין תלויות מעגליות.
  • ‫GenAiException.STRUCTURED_OUTPUT_INVALID_VALUE ‏(-105): הערכים שהמודל יצר לא תקינים או לא עומדים באימות האילוצים. זו שגיאת זמן ריצה. אם אתם נתקלים בשגיאה הזו לעיתים קרובות, נסו את הפתרונות הבאים:
    • לשפר את ההנחיות כדי להדריך את המודל בצורה קפדנית יותר.
    • להגמיש את המגבלות (כמו מגבלות על המינימום, המקסימום או גודל הרשימה) בהערות @Guide אם הן מגבילות מדי את יכולות המודל.
    • הטמעת אסטרטגיית גיבוי באפליקציה, כמו ניסיון חוזר של הבקשה או הצגת מצב ברירת מחדל.

ספירת טוקנים

כדי לבדוק אם ההנחיה המובנית לא חורגת ממגבלת הטוקנים לקלט, מחשבים את מספר הטוקנים באמצעות השיטה countTokens().

בבקשות לפלט מובנה צריך להנחות את המודל לגבי מבנה הסכימה, ולכן ספירת אסימונים רק בטקסט הגולמי של ההנחיה (באמצעות מכונה של GenerateContentRequest) לא מדויקת. כדי לקבל ספירת אסימונים מדויקת, צריך להעביר את המכונה המלאה של GenerateTypedContentRequest, שכוללת את מחלקת היעד והגדרות הסכימה, ל-method‏ countTokens():

suspend fun <T : Any> countTokens(request: GenerateTypedContentRequest<T>): CountTokensResponse