تولید تصویر بومی با Gemini 2.0 Flash Experimental اکنون در دسترس است! بیشتر بدانید

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

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

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

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

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

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

کلید API خود را دریافت و ایمن کنید

برای فراخوانی Gemini API به یک کلید API نیاز دارید. اگر قبلاً یکی ندارید، یک کلید در Google AI Studio ایجاد کنید.

یک کلید API دریافت کنید

اکیداً توصیه می شود که یک کلید API را در سیستم کنترل نسخه خود بررسی نکنید .

شما باید کلید API خود را در یک فروشگاه محرمانه مانند Google Cloud Secret Manager ذخیره کنید.

این آموزش فرض می کند که شما به کلید API خود به عنوان یک متغیر محیطی دسترسی دارید.

بسته SDK را نصب کنید و کلید API خود را پیکربندی کنید

Python SDK برای Gemini API در بسته google-generativeai موجود است.

وابستگی را با استفاده از pip نصب کنید:
```
pip install -U google-generativeai
```

بسته را وارد کنید و سرویس را با کلید API خود پیکربندی کنید:

import os
import google.generativeai as genai

genai.configure(api_key=os.environ['API_KEY'])

JSON تولید کنید

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

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

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

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

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

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

from google import genai

prompt = """List a few popular cookie recipes in JSON format.

Use this JSON schema:

Recipe = {'recipe_name': str, 'ingredients': list[str]}
Return: list[Recipe]"""

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=prompt,
)

# Use the response as a JSON string.
print(response.text)

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

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 cups chocolate chips"
    ]
  },
  ...
]

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

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

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

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

from google import genai
from pydantic import BaseModel


class Recipe(BaseModel):
  recipe_name: str
  ingredients: list[str]


client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List a few popular cookie recipes. Be sure to include the amounts of ingredients.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)
# Use the response as a JSON string.
print(response.text)

# Use instantiated objects.
my_recipes: list[Recipe] = response.parsed

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

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "2 cups chocolate chips"
    ]
  },
  ...
]

نحو تعریف طرحواره

طرحی را برای پاسخ JSON در ویژگی response_schema پیکربندی مدل خود مشخص کنید. مقدار response_schema باید یک یا زیر باشد:

یک نوع، همانطور که در حاشیه نویسی نوع استفاده می کنید. ماژول typing پایتون را ببینید.
نمونه ای از genai.types.Schema .
معادل dict genai.types.Schema .

یک طرحواره را با یک نوع تعریف کنید

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

config={'response_mime_type': 'application/json',
        'response_schema': list[Recipe]}

کتابخانه سرویس گیرنده Gemini API Python از طرحواره های تعریف شده با انواع زیر پشتیبانی می کند (که در آن AllowedType هر نوع مجاز باشد):

int
float
bool
str
list[AllowedType]
برای انواع ساختار یافته:
- dict[str, AllowedType] . این حاشیه نویسی همه مقادیر dict را یک نوع اعلام می کند، اما مشخص نمی کند که چه کلیدهایی باید گنجانده شوند.
- مدل های Pydantic تعریف شده توسط کاربر. این رویکرد به شما امکان می دهد نام کلیدها را مشخص کنید و انواع مختلفی را برای مقادیر مرتبط با هر یک از کلیدها از جمله ساختارهای تودرتو تعریف کنید.

از یک enum برای محدود کردن خروجی استفاده کنید

در برخی موارد ممکن است بخواهید مدل یک گزینه را از لیست گزینه ها انتخاب کند. برای پیاده سازی این رفتار، می توانید یک enum را در طرحواره خود ارسال کنید. می‌توانید از گزینه enum در هر جایی که می‌توانید از str در response_schema استفاده کنید، استفاده کنید، زیرا enum لیستی از رشته‌ها است. مانند یک طرح JSON، یک enum به شما امکان می دهد خروجی مدل را برای برآورده کردن الزامات برنامه خود محدود کنید.

به عنوان مثال، فرض کنید که در حال توسعه برنامه‌ای برای طبقه‌بندی آلات موسیقی به یکی از پنج دسته هستید: "Percussion" ، "String" ، "Woodwind" ، "Brass" یا « "Keyboard" ». شما می توانید یک enum برای کمک به این کار ایجاد کنید.

در مثال زیر، کلاس enum Instrument به عنوان response_schema ارسال می‌کنید و مدل باید مناسب‌ترین گزینه enum را انتخاب کند.

from google import genai
import enum

class Instrument(enum.Enum):
  PERCUSSION = "Percussion"
  STRING = "String"
  WOODWIND = "Woodwind"
  BRASS = "Brass"
  KEYBOARD = "Keyboard"

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': Instrument,
    },
)

print(response.text)
# Woodwind

Python SDK اعلان‌های نوع API را ترجمه می‌کند. با این حال، API زیرمجموعه ای از طرحواره OpenAPI 3.0 ( Schema ) را می پذیرد. شما همچنین می توانید این طرح را به عنوان JSON ارسال کنید:

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': {
            "type": "STRING",
            "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
        },
    },
)

print(response.text)
# Woodwind

فراتر از مشکلات اساسی چند گزینه ای، می توانید از enum در هر جایی از طرحواره برای JSON یا فراخوانی تابع استفاده کنید. به عنوان مثال، می‌توانید از مدل فهرستی از عناوین دستور غذا را بخواهید و از Grade enum برای دادن درجه محبوبیت به هر عنوان استفاده کنید:

from google import genai

import enum
from pydantic import BaseModel

class Grade(enum.Enum):
    A_PLUS = "a+"
    A = "a"
    B = "b"
    C = "c"
    D = "d"
    F = "f"

class Recipe(BaseModel):
  recipe_name: str
  rating: Grade

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List 10 home-baked cookies and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)
# [{"rating": "a+", "recipe_name": "Classic Chocolate Chip 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 -> قالب
bool
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": "bool" }

{ "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 نیست - آرایه ای از رشته ها است که برای تعیین ترتیب خواص در پاسخ استفاده می شود. با مشخص کردن ترتیب ویژگی ها و سپس ارائه مثال هایی با ویژگی ها به همان ترتیب، به طور بالقوه می توانید کیفیت نتایج را بهبود بخشید.