Gemini API ilə memarlıq vizuallarını JSON çıxışına çevirmək üçün bələdçi

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

Memarlıq vizualından məkan, obyekt və ya görünən xüsusiyyətlər barədə strukturlaşdırılmış qeydlər çıxarmaq, sonra isə bu qeydləri JSON formatında əldə etmək mümkündür. Bu bələdçidə Gemini API-yə mətn və vizualı birlikdə göndərməyi, promptu aydın yazmağı və cavabın strukturunu sxemlə təsvir etməyi addım-addım nəzərdən keçiririk. Nümunələr interyer vizualı əsasında hazırlanıb; vizualda olmayan ölçü və ya materialı təxmin etdirməmək üçün promptlarda qeyri-müəyyənliyi qeyd etməyə də yer veririk.

Google-ın Gemini API sənədlərində vizual anlama vizual təsvir, təsnifat və vizual sual-cavab kimi istifadə sahələri ilə izah olunur. Vizual girişi URL, daxili məlumat və ya Files API vasitəsilə ötürülə bilər. Bu nümunədə model adı kimi sənədlərdəki nümunələrdə yer alan gemini-3.8-flash istifadə olunur.

Tələblər

• Gemini API ilə işləyə bilən müştəri və ya REST sorğusu. Sənədlərdə Python və JavaScript nümunələri ilə yanaşı Java və Go nümunələri də təqdim olunur.

• Vizualı API-yə ötürmək üçün üsul: kiçik vizuallarda base64 kodlu daxili məlumat, böyük fayllarda və ya təkrar istifadə olunacaq vizuallarda Files API.

• JSON çıxışı tələb olunursa, cavabın hansı sahələrdən ibarət olacağını müəyyən edən JSON Schema. Google GenAI SDK-larında sxemi Python üçün Pydantic, JavaScript üçün Zod ilə müəyyənləşdirmək mümkündür.

• REST istifadə edilirsə, sorğuda API açarı. Bu bələdçidə hesab açmaq, ödəniş və ya istifadə kvotası barədə mənbələrdə göstərilməyən fərziyyələr irəli sürülmür.

Nümunə olaraq, interyer vizualında görünən obyektləri və onların yerini təsvir edən qeydləri strukturlaşdırılmış siyahı şəklində əldə etmək istədiyimizi düşünək. Aşağıdakı sxem bu məqsəd üçün istifadə oluna biləcək sadə quruluşu göstərir. Sahələri real iş axınına uyğun dəyişmək mümkündür; əsas məsələ promptda tələb olunan çıxışla sxemdəki sahələrin uyğun gəlməsidir.

{
  "type": "object",
  "properties": {
    "gozlemler": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "unsur": { "type": "string" },
          "konum": { "type": "string" },
          "gorunur_ozellik": { "type": "string" }
        },
        "required": ["unsur", "konum", "gorunur_ozellik"]
      }
    }
  },
  "required": ["gozlemler"]
}

Tətbiq mərhələləri

1. Vizualı və məqsədi müəyyənləşdirin

Əvvəlcə təhlil ediləcək vizualın hansı suala cavab verməli olduğunu dəqiqləşdirin. Məsələn, məqsəd perspektivdə görünən mebelləri siyahıya almaq ola bilər; başqa bir istifadə ssenarisində görünən səth xüsusiyyətləri təsvir edilə bilər. Vizualda olmayan ölçü, konstruksiya sistemi və ya məhsul məlumatlarını prompta daxil etməyin. Bu cür məlumatı görüntüdən dəqiq çıxarmaq mümkün deyilsə, modeldən bunu açıq şəkildə bildirməsini istəyin.

2. Promptu aydın və məhdud çərçivədə yazın

Google-ın prompt dizaynı bələdçisi tapşırıq və məhdudiyyətlərin aydın göstərilməsini, həmçinin tələb olunan cavab formatının təsvir edilməsini tövsiyə edir. Aşağıdakı nümunədə bu yanaşma interyer vizualına tətbiq olunur:

Görseli bir iç mekân sunum paftasını inceler gibi değerlendir. Yalnızca görüntüde açıkça seçilebilen unsurları listele. Her unsur için kısa bir konum tarifi ve görülebilir özelliğini yaz. Ölçü, marka veya malzeme türünü görüntüden kesin biçimde belirleyemiyorsan tahmin etme; bunu belirt. Yanıtı, tanımladığım JSON şemasındaki alanlara uygun biçimde ver.

Prompt tapşırığı və əhatə dairəsini müəyyən edir; sxem isə cavabın hansı sahələr üzrə qaytarılacağını göstərir. Sadəcə “vizualı təhlil et” demək, hansı detallara önəm verilməli olduğunu modelin öhdəsinə buraxır. Tələb olunan sahələri və təxmin edilməməli məlumatları əvvəlcədən qeyd etmək çıxışdan layihə qeydlərində istifadəni asanlaşdırır. Bununla belə, nəticə vizualın məzmunu barədə təsdiqlənmiş ölçmə və ya texniki ekspertiza hesab olunmur.

3. Vizualı API sorğusuna əlavə edin

Kiçik vizualı base64 formatına kodlayıb data sahəsi ilə göndərə bilərsiniz. Sənədlərdə bu üsul üçün mətn promptu ilə birlikdə vizual məlumatı və MIME növündən istifadə olunur. Daxili vizual məlumatı, prompt mətni və sistem təlimatları birlikdə sorğunun ümumi ölçüsünü 20 MB-la məhdudlaşdırır. Bu həddin aşılması mümkündürsə, faylı Files API-yə yükləmək və alınan URI-ni sorğuya əlavə etmək lazımdır.

Files API sənədlərdə böyük fayllar və ya eyni vizualdan bir neçə sorğuda istifadə halları üçün tövsiyə olunur. Sorğuda mətn girişi ilə vizual girişini birlikdə ötürün; vizualın MIME növünü də uyğun şəkildə göstərin. Sənədlərdə nümunə kimi verilən vizual növlərindən biri image/jpeg-dir.

4. JSON cavab formatını tənzimləyin

Structured outputs xüsusiyyətində cavab formatını JSON olaraq seçib sxemi sorğuya əlavə edirsiniz. Sənədlərdəki REST nümunəsində bunun üçün mime_type dəyəri application/json olaraq göstərilir, sxem isə schema sahəsinə yerləşdirilir. Python nümunəsi də Pydantic modelindən JSON Schema yaradaraq cavabı həmin modellə yoxlayır; JavaScript nümunəsində Zod sxemindən istifadə olunur.

Memarlıq iş axınında sxemi lazımsız yerə böyütməyin. Məsələn, yalnız obyekt, yerləşmə və görünən xüsusiyyət lazımdırsa, iş axınında istifadə olunmayan əlavə sahələr texniki xidmət və yoxlama yükü yarada bilər. Sxemdəki məcburi sahələri də promptda tələb etdiyiniz məlumatlarla uyğunlaşdırın.

5. Cavabı yoxlayın və istifadəyə verin

Modeldən gələn JSON-u müəyyən edilmiş sahələrin doldurulub-doldurulmadığına və məzmunun vizualla uyğunluğuna görə yoxlayın. Structured outputs format baxımından sxemə uyğun cavablar almağı asanlaşdırır; bu, vizual şərhinin hər zaman düzgün olduğu anlamına gəlmir. Xüsusilə material, ölçü və ya dizayn qərarları kimi nəticələri çertyoj, layihə sənədi və ya mütəxəssis rəyi ilə ayrıca təsdiqləyin.

Bir neçə vizual üçün eyni sxemdən istifadə etmək nəticələri müqayisə etməyi asanlaşdıra bilər. Hər sorğuda vizualın hansı aspektdən təhlil olunacağını aydın bildirin və eyni tapşırıq üçün promptda kiçik dəyişikliklər edərək alınan cavabları qiymətləndirin. Prompt dizaynı iterativ prosesdir; ilk cəhdi yekun hesab etməkdənsə, səhv və ya lazımsız sahələri müəyyənləşdirib təsvirləri dəqiqləşdirin.

Tez-tez rast gəlinən səhvlər

• Vizualda görünməyəni dəqiq məlumat kimi tələb etmək: Perspektiv, təsvir ölçüsü və ya kadr bəzi detalları qeyri-müəyyən edə bilər. Promptda modeldən təxmin etmək əvəzinə qeyri-müəyyənliyi bildirməsini istəyin.

• Sxemlə promptu fərqli qurmaq: Promptda tələb olunan sahə sxemdə yoxdursa və ya sxemdə məcburi sahə olub tapşırıqda izah edilməyibsə, nəticələrdən istifadə çətinləşir. Hər ikisini birlikdə nəzərdən keçirin.

• Böyük faylı daxili məlumatla göndərmək: Daxili vizual məlumatı üçün sorğunun ümumi ölçüsünə 20 MB həddi tətbiq olunur. Böyük fayllarda Files API-dən istifadə edin.

• JSON formatını dəqiqlik zəmanəti hesab etmək: Strukturlaşdırılmış cavab məlumatın vizualla dəqiq uyğun gəldiyini sübut etmir. Vacib dizayn və texniki qərarları ayrıca yoxlayın.

• İlk promptu yekun versiya saymaq: Tapşırıq və məhdudiyyətlər nə qədər aydın olsa da, real nümunələrdə çıxışı nəzərdən keçirib promptu təkmilləşdirmək lazımdır.

Memarlıq və archviz iş axınına təsiri

Bu üsul vizual arxivindəki interyer görüntülərini təsvir etmək, təqdimat vizuallarından strukturlaşdırılmış müşahidə siyahıları yaratmaq və ya müxtəlif vizualları ortaq sahələr üzrə müqayisə etmək istəyən memarlıq büroları, interyer dizaynerləri və tələbələr üçün faydalı ola bilər. JSON formatı eyni sahələrin təkrar istifadə olunduğu qiymətləndirmə və təsnifat işlərində məlumatları daha nizamlı saxlayır. Bununla belə, nəticələri layihə paftasına və ya texniki sənədə birbaşa təsdiqlənmiş məlumat kimi daxil etmək olmaz.

Uyğunluq baxımından istifadə olunan müştərinin və API sorğusunun sənədlərdəki vizual girişini və structured output formatlarını dəstəkləməsi lazımdır. Vizualı daxili məlumat kimi göndərmək və ya Files API vasitəsilə istifadə etmək seçimi fayl ölçüsünə və təkrar istifadə ehtiyacına əsasən edilməlidir. API-yə giriş və xərc şərtləri bu bələdçinin mənbələrində göstərilmədiyindən, real ofis iş axınına keçməzdən əvvəl aktual giriş və lisenziya şərtlərini ayrıca yoxlamaq lazımdır.

Növbəti addımlar

Əvvəlcə bir neçə nümunəvi vizual üzərində kiçik sxemi sınaqdan keçirin. Cavablarda tez-tez təkrarlanan və iş axınında həqiqətən istifadə ediləcək sahələri müəyyənləşdirin; qeyri-müəyyən müşahidələri ayrıca işarələyin. Daha sonra promptu, sxemi və vizualın göndərilmə üsulunu birlikdə nəzərdən keçirin. Daha əhatəli JSON strukturları lazım olduqda Gemini API-nin structured output sənədlərindəki SDK nümunələrini, vizual girişi üçün isə Image understanding bələdçisini nəzərdən keçirmək olar.

Mənbə və lisenziya

Bu məzmun Google AI for Developers-in “Structured outputs”, “Image understanding” və “Prompt design strategies” bələdçilərindən istifadə edilərək türkcədən uyğunlaşdırılıb. Hər üç mənbə CC BY 4.0 lisenziyası ilə təqdim olunur.