Gemini'yi yapılandırılmamış metin yerine yapılandırılmış çıkış için yapılandırarak daha fazla işleme tabi tutulacak bilgilerin doğru şekilde ayıklanmasına ve standartlaştırılmasına olanak tanıyabilirsiniz. Örneğin, özgeçmişlerden bilgi ayıklamak ve yapılandırılmış bir veritabanı oluşturmak için bu bilgileri standartlaştırmak amacıyla yapılandırılmış çıkışı kullanabilirsiniz.
Gemini, yapılandırılmış çıkış olarak JSON veya enum değerleri oluşturabilir.
JSON oluşturma
Gemini API'yi kullanarak JSON oluşturmanın iki yolu vardır:
- Modelde bir şema yapılandırma
- Metin isteminde şema sağlama
Modelde bir şema yapılandırmak, modeli JSON çıkışı verecek şekilde kısıtladığından JSON oluşturmanın önerilen yoludur.
Şema yapılandırma (önerilir)
Modeli JSON oluşturacak şekilde kısıtlamak için bir responseSchema yapılandırın. Ardından model, tüm istemlere JSON biçimli çıkışla yanıt verir.
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
Çıkış şu şekilde görünebilir:
[
{
"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"
]
},
...
]
Metin isteminde şema sağlama
Bir şemayı yapılandırmak yerine, metin isteminde şemayı doğal dil veya sözde kod olarak sağlayabilirsiniz. Bu yöntem, daha düşük kaliteli sonuçlar verebileceği ve model şemayı takip etmekle sınırlı olmadığı için önerilmez.
Metin isteminde sağlanan bir şemaya dair genel bir örnek aşağıda verilmiştir:
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>
Model şemayı istemdeki metinden aldığından şemayı nasıl temsil ettiğiniz konusunda biraz esneklik olabilir. Ancak bu şekilde satır içi bir şema sağladığınızda model aslında JSON döndürmek için kısıtlanmamıştır. Daha kesin ve daha yüksek kaliteli bir yanıt için modelde bir şema yapılandırın ve şemayı metin isteminde kopyalamayın.
Enum değerleri oluşturma
Bazı durumlarda modelin seçenekler listesinden tek bir seçenek seçmesini isteyebilirsiniz. Bu davranışı uygulamak için şemanıza bir enum iletebilirsiniz. Enum, bir dize dizisi olduğundan responseSchema içinde string kullanabileceğiniz her yerde enum seçeneğini kullanabilirsiniz. JSON şeması gibi bir enum, model çıkışını uygulamanızın şartlarını karşılayacak şekilde kısıtlamanıza olanak tanır.
Örneğin, müzik aletlerini "Percussion", "String", "Woodwind", "Brass" veya ""Keyboard"" kategorilerinden birine sınıflandıracak bir uygulama geliştirdiğinizi varsayalım. Bu görevi kolaylaştırmak için bir enum oluşturabilirsiniz.
Aşağıdaki örnekte, responseSchema olarak bir enum ileterek modeli en uygun seçeneği seçecek şekilde kısıtlarsınız.
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 kitaplığı, API için tür beyanlarını çevirir. Ancak API, OpenAPI 3.0 şemasının bir alt kümesini (şema) kabul eder.
Bir sayımı belirtmenin başka iki yolu vardır. Literal kullanabilirsiniz:
Literal["Percussion", "String", "Woodwind", "Brass", "Keyboard"]
Şemayı JSON olarak da iletebilirsiniz:
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
Temel çoklu seçim problemlerinin yanı sıra, JSON şemasının herhangi bir yerinde bir enum kullanabilirsiniz. Örneğin, modelden yemek tarifi başlıklarının listesini isteyebilir ve her bir başlığa popülerlik notu vermek için bir Grade enum kullanabilirsiniz:
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)
Yanıt aşağıdaki gibi görünebilir:
[
{
"recipe_name": "Chocolate Chip Cookies",
"rating": "a+"
},
{
"recipe_name": "Peanut Butter Cookies",
"rating": "a"
},
{
"recipe_name": "Oatmeal Raisin Cookies",
"rating": "b"
},
...
]
JSON şemaları hakkında
responseSchema parametresini kullanarak modeli JSON çıkışı için yapılandırırken yapısını tanımlamak için Schema nesnesine ihtiyaç duyulur. Bu nesne, OpenAPI 3.0 Schema nesnesinin belirli bir alt kümesini temsil eder ve ayrıca bir propertyOrdering alanı ekler.
Tüm Schema alanlarının sözde JSON gösterimi aşağıda verilmiştir:
{
"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)
}
}
Şemanın Type değeri, OpenAPI veri türlerinden biri veya bu türlerin bir birleşimi (anyOf kullanılarak) olmalıdır. Her Type için yalnızca bir alan alt kümesi geçerlidir.
Aşağıdaki listede her Type, ilgili tür için geçerli olan alanların bir alt kümesiyle eşlenir:
string->enum,format,nullableinteger->format,minimum,maximum,enum,nullablenumber->format,minimum,maximum,enum,nullableboolean->nullablearray->minItems,maxItems,items,nullableobject->properties,required,propertyOrdering,nullable
Geçerli tür ve alan kombinasyonlarını gösteren bazı örnek şemalar aşağıda verilmiştir:
{ "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"]
}
Gemini API'sinde kullanılan şema alanlarının tam dokümanları için Şema referansı başlıklı makaleyi inceleyin.
Mülk sıralaması
Gemini API'de JSON şemalarıyla çalışırken mülklerin sırası önemlidir. API varsayılan olarak mülkleri alfabetik olarak sıralar ve mülklerin tanımlandığı sırayı korur (Google üretken yapay zeka SDK'ları bu sırayı koruyabilir). Yapılandırılmış bir şema içeren modele örnek sağlıyorsanız ve örneklerin özellik sıralaması, şemanın özellik sıralamasıyla tutarlı değilse çıkış dağınık veya beklenmedik olabilir.
Mülklerin tutarlı ve tahmin edilebilir bir şekilde sıralanması için isteğe bağlı propertyOrdering[] alanını kullanabilirsiniz.
"propertyOrdering": ["recipeName", "ingredients"]
propertyOrdering[], OpenAPI spesifikasyonunda standart bir alan değildir ve yanıttaki özelliklerin sırasını belirlemek için kullanılan bir dize dizisidir. Mülklerin sırasını belirtip aynı sırayla mülkleri içeren örnekler sağlayarak sonuçların kalitesini artırabilirsiniz. propertyOrdering yalnızca types.Schema'ı manuel olarak oluşturduğunuzda desteklenir.
Python'da şemalar
Python kitaplığını kullanırken response_schema değerinin aşağıdakilerden biri olması gerekir:
- Tür ek açıklamalarında kullanacağınız tür (Python
typingmodülüne bakın) genai.types.Schemaörneğigenai.types.Schemadeğerinindicteşdeğeri
Şema tanımlamanın en kolay yolu, Pydantic türü kullanmaktır (önceki örnekte gösterildiği gibi):
config={'response_mime_type': 'application/json',
'response_schema': list[Recipe]}
Pydantic türü kullandığınızda Python kitaplığı sizin için bir JSON şeması oluşturur ve bunu API'ye gönderir. Daha fazla örnek için Python kitaplığı dokümanlarına bakın.
Python kitaplığı, aşağıdaki türlerle tanımlanan şemalarla desteklenir (AllowedType, izin verilen herhangi bir türdür):
intfloatboolstrlist[AllowedType]AllowedType|AllowedType|...- Yapılandırılmış türler için:
dict[str, AllowedType]. Bu ek açıklama, tüm sözlük değerlerinin aynı türde olduğunu belirtir ancak hangi anahtarların dahil edilmesi gerektiğini belirtmez.- Kullanıcı tanımlı Pydantic modelleri. Bu yaklaşım, anahtar adlarını belirtmenize ve iç içe yerleştirilmiş yapılar da dahil olmak üzere her anahtarla ilişkili değerler için farklı türler tanımlamanıza olanak tanır.
En iyi uygulamalar
Yanıt şeması kullanırken aşağıdaki hususları ve en iyi uygulamaları göz önünde bulundurun:
- Yanıt şemanızın boyutu, giriş jetonu sınırına dahil edilir.
- Alanlar varsayılan olarak isteğe bağlıdır. Yani model, alanları doldurabilir veya atlayabilir. Modeli bir değer sağlamaya zorlamak için alanları gerektiği gibi ayarlayabilirsiniz. İlişkili giriş isteminde yeterli bağlam yoksa model, yanıtları temel olarak eğitildiği verilere göre oluşturur.
Karmaşık bir şema
InvalidArgument: 400hatasına neden olabilir. Karmaşıklık, uzun özellik adlarından, uzun dizi uzunluğu sınırlarından, çok sayıda değere sahip enum'lardan, çok sayıda isteğe bağlı özelliğe sahip nesnelerden veya bu faktörlerin bir kombinasyonundan kaynaklanabilir.Bu hatayı geçerli bir şemada alırsanız hatayı gidermek için aşağıdaki değişikliklerden en az birini yapın:
- Mülk adlarını veya enum adlarını kısaltın.
- İç içe yerleştirilmiş dizileri düzleştirin.
- Minimum ve maksimum sınırlara sahip sayılar gibi kısıtlamalara sahip özelliklerin sayısını azaltın.
- Karmaşık kısıtlamalara sahip tesislerin sayısını azaltın (ör.
date-timegibi karmaşık biçimlere sahip tesisler). - İsteğe bağlı özelliklerin sayısını azaltın.
- Listeli değerler için geçerli değer sayısını azaltın.
Beklediğiniz sonuçları görmüyorsanız giriş istemlerinize daha fazla bağlam bilgisi ekleyin veya yanıt şemanızı düzeltin. Örneğin, modelin nasıl yanıt verdiğini görmek için modelin yapılandırılmış çıkış olmadan verdiği yanıtı inceleyin. Ardından, yanıt şemanızı modelin çıktısına daha uygun olacak şekilde güncelleyebilirsiniz.
Sırada ne var?
Yapılandırılmış çıkış oluşturmayı öğrendiniz. Şimdi Gemini API araçlarını kullanmayı deneyebilirsiniz: