Gemini API ilə memarlıq mətnlərindən sxemli JSON çıxışı yaratmaq

Bu bələdçidə nə öyrənəcəksiniz?

Layihə brifi, material qeydləri və ya məkan təsviri çox vaxt sərbəst mətn şəklində təqdim olunur. Bu mətnlərdən otağın adı, material və istifadə məqsədi kimi məlumatları nizamlı şəkildə çıxarmaq lazım gələndə, cavabın yalnız təbii dildə verilməsi sonrakı emalı çətinləşdirə bilər. Gemini API-nin strukturlaşdırılmış çıxış funksiyası model cavabının əvvəlcədən müəyyən edilmiş JSON Schema-ya uyğun olmasını tələb etməyə imkan verir.

Bu tətbiqdə üç məqamı birlikdə nəzərdən keçirəcəyik: gözlənilən sahələri müəyyənləşdirmək, tapşırığı və məhdudiyyətləri aydın təlimatla izah etmək, sonra isə uyğun sxemi API sorğusuna əlavə etmək. Nümunələr memarlıq iş axınları üçün hazırlanıb; aşağıdakı təlimatlar mənbələrdə olduğu kimi təqdim edilmir, sənədləşdirilmiş üsullara əsaslanan orijinal nümunələrdir.

Tələblər və əhatə dairəsi

Google-un sənədlərində strukturlaşdırılmış çıxışlar üçün REST API-də JSON Schema dəstəyindən bəhs olunur. Google GenAI SDK-larında isə sxem təyin etmək üçün Python tərəfdə Pydantic, JavaScript tərəfdə Zod göstərilir. Mənbədə Java, Go və digər nümunələr də var; bu bələdçidə kod əvəzinə asanlıqla uyğunlaşdırıla bilən JSON Schema qaralamasından istifadə edirik.

Sənəd nümunələrində JavaScript üçün Zod-un quraşdırılmalı olduğu qeyd edilir; lakin SDK versiyası, hesab tələbləri və ya qiymət barədə bu mənbələrdə məlumat verilmir. Buna görə layihəyə başlamazdan əvvəl istifadə edəcəyiniz SDK və modelin cari tələblərini müvafiq Gemini API sənədlərindən yoxlayın. Sənədlərin yuxarı hissəsində Gemini 4 Argon-un əlçatan olduğu yazılsa da, nümunə kodda gemini-3.8-flash model adı işlədilir. Nümunədəki model adının avtomatik olaraq aktual və ya bütün istifadə halları üçün uyğun olduğunu düşünməyin.

1. Çıxarılacaq sahələri müəyyənləşdirin

Sxem hazırlamazdan əvvəl mətndən hansı məlumatların çıxarılacağını və hər birinin hansı tipdə olacağını qərarlaşdırın. Məsələn, aşağıdakı qaralama interyer brifindən məkanın adını, göstərilən materialı və funksiyanın təsvirini çıxarmaq üçün nəzərdə tutulub. object, properties, string və required kimi JSON Schema-nın əsas strukturları mənbədə göstərilən nümunələrə uyğundur.

{
  "type": "object",
  "properties": {
    "mekan_adi": { "type": "string" },
    "malzeme": { "type": "string" },
    "islev": { "type": "string" }
  },
  "required": ["mekan_adi", "malzeme", "islev"]
}

Burada hər üç sahə məcburi göstərilib. Mənbə mətndə hansısa məlumat yoxdursa, bunun necə işlənməli olduğunu təlimatda ayrıca izah edin; məsələn, sahənin boş saxlanmasını və ya “qeyd olunmayıb” yazılmasını tələb edə bilərsiniz. Bu seçim layihə məlumatlarının necə emal ediləcəyindən asılıdır; sxemi qurarkən qərarı əvvəlcədən vermək komanda daxilində ardıcıl nəticələr əldə etməyə kömək edir.

2. Tapşırığı və giriş məlumatını aydın yazın

Yaxşı təlimat görüləcək işi, üzərində işlənəcək mətni və cavabın formatını aydın şəkildə təsvir edir. Google-un təlimat dizaynı bələdçisi aydın və konkret göstərişlərdən istifadə etməyi, zərurət olduqda məhdudiyyətləri və format gözləntilərini qeyd etməyi tövsiyə edir. Aşağıdakı nümunəni öz brif sahələrinizə uyğunlaşdıra bilərsiniz.

Aşağıdakı interyer layihəsi brifindən məkanın adını, açıq şəkildə göstərilən materialı və məkanın funksiyasını çıxar. Yalnız təqdim olunan mətndəki məlumatlara əsaslan. Məlumat mətndə yoxdursa, bunu “qeyd olunmayıb” kimi yaz. Cavabı təqdim edilmiş JSON sxemindəki sahələrə uyğun JSON obyekti şəklində yarat.

Brif: Birinci mərtəbədə yerləşən oxu zonasında palıd üzlüklü səthlər və birgə iş masaları var.

Bu təlimat mətni giriş kimi təqdim edir, çıxarılmalı məlumatı müəyyənləşdirir və naməlum sahələrlə necə davranılacağını bildirir. Strukturlaşdırılmış çıxış funksiyası da gözlənilən cavabın sxemə uyğun olmasını təmin edir. Təlimat və sxemdə eyni sahələr nəzərdə tutulmalıdır: sxemdə olmayan yeni açarlar təlimatda tələb edilməməli, tələb olunan sahələr də sxemdən çıxarılmamalıdır.

3. Məhdudiyyətləri layihənin ehtiyacına uyğun daraldın

Memarlıq sənədlərində şərhlə mənbə məlumatını bir-birindən ayırmaq vacibdir. Material siyahısı çıxarırsınızsa, mətndə olmayan məhsul və ya texniki xüsusiyyətlərin əlavə edilməməsini açıq şəkildə tələb edin. Məsələn, aşağıdakı təlimat məkan təsvirində yalnız yazılı materialları toplamağa yönəlib.

Bu məkan təsvirində adı çəkilən üzlük və səth materiallarını çıxar. Yeni material təklif etmə, sinonim və ya marka təxminləri əlavə etmə. Nəticəni yalnız material adlarından ibarət siyahı kimi ver.

Təsvir: Giriş holunda terrazzo döşəmə və boyalı suvaq divar səthi istifadə olunacaq.

Bu nümunədə siyahı formatı tələb olunur; buna görə onu JSON obyekti gözləyən əvvəlki sxemlə eyni tapşırıqda birbaşa istifadə etməyin. Cavab formatı ehtiyaca görə dəyişir: strukturlaşdırılmış çıxışdan istifadə edərkən sxem təlimatda təsvir edilən nəticəyə uyğun olmalıdır. Eyni sxemi müxtəlif tipli tapşırıqlarda təkrar istifadə etməkdənsə, hər işin sahələrini və məlumat tiplərini yenidən nəzərdən keçirin.

4. Nümunə cavabla formatı göstərin

Tapşırıqda tələb olunan təsnifat və ya yazı qaydası təbii dillə izah ediləndə qeyri-müəyyən qala bilər. Belə hallarda qısa nümunələr əlavə etmək formatı aydınlaşdıra bilər. Google-un bələdçisində few-shot yanaşmasında modelə nümunə giriş və gözlənilən cavab formatının göstərilə biləcəyi, nümunələrin aydın və müxtəlif olmasının faydalı olduğu bildirilir.

Yeni məkan qeydini aşağıdakı nümunədəki sahələrdən istifadə edərək təsnifləşdir.

Nümunə qeyd: “Mətbəx tezgâhı kvars kompozitdir, şkaf qapıları mat laklıdır.”
Nümunə çıxış: {"mekan": "Mutfak", "malzemeler": ["kuvars kompozit", "mat lake"]}

Yeni qeyd: “İş otağında taxta parket və suvaq üzərində boya var.”
Yalnız eyni sahə quruluşunda cavab ver.

Bu nümunə çıxışın quruluşunu göstərir; real API sorğusunda istifadə ediləcək sxemi ayrıca təyin etməlisiniz. Mənbə bələdçisində az sayda nümunə ilə başlamağın və nümunələrin sayını istifadə vəziyyətinə uyğun sınaqdan keçirməyin lazım ola biləcəyi bildirilir. Həddindən artıq çox nümunənin modeldə ifrat uyğunlaşmaya səbəb ola biləcəyi də qeyd olunur.

Tez-tez edilən səhvlər

Ən çox rast gəlinən problemlərdən biri tələbləri yalnız təlimatda yazmaq, API tərəfində isə sxem göstərməməkdir. Google bildirir ki, sadə JSON formatlarını təbii dildə istəmək mümkündür; daha mürəkkəb JSON Schema tələblərində isə strukturlaşdırılmış çıxış funksiyasından istifadə etmək tövsiyə olunur. Digər problem sxemlə təlimatda fərqli sahələrin və ya fərqli cavab formatlarının tələb edilməsidir. Əvvəlcə sahələri və tipləri dəqiqləşdirin, sonra təlimatı həmin quruluşa uyğun yazın.

Digər bir səhv qeyri-müəyyən mətnlərdə modeldən mənbədə olmayan detalları tamamlamasını gözləməkdir. Təlimatda hansı məlumatın çıxarılacağını, hansının kənarda saxlanacağını və çatışmayan məlumatın necə göstəriləcəyini qeyd edin. Sxem formatın ardıcıl olmasına kömək edir; lakin mənbə materialının düzgünlüyünə və ya tamlığına öz-özlüyündə zəmanət vermir. Yaradılmış qeydləri orijinal briflə müqayisə etmək, xüsusən təhvil və sənədləşdirmə proseslərində vacibdir.

Memarlıq və vizuallaşdırma iş axınlarında istifadə

Bu yanaşma çoxsaylı layihə qeydlərini eyni sahələrə ayırmalı olan memarlıq ofisləri, interyer dizaynerləri və tələbələr üçün faydalı ola bilər. Məkan təsvirlərindən material adlarını, məkan növlərini və ya funksiya təriflərini çıxarmaq, bu məlumatların sonradan başqa alətə ötürüləcəyi iş axınları üçün nizamlı başlanğıc nöqtəsi yaradır. Mənbələrdə konkret BIM, CAD və ya vizuallaşdırma proqramına inteqrasiya təsvir olunmur; buna görə əlaqələndirmə və uyğunluq ayrıca qiymətləndirilməlidir.

Ofislər əvvəlcə kiçik mətn toplusunda sahələrin işə yarayıb-yaramadığını sınaqdan keçirməli, sonra eyni sxem və təlimatın müxtəlif briflərdə necə nəticə verdiyini yoxlamalıdır. Tələbələr üçün bu üsul sərbəst mətndən məlumat çıxarmağı və JSON strukturunu öyrənməyi praktik şəkildə bir araya gətirir. Mənbələrdə avadanlıq, lisenziya və API istifadə xərcləri barədə məlumat yoxdur; istehsal mərhələsinə keçməzdən əvvəl bunları müvafiq xidmət sənədlərindən yoxlayın.

Növbəti addımlar

Əvvəlcə bir istifadə vəziyyəti seçin: məsələn, məkan qeydindən materialları çıxarmaq. Sahələri müəyyənləşdirib sxemi qurun, sonra aydın göstərişlərdən ibarət təlimatla sınaqdan keçirin. Nəticələri mənbə mətnlə müqayisə edin, təkrarlanan səhvləri müşahidə edin və yalnız həqiqətən lazım olduqda təlimata nümunə əlavə edin. Tətbiqdə Python istifadə olunursa, Pydantic; JavaScript istifadə olunursa, Zod ilə sxem təyin etmək variantlarını nəzərdən keçirin. REST API istifadəsi də sənədlərdə dəstəklənir.

İş həcmi böyüdükcə sxem dəyişikliklərini və gözlənilən sahələri komanda daxilində sənədləşdirin. Beləliklə, memarlıq briflərini emal edən müxtəlif tapşırıqlarda eyni məlumat strukturunun qorunub-qorunmadığını izləmək asanlaşar. Başlanğıcda məqsəd hər şeyi avtomatlaşdırmaq deyil; təkrarlanan mətn tapşırığını aydın qaydalar və yoxlanıla bilən cavab formatı ilə sınaqdan keçirməkdir.

Mənbə və lisenziya

Bu bələdçi Google-un “Structured outputs” və “Prompt design strategies” sənədlərindən türk dilinə uyğunlaşdırılıb. Hər iki mənbə CC BY 4.0 lisenziyalıdır.