Qazanclar:
- LLM API sorğusunun əsas strukturunu təsvir edə bilər (son nöqtə, model, mesajlar, max_tokens)
- Sistem, istifadəçi və köməkçi rolları və vətəndaşlığı olmayan söhbət tarixçəsi arasındakı fərqi başa düşür
- Qaytarılan cavabın sahələrini (məzmun blokları, stop_reason, istifadə) oxuya və şərh edə bilər
Əvvəlki modullarda biz söhbət pəncərəsindən süni intellektdən istifadə edirdik. Ancaq AI-ni öz məhsulunuza, avtomatlaşdırmanıza və ya iş prosesinizə daxil etmək istəyirsinizsə, söhbət interfeysi onu kəsməyəcək; Modelə proqramlı şəkildə, yəni kod və ya avtomatlaşdırma vasitəsi ilə qoşulmaq lazımdır. Bu körpünün adı API-dir (Application Programming Interface, iki proqram təminatının müəyyən qaydalarla danışmasına imkan verən müqavilə). Bu bölməni bitirdikdə siz LLM (Böyük Dil Modeli) API sorğusunun nədən ibarət olduğunu, hansı mesaj rollarının yerinə yetirildiyini və cavabı necə oxuyacağınızı biləcəksiniz. Bu, modulun qalan hissəsinin qurulacağı təməldir.
API necə işləyir?
API-də əsas axın belədir: müəyyən formatda sorğu göndərirsiniz; Server müəyyən bir formatda cavab qaytarır. LLM-lərdə bu adətən bir ünvana (son nöqtə, sorğunuzu idarə edən serverdəki sabit ünvan) HTTP zəngidir (HTTP: internetdə sorğu-cavab daşımaq üçün standart protokol). Məsələn, mesajlaşma API-də bütün sorğular bir ünvana gedir və JSON (JavaScript Object Notation — həm insanlar, həm də maşınlar tərəfindən oxuna bilən açar/dəyər cütlərindən ibarət mətn formatı) kimi bədəndə daşınır.
Sorğuda ən azı bu üç şeyi qeyd edirsiniz:
- Model: Hansı modeldən istifadə edəcəksiniz (məsələn, sürətli və ucuz model və ya güclü model).
- max_tokens: Modelin istehsal edə biləcəyi tokenlərin maksimum sayı (mətnin işləndiyi ən kiçik vahid, növbəti bölmədə ətraflı şəkildə işlənəcək); yəni çıxış limiti.
- mesajlar: Söhbəti təşkil edən mesajların siyahısı.
Addım-addım: Sorğunu necə qurmaq olar
- Son nöqtəni və etimadnamələri hazırlayın. Başlıqdakı sorğuya API açarınızı (şəxsiyyətinizi sübut edən gizli sətir) əlavə edirsiniz. Siz heç vaxt açarı kodda yerləşdirməmisiniz; Biz 9-cu bölmədə təhlükəsiz saxlama sahəsini əhatə edəcəyik.
- Modeli və çıxış limitini seçin. Yüngül model + sadə tapşırıq üçün kiçik max_tokens; Güclü model + mürəkkəb tapşırıq üçün daha böyük limit.
- Mesaj siyahısını qurun. List the system instruction, user message, and past rounds (if any).
- Sorğunu göndərin və cavabı təhlil edin. Qaytarılan JSON-dan mətn məzmununu oxuyun, səbəb və nişan istifadəsini dayandırın.
Mesaj rolları: sistem, istifadəçi, köməkçi
Söhbət ardıcıllıqla düzülmüş mesajlardan ibarətdir və hər mesajın öz rolu var. Rol modelin həmin mətnlə necə davranacağını müəyyən edir.
Rol
Kim yazır
Məqsəd
sistemi
Tərtibatçı/operator
Bütün söhbət boyu tətbiq olunan daimi təlimatlar, şəxsiyyət və qaydalar
istifadəçi
son istifadəçi
İstifadəçinin cari sualı və ya girişi
köməkçi
model
Model tərəfindən hazırlanmış cavab (və əvvəlki cavablar)
Sistem rolu əksər provayderlərdə sorğu orqanında ayrıca sistem sahəsi kimi mövcuddur; istifadəçi və köməkçi mesajlar siyahısında ardıcıl olaraq qeyd olunur. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "sistem": "Siz korporativ dəstək köməkçisisiniz. Qısa, rəsmi və təsdiqlənmiş cavab verin. Əmin olmadığınız məlumatı uydurmayın.", "mesajlar": [ { "rol": "istifadəçi", "məzmun": "prosesimi qaytarıram?" } ]}
Nitq Vətənsizdir
Ən çox yayılmış yanlış təsəvvür budur: LLM API çağırışları vətəndaşsızdır — server iki sorğu arasında yaddaş saxlamır. Model əvvəlki sorğunuzu xatırlamır. Əgər siz çoxtərəfli söhbət qurursunuzsa, hər yeni sorğu ilə keçmiş raundları yenidən göndərməlisiniz. Modelin "yaddaşı" göndərdiyiniz mesajların siyahısından ibarətdir.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "rol": "user", "content": "Salam, mənim adım Dənizdir." }, { "rol": "assistent", "content": "Salam Dəniz, sənə necə kömək edə bilərəm?" }, { "rol": "istifadəçi", "məzmun": "Adımı dedim, yadınızdadır?" } ]}
Üçüncü mesaja düzgün cavab vermək əvvəlki hər iki mesajı göndərməyinizdən asılıdır. Göndərməsəniz, model "Dəniz"i bilməyəcək və səhv cavab verəcək. Bu da birbaşa xərcə təsir edir: söhbət nə qədər uzun olarsa, siyahı da bir o qədər böyük olar, hər sorğu daha çox token istehlak edir.
İpucu: Uzun söhbətlərdə bütün tarixçəni göndərmək əvəzinə köhnə dövrləri ümumiləşdirmək və köçürmək (xülasə + son bir neçə tur) xərcləri azaldır və kontekst pəncərəsini qoruyur. Bunu 6 və 11-ci bölmələrdə dərinləşdirəcəyik.
Cavabı Oxuyun
Model cavab qaytardıqda, siz düz mətn deyil, strukturlaşdırılmış obyekt alırsınız. Tipik sahələr:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "rol": "assistent", "content": [ { "növ": "mətn", "mətn": "Geri qaytarmağa başlamaq üçün hesabınızdakı "Sifarişlərim" səhifəsinə keçin..." } ], "stop_:us":" "input_tokens": 47, "output_tokens": 88 }}
- məzmun: Cavabın özü; Bu məzmun bloklarının siyahısıdır. Mətn blokunun mətn sahəsi faktiki cavabdır.
- stop_reason: Model niyə dayandı. son_dönüş = təbii son; max_tokens = çıxış limitində ilişib (cavab natamam ola bilər); imtina = təhlükəsizlik səbəbi ilə rədd edildi. Kodunuz həmişə əvvəlcə stop_reason-a baxmalıdır.
- istifadə: Giriş və çıxış işarəsi nömrələri. Xərc və limit izləmənin əsasını təşkil edir.
Diqqət: stop_reason max_tokens olarsa, cavab tamamlanmayıb. Buna “uğurlu cavab” kimi yanaşmaq və istifadəçiyə mətnin yarısını göstərmək istehsalda ən çox yayılmış səhvlərdən biridir. Ya max_tokenləri artırın, ya da axından istifadə edin.
Zəif məlumat / Güclü göstəriş
İki fərqli sistem sorğusu ilə eyni tapşırıq:
# ZƏFSİZSən köməkçisən. Suallara cavab verin.
# GÜÇLÜ Siz korporativ dəstək köməkçisisiniz. Qaydalar: - Yalnız təqdim olunan siyasət sənədindəki məlumatlara etibar edin; Əgər sənəddə yoxdursa, “məndə bu məlumat yoxdur, aidiyyatı bölməyə yönləndirirəm” deyin. - Cavablar 3 cümlədən çox olmamalı, formal və aydın olmalıdır. - Şəxsi məlumatları (TC ID nömrəsi, kart nömrəsi) istəməyin və təkrar etməyin. - Əmin olmadığınız zaman təxmin etməyin.
Güclü versiya; O, əhatə dairəsini, formasını, təhlükəsizlik marjasını və qeyri-müəyyənlikdə davranışı müəyyən edir. Model çıxışının ardıcıllığı birbaşa bu aydınlıqdan irəli gəlir.
Üç mini qutu
Case 1 — Dəstək botu (vətəndaşsızlıq tələsi). Bir e-ticarət komandası botu canlı olaraq götürdü; İstifadəçi “əvvəlki sifarişi ləğv et” dedikdə, bot sifariş nömrəsini “unudub”. Səbəb: hər sorğunu yalnız son mesajla göndərirdilər. Həll yolu: mesajlar siyahısına son 6 raund əlavə etdilər. Nəticə: kontekst qorunub saxlanıldı, lakin sorğu üzrə daxiletmə 40 tokendən ~600 tokenə qədər artdı — biz 2-ci bölmədə xərc dərsini əhatə edəcəyik.
2-ci hal — Müqavilənin natamam xülasəsi. Hüquqi qrup 10 səhifəlik müqavilələri qeyd edirdi; max_tokens: 300 aşağı qaldı, xülasələr cümlənin ortasını kəsirdi. stop_reason hər dəfə max_token idi, lakin heç kim baxmırdı. max_tokens 1500-ə qədər artırıldı və stop_reason yoxlanışı əlavə edildi; Kəsilmiş xülasə nisbəti 18%-dən 0%-ə enmişdir.
Məsələn 3 - Rolların qarışdırılması. Marketinq qrupu bütün təlimatları istifadəçi mesajına yazır, sistemi boş qoyurdu. İstifadəçi girişi təlimatla qarışdıqda, model bəzən istifadəçinin “əvvəlki qaydaları unutma” əmrinə əməl edirdi. Onlar sistemə daimi qaydaları köçürdülər; İstifadəçi girişini təlimatdan ayırmaqla, qayda pozuntuları əhəmiyyətli dərəcədə azalıb.
Ümumi səhvlər
- Keçmişi göndərməyi unutmaq: Modelin "xatırlamadığı" düşünülür; halbuki vətəndaşlığı olmayandır. Siz konteksti daşıyırsınız.
- `stop_reason`a baxılmır: max_tokens ilə dayandırılmış cavab tamamlanmış sayılır.
- Təlimatın “istifadəçi”yə daxil edilməsi: Sistemə davamlı qaydalar; ani giriş istifadəçiyə gedir. Qarışdırma təhlükəsizlik zəiflikləri yaradır.
- “Məzmun”u sadə sətirlə səhv salmaq: Cavab blokların siyahısıdır; birinci mətn blokunun mətn sahəsini oxuyun, məzmunu[0] kor indekslə əldə etməzdən əvvəl onun növünü yoxlayın.
- Açarın kodda yerləşdirilməsi: Mühit dəyişənindən istifadə edin (vahid 9).
Daha dərin: Məzmun blokları və çox hissəli cavablar
Cavabdakı məzmun sahəsinin niyə siyahı olduğunu başa düşmək daha sonra qarşılaşacağınız qabaqcıl funksiyalar üçün əsasdır. Bəzən model tək mətn blokunu deyil, bir neçə bloku qaytarır: düşüncə bloku, ardınca mətn bloku; və ya mətn blokundan sonra alətdən istifadə bloku. Buna görə də məzmunu[0] kor-koranə "cavab" kimi hesablamaq kövrəkdir. Düzgün yanaşma siyahıdan keçmək və onu növə görə çeşidləməkdir: tip sahəsi mətn olan blokların mətn məzmununu toplayır və digər növlərə (düşüncə, alət) ayrıca yanaşırsınız.
Praktikada bu fərq ondan ibarətdir ki, siz modelin əsaslandırmasını (əgər varsa) istifadəçiyə açıqlamadan daxil edə, alət çağırışlarını ayrı məntiqə yönləndirə və yalnız faktiki cavabı ekranda çap edə bilərsiniz. Modul irəlilədikcə (xüsusilə 4 və 11-ci bölmələrdə) bu blok strukturunun çıxışı yoxlamaq və yönləndirmək üçün nə qədər faydalı olduğunu görəcəksiniz.
Başqa bir praktik məqam: eyni modelə müxtəlif provayder platformalarından (birbaşa API, bulud provayderi vasitəsilə) daxil ola bilərsiniz. Son nöqtə ünvanı və autentifikasiya formatı dəyişə bilsə də, mesaj rolları, vətəndaşlıqsızlıq və cavab strukturu kimi əsas anlayışlar eyni qalır. Beləliklə, bu bölmədəki əsaslar hansı platformadan istifadə etməyinizdən asılı olmayaraq tətbiq olunur.
Xülasə
LLM API sorğusu model, çıxış limiti və mesaj siyahısından ibarətdir; rollar (sistem, istifadəçi, köməkçi) modelin davranışını müəyyən edir. Zənglər vətəndaşsızdır: hər sorğu ilə konteksti daşıyırsınız. Cavab strukturlaşdırılmış obyektdir; Məzmunu, stop_reason və istifadə sahələrini oxumaq və şərh etmək istehsalda davamlılığın əsasını təşkil edir.
Tətbiq tapşırığı
Öz peşənizdən bir tapşırıq seçin (məsələn, daxil olan e-poçtu çeşidləmək, qısa xülasələr yaratmaq). Bir kağız parçasına: (1) 4-5 qayda ilə sistem sorğusunu yazın, (2) nümunə istifadəçi mesajı və əgər varsa, 2 raund tarixçəsi qurun, (3) max_tokens üçün ağlabatan dəyər təyin edin və əsaslandırmanı yazın, (4) qaytarılan cavabda hansı stop_reason dəyərlərini və necə idarə edəcəyinizi siyahıya alın.
yoxlama siyahısı
- [ ] Mən sorğunun üç məcburi hissəsini (model, max_tokens, mesajlar) saya bilərəm.
- [ ] Sistem, istifadəçi və köməkçi rolları arasındakı fərqi izah edə bilərəm.
- [ ] Mən bilirəm ki, zənglər vətəndaşsızdır və keçmişi daşımalıyam.
- Mən [ ] məzmun, stop_reason və istifadə sahələrini oxuya və şərh edə bilərəm.
- [ ] max_tokens ilə mən kəsilmiş cavabı fərq edə və idarə edə bilərəm.