Gemini API ilə memarlıq iş axını: Python-da ilk mətn sorğusu

Bu təlimdə nə öyrənəcəksiniz?

Bu bələdçi Gemini API ilə ilk mətn sorğusunu Python vasitəsilə göndərmək istəyən memarlıq, interyer dizaynı və vizuallaşdırma komandaları üçün hazırlanıb. Google-ın Interactions API interfeysindən istifadə edərək prompt yaratmağı, daxil olan mətn cavabını oxumağı və cavabı axın şəklində almağı göstərəcəyik. Nümunələr dizayn prosesində rast gəlinən mətn tapşırıqlarına yönəlib: məsələn, kiçik yaşayış otağı üçün təkliflər istəmək və kafe konsepti üzrə görüşə hazırlaşmaq.

Bu təlimdəki kod nümunələri mətn cavabı almaq üçün nəzərdə tutulub. Gemini API-nin imkanları bununla məhdudlaşmır: Google-ın başlanğıc bələdçisində mətn yaratmaqla yanaşı, multimodal anlama, təsvir yaratma, strukturlaşdırılmış çıxış və alətlərdən istifadə də API vasitəsilə yerinə yetirilə bilən mövzular kimi göstərilir. Ancaq burada nümayiş etdirilən mətn nəticələri çertyojı, renderi və ya texniki yoxlamanı əvəz etmir; layihə qərarları komanda tərəfindən yoxlanmalıdır.

Tələblər: hesab, açar və proqram təminatı

Başlamaq üçün Google AI Studio vasitəsilə API açarı əldə edin. Google-ın bələdçisinə əsasən, yeni istifadəçilər üçün AI Studio avtomatik olaraq layihə və açar yarada bilər; mövcud istifadəçilər isə API açarları səhifəsindən yeni açar-layihə uyğunluğu yarada bilərlər. Google Cloud-dan idxal edilmiş əlavə layihələrin pulsuz səviyyədən istifadə etməsi üçün layihənin doğrulanması tələb oluna bilər.

Bu təlimdə Python SDK-sından istifadə ediləcək. Mənbədə göstərilən quraşdırma əmri google-genai paketini quraşdırır və ya yeniləyir. Bələdçidə konkret Python versiyası tələbi göstərilmədiyi üçün burada əlavə versiya şərti müəyyən edilmir. API açarını birbaşa mənbə koduna yazmaq əvəzinə mühit dəyişəni kimi təyin edin:

export GEMINI_API_KEY="YOUR_API_KEY"

YOUR_API_KEY hissəsini öz açarınızla əvəz edin. Bu əmr açarı əmrin icra olunduğu mühitdə GEMINI_API_KEY adı ilə təyin edir. Girişə nəzarəti təmin etmək üçün açarı açıq kod repozitoriyalarına və ya komanda xaricinin görə biləcəyi fayllara əlavə etməmək vacibdir.

Ödənişli səviyyəyə keçmək istəyənlər Cloud Billing qurmalı, ödəniş üsulu əlavə etməli və ən azı 5 dollar və ya ekvivalent məbləğdə ödənişli kredit üçün əvvəlcədən ödəniş etməlidirlər. Google bildirir ki, ödənişli səviyyə sorğu limitlərini artırır. API istifadəsini Google AI Studio-dakı istifadə ekranından izləmək mümkündür.

İlk sorğunu addım-addım göndərin

1. SDK-nı quraşdırın. Python mühitinizdə aşağıdakı əmri icra edin:

pip install -U google-genai

Əmr google-genai paketini pip vasitəsilə quraşdırır və ya mövcud quraşdırmanı yeniləyir. Bir neçə Python mühitindən istifadə edirsinizsə, əmri kodun icra olunacağı mühitdə işlətməyə diqqət edin.

1. İlk mətn sorğusunu hazırlayın. Aşağıdakı nümunəni Python faylına əlavə edin. Prompt kiçik yaşayış otağı üçün yazılı təkliflər istəyir:

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Küçük bir konut salonu için gün ışığını ve dolaşımı gözeten üç tasarım önerisi yaz. Her öneride tasarım kararını ve gerekçesini belirt."
)
print(interaction.output_text)

Sorğu Interactions API vasitəsilə gemini-3.8-flash modelinə göndərilir; nümunədə nəticə interaction.output_text ilə ekrana çıxarılır. Prompt mətnini real iş axınında tələb olunan mətn tapşırığına uyğunlaşdıra bilərsiniz. Məsələn, təqdimat üçün konsept izahı, material seçimlərini müqayisə edən qaralama və ya müştəri görüşü üçün suallar siyahısı istəyə bilərsiniz. Gözlənilən cavabın əhatə dairəsini və formatını aydın təsvir etmək daxil olan mətni qiymətləndirməyi asanlaşdırır.

1. Promptu layihənin kontekstinə uyğun dəqiqləşdirin. Ümumi əmr əvəzinə məkanın növünü və istədiyiniz nəticəni göstərin. Aşağıdakı nümunə interyer dizaynı görüşünə hazırlıq üçün hazırlanmış orijinal promptdur:

Bir kafe iç mekânı için konsept geliştirme toplantısına hazırlanıyorum. Tasarım ekibinin tartışması için üç farklı atmosfer yönü öner. Her yönü kısa bir başlık, mekânsal yaklaşım ve müşteriye sorulacak iki net soruyla açıkla. Proje verisi verilmediğinde varsayım üretme; eksik bilgileri ayrıca belirt.

Bu prompt vizual və ya texniki nəticə deyil, görüşdə müzakirə ediləcək yazılı qaralama istəyir. Naməlum məqamları ayrıca qeyd etməsini istəmək cavabın layihə məlumatları ilə qarışmasının qarşısını almağa kömək edə bilər; buna baxmayaraq, yaradılan mətn komanda tərəfindən nəzərdən keçirilməlidir.

1. Cavabı axın şəklində alın. Tətbiq cavabı yaradılarkən onu hissə-hissə emal etməlidirsə, sorğuda stream=True istifadə etmək olar. Aşağıdakı nümunə API-dən qaytarılan hadisələri dövrə alaraq ekrana çıxarır:

from google import genai

client = genai.Client()
stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Bir mimari konsept sunumu için kısa bir açılış metni yaz.",
    stream=True
)
for event in stream:
    print(event)

Axın istifadə edildikdə cavab vahid mətn kimi deyil, hadisələr şəklində gəlir. Google-ın bələdçisində izah olunur ki, step.delta hadisələri cavab yaradılarkən mətn hissələrini daşıya bilər. Bu nümunədə hər hadisə birbaşa ekrana çıxarılır; tətbiq hazırlayarkən hadisələrin istifadəçiyə necə göstəriləcəyini ayrıca nəzərə almaq lazımdır.

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

Bu nümunələr konsept izahı hazırlamaq, görüş gündəliyinə dəstək olacaq suallar yaratmaq, dizayn variantlarını yazılı şəkildə müqayisə etmək və təqdimat mətni üçün qaralama hazırlamaq kimi mətn yönümlü işlərə başlanğıc ola bilər. Komanda təkrarlanan və əhatə dairəsi aydın olan bir tapşırıq seçərək nəticənin nə qədər redaktə tələb etdiyini qiymətləndirə bilər. Bu yanaşma API-nin təsvir yaratmaq və ya layihəni yoxlamaq imkanları barədə nəticə çıxarmağa əsas vermir; yalnız burada göstərilən mətn sorğularının iş axınına uyğunluğunu sınaqdan keçirir.

İş stansiyası baxımından bu nümunələr yerli render performansını ölçmür. Mənbədə bu istifadə üçün konkret GPU tələbi və ya aparat tövsiyəsi verilmədiyindən, nümunələrə əsaslanaraq cihazı yeniləmək qərarı vermək olmaz. Hesab tərəfdən API açarının idarə olunması, istifadənin izlənməsi və lazım gələrsə ödənişli səviyyənin xərcinin qiymətləndirilməsi vacibdir. Ödənişli istifadəyə keçmək üçün Cloud Billing və əvvəlcədən ödəniş tələb olunur; komandaların istifadə məsuliyyətini və büdcə nəzarətini əvvəlcədən müəyyənləşdirməsi faydalıdır.

Tez-tez rast gəlinən səhvlər və növbəti addımlar

• Açar təyin edilməyib: Python faylını GEMINI_API_KEY dəyişəninin təyin olunduğu mühitdən icra edin.

• Paket başqa mühitə quraşdırılıb: google-genai paketinin kodu icra edən Python mühitində olduğuna əmin olun.

• Prompt həddən artıq ümumidir: Məkanın növünü, mətnin məqsədini və cavab formatını göstərin.

• Cavabı təsdiqlənmiş layihə məlumatı hesab etmək: Mətni dizayn qərarı və ya texniki yoxlama kimi qəbul etməyin; komanda tərəfindən qiymətləndirilməsini təmin edin.

• Ödənişli istifadəyə plansız başlamaq: Ödənişli istifadəyə keçməzdən əvvəl Cloud Billing və əvvəlcədən ödəniş şərtlərini nəzərdən keçirin.

İlk sorğunuz işlədikdən sonra dərhal geniş avtomatlaşdırma qurmaq əvəzinə komandada tez-tez təkrarlanan, sərhədləri müəyyən edilmiş bir mətn tapşırığı seçin. Promptu kiçik addımlarla təkmilləşdirin, nəticələrin yararlılığını, tələb olunan düzəlişlərin həcmini və API istifadəsini izləyin. Google-ın bələdçisində tətbiq hazırlamaq üçün SDK-lar, skript və ya komanda sətri işinin birbaşa API sorğusu göndərməsi üçün isə Gemini API CLI seçimi də izah olunur. Bu təlimdə kod nümunələri Python SDK-sı və Interactions API ilə məhdudlaşdırılıb.

Mənbə və lisenziya

Bu təlim Google-ın Gemini API üçün dərc etdiyi “Getting started” bələdçisindən (K1) istifadə edilərək Azərbaycan dilinə uyğunlaşdırılıb. Mənbə CC BY 4.0 lisenziyası ilə dərc olunub. Memarlıq və interyer mövzulu nümunə promptlar bu təlim üçün xüsusi hazırlanıb.