Gemini API function calling: Memarlıq iş axınlarında alət çağırışı

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

Gemini API function calling modelə yalnız cavab mətni yaratmaq əvəzinə, xarici sistemlərdə istifadə edilə biləcək funksiyanı seçməyə və həmin funksiya üçün tələb olunan parametrləri hazırlamağa imkan verir. Funksiyanı həqiqətən icra edən modelin özü deyil; model ilə xarici sistem arasında əlaqə yaradan tətbiqdir. Google-un bələdçisində bu yanaşma xarici sistemlərdə əməliyyatlar aparmaq, API və ya verilənlər bazası kimi mənbələrdən məlumat almaq, habelə hesablama kimi alətlərlə imkanları genişləndirmək üçün izah olunur.

Memarlıq, interyer dizaynı və vizuallaşdırma komandaları üçün bu struktur, məsələn, material kataloqunda axtarış aparan və ya layihə haqqında məlumat gətirən tətbiqin qurulmasına əsas ola bilər. Aşağıdakı nümunədə modelin kataloq axtarışı funksiyasına hansı parametrləri ötürəcəyini hazırlaması göstərilir. Real kataloqa qoşulma və nəticələrdən istifadə tətbiqin hazırlanmasından asılıdır.

Tələblər

Başlamaq üçün Gemini API açarı və API sorğusu göndərə bilən mühit lazımdır. Rəsmi başlanğıc bələdçisində Python SDK, JavaScript SDK və REST istifadəsi göstərilir; Java və Go üçün də nümunələr təqdim olunur. Bu izahda Python seçilib.

Google AI Studio yeni istifadəçilər üçün avtomatik olaraq layihə və API açarı yaradır. Açarı AI Studio-dakı API keys səhifəsindən əldə etmək mümkündür. Bələdçidə açarın mühit dəyişəni kimi təyin edilməsi nümunəsi göstərilir. API açarı sorğunun hesabla əlaqələndirilməsinə və istifadənin hesab üzərindən izlənməsinə xidmət edir; həmçinin sorğular üçün təhlükəsizlik məhdudiyyətlərinin tətbiqinə kömək edir.

Ödənişli istifadəyə keçdikdə hesab üçün daha geniş sorğu limitləri açılır; bu mərhələdə Cloud Billing-i konfiqurasiya etmək lazımdır. Google-un bələdçisində ödənişli kreditlər üçün ən azı 5 ABŞ dolları və ya valyuta ekvivalentinin əvvəlcədən ödənilməsi qeyd olunur. Bu, istifadə xərclərinin təxmini deyil, mənbədə göstərilən ilkin ödəniş şərtidir. Ödənişli istifadəyə keçməzdən əvvəl hesab və ödəniş ayarlarını yoxlayın.

Python SDK-nı quraşdırmaq üçün rəsmi bələdçidəki əmr:

pip install -U google-genai

Funksiya çağırışının yaradılması: addım-addım

1. Funksiyanın məqsədini müəyyənləşdirin. Funksiyanın adı və təsviri tətbiqin nə etdiyini aydın ifadə etməlidir. Bu nümunədə məqsəd layihə üçün uyğun material variantlarını xarici kataloqda axtarmaqdır. Kataloq sorğusu burada icra edilmir; modelin həmin sorğu üçün lazım olan arqumentləri yaratması göstərilir.

2. Modeldən tələb olunacaq məlumatları müəyyənləşdirin. İstifadəçi sorğusu, məsələn, belə ola bilər:

Layihəm üçün açıq rəngli, daş görünüşlü döşəmə örtüklərini material kataloqunda axtar.

Bu mətn təbii dildə verilən sorğunun model tərəfindən funksiya parametrlərinə çevrilməsinə nümunədir. Tətbiq tərəfində hansı sahələrin lazım olacağı kataloqun strukturuna görə müəyyənləşdirilməlidir; aşağıdakı nümunədə axtarış sorğusu bir mətn sahəsində saxlanılır.

1. Funksiya sxemini hazırlayın. Google-un funksiya çağırışı nümunələrində funksiyanın adı, təsviri və parametr sxemi müəyyənləşdirilir. Parametrlərin növü göstərilir; məcburi sahələr required siyahısına əlavə olunur. Buradakı search_materials və query sahəsi memarlıq kataloquna uyğunlaşdırılmış nümunədir.

from google import genai

search_materials_function = {
    "type": "function",
    "name": "search_materials",
    "description": "Searches a project material catalog using a text query.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The material search query."
            }
        },
        "required": ["query"]
    }
}

Təsviri funksiyanın həqiqi vəzifəsini izah edəcək şəkildə yazın. Parametr adlarını da qoşulmuş tətbiqin gözlədiyi sahələrə uyğun seçin. Kataloq bir neçə filtr tələb edirsə, sxem də buna uyğun qurulmalıdır; lakin sahələr və filtrlər sistemdə həqiqətən mövcud olan məlumatlara əsaslanmalıdır.

1. Sorğunu Gemini API-yə göndərin və çağırış mərhələsini yoxlayın. Başlanğıc bələdçisindəki nümunələrdə genai.Client() klienti, interactions.create sorğusu və interaction.output_text kimi nəticə sahələri işlədilir. Function calling sənədində isə cavab mərhələləri arasında function_call növünün yoxlanılması, funksiyanın adı və arqumentlərinin oxunması göstərilir.

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Layihəm üçün açıq rəngli, daş görünüşlü döşəmə örtüklərini axtar.",
    tools=[search_materials_function],
)

for step in interaction.steps:
    if step.type == "function_call":
        print("Funksiya:", step.name)
        print("Arqumentlər:", step.arguments)

Bu nümunədə modeldən gözlənilən nəticə funksiya çağırışının adı və arqumentləridir. Modelin hazırladığı arqumentləri tətbiq tərəfində yoxlayın. Kataloqa giriş, sorğunun icrası və nəticələrin istifadəçiyə göstərilməsi bu nümunəyə daxil olmayan tətbiq mərhələləridir.

1. Real istifadədən əvvəl girişləri sınaqdan keçirin. Müxtəlif layihə sorğuları ilə modelin hansı funksiyanı seçdiyini və hansı arqumentləri yaratdığını müşahidə edin. Sorğu qeyri-müəyyən olduqda tətbiqin təhlükəsiz və düzgün işləməsi üçün lazımi yoxlamaları öz sisteminizdə qurun. Mənbə bələdçiləri API istifadəsini və çağırış mərhələlərini izah edir, lakin konkret memarlıq kataloqunun dəqiqliyinə və ya məlumat keyfiyyətinə zəmanət vermir.

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

• Funksiya təsvirini qeyri-müəyyən yazmaq: Modelin seçməsi gözlənilən alətin vəzifəsi aydın təsvir edilməlidir. Funksiyanın adı, təsviri və parametr tərifləri bir-birini tamamlamalıdır.

• Parametrləri tətbiqlə uyğunlaşdırmamaq: Sxemdəki sahələr xarici sistemin tələb etdiyi məlumatlara uyğun olmalıdır. Əks halda, model arqumentlər yaratsa belə, tətbiq onlardan düzgün istifadə edə bilməyə bilər.

• Model çağırışını əməliyyatın özü hesab etmək: Function calling xarici sistemlə əlaqə qurmaq üçün çağırış və arqumentlər yaradır. Funksiyanın real sistemdə icrası tətbiq tərəfindəki bağlantıdan asılıdır.

• API açarını diqqətsiz idarə etmək: Açar API sorğularını hesabla əlaqələndirməyə və istifadəyə nəzarət etməyə kömək edir. Başlanğıc bələdçisində açarı mühit dəyişənində saxlamaq nümunəsi göstərilir.

• Ödəniş və istifadə limitlərini nəzərə almamaq: Ödənişli səviyyəyə keçdikdə sorğu limitləri və ödəniş ayarları dəyişir. İstifadəyə başlamazdan əvvəl AI Studio-dakı istifadə və ödəniş məlumatlarını yoxlayın.

Memarlıq və vizuallaşdırma iş axınına təsiri

Bu yanaşma təbii dildə verilən sorğunu tətbiqin müəyyən etdiyi alətlərə yönəltmək istəyən komandalar üçün faydalı ola bilər. Məsələn, interyer layihəsində modeldən material axtarışı sorğusunu strukturlaşdırılmış kataloq sorğusuna çevirməsi gözlənilə bilər. Eyni şəkildə, xarici API və ya verilənlər bazasından məlumat almaq da mənbədə göstərilən istifadə sahələrindəndir. Bu, Revit, 3ds Max və ya başqa dizayn proqramına hazır bağlantı demək deyil; inteqrasiyanı qurmaq lazımdır.

Ofislər və tələbələr üçün əsas məqamlar API açarı, tətbiqin xarici sistemlə uyğunluğu, sorğu limitləri və mümkün ödənişli istifadə şərtləridir. Mənbələrdə xüsusi avadanlıq tələbi göstərilmir. Buna görə qərar verərkən avadanlıqla bağlı fərziyyələr irəli sürməkdənsə, API istifadəsini və iş axınında hansı məlumatların xaricə ötürüləcəyini qiymətləndirmək daha məqsədəuyğundur.

Növbəti addımlar

Əvvəlcə kataloq axtarışı kimi əhatə dairəsi aydın olan funksiya üçün sxem qurun və nümunə istifadəçi sorğularına qaytarılan arqumentləri yoxlayın. Sonra tətbiq tərəfində bu arqumentləri qəbul edəcək xarici API və ya məlumat mənbəyini müəyyənləşdirin. Başqa dilə üstünlük verilirsə, rəsmi başlanğıc bələdçisindəki JavaScript və ya REST nümunələrinə də baxmaq olar. Çoxmərhələli söhbətlər üçün bələdçi serverin tarixçəni idarə etdiyi previous_interaction_id yanaşmasını tövsiyə olunan vəziyyət idarəetmə üsulu kimi izah edir.

Mənbə və lisenziya

Bu bələdçi Google-un Gemini API function calling və başlanğıc bələdçiləri əsasında hazırlanıb. Hər iki mənbə CC BY 4.0 lisenziyalıdır. Məzmun Azərbaycan dilinə çevrilib və memarlıq material kataloqu ssenarisinə uyğunlaşdırılıb.