Prodhimi i strukturuar

Ju mund ta konfiguroni Binjakët për dalje të strukturuar në vend të tekstit të pastrukturuar, duke lejuar nxjerrjen dhe standardizimin e saktë të informacionit për përpunim të mëtejshëm. Për shembull, ju mund të përdorni dalje të strukturuar për të nxjerrë informacion nga CV-të, për t'i standardizuar ato për të ndërtuar një bazë të dhënash të strukturuar.

Binjakët mund të gjenerojnë vlera JSON ose enum si rezultat i strukturuar.

Po gjeneron JSON

Ka dy mënyra për të gjeneruar JSON duke përdorur Gemini API:

  • Konfiguro një skemë në model
  • Siguroni një skemë në një kërkesë teksti

Konfigurimi i një skeme në model është mënyra e rekomanduar për të gjeneruar JSON, sepse e kufizon modelin të nxjerrë JSON.

Konfigurimi i një skeme (rekomandohet)

Për të kufizuar modelin për të gjeneruar JSON, konfiguroni një responseSchema . Më pas, modeli do t'i përgjigjet çdo kërkese me dalje të formatuar JSON.

Python JavaScript Shkoni PUSHIMI 
from google import genai
from pydantic import BaseModel

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

client = genai.Client(api_key="GOOGLE_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="List a few popular cookie recipes, and 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

import { GoogleGenAI, Type } from "@google/genai";

const ai = new GoogleGenAI({ "GOOGLE_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.0-flash",
    contents:
      "List a few popular cookie recipes, and include the amounts of ingredients.",
    config: {
      responseMimeType: "application/json",
      responseSchema: {
        type: Type.ARRAY,
        items: {
          type: Type.OBJECT,
          properties: {
            recipeName: {
              type: Type.STRING,
            },
            ingredients: {
              type: Type.ARRAY,
              items: {
                type: Type.STRING,
              },
            },
          },
          propertyOrdering: ["recipeName", "ingredients"],
        },
      },
    },
  });

  console.log(response.text);
}

main();

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey:  "GOOGLE_API_KEY",
        Backend: genai.BackendGeminiAPI,
    })
    if err != nil {
        log.Fatal(err)
    }

    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseSchema: &genai.Schema{
            Type: genai.TypeArray,
            Items: &genai.Schema{
                Type: genai.TypeObject,
                Properties: map[string]*genai.Schema{
                    "recipeName": {Type: genai.TypeString},
                    "ingredients": {
                        Type:  genai.TypeArray,
                        Items: &genai.Schema{Type: genai.TypeString},
                    },
                },
                PropertyOrdering: []string{"recipeName", "ingredients"},
            },
        },
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.0-flash",
        genai.Text("List a few popular cookie recipes, and include the amounts of ingredients."),
        config,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [{
        "parts":[
          { "text": "List a few popular cookie recipes, and include the amounts of ingredients." }
        ]
      }],
      "generationConfig": {
        "responseMimeType": "application/json",
        "responseSchema": {
          "type": "ARRAY",
          "items": {
            "type": "OBJECT",
            "properties": {
              "recipeName": { "type": "STRING" },
              "ingredients": {
                "type": "ARRAY",
                "items": { "type": "STRING" }
              }
            },
            "propertyOrdering": ["recipeName", "ingredients"]
          }
        }
      }
}' 2> /dev/null | head

Prodhimi mund të duket si ky:

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

Sigurimi i një skeme në një prompt teksti

Në vend që të konfiguroni një skemë, mund të jepni një skemë si gjuhë natyrale ose pseudo-kod në një kërkesë teksti. Kjo metodë nuk rekomandohet , sepse mund të prodhojë rezultate me cilësi më të ulët dhe sepse modeli nuk është i kufizuar të ndjekë skemën.

Këtu është një shembull i përgjithshëm i një skeme të dhënë në një kërkesë teksti:

List a few popular cookie recipes, and include the amounts of ingredients.

Produce JSON matching this specification:

Recipe = { "recipeName": string, "ingredients": array<string> }
Return: array<Recipe>

Meqenëse modeli e merr skemën nga teksti në prompt, mund të keni njëfarë fleksibiliteti në mënyrën se si e përfaqësoni skemën. Por kur jepni një skemë inline si kjo, modeli në fakt nuk është i kufizuar të kthejë JSON. Për një përgjigje më deterministe dhe me cilësi më të lartë, konfiguroni një skemë në model dhe mos e dyfishoni skemën në kërkesën e tekstit.

Gjenerimi i vlerave enum

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. Ju mund të përdorni një opsion enum kudo ku mund të përdorni një string në responseSchema , sepse një enum është një grup 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 një numër si responseSchema , duke e kufizuar modelin të zgjedhë opsionin më të përshtatshëm.

Python 
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

Biblioteka e Python do të përkthejë deklaratat e tipit për API. Megjithatë, API pranon një nëngrup të skemës OpenAPI 3.0 ( Skema ).

Ka dy mënyra të tjera për të specifikuar një numërim. Ju mund të përdorni një Literal :

Python 
Literal["Percussion", "String", "Woodwind", "Brass", "Keyboard"]

Dhe gjithashtu mund ta kaloni skemën si JSON:

Python 
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 bazë me zgjedhje të shumëfishta, mund të përdorni një numër kudo në një skemë JSON. 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:

Python 
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 cookie recipes and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)

Përgjigja mund të duket si kjo: 

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "rating": "a+"
  },
  {
    "recipe_name": "Peanut Butter Cookies",
    "rating": "a"
  },
  {
    "recipe_name": "Oatmeal Raisin Cookies",
    "rating": "b"
  },
  ...
]

Rreth skemave JSON

Konfigurimi i modelit për daljen JSON duke përdorur parametrin responseSchema mbështetet në objektin Schema për të përcaktuar strukturën e tij. Ky objekt përfaqëson një nënbashkësi të zgjedhur të objektit OpenAPI 3.0 Schema , dhe gjithashtu shton një fushë propertyOrdering .

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": integer,
  "minItems": integer,
  "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 , ose një bashkim i këtyre llojeve (duke përdorur anyOf ). Vetëm një nëngrup fushash është e vlefshme për çdo Type . Lista e mëposhtme harton çdo Type me një nënbashkësi të fushave që janë të vlefshme për atë lloj:

  • string -> enum , format , i nullable
  • integer -> format , minimum , maximum , enum , nullable
  • number -> format , minimum , maximum , enum , nullable
  • boolean -> nullable
  • array -> minItems , maxItems , items , nullable
  • object -> properties , required , propertyOrdering , nullable

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

Për dokumentacionin e plotë të fushave të Skemës pasi ato përdoren në API-në 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": ["recipeName", "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. propertyOrdering mbështetet vetëm kur krijoni manualisht types.Schema .

Skemat në Python

Kur përdorni bibliotekën Python, vlera e response_schema duhet të jetë një nga sa vijon:

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

Mënyra më e lehtë për të përcaktuar një skemë është me një lloj pidantik (siç tregohet në shembullin e mëparshëm):

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

Kur përdorni një tip Pydantic, biblioteka e Python ndërton një skemë JSON për ju dhe e dërgon atë në API. Për shembuj shtesë, shihni dokumentet e bibliotekës Python .

Biblioteka 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]
  • AllowedType|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.

Mbështetje për skemën JSON

Skema JSON është një specifikim më i fundit se OpenAPI 3.0, mbi të cilin bazohet objekti i skemës . Mbështetja për skemën JSON është e disponueshme si një pamje paraprake duke përdorur responseJsonSchema fushësJsonSchema e cila pranon çdo Skemë JSON me kufizimet e mëposhtme:

  • Punon vetëm me Gemini 2.5.
  • Ndërsa të gjitha vetitë e skemës JSON mund të kalohen, jo të gjitha mbështeten. Shikoni dokumentacionin për këtë fushë për më shumë detaje.
  • Referencat rekursive mund të përdoren vetëm si vlerë e një vetie të objektit që nuk kërkohet.
  • Referencat rekursive zbërthehen në një shkallë të fundme, bazuar në madhësinë e skemës.
  • Skemat që përmbajnë $ref nuk mund të përmbajnë veçori të tjera përveç atyre që fillojnë me një $ .

Këtu është një shembull i krijimit të një skeme JSON me Pydantic dhe dorëzimit të saj në model: 

curl "https://generativelanguage.googleapis.com/v1alpha/models/\
gemini-2.5-flash-preview-05-20:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d @- <<EOF
{
  "contents": [{
    "parts":[{
      "text": "Please give a random example following this schema"
    }]
  }],
  "generationConfig": {
    "response_mime_type": "application/json",
    "response_json_schema": $(python3 - << PYEOF
from enum import Enum
from typing import List, Optional, Union, Set
from pydantic import BaseModel, Field, ConfigDict
import json

class UserRole(str, Enum):
    ADMIN = "admin"
    VIEWER = "viewer"

class Address(BaseModel):
    street: str
    city: str

class UserProfile(BaseModel):
    username: str = Field(description="User's unique name")
    age: Optional[int] = Field(ge=0, le=120)
    roles: Set[UserRole] = Field(min_items=1)
    contact: Union[Address, str]
    model_config = ConfigDict(title="User Schema")

# Generate and print the JSON Schema
print(json.dumps(UserProfile.model_json_schema(), indent=2))
PYEOF
)
  }
}
EOF

Kalimi direkt i skemës JSON nuk mbështetet ende kur përdoret SDK.

Praktikat më të mira

Mbani parasysh konsideratat dhe praktikat më të mira të mëposhtme kur jeni duke përdorur një skemë përgjigjeje:

  • Madhësia e skemës suaj të përgjigjes llogaritet në kufirin e kodit të hyrjes.
  • Si parazgjedhje, fushat janë opsionale, që do të thotë se modeli mund të plotësojë fushat ose t'i kapërcejë ato. Ju mund të vendosni fushat siç kërkohet për të detyruar modelin të japë një vlerë. Nëse nuk ka kontekst të mjaftueshëm në kërkesën e hyrjes shoqëruese, modeli gjeneron përgjigje kryesisht bazuar në të dhënat mbi të cilat është trajnuar.

  • Një skemë komplekse mund të rezultojë në një gabim InvalidArgument: 400 . Kompleksiteti mund të vijë nga emrat e gjatë të pronave, kufijtë e gjatësisë së vargjeve të gjata, numrat me shumë vlera, objektet me shumë veti opsionale ose një kombinim i këtyre faktorëve.

    Nëse e merrni këtë gabim me një skemë të vlefshme, bëni një ose më shumë nga ndryshimet e mëposhtme për të zgjidhur gabimin:

    • Shkurtoni emrat e pronave ose emrat e numrit.
    • Rrafshoni vargjet e mbivendosura.
    • Zvogëloni numrin e pronave me kufizime, siç janë numrat me kufijtë minimalë dhe maksimalë.
    • Zvogëloni numrin e vetive me kufizime komplekse, të tilla si vetitë me formate komplekse si date-time .
    • Zvogëloni numrin e vetive opsionale.
    • Zvogëloni numrin e vlerave të vlefshme për enums.

  • Nëse nuk po i shihni rezultatet që prisni, shtoni më shumë kontekst në kërkesat tuaja të hyrjes ose rishikoni skemën tuaj të përgjigjes. Për shembull, rishikoni përgjigjen e modelit pa rezultat të strukturuar për të parë se si përgjigjet modeli. Më pas mund të përditësoni skemën tuaj të përgjigjes në mënyrë që të përshtatet më mirë me rezultatin e modelit.

Çfarë është më pas

Tani që keni mësuar se si të gjeneroni rezultate të strukturuara, mund të provoni të përdorni mjetet e Gemini API: