با Gemini API خروجی ساختاریافته تولید کنید

Python Node.js Go Dart (Flutter) Android Swift Web REST

Gemini به طور پیش فرض متن بدون ساختار تولید می کند، اما برخی از برنامه ها به متن ساختاریافته نیاز دارند. برای این موارد استفاده، می‌توانید Gemini را محدود کنید تا با JSON، یک قالب داده ساختاریافته مناسب برای پردازش خودکار، پاسخ دهد. همچنین می توانید مدل را محدود کنید تا با یکی از گزینه های مشخص شده در enum پاسخ دهد.

در اینجا چند مورد استفاده وجود دارد که ممکن است به خروجی ساختاریافته از مدل نیاز داشته باشد:

• با بیرون کشیدن اطلاعات شرکت از مقالات روزنامه، پایگاه داده ای از شرکت ها بسازید.
• اطلاعات استاندارد شده را از رزومه خارج کنید.
• مواد تشکیل دهنده را از دستور العمل ها استخراج کنید و پیوندی به یک وب سایت خواربار فروشی برای هر عنصر نمایش دهید.

در درخواست خود، می توانید از Gemini بخواهید خروجی با فرمت JSON تولید کند، اما توجه داشته باشید که این مدل تضمینی برای تولید JSON و چیزی جز JSON ندارد. برای پاسخ قطعی تر، می توانید یک طرح JSON خاص را در یک فیلد responseSchema ارسال کنید تا Gemini همیشه با ساختار مورد انتظار پاسخ دهد. برای کسب اطلاعات بیشتر در مورد کار با طرحواره ها، بیشتر در مورد طرحواره های JSON را ببینید.

این راهنما به شما نشان می دهد که چگونه با استفاده از روش generateContent از طریق SDK انتخابی خود یا با استفاده مستقیم از REST API، JSON تولید کنید. مثال‌ها فقط ورودی متنی را نشان می‌دهند، اگرچه Gemini همچنین می‌تواند پاسخ‌های JSON را به درخواست‌های چندوجهی که شامل تصاویر ، ویدیوها و صدا می‌شود، تولید کند.

قبل از شروع: پروژه و کلید API خود را تنظیم کنید

قبل از فراخوانی Gemini API، باید پروژه خود را راه اندازی کرده و کلید API خود را پیکربندی کنید.

JSON تولید کنید

هنگامی که مدل برای خروجی JSON پیکربندی می شود، به هر درخواستی با خروجی فرمت JSON پاسخ می دهد.

شما می توانید ساختار پاسخ JSON را با ارائه یک طرح واره کنترل کنید. دو روش برای ارائه یک طرحواره به مدل وجود دارد:

• به عنوان متن در اعلان
• به عنوان یک طرح واره ساختاریافته که از طریق پیکربندی مدل ارائه می شود

یک طرحواره را به عنوان متن در اعلان ارائه کنید

مثال زیر از مدل می خواهد دستور العمل های کوکی را در قالب JSON خاص برگرداند.

از آنجایی که مدل مشخصات قالب را از متن در اعلان دریافت می کند، ممکن است در نحوه نمایش مشخصات انعطاف پذیری داشته باشید. هر قالب معقولی برای نمایش طرحواره JSON ممکن است کار کند.

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-flash",
});

const prompt = `List a few popular cookie recipes using this JSON schema:

Recipe = {'recipeName': string}
Return: Array<Recipe>`;

const result = await model.generateContent(prompt);
console.log(result.response.text());
controlled_generation.js

خروجی ممکن است به شکل زیر باشد:

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

یک طرحواره از طریق پیکربندی مدل تهیه کنید

مثال زیر موارد زیر را انجام می دهد:

1. مدلی را که از طریق طرحی برای پاسخگویی با JSON پیکربندی شده است، نمونه سازی می کند.
2. از مدل می خواهد دستور العمل های کوکی را برگرداند.

این روش رسمی تر برای اعلان طرحواره JSON به شما کنترل دقیق تری نسبت به تکیه بر متن در اعلان می دهد.

// Make sure to include these imports:
// import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const schema = {
  description: "List of recipes",
  type: SchemaType.ARRAY,
  items: {
    type: SchemaType.OBJECT,
    properties: {
      recipeName: {
        type: SchemaType.STRING,
        description: "Name of the recipe",
        nullable: false,
      },
    },
    required: ["recipeName"],
  },
};

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-pro",
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: schema,
  },
});

const result = await model.generateContent(
  "List a few popular cookie recipes.",
);
console.log(result.response.text());
controlled_generation.js

خروجی ممکن است به شکل زیر باشد:

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

اطلاعات بیشتر در مورد طرحواره های JSON

وقتی مدل را برای بازگرداندن پاسخ JSON پیکربندی می‌کنید، می‌توانید از یک شی Schema برای تعریف شکل داده‌های JSON استفاده کنید. Schema یک زیرمجموعه انتخابی از شی OpenAPI 3.0 Schema را نشان می دهد.

در اینجا یک نمایش شبه JSON از تمام فیلدهای Schema آمده است:

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

Type طرحواره باید یکی از انواع داده های OpenAPI باشد. فقط یک زیر مجموعه از فیلدها برای هر Type معتبر است. لیست زیر هر Type به فیلدهای معتبر برای آن نوع نگاشت می کند:

• string -> enum, format
• integer -> قالب
• number -> قالب
• boolean
• array -> minItems، maxItems، آیتم ها
• object -> خواص، مورد نیاز، propertyOrdering، nullable

در اینجا چند نمونه طرحواره وجود دارد که ترکیبات نوع و فیلد معتبر را نشان می دهد:

{ "type": "string", "enum": ["a", "b", "c"] }

{ "type": "string", "format": "date-time" }

{ "type": "integer", "format": "int64" }

{ "type": "number", "format": "double" }

{ "type": "boolean" }

{ "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } }

{ "type": "object",
  "properties": {
    "a": { "type": ... },
    "b": { "type": ... },
    "c": { "type": ... }
  },
  "nullable": true,
  "required": ["c"],
  "propertyOrdering": ["c", "b", "a"]
}

برای مستندات کامل فیلدهای Schema همانطور که در Gemini API استفاده می شود، به مرجع Schema مراجعه کنید.

سفارش ملک

هنگامی که با طرحواره های JSON در Gemini API کار می کنید، ترتیب ویژگی ها مهم است. به‌طور پیش‌فرض، API ویژگی‌ها را بر اساس حروف الفبا مرتب می‌کند و ترتیب تعریف ویژگی‌ها را حفظ نمی‌کند (اگرچه Google Gen AI SDKs ممکن است این ترتیب را حفظ کند). اگر در حال ارائه مثال‌هایی برای مدل با طرح‌واره‌ای پیکربندی‌شده هستید، و ترتیب ویژگی‌های نمونه‌ها با ترتیب ویژگی‌های طرح سازگار نیست، خروجی می‌تواند نامشخص یا غیرمنتظره باشد.

برای اطمینان از یک ترتیب ثابت و قابل پیش‌بینی خواص، می‌توانید از فیلد اختیاری propertyOrdering[] استفاده کنید.

"propertyOrdering": ["recipe_name", "ingredients"]

propertyOrdering[] - یک فیلد استاندارد در مشخصات OpenAPI نیست - آرایه ای از رشته ها است که برای تعیین ترتیب خواص در پاسخ استفاده می شود. با مشخص کردن ترتیب ویژگی ها و سپس ارائه مثال هایی با ویژگی ها به همان ترتیب، به طور بالقوه می توانید کیفیت نتایج را بهبود بخشید.