Gjenerimi i imazheve vendase me Gemini 2.0 Flash Experimental është tani i disponueshëm! Mësoni më shumë

Kjo faqe është përkthyer nga Cloud Translation API.

Gjeneroni dalje të strukturuar me Gemini API

Binjakët gjenerojnë tekst të pastrukturuar si parazgjedhje, por disa aplikacione kërkojnë tekst të strukturuar. Për këto raste përdorimi, mund ta kufizoni Gemini të përgjigjet me JSON, një format i strukturuar i të dhënave i përshtatshëm për përpunim të automatizuar. Ju gjithashtu mund ta kufizoni modelin që të përgjigjet me një nga opsionet e specifikuara në një numër.

Këtu janë disa raste përdorimi që mund të kërkojnë dalje të strukturuar nga modeli:

Ndërtoni një bazë të dhënash të kompanive duke nxjerrë informacionin e kompanisë nga artikujt e gazetave.
Tërhiqni informacionin e standardizuar nga CV-të.
Nxjerr përbërësit nga recetat dhe shfaq një lidhje në një faqe interneti ushqimore për secilin përbërës.

Në kërkesën tuaj, mund t'i kërkoni Binjakëve që të prodhojë dalje të formatuar JSON, por kini parasysh se modeli nuk është i garantuar të prodhojë JSON dhe asgjë tjetër përveç JSON. Për një përgjigje më deterministe, ju mund të kaloni një skemë specifike JSON në një fushë responseSchema në mënyrë që Binjakët të përgjigjen gjithmonë me një strukturë të pritshme. Për të mësuar më shumë rreth punës me skemat, shihni Më shumë rreth skemave JSON .

Ky udhëzues ju tregon se si të gjeneroni JSON duke përdorur metodën generateContent përmes SDK-së së zgjedhjes suaj ose duke përdorur drejtpërdrejt API REST. Shembujt tregojnë hyrjen vetëm me tekst, megjithëse Gemini mund të prodhojë gjithashtu përgjigje JSON ndaj kërkesave multimodale që përfshijnë imazhe , video dhe audio .

Përpara se të filloni: Vendosni projektin tuaj dhe çelësin API

Përpara se të telefononi Gemini API, duhet të konfiguroni projektin tuaj dhe të konfiguroni çelësin tuaj API.

Zgjero për të parë se si të konfigurosh projektin dhe çelësin API

Merrni dhe sigurojeni çelësin tuaj API

Ju duhet një çelës API për të thirrur Gemini API. Nëse nuk e keni tashmë një të tillë, krijoni një çelës në Google AI Studio.

Merrni një çelës API

Rekomandohet fuqimisht që të mos kontrolloni një çelës API në sistemin tuaj të kontrollit të versionit.

Ju duhet të ruani çelësin tuaj API në një dyqan sekretesh si Google Cloud Secret Manager .

Ky udhëzues supozon se ju po përdorni çelësin tuaj API si një variabël mjedisi.

Instaloni paketën SDK dhe konfiguroni çelësin tuaj API

Python SDK për API-në Gemini gjendet në paketën google-generativeai .

Instaloni varësinë duke përdorur pip:
```
pip install -U google-generativeai
```

Importoni paketën dhe konfiguroni shërbimin me çelësin tuaj API:

import os
import google.generativeai as genai

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

Gjeneroni JSON

Kur modeli është konfiguruar për të nxjerrë JSON, ai i përgjigjet çdo kërkese me dalje të formatuar JSON.

Ju mund të kontrolloni strukturën e përgjigjes JSON duke ofruar një skemë. Ekzistojnë dy mënyra për t'i dhënë një skemë modelit:

Si tekst në prompt
Si një skemë e strukturuar e ofruar përmes konfigurimit të modelit

Jepni një skemë si tekst në prompt

Shembulli i mëposhtëm e shtyn modelin të kthejë recetat e cookie-ve në një format specifik JSON.

Meqenëse modeli merr specifikimin e formatit nga teksti në prompt, mund të keni njëfarë fleksibiliteti në mënyrën se si e përfaqësoni specifikimin. Çdo format i arsyeshëm për paraqitjen e një skeme JSON mund të funksionojë.

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)

Prodhimi mund të duket si ky:

[
  {
    "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"
    ]
  },
  ...
]

Siguroni një skemë përmes konfigurimit të modelit

Shembulli i mëposhtëm bën sa vijon:

Instancon një model të konfiguruar përmes një skeme për t'u përgjigjur me JSON.
E kërkon modelin të kthejë recetat e biskotave.

Kjo metodë më formale për deklarimin e skemës JSON ju jep kontroll më të saktë sesa të mbështeteni vetëm në tekstin në kërkesë.

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

Prodhimi mund të duket si ky:

[
  {
    "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"
    ]
  },
  ...
]

Sintaksa e përkufizimit të skemës

Specifikoni skemën për përgjigjen JSON në veçorinë response_schema të konfigurimit të modelit tuaj. Vlera e response_schema duhet të jetë një:

Një lloj, siç do të përdorni në një shënim tipi. Shihni modulin typing Python.
Një shembull i genai.types.Schema .
Ekuivalenti i dict të genai.types.Schema .

Përcaktoni një skemë me një lloj

Mënyra më e lehtë për të përcaktuar një skemë është me një lloj të drejtpërdrejtë. Kjo është qasja e përdorur në shembullin e mëparshëm:

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

Biblioteka e klientit Gemini API Python mbështet skemat e përcaktuara me llojet e mëposhtme (ku AllowedType është çdo lloj i lejuar):

int
float
bool
str
list[AllowedType]
Për llojet e strukturuara:
- dict[str, AllowedType] . Ky shënim deklaron se të gjitha vlerat e diktimit janë të të njëjtit lloj, por nuk specifikon se cilat çelësa duhet të përfshihen.
- Modele Pydantic të përcaktuara nga përdoruesi. Kjo qasje ju lejon të specifikoni emrat e çelësave dhe të përcaktoni lloje të ndryshme për vlerat e lidhura me secilin prej çelësave, duke përfshirë strukturat e ndërlidhura.

Përdorni një numër për të kufizuar prodhimin

Në disa raste ju mund të dëshironi që modeli të zgjedhë një opsion të vetëm nga një listë opsionesh. Për të zbatuar këtë sjellje, mund të kaloni një numër në skemën tuaj. Mund të përdorni një opsion enum kudo ku mund të përdorni një str në response_schema , sepse një enum është një listë vargjesh. Ashtu si një skemë JSON, një enum ju lejon të kufizoni daljen e modelit për të përmbushur kërkesat e aplikacionit tuaj.

Për shembull, supozoni se po zhvilloni një aplikacion për të klasifikuar instrumentet muzikore në një nga pesë kategoritë: "Percussion" , "String" , "Woodwind" , "Brass" ose " "Keyboard" ". Ju mund të krijoni një numër për të ndihmuar me këtë detyrë.

Në shembullin e mëposhtëm, ju kaloni Instrument e klasës enum si response_schema , dhe modeli duhet të zgjedhë opsionin më të përshtatshëm 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 do të përkthejë deklaratat e tipit për API. Megjithatë, API pranon një nëngrup të skemës OpenAPI 3.0 ( Skema ). Ju gjithashtu mund ta kaloni skemën si 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

Përtej problemeve themelore me zgjedhje të shumëfishta, mund të përdorni një numër kudo në një skemë për JSON ose thirrje funksioni. Për shembull, mund t'i kërkoni modelit një listë titujsh recetash dhe të përdorni një Grade notash për t'i dhënë secilit titull një notë popullariteti:

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"}, ...]

Më shumë rreth skemave JSON

Kur konfiguroni modelin që të kthejë një përgjigje JSON, mund të përdorni një objekt Schema për të përcaktuar formën e të dhënave JSON. Schema përfaqëson një nënbashkësi të zgjedhur të objektit OpenAPI 3.0 Schema .

Këtu është një përfaqësim pseudo-JSON i të gjitha fushave 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 i skemës duhet të jetë një nga llojet e të dhënave OpenAPI. Vetëm një nëngrup fushash është e vlefshme për çdo Type . Lista e mëposhtme harton çdo Type në fusha të vlefshme për atë lloj:

string -> enum, format
integer -> format
number -> format
bool
array -> minItems, maxItems, artikuj
object -> vetitë, të kërkuara, pronëRendimi, i pavlefshëm

Këtu janë disa skema shembuj që tregojnë kombinime të vlefshme të tipit dhe fushës:

{ "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"]
}

Për dokumentacionin e plotë të fushave të Skemës pasi ato përdoren në API-në e Gemini, shihni referencën e skemës .

Renditja e pronës

Kur jeni duke punuar me skemat JSON në Gemini API, renditja e vetive është e rëndësishme. Si parazgjedhje, API i rendit pronat në mënyrë alfabetike dhe nuk ruan rendin në të cilin përcaktohen vetitë (edhe pse SDK-të e AI të Genit të Google mund ta ruajnë këtë renditje). Nëse po i jepni shembuj modelit me një skemë të konfiguruar dhe renditja e vetive të shembujve nuk është në përputhje me renditjen e vetive të skemës, rezultati mund të jetë i ngathët ose i papritur.

Për të siguruar një renditje të qëndrueshme dhe të parashikueshme të pronave, mund të përdorni fushën opsionale propertyOrdering[] .

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

propertyOrdering[] – jo një fushë standarde në specifikimin OpenAPI – është një grup vargjesh që përdoren për të përcaktuar rendin e vetive në përgjigje. Duke specifikuar rendin e vetive dhe më pas duke ofruar shembuj me vetitë në të njëjtin rend, mund të përmirësoni potencialisht cilësinë e rezultateve.