Как да направите структурирани LLM изходи преносими в OpenAI, Anthropic и Gemini

Структурираните LLM резултати стават крехки, когато екипите третират поддръжката на доставчика като взаимозаменяема. OpenAI, Anthropic и Gemini могат да генерират структурирани данни, но не излагат един и същ договор. Синтаксисът на схемата, обвивките за извикване на инструменти, гаранции за строгост, поведение при отказ, поведение при поточно предаване и режими на неуспешно валидиране се различават достатъчно, че анализатор, който работи с един модел, може тихо да се провали с друг.

Практическото решение е да спрете да третирате специфичните за доставчика структурирани изходни функции като бизнес договор. Дефинирайте един каноничен изходен договор за всеки работен поток, компилирайте го в поддържания формат на заявка на всеки доставчик, валидирайте всеки отговор спрямо каноничната схема и тествайте всеки модел, преди да му бъде разрешено да обслужва производствен трафик.

Какво е преносим структуриран изход?

Преносим структуриран изход означава, че приложението може да разчита на една и съща форма на отговор на бизнес ниво, дори когато основният доставчик на модел се промени. Това не означава, че всеки доставчик получава една и съща JSON схема. Това също не означава, че валидирането от страна на доставчика е достатъчно.

Преносимият договор има пет слоя:

• Каноническа схема: форма на данни на работния поток, неутрална спрямо доставчика.
• Линтинг за преносимост: проверява дали схемата избягва конструкции, които не се поддържат, прилагат се слабо или са рискови при различните доставчици.
• Компилация на доставчика: превод от каноничния договор в OpenAI, Anthropic, Gemini или естествена повърхност за структуриран изход на друг доставчик.
• Валидиране по време на изпълнение: валидиране от страна на приложението на върнатия обект спрямо каноничната схема.
• Договорни тестове: повторяеми тестове, които доказват, че всеки модел обработва задължителни полета, изброявания, откази, съкращаване, неправилно формирани заявки и семантични крайни случаи, преди да се промени производственият маршрут.

Този модел е особено важен за корпоративен LLM API, където няколко екипа, наематели или работни процеси на партньори зависят от предвидими договори за изход.

Факти: Структурираният изход на доставчика не е един стандарт

Преди да проектирате слоя за преносимост, отделете документираното поведение на доставчика от предположенията.

OpenAI

OpenAI документира структурирани изходи за разлика от режим JSON. Режимът JSON е предназначен да осигури валиден JSON, докато структурираните изходи са предназначени да съответстват на предоставена схема JSON. OpenAI поддържа структуриран изход чрез форматиране на отговора и чрез извикване на функция със стриктно спазване на схемата, но документираното поведение включва ограничения на модела и версията и поддържано подмножество на схемата. Неподдържаните схеми в строг режим могат да доведат до грешки API и приложенията все още трябва да обработват крайни случаи.

Anthropic

Anthropic документи Claude използване на инструмента като структурирани извиквания на инструменти въз основа на предоставени от разработчиците инструменти с input_schema. Моделът връща блок tool_use и приложението изпълнява искания инструмент. Това прилича на извикване на функция, но не е същият договор като OpenAI отговор-формат JSON схема отговор. Инженерните указания на Anthropic също отбелязват, че JSON Схемата може да дефинира структура, задължителни полета и изброявания, но не може да изрази модели на използване, като например кога незадължителните параметри трябва да бъдат включени или кои комбинации от полета имат бизнес смисъл.

Gemini

Google Gemini API казва, че структурираният изход може да бъде конфигуриран за JSON отговори и че Gemini структурираният изходен режим поддържа подмножество от JSON спецификацията на схемата. Това има значение, защото схема, която е валидна JSON Схема все още може да е неподходяща като преносима схема за заявка на доставчик.

Наблюдаемост

Семантичните конвенции на OpenTelemetry GenAI включват атрибути за доставчик, заявен модел, модел на отговор, тип изход, причини за завършване, използване на токени, дефиниции на инструменти, аргументи за извикване на инструменти и свързани полета за заявка и отговор на GenAI. Тези полета могат да поддържат отстраняване на грешки при кръстосани доставчици, когато грешките в структурирания изход са трудни за разграничаване от проблеми с подкана, схема, модел или доставчик.

Стъпка 1: Дефиниране на каноничната бизнес схема

Започнете с бизнес процеса, а не с доставчика API. Всеки работен процес за сортиране на поддръжка, работен процес за извличане на фактури, препоръка за одобрение или крайна точка за автоматизация, насочена към партньор, трябва да има канонична схема, която представя това, от което се нуждае приложението надолу по веригата.

Например работен поток за поддръжка и сортиране може да използва тази канонична форма:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["category", "priority", "summary", "requires_human_review"],
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "security", "account", "other"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "high", "urgent"]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "requires_human_review": {
      "type": "boolean"
    },
    "customer_risk_signals": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    }
  }
}

Тази схема е договорът, на който се доверява останалата част от приложението. От него се генерират специфични за доставчика формати на заявки; те не са източникът на истината.

Използвайте изрично задължителни полета, ограничени масиви, ограничени низове, затворени преброявания и additionalProperties: false там, където вашият валидатор го поддържа. Избягвайте приемането на произволни вложени обекти, освен ако системата надолу по веригата не е проектирана да обработва произволни ключове.

Стъпка 2: Добавете схема за преносимост Стъпка

Линтерът за преносимост трябва да отхвърля схеми, които са технически валидни JSON Схема, но рискови за използване с няколко модела. Целта не е пълна JSON изразителност на схемата. Целта е стабилен изходен договор, който може да бъде компилиран в няколко повърхности на доставчика, без да се отслабва гаранцията на приложението.

Полезните проверки за мъх включват:

• Отхвърлете неподдържаните ключови думи за съставяне, освен ако вашият компилатор няма изрични съпоставяния на доставчика за тях.
• Отхвърляне на неограничени object полета, които позволяват произволни свойства.
• Изискване на enum за класификационни полета, които управляват маршрутизиране, таксуване, одобрения или състояние, видимо от партньора.
• Изискване maxItems за масиви, използвани при автоматизиране или показване на потребителски интерфейс.
• Изискване maxLength за текстови полета, които въвеждат бази данни, опашки или партньорски API.
• Маркиране на незадължителни полета, чиято липса променя бизнес значението.
• Отхвърляне на схеми, чието влагане или размер надхвърля известните ограничения на доставчика във вашата матрица на възможности.

Linter трябва да работи в CI и преди внедряването на схемата. Не чакайте, докато производствена заявка попадне на грешка на доставчика, защото ключова дума от схемата не се поддържа.

Стъпка 3: Компилирайте във формати на заявки, специфични за доставчика

Компилацията на доставчика превежда каноничната схема в API повърхността, която всеки модел действително поддържа. Компилаторът трябва да бъде детерминистичен и с версии. Трябва също така да остави одитна пътека, показваща коя канонична версия на схемата е произвела кой полезен товар за заявка на доставчик.

OpenAI компилация

За OpenAI компилаторът може да се насочи към структурирани изходи чрез форматиране на отговор за задачи за извличане и класифициране или строго извикване на функция за ориентирани към действие работни потоци. Компилираният полезен товар трябва да включва поддържаното подмножество на схемата и специфични за доставчика настройки за строгост, когато са налични.

Anthropic компилация

За Anthropic компилаторът често ще представя желания резултат като инструмент с input_schema. След това приложението очаква блок за използване на инструмента и валидира входа на инструмента спрямо каноничната схема. Това означава, че адаптерът трябва да нормализира обвивката на отговора, а не просто да анализира JSON.

Gemini компилация

За Gemini компилаторът трябва да насочи своята структурирана JSON конфигурация на отговор, като използва само поддържаното подмножество от схеми. Ако канонична схема използва ограничения, които Gemini не се прилагат естествено, компилаторът трябва да запише тези ограничения като изискващи валидиране от страна на приложението.

Изходът на адаптера трябва да бъде нормализиран в един вътрешен тип резултат:

type StructuredResult = {
  provider: "openai" | "anthropic" | "gemini";
  model: string;
  schema_version: string;
  status: "ok" | "refusal" | "truncated" | "provider_error" | "invalid";
  raw_response: unknown;
  parsed_output?: unknown;
  finish_reason?: string;
};

Тази нормализация предпазва кода на работния поток надолу по веригата от зависимост от пликовете на доставчика.

Стъпка 4: Валидирайте всеки отговор спрямо каноничната схема

Структурата от страна на доставчика е първата линия на защита, а не крайната проверка за коректност. Винаги проверявайте анализирания изход спрямо каноничната схема, след като моделът отговори.

Проверката по време на изпълнение трябва да генерира структурирани грешки като:

• missing_required_field
• invalid_enum
• unexpected_property
• type_mismatch
• array_too_long
• string_too_long
• semantic_rule_failed

Дръжте структурното валидиране отделно от семантичното валидиране. JSON Схемата може да проверява формата, задължителните свойства, изброяванията и основните ограничения на типа. Той не може да изрази напълно бизнес правила като валидни преходи на състояния, прагове за одобрение, специфични за клиента правила или взаимно зависими комбинации от полета.

Например това е семантичен валидатор, а не правило за схема:

if (output.priority === "urgent" && output.requires_human_review !== true) {
  throw new SemanticValidationError(
    "urgent tickets must require human review"
  );
}

Поставете тези проверки в кода на приложението, където те могат да използват конфигурацията на клиента, състоянието на работния поток, контекста на оторизацията и версията на правилата.

Стъпка 5: Използвайте ограничена поправка, след което неуспешно затваряне

Пътят за поправка може да се възстанови от малки изходни дефекти, но също така може да скрие системна схема и проблеми с подканите. Използвайте един целенасочен опит за ремонт с включена грешка при валидиране. Ако поправеният отговор все още не е валидиран, неуспешно затваряне или насочване към преглед.

Една практическа политика за ремонт изглежда така:

• Опит за поправка само за допустими типове грешки, като липсващи задължителни полета, невалидни изброявания или неправилно образувани JSON.
• Не поправяйте откази на доставчик, безопасни блокове, неуспешни авторизации или чувствителни към правилата изходи.
• Включете версията на каноничната схема и грешката при валидиране в подканата за поправка.
• Разрешаване на най-много един опит за поправка за видими от клиента или задействащи действия работни процеси.
• Брой поправки на регистрационни файлове, успех на поправката, използване на токен и крайно състояние.

За задачи за вътрешно извличане с нисък риск може да е приемлив втори опит за поправка, ако забавянето не е важно. За работни потоци, които задействат плащания, промени в достъпа, отговори на партньор API или действия за съответствие, правилото за затваряне при отказ обикновено е по-безопасно.

Стъпка 6: Изграждане на договорни тестове за всеки производствен модел

Договорните тестове решават дали даден модел отговаря на условията за работен процес. Те трябва да се изпълняват преди първоначалното стартиране, преди надстройките на модела и преди промените в правилата за маршрутизиране.

Тествайте всеки модел и адаптер на доставчик най-малко за:

• Валиден резултат за щастлив път.
• Липсващи задължителни полета.
• Невалидни стойности на enum.
• Допълнителни свойства, когато схемата е затворена.
• Твърде много елементи от масив.
• Прекалено дълги низове.
• Отказ или невъзможност за спазване.
• Скъсен изход.
• Несъответствие при повикване на инструмент или липсващо извикване на инструмент.
• Структурно валиден, но семантично грешен изход.

Използвайте състезателни подкани, които оказват натиск върху модела да наруши договора. Например, помолете го да добави допълнително поле за обяснение, да върне приоритет извън enum или да пропусне задължително булево значение. Тестът преминава само ако доставчикът плюс адаптерът плюс валидаторът генерират очаквания статус на приложението.

За всеки работен процес поддържайте прост запис за съвместимост:

{
  "workflow": "support_triage",
  "schema_version": "2026-09-24",
  "model": "provider-model-name",
  "supports_strict_schema": true,
  "supports_tool_calling": true,
  "supports_streaming_structured_output": false,
  "refusal_signal_normalized": true,
  "contract_tests_passed": true,
  "known_limitations": ["max schema depth 4"]
}

Тази матрица на възможностите принадлежи към контролната равнина, а не към разпръснатите константи на приложението.

Стъпка 7: Надеждност на структурирания изход на инструмента

Без телеметрия екипите не могат да разберат дали грешките идват от несъвместимост на доставчика, отклонение на модела, дефекти на схемата, дефекти на подканите, съкращаване или валидатори надолу по веригата.

Регистрирайте тези полета за всяка заявка за структуриран изход:

• Име на работния поток и версия на схемата.
• Доставчик, заявен модел и модел на отговор.
• Режим на изход, като схема на отговор, извикване на инструмент или JSON режим.
• Статус на проверка и тип грешка.
• Брой ремонти и резултат от ремонта.
• Причина за приключване и статус на отказ.
• Токени за подкана, токени за завършване, обща цена и закъснение.
• Версия на адаптера и версия на компилатора.

Използвайте тези данни, за да сравните модели, преди да промените маршрута. По-евтиният модел не е по-евтин, ако увеличава опитите за ремонт, ръчен преглед, откази на партньор API или обработка на инциденти надолу по веригата.

Компромиси за изрично решение

Схемите с най-нисък общ знаменател подобряват преносимостта, но отслабват ограниченията. Ако схемата на заявката на доставчика трябва да бъде опростена, запазете по-строги проверки в каноничното валидиране и семантичните валидатори.

Специфичната за доставчика компилация запазва естествените силни страни, но добавя поддръжка. Това обикновено си струва за производствени работни потоци, но само ако компилаторите са с версии и са обхванати от договорни тестове.

Строгите схеми намаляват неуспехите на анализатора, но изискват по-добър дизайн на задачата. Ако задачата е недостатъчно определена, строгостта разкрива неяснотата по-рано. Това е полезно, но може да забави първоначалното развитие.

Поправката подобрява процента на завършване, но добавя разходи и забавяне. Ограничената поправка е механизъм за възстановяване, а не заместител на дизайна на схемата.

Извикването на инструмент и форматът на отговор JSON обслужват различни работни потоци. Извикването на инструмент често е по-подходящо за работни потоци, ориентирани към действие. Форматът на отговора JSON е по-прост за извличане, класифициране и обобщаване. Платформа с няколко модела може да поддържа и двете, но политиката на работния процес трябва да е изрична.

Прогнози: Накъде върви преносимостта на структурирания изход

Поддръжката на доставчика за структуриран изход вероятно ще продължи да се подобрява, но не трябва да се предполага пълна JSON преносимост на схемата между моделите. Доставчиците имат различни архитектури на модели, API истории, модели на използване на инструменти и поведение при безопасност. Дори когато поддръжката на схеми стане по-силна, приложенията пак ще се нуждаят от канонично валидиране, тъй като коректността на бизнеса зависи от повече от JSON форма.

Екипите трябва да очакват решенията за маршрутизиране на структуриран изход да станат в по-голяма степен управлявани от данни. Надеждността, степента на ремонт, обработката на отказите, забавянето и цената ще имат значение заедно с качеството на модела. Оперативният въпрос ще се измести от "този модел поддържа ли JSON?" до „този модел отговаря ли на договора на този работен поток на приемлива цена и процент на неуспех?“

Контролен списък за внедряване

• Дефинирайте една канонична схема за всеки работен поток.
• Схеми на версиите и запазване на възпроизводимостта на заявките на доставчика.
• Добавете CI linting за неподдържани или рискови функции на схема.
• Компилирайте канонични схеми в специфични за доставчика формати.
• Нормализиране на пликовете на доставчика в един вътрешен тип резултат.
• Потвърдете всеки анализиран отговор спрямо каноничната схема.
• Добавяне на семантични валидатори за бизнес правила.
• Разрешаване само на ограничени опити за поправка.
• Неуспешно затваряне или насочване към преглед за високорискови работни потоци.
• Изпълнете договорни тестове, преди да добавите или надстроите производствени модели.
• Поддържане на матрица на възможностите на модела в контролната равнина.
• Полета за проверка, поправка, цена, латентност, доставчик и модел за всяка заявка.

Приложимо заключение

Преносимостта на структурирания изход е API проблем с договора, а не проблем с бързото форматиране. Надеждният модел е да се дефинира канонична бизнес схема, да се направи линт за преносимост, да се компилира в естествената повърхност на всеки доставчик, да се валидира всеки отговор, след като доставчикът го върне, и да се използват договорни тестове, за да се реши кои модели са допустими за производство.

Този дизайн добавя известна предварителна инженерна работа, но предотвратява по-скъпия режим на повреда: системи надолу по веригата приемат стабилен договор, докато маршрутизирането на модела, поведението на доставчика или прилагането на схема тихо се променят под тях.

Свързано четене

• резервно маршрутизиране, което защитава структуриран изход договори