Структуровані результати: отримання надійного JSON із мовної моделі

Перша версія кожної інтеграції LLM аналізує прозу. Ви запитуєте «три основні ризики, по одному на рядок», розділені на нові рядки, і це працює до того дня, коли модель першим напише вступне речення. Для завершення цього циклу існують структуровані виходи: ви передаєте моделі схему JSON, декодер обмежений, тому він не може видавати нічого, що порушує його, і ви отримуєте назад корисне навантаження з полями, які ви запитували. Ця гарантія реальна, але вужча, ніж здається, і різниця полягає в тому, де живуть помилки.

Що насправді покриває гарантія

Гарантії обмеженого декодування форму. Відповідь аналізуватиметься як JSON, вона матиме ваші ключі, типи збігатимуться, а поля enum міститимуть одне з указаних вами значень. Це значне покращення в порівнянні з підказкою та надією.

Це нічого не гарантує вміст. Поле, введене як рядок, міститиме рядок; чи цей рядок є точним, чи винайдений, щоб задовольнити схему, не змінюється порівняно з попереднім. Насправді сувора схема робить винахід дещо більш вірогідним, оскільки обов’язкове поле має бути чимось заповнене, а модель не має можливості сказати «немає в джерелі». Це єдиний найпоширеніший збій у виробництві: обов’язковий invoice_number в документі, який не має.

Дизайн навколо нього. Дозволити null, де можлива відсутність, додайте явний found: boolean або a "unknown" enum і ніколи не робіть поле обов’язковим, якщо відповідь справді не існує в кожному введенні.

Розробка схеми, яку модель може заповнити

Схеми, написані для перевірки, і схеми, написані для генерації, виглядають по-різному. Кілька правил, які діють для всіх провайдерів:

• Вкладені бемолі. Кожен рівень вкладеності є місцем, де модель може втратити слід. Три неглибокі об'єкти, витягнуті за три виклики, перемагають одне глибоко вкладене дерево.
• Переліки перемагають вільні рядки. Якщо поле має п’ять допустимих значень, укажіть їх. Ви видаляєте цілий клас коду нормалізації, і обмежений декодер примусово виконує його за вас.
• Назви полів є інструкціями. due_date_iso8601 дає кращий результат, ніж date з поясненням формату в окремому запиті. Назви в контексті; використовувати їх.
• використання description на полях. Більшість провайдерів передають описи схем моделі. Одне речення на неоднозначне поле дешевше та надійніше, ніж абзац прозових інструкцій вище.
• встановити additionalProperties: false. Декілька провайдерів все одно вимагають його для суворого режиму, і це не дозволяє моделі послужливо винаходити додатковий ключ, який ваш аналізатор мовчки ігнорує.
• Віддавайте перевагу масивам плоских об’єктів перед картами. Динамічні ключі — об’єкти, імена властивостей яких заздалегідь невідомі — погано підтримуються суворими режимами, і їх незручно вводити на приймальному кінці.

Постачальники також обмежують, які ключові слова схеми JSON вони підтримують у суворому режимі: oneOf, обмеження шаблонів, числові межі та рекурсія зазвичай обмежуються або ігноруються. Припустімо, що схема обмежує лише структуру, і самостійно застосуйте свої бізнес-правила після аналізу.

Все одно перевірте

Навіть у строгому режимі перевіряйте кожну відповідь, перш ніж вона торкнеться вашої бази даних. Строгий режим може бути вимкнено зміною конфігурації, резервний шлях може потрапити на модель, яка його не підтримує, повторна спроба мережі може повернути об’єкт помилки, а відповідь може бути скорочена об’єктом обмеження маркера в середині, що створює недійсний JSON, якому режим схеми не заважає.

Коли корисне навантаження не вдається, виникає корисне запитання, яке поле і чому. The Валідатор схеми JSON бере документ і схему та звітує по одному рядку для кожної проблеми із шляхом вказівника JSON, ключовим словом, яке не вдалося виконати, і фактично знайденим значенням. Це саме та форма, яка вам потрібна для двох цілей: виправлення вашої схеми під час розробки та повернення до повторної спроби — звіт про невдалу перевірку, вставлений у наступне повідомлення, є надзвичайно ефективним підказкою щодо відновлення, оскільки модель може точно бачити, що вона помилилася.

Обмежте повторні спроби однією або двома. Модель, яка двічі не відповідає схемі, зазвичай запитує щось, чого вхідні дані не містять, і третя спроба винаходить це.

Від прикладу корисного навантаження до коду

Більшість схем починаються як зразок відповіді, який хтось вставив у чат. Перетворення цього на введений, перевірений код вручну є стомлюючим і схильним до помилок, тому не робіть це.

Вставте зразок у Схема JSON до Zod і ви отримаєте схему Zod плюс виведений тип TypeScript. Він робить висновки для кожного поля, а не вводить все як рядок: значення, які виглядають як електронні листи, URL-адреси, UUID або дати ISO .email(), .url(), .uuid() і .datetime() замість голого z.string(), масиви містять свій тип елемента, а поле, тип якого змінюється в різних входженнях, стає об’єднанням, а не мовчки вибирає перше, яке побачило. Цю останню поведінку варто свідомо підживлювати: вставте три або чотири реальні відповіді, об’єднані, а не одну, щоб необов’язкові та поліморфні поля відображалися як об’єднання замість того, щоб бути заблокованими до того, що містить перший зразок.

Якщо вам потрібні лише типи, а не перевірка під час виконання — оскільки корисне навантаження надходить із джерела, якому ви вже довіряєте — JSON до TypeScript створює інтерфейси напряму, із вкладеними об’єктами, розбитими як іменовані підінтерфейси, а не як вбудовані анонімні блоби.

Зберігайте напрям правди прямо: одне визначення схеми, а все інше генерується з нього. Схема Zod і схема JSON, які обслуговуються окремо, не узгодяться протягом місяця, і розбіжність виявиться як помилка аналізу виробництва, а не помилка тесту.

Читаючи те, що повернулося

Відповіді моделі надходять мінімізованими в одному рядку, що робить їх жалюгідними. The Формат JSON робить відступи та сортує їх у щось читабельне, а його перевірка миттєво вловлює регістр усічення — корисне навантаження, яке закінчується в середині рядка, є підписом ліміту маркерів попадання, а виправленням є вищий вихідний ліміт або менша схема, а не швидка зміна.

Коли ви порівнюєте те, що дві моделі створили з однакових вхідних даних, або перевіряєте, чи миттєва зміна змінила вихідні дані так, як ви не бажали, розрізняйте відформатовані корисні навантаження, а не читайте обидва. Структурні відмінності, невидимі в стіні JSON — поле, яке непомітно перетворилося на рядок цифр замість числа — відразу виділяються в diff.

Керування версіями

Схеми змінюються, і вихід моделі змінюється разом з ними. Помістіть поле версії в корисне навантаження з першого дня, щоб збережені записи мали форму, у якій вони були записані. Переналаштування після того, як у вас є мільйон рядків JSON без тегів, — це тип міграції, на який ніхто не планує час.

Усі ці інструменти працюють локально у вашому браузері, що для цього робочого процесу важливіше, ніж зазвичай: приклади корисних навантажень, які ви перетворюєте на схеми, зазвичай є реальними відповідями API із реальними даними клієнтів у них, і їх не слід завантажувати до служби форматування для покращення.