Gemini API-də alət çağırışı və strukturlaşdırılmış çıxış: Memarlıq üçün bələdçi

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

Gemini API-də alət çağırışının və strukturlaşdırılmış çıxış əldə etməyin nə işə yaradığını, bu iki yanaşmanın hansı işlərdə seçilə biləcəyini və memarlıq yönümlü nümunənin necə qurulacağını öyrənəcəksiniz. Bələdçinin diqqət mərkəzində layihə qeydlərindən məkan məlumatlarını toplamaq və modelin xarici funksiya üçün tələb olunan parametrləri yaratmasını təmin etmək dayanır.

Bu iki xüsusiyyət eyni deyil. Funksiya çağırışında model müəyyən edilmiş funksiyalardan birinin çağırılmasının lazım olub-olmadığını qiymətləndirir və tələb olunan parametrləri qaytarır. Strukturlaşdırılmış çıxışda isə cavabın əvvəlcədən təyin olunmuş sxemə uyğun yaradılması istənilir. Birincisi alətlərlə qarşılıqlı əlaqəyə, ikincisi isə nizamlı verilənlər əldə etməyə xidmət edir; lazım gəldikdə eyni iş axınının müxtəlif mərhələlərində istifadə oluna bilərlər.

Tələblər

Google-un Gemini API sənədlərində Python və JavaScript SDK nümunələri ilə yanaşı Java, Go və REST nümunələri də var. Python nümunəsində google paketinin genai müştərisi, JavaScript nümunəsində isə @google/genai paketi istifadə olunur. REST nümunəsində API açarı GEMINI_API_KEY dəyişəni ilə ötürülür. Mənbələr quraşdırma addımlarını, ödənişləri və ya hesab şərtlərini izah etmədiyindən bu məsələlərlə bağlı fərziyyə irəli sürmək olmaz; tətbiq etməzdən əvvəl API-yə giriş və qiymət məlumatları ayrıca yoxlanmalıdır.

Nümunələrdə istifadə olunan modelin adı gemini-3.8-flash-dır. Model tətbiqin tələblərinə uyğun seçilməlidir; burada verilən nümunə mənbə sənədlərdəki model adını əsas götürür. Kodla işləyəcək komandaların istifadə etdikləri proqramlaşdırma dilinə uyğun SDK-sı və Gemini API-yə çıxışı hazır olmalıdır. Bu bələdçi konkret IDE və ya memarlıq proqramı əlavəsi tələb etmir.

Funksiya çağırışı nümunəsi üçün tətbiqdə çağırıla bilən xidmət və ya funksiya olmalıdır. Məsələn, bu, layihədəki məkan qeydlərini qaytaran daxili xidmət ola bilər. Model funksiya təsvirini və parametrləri yaradır; xidmət çağırışını etmək, qaytarılan nəticəni emal etmək və lazım gəldikdə istifadəçiyə təqdim etmək məsuliyyəti tətbiqin iş axınında qalır.

Addım-addım: Funksiya çağırışı

1. Funksiyanı müəyyənləşdirin. Funksiyanın adını, təsvirini və parametr sxemini təyin edin. Aşağıdakı nümunədə layihənin məkan məlumatlarını əldə etmək üçün tətbiqin təqdim edə biləcəyi funksiya təsviri göstərilir. project_id mətn parametri kimi qeyd olunur; o, real xidmətin tələblərinə uyğun müəyyənləşdirilməlidir.

from google import genai

get_room_data_function = {
    "type": "function",
    "name": "get_room_data",
    "description": "Returns room data for a project.",
    "parameters": {
        "type": "object",
        "properties": {
            "project_id": {"type": "string"}
        },
        "required": ["project_id"]
    }
}

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Mimari projedeki mekân verilerini getir.",
    tools=[{"type": "function", **get_room_data_function}]
)

for step in interaction.steps:
    if step.type == "function_call":
        print(step.name)
        print(step.arguments)

Bu nümunədə modelin funksiya çağırışı addımındakı funksiya adını və arqumentlərini oxumaq göstərilir. Burada tətbiqi məlumat xidmətinə qoşan kod yoxdur: funksiya təsviri öz-özlüyündə məkan məlumatlarını gətirmir. Tətbiq qaytarılan çağırışı öz xidmətində emal etməli, parametrləri yoxlamalı və əməliyyatın nəticəsini öz iş axınında nəzərə almalıdır.

1. Funksiyanın əhatə dairəsini məhdud saxlayın. Funksiyanın nə etdiyi və hansı parametrləri tələb etdiyi aydın olmalıdır. Memarlıq iş axınında məkan siyahısını oxumaqla layihə qeydini dəyişdirmək ayrı əməliyyatlardır; bu tapşırıqları ayrıca müəyyənləşdirmək tətbiqin hansı əməliyyatı icra etməli olduğunu aydınlaşdırır. Real sistemlərdə yazma və ya xarici aləmdə nəticə yarada bilən əməliyyatlar üçün tətbiq tərəfində yoxlama və təsdiq mərhələlərini də planlaşdırın.

2. Çağırış mərhələsini tətbiq tərəfində idarə edin. Rəsmi nümunələr qarşılıqlı əlaqənin addımları arasında function_call tipli addımları tapmağı, funksiya adını və arqumentləri oxumağı göstərir. Növbəti mərhələdə uyğun tətbiq funksiyası icra olunmalı və nəticə emal edilməlidir. Modelin funksiya çağırışı yaratması xarici xidmətin uğurla işlədiyi demək deyil; xətaların idarə edilməsi və nəticənin yoxlanması xidmət inteqrasiyasının bir hissəsidir.

Addım-addım: Strukturlaşdırılmış çıxış

1. Lazım olan məlumat sahələrini müəyyənləşdirin. Məsələn, layihə qeydindən məkan adı, sahə və tələblər siyahısını çıxarmaq üçün obyekt, massiv, mətn və tam ədəd tiplərindən ibarət sxem qurmaq olar. Sahə tiplərini tətbiqin bu məlumatlardan necə istifadə edəcəyinə uyğun seçin. Mənbədə JSON Schema ilə yanaşı Python üçün Pydantic, JavaScript üçün isə Zod vasitəsilə sxem müəyyənləşdirmə variantları da izah olunur.

2. Sxemi sorğuya əlavə edin. Aşağıdakı Python nümunəsində cavabı JSON formatında istəmək və output_text sahəsindən götürmək göstərilir. Sahə adları memarlıq yönümlü təlim nümunəsidir; layihə sənədlərindən hansı məlumatların çıxarılacağı iş tələblərinə əsasən müəyyən edilməlidir.

from google import genai

client = genai.Client()
room_schema = {
    "type": "object",
    "properties": {
        "rooms": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "room_name": {"type": "string"},
                    "area_m2": {"type": "integer"},
                    "requirements": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["room_name", "area_m2", "requirements"]
            }
        }
    },
    "required": ["rooms"]
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Proje notundaki mekânları çıkar: giriş holü 12 m²; doğal ışık gereksinimi var.",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": room_schema
    }
)

print(interaction.output_text)

Sxem cavabın sahələrini və gözlənilən məlumat tiplərini müəyyənləşdirir; lakin layihə qeydində olmayan məlumatı təsdiqlənmiş etmir. Məsələn, sahə ölçüsü mətndə yoxdursa, tətbiq bu məlumatı ayrıca yoxlamalı və ya çatışmayan məlumatı öz verilənlər modelində nəzərə almalıdır. Sxemdə məcburi sahələri elə seçmək də vacibdir ki, onlar mənbə mətnlərdə həmişə olsun.

1. Nəticəni tətbiqdə yoxlayın. Strukturlaşdırılmış çıxış verilənlərin təhlilini asanlaşdırmaq üçün nəzərdə tutulub; memarlıq qərarlarının düzgünlüyünə zəmanət verən yoxlama deyil. Modelin çıxışını layihə sənədi, ölçü çertyoju və ya səlahiyyətli qeyd ilə müqayisə edin. Xüsusilə sahə, şəxs, tarix və texniki tələb kimi nəticələrə təsir edə biləcək məlumatları təsdiq almadan çertyoja və ya layihə verilənlər bazasına daxil etməyin.

Tez-tez buraxılan səhvlər

Funksiya çağırışını modelin xarici sistemi avtomatik işə salması kimi başa düşmək əsas səhvlərdən biridir. Model çağırış adını və parametrləri təqdim edə bilər; tətbiq isə bu çağırışı uyğun xidmətlə əlaqələndirib icra etməlidir. Funksiya adlarını qeyri-müəyyən saxlamaq, təsviri ümumi yazmaq və ya tələb olunan parametrləri sxemdə göstərməmək də inteqrasiyanı çətinləşdirir.

Strukturlaşdırılmış çıxışda isə sxemə uyğunluğun məzmundakı bütün məlumatların doğru olduğu anlamına gəlmədiyini unutmayın. Həmçinin mənbə mətndə olub-olmadıqlarını nəzərə almadan məcburi sahələr müəyyənləşdirmək natamam və ya istifadə edilə bilməyən qeydlərə səbəb ola bilər. Model çıxışına iş axınının yekun və yoxlanılmış məlumatı kimi deyil, qaydalı bir məlumat mərhələsi kimi yanaşın.

Memarlıq və archviz iş axınında növbəti addımlar

Ofislər layihə qeydlərinin müəyyən sahələrə ayrılması və ya daxili alətlərdən məlumat alınması tələb olunan proseslərdə bu yanaşmaları nəzərdən keçirə bilər. Tələbələr üçün də mətndən nizamlı məlumat çıxarmağı və API inteqrasiyasının əsas məntiqini öyrənmək faydalıdır. Lakin mənbələrdə bu xüsusiyyətlər konkret BIM, CAD və ya vizuallaşdırma proqramına birbaşa qoşulan əlavə kimi təqdim edilmir; belə bir əlaqəni tətbiq ayrıca qurmalıdır.

İlk sınaqda yalnız oxumaq üçün nəzərdə tutulmuş, əhatə dairəsi məhdud funksiya və yoxlanıla bilən sxemdən istifadə edin. Əvvəlcə bir neçə layihə qeydində sahələrin necə çıxarıldığını yoxlayın; sonra nəticələri mənbə ilə müqayisə edin. Ofisdə paylaşılacaq alətə keçməzdən əvvəl API-yə girişi və mümkün istifadə xərclərini, layihə məlumatlarının hansı xidmətə göndəriləcəyini, eləcə də mövcud proqram təminatı ilə uyğunluğu dəqiqləşdirin. Bu məsələlər mənbə mətnlərdə ətraflı izah edilmədiyindən, onları müəssisəyə və seçilmiş tətbiqə uyğun olaraq ayrıca qiymətləndirmək lazımdır.

Mənbə və lisenziya

Bu bələdçi Google-un Gemini API üçün dərc etdiyi “Function calling with the Gemini API” və “Structured outputs” sənədləri əsasında Azərbaycan dilinə uyğunlaşdırılıb. Hər iki mənbə CC BY 4.0 lisenziyasına malikdir. Memarlıq yönümlü nümunələr bələdçi üçün yenidən hazırlanıb.