Rezultatet e strukturuara

Ju mund të konfiguroni modelet Gemini për të gjeneruar përgjigje që i përmbahen një skeme JSON të dhënë. Kjo siguron rezultate të parashikueshme dhe të sigurta për llojin dhe thjeshton nxjerrjen e të dhënave të strukturuara nga teksti i pastrukturuar.

Përdorimi i rezultateve të strukturuara është ideal për:

  • Nxjerrja e të dhënave: Nxirrni informacione specifike si emrat dhe datat nga teksti.
  • Klasifikimi i strukturuar: Klasifikoni tekstin në kategori të paracaktuara.
  • Flukset e punës agjentike: Gjeneroni të dhëna të strukturuara për mjete ose API.

Përveç mbështetjes së Skemës JSON në API-n REST, SDK-të e Google GenAI lejojnë përcaktimin e skemave duke përdorur Pydantic (Python) dhe Zod (JavaScript).

Ky shembull demonstron se si të nxirren të dhëna të strukturuara nga teksti duke përdorur llojet themelore të skemës JSON si object , array , string dhe integer .

Python 

from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional

class Ingredient(BaseModel):
    name: str = Field(description="Name of the ingredient.")
    quantity: str = Field(description="Quantity of the ingredient, including units.")

class Recipe(BaseModel):
    recipe_name: str = Field(description="The name of the recipe.")
    prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.")
    ingredients: List[Ingredient]
    instructions: List[str]

client = genai.Client()

prompt = """
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
"""

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Recipe.model_json_schema()
    },
)

recipe = Recipe.model_validate_json(interaction.steps[-1].content[0].text)
print(recipe)

JavaScript 

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ingredientSchema = z.object({
  name: z.string().describe("Name of the ingredient."),
  quantity: z.string().describe("Quantity of the ingredient, including units."),
});

const recipeSchema = z.object({
  recipe_name: z.string().describe("The name of the recipe."),
  prep_time_minutes: z.number().optional().describe("Optional time in minutes to prepare the recipe."),
  ingredients: z.array(ingredientSchema),
  instructions: z.array(z.string()),
});

const client = new GoogleGenAI({});

const prompt = `
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
`;

const interaction = await client.interactions.create({
  model: "gemini-3-flash-preview",
  input: prompt,
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: zodToJsonSchema(recipeSchema)
  },
});

const recipe = recipeSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
console.log(recipe);

PUSHTIM 

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3-flash-preview",
      "input": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.",
      "response_format": {
        "type": "text",
        "mime_type": "application/json",
        "schema": {
          "type": "object",
          "properties": {
            "recipe_name": {
              "type": "string",
              "description": "The name of the recipe."
            },
            "prep_time_minutes": {
                "type": "integer",
                "description": "Optional time in minutes to prepare the recipe."
            },
            "ingredients": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "description": "Name of the ingredient."},
                  "quantity": { "type": "string", "description": "Quantity of the ingredient, including units."}
                },
                "required": ["name", "quantity"]
              }
            },
            "instructions": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["recipe_name", "ingredients", "instructions"]
        }
      }
      }
    }'

Shembull Përgjigjeje: 

{
  "recipe_name": "Delicious Chocolate Chip Cookies",
  "ingredients": [
    { "name": "all-purpose flour", "quantity": "2 and 1/4 cups" },
    { "name": "baking soda", "quantity": "1 teaspoon" },
    { "name": "salt", "quantity": "1 teaspoon" },
    { "name": "unsalted butter (softened)", "quantity": "1 cup" },
    { "name": "granulated sugar", "quantity": "3/4 cup" },
    { "name": "packed brown sugar", "quantity": "3/4 cup" },
    { "name": "vanilla extract", "quantity": "1 teaspoon" },
    { "name": "large eggs", "quantity": "2" },
    { "name": "semisweet chocolate chips", "quantity": "2 cups" }
  ],
  "instructions": [
    "Preheat the oven to 375°F (190°C).",
    "In a small bowl, whisk together the flour, baking soda, and salt.",
    "In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.",
    "Beat in the vanilla and eggs, one at a time.",
    "Gradually beat in the dry ingredients until just combined.",
    "Stir in the chocolate chips.",
    "Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes."
  ]
}

Rezultatet e transmetimit

Mund të transmetoni rezultate të strukturuara, duke ju lejuar të filloni përpunimin e përgjigjes ndërsa ajo gjenerohet. Pjesët e transmetuara janë vargje të vlefshme të pjesshme JSON që mund të bashkohen për të formuar objektin përfundimtar JSON.

Python 

from google import genai
from pydantic import BaseModel
from typing import Literal

class Feedback(BaseModel):
    sentiment: Literal["positive", "neutral", "negative"]
    summary: str

client = genai.Client()
prompt = "The new UI is incredibly intuitive. Add a very long summary to test streaming!"

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Feedback.model_json_schema()
    },
    stream=True
)
for event in stream:
    if event.event_type == "step.delta" and event.delta.text:
        print(event.delta.text, end="")

JavaScript 

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const client = new GoogleGenAI({});
const feedbackSchema = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  summary: z.string(),
});

const stream = await client.interactions.create({
  model: "gemini-3-flash-preview",
  input: "The new UI is incredibly intuitive. Add a very long summary!",
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: zodToJsonSchema(feedbackSchema)
  },
  stream: true,
});

for await (const event of stream) {
  if (event.type === "step.delta" && event.delta?.text) {
    process.stdout.write(event.delta.text);
  }
}

Rezultate të strukturuara me mjete

Gemini 3 ju lejon të kombinoni Daljet e Strukturuara me mjete të integruara, duke përfshirë Grounding with Google Search , URL Context , Code Execution , File Search dhe Function Calling .

Python 

from google import genai
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="Search for all details for the latest Euro.",
    tools=[{"type": "google_search"}, {"type": "url_context"}],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": MatchResult.model_json_schema()
    },
)

result = MatchResult.model_validate_json(interaction.steps[-1].content[0].text)
print(result)

JavaScript 

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const client = new GoogleGenAI({});
const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

const interaction = await client.interactions.create({
  model: "gemini-3.1-pro-preview",
  input: "Search for all details for the latest Euro.",
  tools: [{type: "google_search"}, {type: "url_context"}],
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: zodToJsonSchema(matchSchema)
  },
});

const match = matchSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
console.log(match);

PUSHTIM 

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.1-pro-preview",
    "input": "Search for all details for the latest Euro.",
    "tools": [{"type": "google_search"}, {"type": "url_context"}],
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
            "winner": {"type": "string"},
            "final_match_score": {"type": "string"},
            "scorers": {"type": "array", "items": {"type": "string"}}
        },
        "required": ["winner", "final_match_score", "scorers"]
      }
    }
  }'

Mbështetje për skemën JSON

Për të gjeneruar një objekt JSON, konfiguroni response_format me një objekt (ose një varg që përmban një objekt) të tipit text dhe vendosni mime_type ​​e tij në application/json . Skema duhet të jepet në fushën e schema .

Modaliteti i strukturuar i daljes së Gemini mbështet një nëngrup të specifikimit të Skemës JSON .

Vlerat e mëposhtme të type mbështeten:

  • string : Për tekstin.
  • number : Për numra me pikë lundruese.
  • integer : Për numra të plotë.
  • boolean : Për vlera të vërteta ose të rreme.
  • object : Për të dhëna të strukturuara me çifte çelës-vlerë.
  • array : Për listat e artikujve.
  • null : Për të lejuar që një veti të jetë null, përfshi "null" në vargun e tipit (p.sh., {"type": ["string", "null"]} ).

Këto veti përshkruese ndihmojnë në udhëzimin e modelit:

  • title : Një përshkrim i shkurtër i një prone.
  • description : Një përshkrim më i gjatë dhe më i detajuar i një prone.

Vetitë specifike të tipit

Për vlerat object :

  • properties : Një objekt ku çdo çelës është një emër prone dhe çdo vlerë është një skemë për atë veti.
  • required : Një varg vargjesh, që rendit cilat veti janë të detyrueshme.
  • additionalProperties : Kontrollon nëse lejohen vetitë që nuk janë të listuara në properties . Mund të jetë një vlerë booleane ose një skemë.

Për vlerat string :

  • enum : Liston një grup specifik vargjesh të mundshme për detyrat e klasifikimit.
  • format : Specifikon një sintaksë për vargun, siç është date-time , date , time .

Për vlerat number dhe integer :

  • enum : Liston një grup specifik vlerash numerike të mundshme.
  • minimum : Vlera minimale gjithëpërfshirëse.
  • maximum : Vlera maksimale gjithëpërfshirëse.

Për vlerat array :

  • items : Përcakton skemën për të gjitha elementet në varg.
  • prefixItems : Përcakton një listë skemash për N artikujt e parë, duke lejuar struktura të ngjashme me tuple.
  • minItems : Numri minimal i artikujve në varg.
  • maxItems : Numri maksimal i artikujve në varg.

Mbështetje për modelin

Model Rezultatet e strukturuara
Pamje paraprake e Gemini 3.1 Pro ✔️
Pamje paraprake e shpejtë e Gemini 3 ✔️
Gemini 2.5 Pro ✔️
Binjakët 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Binjakët 2.0 Flash ✔️*
Gemini 2.0 Flash-Lite ✔️*

* Gemini 2.0 kërkon një listë të qartë propertyOrdering .

Daljet e strukturuara kundrejt thirrjes së funksioneve

Karakteristikë Rasti i Përdorimit Kryesor
Rezultatet e strukturuara Formatimi i përgjigjes përfundimtare. Përdoret kur dëshironi përgjigjen e modelit në një format specifik.
Thirrja e funksionit Ndërmarrja e veprimeve gjatë bisedës. Përdoret kur modeli duhet t'ju kërkojë të kryeni një detyrë përpara se të japë një përgjigje përfundimtare.

Praktikat më të mira

  • Përshkrime të qarta: Përdorni fushën e description për të udhëhequr modelin.
  • Shtypje e fortë: Përdorni lloje specifike ( integer , string , enum ).
  • Inxhinieri e shpejtë: Shpjegoni qartë se çfarë dëshironi të bëjë modeli.
  • Validimi: Ndërsa rezultati është JSON i saktë nga ana sintaksore, gjithmonë validoni vlerat në aplikacionin tuaj.
  • Trajtimi i gabimeve: Implementoni trajtim të fuqishëm të gabimeve për daljet në përputhje me skemën, por semantikisht të pasakta.

Kufizime

  • Nënbashkësia e skemës: Jo të gjitha veçoritë e skemës JSON mbështeten.
  • Kompleksiteti i skemës: Skemat shumë të mëdha ose të ndërthurura thellë mund të refuzohen.