JSON mode სქემას არ იცავს — როდის გჭირდებათ Structured Outputs

თუ აპლიკაცია პასუხში განსაზღვრულ ველებს, ტიპებსა და მნიშვნელობებს ელის, JSON mode საკმარისი არ არის: ის პარსირებად JSON-ს უზრუნველყოფს, მაგრამ სქემის დაცვას ვერ ჰპირდება. OpenAI-ის რეჟიმების შედარება ამ განსხვავებას პირდაპირ ასახელებს: Structured Outputs პასუხს მხარდაჭერილ JSON Schema-ს უსადაგებს. არჩევანი დამოკიდებულია იმაზეც, შედეგი მონაცემად გამოიყენება თუ აპლიკაციაში მოქმედებას იწყებს.

ტექსტიდან მონაცემების ამოსაღებად ან მომხმარებლისთვის განსაზღვრული ფორმის პასუხის მისაცემად გამოიყენეთ Structured Outputs. როცა მოდელმა გარე ფუნქციას არგუმენტები უნდა გადასცეს, გამოიყენეთ function calling და, თუ სქემის დაცვა საჭიროა, მისი მკაცრი რეჟიმი. ორივე შემთხვევაში აპლიკაციამ ცალკე უნდა დაამუშაოს უარი, შეწყვეტილი პასუხი და შინაარსობრივად მცდარი მნიშვნელობა.

სწორი სინტაქსი რატომ არ ნიშნავს სწორ მონაცემს

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

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

რომელი გზა შეესაბამება სამ ჩვეულებრივ სცენარს

გადაწყვეტილებისთვის შეხედეთ, ვინ მოიხმარს შედეგს და უნდა გამოიწვიოს თუ არა მან მოქმედება. ერთსა და იმავე JSON ფორმას შეიძლება სამი განსხვავებული დანიშნულება ჰქონდეს:

• ტექსტიდან მონაცემების ამოღება — Structured Outputs. პირობითად, ქართულ განცხადებაში მისამართი, სამუშაო დრო და საკონტაქტო ნომერია მოსაძებნი. სქემაში თითოეული ველის ტიპი აღწერეთ, ხოლო დაკარგული ინფორმაციისთვის წინასწარ შეთანხმებული მნიშვნელობა განსაზღვრეთ. ასე გამოტოვებული ნომერი და მოდელის მიერ გამოცნობილი ნომერი ერთსა და იმავე წარმატებულ პასუხად არ ჩაითვლება. თუ მხარდაჭერილი სქემა ამოცანას ვერ გამოხატავს, JSON mode-ს დაუმატეთ საკუთარი ვალიდაცია.
• მომხმარებლისთვის სტრუქტურირებული პასუხი — Structured Outputs. როცა ინტერფეისი სათაურს, მოკლე პასუხსა და განმარტებას ცალ-ცალკე აჩვენებს, ეს ნაწილები სქემის ველებად აღწერეთ. ინტერფეისს აღარ უწევს თავისუფალი ტექსტიდან სათაურის გამოცნობა. სქემა უზრუნველყოფს ნაწილების ფორმას; პასუხის სიზუსტე და შესაბამისობა მომხმარებლის შეკითხვასთან კვლავ ცალკე შესაფასებელია.
• ინსტრუმენტის გამოძახება — function calling. კალენდარში ჩანაწერის შექმნა ან მონაცემთა ბაზაში ძიება მოითხოვს ფუნქციის გამოძახების არგუმენტებს და ამ ფუნქციის შესრულებას აპლიკაციის მხარეს. OpenAI-ის function calling-ის გზამკვლევი აღწერს არგუმენტების JSON Schema-ს, მკაცრ რეჟიმს და გამოძახების შესრულების ეტაპებს. მკაცრ რეჟიმში თითოეული ობიექტისთვის დამატებითი ველები უნდა აიკრძალოს, ხოლო აღწერილი ველები სავალდებულოდ განისაზღვროს; საჭიროებისას მნიშვნელობა შეიძლება null იყოს. მოქმედების ნებართვა და პირობები უშუალოდ თქვენს კოდში მოწმდება.

ამ არჩევანში Structured Outputs და function calling სხვადასხვა ამოცანას ასრულებს. პირველი აყალიბებს მომხმარებლისკენ მიმავალ პასუხს, მეორე კი მოდელს თქვენი სისტემის ფუნქციასთან აკავშირებს. Function calling-ის არგუმენტებიც შეიძლება სქემას მკაცრად დაექვემდებაროს; ფორმის დაცვა ფუნქციის ავტომატურ შესრულებას არ ნიშნავს.

სქემა, რომელიც პროვაიდერის შეცვლას გაუძლებს

JSON Schema-ს საერთო სახელი არ ნიშნავს, რომ ყველა პროვაიდერი მის ყველა შესაძლებლობას ერთნაირად იღებს. Gemini API-ის Structured Outputs-ის აღწერა მიუთითებს, რომ Gemini მხარს უჭერს JSON Schema-ს ნაწილს; მის SDK-ებში სქემის განსაზღვრა Pydantic-ით Python-ში და Zod-ით JavaScript-ში შეიძლება. მკაცრ რეჟიმსაც საკუთარი შეზღუდვები აქვს. ამიტომ გადასატანი სქემა მცირე, მკაფიო კონტრაქტით დაიწყეთ და ორივე API-ში მისი მიღება გადაამოწმეთ.

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

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

უარი, შეწყვეტა და ვალიდაციის ჩავარდნა

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

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

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