API-ის ტერმინები

პროგრამული ინტერფეისი — API

პროგრამული ინტერფეისი განსაზღვრავს, როგორ იყენებს ერთი პროგრამა მეორის შესაძლებლობებს. ვებ API-ის აღწერა, ჩვეულებრივ, მოიცავს მოქმედებებს, შესაყვან მონაცემებსა და პასუხებს.

შენიშვნა: API-ზე წვდომა არ ნიშნავს მზა მომხმარებლის ინტერფეისს ან შენს ბიზნესსისტემებთან ავტომატურ კავშირს.

მოთხოვნის მისამართი — Endpoint

Endpoint არის მისამართი, რომელზეც API-ის მოქმედებაა ხელმისაწვდომი. HTTP API-ში გზა მეთოდთან ერთად წაიკითხე, მაგალითად, GET-თან ან POST-თან.

შენიშვნა: საბაზისო URL მხოლოდ საწყისი მისამართია. დოკუმენტაციაში მითითებული გზის ორჯერ დამატებამ შეიძლება არასწორი მისამართი წარმოქმნას.

მოთხოვნა — Request

მოთხოვნა არის შეტყობინება, რომლითაც კლიენტი სერვერს მოქმედების შესრულებას სთხოვს. ის შეიცავს მეთოდს, სამიზნე მისამართს, სათაურებს და ზოგჯერ შიგთავსსაც.

შენიშვნა: მოთხოვნის გაგზავნა წარმატებას არ ადასტურებს. მდგომარეობის შემცვლელი მოთხოვნის გამეორებამ მოქმედებაც შეიძლება გაიმეოროს.

პასუხი — Response

პასუხი არის სერვერის საპასუხო შეტყობინება HTTP სტატუსით, სათაურებითა და, საჭიროების შემთხვევაში, შიგთავსით. შედეგის მნიშვნელობას დოკუმენტაციაში აღწერილი ველები განმარტავს.

შენიშვნა: HTTP 200 AI-ის პასუხის სისწორეს არ ადასტურებს. შეამოწმე მოსალოდნელი ველები, დასრულების მდგომარეობა და შინაარსი.

მონაცემთა გაცვლის ტექსტური ფორმატი — JSON

JSON სტრუქტურირებულ მონაცემებს ობიექტებით, მასივებით, ტექსტური სტრიქონებით, რიცხვებით, ლოგიკური მნიშვნელობებითა და null-ით აღწერს. ობიექტის ველების სახელები და ტექსტური მნიშვნელობები ორმაგ ბრჭყალებში იწერება.

შენიშვნა: სწორი სინტაქსი სწორ სქემას არ ნიშნავს. რიცხვი 2 და ტექსტური "2" სხვადასხვა ტიპის მნიშვნელობებია.

ავთენტიფიკაცია — Authentication

ავთენტიფიკაცია ადგენს გამომძახებლის ვინაობას ან ამოწმებს წარმოდგენილ წვდომის მონაცემს. სერვისმა აპლიკაციის ამოსაცნობად შეიძლება API-ის გასაღები გამოიყენოს.

შენიშვნა: შენი სერვერის ავთენტიფიკაცია თითოეული საბოლოო მომხმარებლის ვინაობას არ ადგენს. აპლიკაციაში მომხმარებლები ცალკე უნდა შეამოწმო.

ავტორიზაცია — Authorization

ავტორიზაცია განსაზღვრავს, რომელ რესურსებსა და მოქმედებებზე აქვს გამომძახებელს წვდომის უფლება. ეს ვინაობის დადასტურებისგან განსხვავებული შემოწმებაა.

შენიშვნა: მოქმედი გასაღები ყველა უფლებას არ იძლევა. ჩანაწერებსა და მოქმედებებზე წვდომა სერვერზე შეამოწმე და არა მოდელისთვის მიწერილი ინსტრუქციით.

API-ის გასაღები — API key

API-ის გასაღები სერვისზე წვდომასთან დაკავშირებული მონაცემია. სერვერის საიდუმლო გასაღების მფლობელს შეიძლება შეეძლოს მოთხოვნების გაგზავნა მისი უფლებებით და შესაბამისი ანგარიშის ხარჯზე.

შენიშვნა: გასაღები არ არის ტექსტის ტოკენი, რომლითაც მოდელის მოხმარება ითვლება. საიდუმლო გასაღებები სერვერზე შეინახე და გამჟღავნებისას გააუქმე.

ტექსტის ტოკენი — Token

ენობრივი მოდელის მუშაობისას ტექსტის ტოკენი არის ერთეული, რომელსაც ტექსტის დამყოფი ქმნის. ის შეიძლება აღნიშნავდეს სიმბოლოს, სიტყვის ნაწილს ან მთელ სიტყვას.

შენიშვნა: ქართული სიტყვების რაოდენობით ტოკენების რაოდენობა პირდაპირ არ განისაზღვრება. გამოიყენე არჩეული მოდელის აღრიცხვის საშუალება ან მოხმარების ჩანაწერი და არა ინგლისური ტექსტის მიახლოებითი წესი.

კონტექსტის ფანჯარა — Context window

კონტექსტის ფანჯარა ზღუდავს, რამდენი ტოკენის გათვალისწინება შეუძლია მოდელს ერთ მოთხოვნაში. შესაყვანი ტექსტი, საუბრის ისტორია და პასუხისთვის განკუთვნილი მოცულობა შეიძლება საერთო ზღვარში ითვლებოდეს; გადაამოწმე კონკრეტული მოდელის ლიმიტები.

შენიშვნა: დიდი კონტექსტის ფანჯარა მუდმივი მეხსიერება არ არის და ვრცელ დოკუმენტში ყველა ფაქტის პოვნას არ გვპირდება.

მოთხოვნათა სიხშირის შეზღუდვა — Rate limit

სიხშირის შეზღუდვა განსაზღვრულ პერიოდში აქტივობას ზღუდავს, ხშირად მოთხოვნების რაოდენობით ან ტოკენების მოცულობით. HTTP 429 მიუთითებს, რომ მოთხოვნები მოქმედ ლიმიტს აჭარბებს.

შენიშვნა: საკმარისი ბალანსი სიხშირის ლიმიტს არ აუქმებს. თუ პასუხში Retry-After მითითებულია, დაიცავი მოცდის დრო და გამეორებების რაოდენობა შეზღუდე.

პასუხის ნაკადურად მიღება — Streaming

ნაკადური მიღებისას პასუხი ნაწილ-ნაწილ მოდის და მთლიანი შიგთავსის დასრულებას არ ელოდები. სერვერის მიერ გაგზავნილი მოვლენები, ანუ SSE, ერთ-ერთი ასეთი ფორმატია; ყველა ნაკადური API ერთნაირად არ არის მოწყობილი.

შენიშვნა: ქსელით მიღებული ნაწილი შეიძლება არც სრულ მოვლენას შეიცავდეს და არც სრულ JSON ობიექტს. გამოიყენე ფორმატის შესაბამისი დამმუშავებელი და შეწყვეტილი ნაკადი დასრულებულ პასუხად არ ჩათვალო.

იდემპოტენტურობა — Idempotency

მოქმედება იდემპოტენტურია, თუ ერთი და იმავე მოთხოვნის გამეორებას სერვერზე იგივე განზრახული შედეგი აქვს, რაც ერთჯერად შესრულებას. აქ იგულისხმება მოქმედების ეფექტი და არა აუცილებლად იდენტური პასუხის ტექსტი.

შენიშვნა: POST თავისთავად იდემპოტენტური არ არის. იდემპოტენტურობის გასაღები გამეორებულ მოქმედებას მხოლოდ მაშინ აღკვეთს, თუ მიმღები სერვისი ამ წესს ახორციელებს.

შუამავალი სერვისი — Gateway

შუამავალი სერვისი იღებს მოთხოვნებს და სხვა სერვისებს გადასცემს. AI-ის ინტეგრაციაში მას შეუძლია მოდელებისადმი მიმართვის საერთო შესასვლელი შექმნას; კონკრეტულ ქცევას მისი კონფიგურაცია განსაზღვრავს.

შენიშვნა: საერთო შუამავალი მოდელების შესაძლებლობებს ერთნაირს არ ხდის და პასუხების გადამოწმების საჭიროებას არ აუქმებს.

პირველწყაროები და დამატებითი ინფორმაცია

ზემოთ მოცემული განმარტებები მომზადებულია AIAPI-ის მიერ. პირველწყაროები აღწერს შესაბამის ტექნიკურ ცნებებს; მათი მითითება პარტნიორობას არ ნიშნავს.

თუ განმარტება გაუგებარია ან შეცდომა შენიშნე, მოგვწერე: [email protected].