Ustrukturyzowane dane wyjściowe w wielomodelowej bramie API: schemat JSON, wywołania narzędzi i zabezpieczenia semantyczne
Praktyczny wzorzec adaptera zapewniający niezawodne ustrukturyzowane wyniki u wielu dostawców LLM: normalizuj schematy, sprawdzaj odpowiedzi, obsługuj wywołania narzędzi, rejestruj awarie i blokuj niebezpieczne działania, zanim dotrą do produkcyjnych przepływów pracy.
Proszenie modelu o „zwrócenie JSON” nie jest umową produkcyjną. Może wygenerować prawidłowy kod JSON z nieprawidłowym wyliczeniem, pominąć wymaganą regułę biznesową lub w sposób pewny zażądać akcji, której użytkownik nigdy nie autoryzował. W przepływie pracy obejmującym wielu dostawców problem staje się trudniejszy: każdy dostawca udostępnia różne mechanizmy ustrukturyzowanego wyjścia i użycia narzędzi, a każdy obsługuje tylko część świata schematu JSON.
Praktyczne rozwiązanie to nie jedna magiczna podpowiedź. Jest to wzorzec bramy warstwowej: znormalizuj schemat pożądany przez programistę, przetłumacz go na natywne dla dostawcy formaty ustrukturyzowanych danych wyjściowych lub formaty wywołań narzędzi, jeśli to możliwe, zweryfikuj zwrócony obiekt i zastosuj bariery semantyczne przed jakimkolwiek skutkiem ubocznym.
W tym przewodniku wyodrębniono trzy różne cele, które często są ze sobą mieszane:
- Ważność składni: odpowiedź jest analizowalna w formacie JSON.
- Ważność schematu: kod JSON pasuje do wymaganych pól, typów, wyliczeń i reguł strukturalnych.
- Prawidłowość biznesowa: obiekt jest bezpieczny, wierny intencjom użytkownika i ważny dla dalszych działań.
Błąd produkcyjny: prawidłowy JSON, nieprawidłowe działanie
Rozważ automatyzację wsparcia, która kieruje przychodzące zgłoszenia:
{ "ticket_id": "t_481", "kategoria": "rozliczenia", „priorytet”: „pilne”, "akcja": "zwrot_klienta", „kwota_usd”: 499
Ten obiekt jest poprawny składniowo. Może nawet przekazać prosty schemat, jeśli action jest ciągiem znaków, a amount_usd jest liczbą. Ale nadal może się mylić. Być może klient poprosił jedynie o kopię faktury. Być może zwroty powyżej 100 USD wymagają zgody menedżera. Być może użytkownik nie jest w ogóle upoważniony do dokonywania zwrotów pieniędzy.
Ustrukturyzowane dane wyjściowe redukują błędy analizy. Nie zastępują autoryzacji, kontroli zasad, kontroli zapasów, kontroli cen, idempotencji ani potwierdzenia przez człowieka w przypadku ryzykownych operacji.
Fakty: jakie tryby ustrukturyzowanego wyjścia dostawcy zapewniają, a czego nie obiecują
Krajobraz dostawców zmienia się szybko, ale dla architektury ma znaczenie kilka stabilnych faktów:
- Tryb JSON może pomóc w tworzeniu prawidłowego formatu JSON, ale prawidłowy format JSON to nie to samo, co zgodność z określonym schematem.
- Tryby strukturalnego wyjścia natywne dla dostawcy zostały zaprojektowane w celu poprawy zgodności ze schematem, ale zwykle obsługują tylko podzbiór schematu JSON.
- Wywoływanie narzędzi zwykle lepiej pasuje do działań niż swobodny format JSON, ponieważ model wybiera zadeklarowane narzędzie i zwraca argumenty strukturalne, podczas gdy aplikacja pozostaje odpowiedzialna za wykonanie.
- Różni dostawcy ujawniają różne umowy. Jeden może używać ścisłego formatu odpowiedzi schematu JSON, inny może używać schematów wejściowych narzędzi, a jeszcze inny może wymagać awaryjnego sprawdzania poprawności i ponownej próby.
- Nawet dane wyjściowe zgodne ze schematem mogą być semantycznie błędne, zanim dotrą do bazy danych, przepływu pracy lub płatnej akcji.
Implikacje architektoniczne są proste: interfejs API zgodny z OpenAI może ujednolicić interfejs klienta, ale warstwa niezawodności musi nadal rozumieć możliwości dostawcy i weryfikować wyniki po wygenerowaniu.
Zalecana architektura: adapter wyjścia strukturalnego
Użyj adaptera po stronie bramy między kodem aplikacji a interfejsami API dostawcy. Aplikacja wysyła jedną intencję schematu. Brama mapuje tę intencję na najsilniejszy obsługiwany mechanizm dostawcy.
1. Zaakceptuj jedno znormalizowane żądanie z aplikacji
Klient nie powinien potrzebować oddzielnych ścieżek kodu dla każdego dostawcy. Praktyczna koperta żądania obejmuje preferencje modelu, dane wejściowe zadania, schemat, metadane schematu i poziom ryzyka:
{ "model": "auto:dokładny", „wiadomości”: [ {"role": "system", "content": "Wyodrębnij pola faktury. Nie wnioskuj o brakujących wartościach."}, {"role": "user", "content": "Tekst faktury..."} ], „strukturalne_wyjście”: { "schema_id": "wyciąg_faktury", "schema_version": "2026-08-01", "tryb": "schemat json", „ścisłe”: prawda, „schemat”: { "typ": "obiekt", „additionalProperties”: fałsz, „wymagane”: [„numer_faktury”, „nazwa_sprzedawcy”, „suma”, „waluta”, „data_terminu”], „właściwości”: { "numer_faktury": {"typ": "string"}, "vendor_name": {"type": "string"}, "ogółem": {"typ": "liczba", "minimum": 0}, "waluta": {"type": "string", "enum": ["USD", "EUR", "GBP"]}, "data_terminu": {"type": "string", "format": "data"}, "pewność": {"typ": "liczba", "minimum": 0, "maksimum": 1} } } }, „metadane”: { "workflow": "accounts_payable", „poziom_ryzyka”: „średni” }
Ta umowa zapewnia bramie wystarczającą ilość informacji, aby wybrać implementację natywną dostawcy, przeprowadzić weryfikację i zarejestrować istotne dane o błędach.
2. Utrzymuj matrycę możliwości dostawcy
Brama powinna utrzymywać matrycę możliwości odczytywalną maszynowo, a nie opierać się na założeniach typu „wszystkie modele kompatybilne z OpenAI obsługują to samo zachowanie schematu”. Przydatna macierz obejmuje:
- Nazwa dostawcy i modelu.
- Obsługuje tryb JSON.
- Obsługuje format odpowiedzi schematu JSON.
- Obsługuje wywołania narzędzi.
- Obsługuje tryb ścisłego schematu.
- Znane ograniczenia podzbioru schematu JSON.
- Czy równoległe wywołania narzędzi są zgodne z trybem ścisłego schematu.
- Zachowanie awaryjne, gdy żądany tryb nie jest obsługiwany.
Przykładowy zapis możliwości:
{ "dostawca": "dostawca_a", "model": "model_x", „json_mode”: prawda, „json_schema_response”: prawda, „tool_calls”: prawda, „strict_schema”: prawda, „schema_limitations”: [„no oneOf”, „ograniczona weryfikacja formatu”], „awaryjny”: „odrzuć_lub_trasę_do_kompatybilnego_modelu”
Ta macierz powinna zostać wersjonowana i przetestowana. Gdy dostawca zmienia zachowanie lub zostaje dodany nowy model, przed skierowaniem produkcji należy sprawdzić zgodność ustrukturyzowanych wyników.
3. Przetłumacz na najsilniejszą umowę natywną dla dostawcy
Adapter powinien przestrzegać jasnej kolejności preferencji:
- Użyj ściśle ustrukturyzowanych wyników natywnych dostawcy, jeśli jest to obsługiwane przez wybrany model i schemat.
- Używaj narzędzi natywnych dostawcy do wykonywania akcji i zadań podobnych do funkcji.
- Używaj nieścisłych danych wyjściowych lub trybu JSON z walidacją i ponownymi próbami, gdy tryb ścisły jest niedostępny.
- Odrzuć żądanie, przejdź do zgodnego modelu awaryjnego lub zwróć odpowiedź nie zawierającą żadnych działań w przypadku przepływów pracy obarczonych wysokim ryzykiem.
Nie zmieniaj po cichu operacji wysokiego ryzyka z trybu ścisłego schematu do „najlepszego formatu JSON”. Jeśli aplikacja zażądała rygorystycznego zachowania, a wybrany dostawca nie może tego obsłużyć, brama powinna to uwidocznić poprzez błąd, decyzję o routingu lub wyraźną flagę obniżenia wersji.
Trzy warstwy walidacji przed wykonaniem
Warstwa 1: weryfikacja analizy
Najpierw ustal, czy odpowiedź można rozłożyć na oczekiwaną kopertę. Szybka awaria w przypadku zniekształconego JSON, brakujących bloków wywołań narzędzi, obciętych odpowiedzi lub mieszanego języka naturalnego i JSON, jeśli zabrania tego umowa.
funkcja parseStructuredResponse(raw) {
spróbuj {
return { ok: prawda, wartość: JSON.parse(raw) };
} złapać (błąd) {
return { ok: false, typ_awarii: "awaria_parsowania", błąd: String(błąd) };
}
Wywołania narzędzi natywne przez dostawcę mogą nie wymagać analizowania obiektu typu blob nieprzetworzonego tekstu, ale nadal wymagają sprawdzania poprawności koperty: czy model wybrał znane narzędzie, czy podał argumenty i czy zatrzymał się w celu wykonania narzędzia zgodnie z oczekiwaniami?
Warstwa 2: Walidacja schematu JSON
Następnie sprawdź poprawność obiektu względem zadeklarowanego schematu za pomocą walidatora po stronie serwera. Zrób to nawet wtedy, gdy dostawca twierdzi, że obsługuje ścisłe schematy. Walidacja po stronie bramy zapewnia spójne rejestrowanie błędów, chroni przed błędami integracji i wychwytuje niezgodności na dalszym etapie.
const valid = schemaValidator.compile(schema);
const valid = valid(obiekt);
jeśli (!ważne) {
zwrócić {
ok: fałsz,
typ_porażki: "awaria_schematu",
błędy: valid.errors
};
W celu zapewnienia przenośności zaprojektuj schematy z uwzględnieniem wspólnego podzbioru:
- Preferuj jawne
type,required,właściwości,enumiadditionalProperties: false. - Unikaj skomplikowanych kombinacji, takich jak głęboko zagnieżdżone
oneOf,anyOfi schematy warunkowe, chyba że wiesz, że docelowy dostawca je obsługuje. - Argumenty dotyczące działań powinny być małe i konkretne.
- Użyj ciągów znaków dla identyfikatorów, dat i kodów, chyba że dalsze systemy wymagają innego typu.
- Wyraźnie przedstaw niepewność za pomocą pól takich jak
confidence,missing_fieldslubrequires_human_review.
Warstwa 3: weryfikacja semantyczna i biznesowa
Na koniec sprawdź, czy ustrukturyzowany wynik jest prawidłowy dla zadania. Ta warstwa jest specyficzna dla domeny i nie można jej zlecić samemu schematowi JSON.
W przypadku wyodrębniania faktur kontrole semantyczne mogą obejmować:
- Suma nie jest ujemna i odpowiada elementom zamówienia w granicach tolerancji.
- Waluta pojawia się w dokumencie źródłowym.
- Termin porodu nie jest niemożliwie odległy w przeszłości lub przyszłości.
- Dostawca znajduje się na liście zatwierdzonych dostawców.
- Zaufanie jest wystarczająco wysokie, aby możliwe było automatyczne wprowadzenie.
W przypadku kwalifikacji potencjalnego klienta kontrole mogą obejmować:
- Wybrany segment jest jednym z aktywnych segmentów zespołu sprzedaży.
- Żądany budżet nie jest ustalany, jeśli użytkownik go nie podał.
- Akcja „demo książki” nie jest wykonywana, chyba że użytkownik wyraźnie o to poprosił.
W przypadku automatyzacji Partner API kontrole mogą obejmować:
- Konto sprzedawcy jest upoważnione do utworzenia żądanego klienta lub klucza.
- Żądany limit wydatków jest zgodny z zasadami partnera.
- Operacja ma klucz idempotencji.
- Działanie jest rejestrowane w dzienniku audytu przed wykonaniem.
Wywołania narzędzi: traktuj dane wyjściowe modelu jako żądanie, a nie wykonanie
Wywoływanie narzędzi to właściwy wzorzec, gdy model musi poprosić aplikację o wykonanie jakiejś czynności: utworzenie zgłoszenia, wysłanie polecenia botowi Telegramu, sprawdzenie cen, zaktualizowanie rekordu klienta lub rozpoczęcie przepływu pracy.
Bezpieczna pętla narzędzi wygląda następująco:
- Aplikacja deklaruje dostępne narzędzia i schematy ich wprowadzania.
- Model zwraca wywołanie narzędzia z argumentami strukturalnymi.
- Brama sprawdza nazwę narzędzia i argumenty.
- Aplikacja sprawdza autoryzację, zasady, idempotencję i wymagania dotyczące potwierdzenia użytkownika.
- Dopiero wtedy aplikacja uruchamia narzędzie.
- Wynik narzędzia jest wysyłany z powrotem do modelu, jeśli rozmowa ma być kontynuowana.
Nigdy nie traktuj wywołania narzędzia jako dowodu, że akcja powinna zostać wykonana. Potraktuj to jako ustrukturyzowaną propozycję. Aplikacja pozostaje autorytetem w zakresie skutków ubocznych.
Bezpieczna drabina awaryjna dla przepływów pracy obejmujących wiele modeli
Brama powinna definiować zachowanie awaryjne przed wystąpieniem incydentów. Praktyczna drabina to:
- Podstawowy: ściśle ustrukturyzowane dane wyjściowe dotyczące preferowanego modelu.
- Zgodne rozwiązanie zastępcze: inny model obsługujący te same rygorystyczne wymagania dotyczące schematu.
- Weryfikacja i ponowna próba: dostawca bez ścisłego wsparcia, używany tylko wtedy, gdy pozwala na to ryzyko.
- Weryfikacja manualna: umieść w kolejce ustrukturyzowany wynik i treść źródłową do zatwierdzenia.
- Reakcja braku działania: wyjaśnij, że system nie może bezpiecznie ukończyć operacji.
Ponowne próby są przydatne w przypadku formatowania lub drobnych błędów schematu, ale nie stanowią strategii bezpieczeństwa. Jeśli obiekt jest semantycznie niebezpieczny, wielokrotne monitowanie może zamienić prawidłowe odrzucenie w niebezpieczny obiekt wykonywalny. W przypadku działań obarczonych wysokim ryzykiem preferuj ocenę lub odmowę zamiast powtarzających się prób wymuszenia sukcesu.
Obserwowalność: rejestruj każdą decyzję dotyczącą ustrukturyzowanego wyniku
Awarie wyjść strukturalnych to sygnały operacyjne. Rejestruj je z wystarczającą ilością szczegółów, aby ulepszyć routing, schematy i podpowiedzi bez ujawniania niepotrzebnych poufnych treści.
Zalecane pola:
schemat_idischemat_version.- Dostawca i model.
- Żądany tryb i aktualnie używany tryb.
- Przeanalizuj stan błędu.
- Stan błędu schematu i błędy sprawdzania poprawności.
- Przyczyna niepowodzenia weryfikacji semantycznej.
- Liczba ponownych prób.
- Opóźnienie.
- Wykorzystanie i koszt tokena.
- Stan końcowego działania: wykonane, umieszczone w kolejce, odrzucone lub zwrócone użytkownikowi.
- Zespół, projekt, klucz API lub identyfikator konta partnera, jeśli to konieczne.
Te dzienniki obsługują debugowanie, analizę kosztów, porównywanie dostawców i zarządzanie interfejsem API zespołu. Pomagają także odpowiedzieć na pytania takie jak: „Która wersja schematu powoduje najwięcej ponownych prób?” oraz „Który model awaryjny spełnia składnię, ale nie przechodzi weryfikacji biznesowej?”
Zasady wersjonowania schematu
Schematy to interfejsy produkcyjne. Traktuj je jak umowy API.
- Uwzględnij
schema_idischema_versionw metadanych i dziennikach żądań. - Nie zmieniaj po cichu wymaganych pól dla istniejących automatyzacji.
- Zachowaj dostępność starych schematów podczas migracji klientów.
- Dodaj nowe pola opcjonalne, zanim staną się wymagane.
- Testuj schematy pod kątem każdego dostawcy i modelu awaryjnego w puli routingu.
- Zapisz, która wersja schematu została użyta w przypadku każdego działania ubocznego.
Wersjonowanie staje się szczególnie ważne dla agencji, sprzedawców i automatyzacji Partner API, gdzie wielu dalszych klientów może polegać na stabilnej umowie strukturalnej.
Kiedy nie wykonywać ustrukturyzowanego wyniku
Zatrzymaj się, gdy wystąpi którykolwiek z poniższych warunków:
- Odpowiedzi nie można przeanalizować.
- Obiekt nie przeszedł weryfikacji schematu JSON.
- Wartość wyliczeniowa jest nieobsługiwana lub wymyślona.
- Nie można podać ilości, ceny, daty ani waluty.
- Wynik jest sprzeczny z deklarowaną intencją użytkownika.
- Model wyraża niską pewność lub brak dowodów.
- Instrukcja użytkownika jest niejednoznaczna.
- Działanie ma skutki uboczne i brakuje potwierdzenia.
- Konto, zespół lub klucz API nie jest autoryzowany.
- Odpowiedź dostawcy obejmuje odmowę lub brak odpowiedzi ze względów bezpieczeństwa.
Rekomendacje a prognozy
Zalecenia: tam, gdzie to możliwe, używaj ustrukturyzowanych wyników natywnych dostawcy, sprawdzaj poprawność każdej bramy odpowiedzi, preferuj wywołania narzędzi dla działań, utrzymuj macierz możliwości, schematy wersji i blokuj skutki uboczne do czasu przejścia kontroli semantycznych.
Przewidywania: obsługa ustrukturyzowanych wyników przez dostawców prawdopodobnie stanie się silniejsza i bardziej spójna, ale przenośność pozostanie problemem, ponieważ rodziny modeli, podzbiory schematów i pętle wywołań narzędzi nie staną się identyczne z dnia na dzień. Zespoły tworzące teraz weryfikację, obserwowalność i wersjonowanie schematu będą lepiej przygotowane do przyjęcia nowych funkcji dostawców bez konieczności przepisywania każdego przepływu pracy.
Praktyczna lista kontrolna wdrożenia
- Zdefiniuj znormalizowany format żądania ustrukturyzowanego wyniku dla swoich aplikacji.
- Utwórz macierz możliwości dostawcy dla każdego modelu w puli routingu.
- Projektuj schematy przy użyciu przenośnego podzbioru schematu JSON.
- Tłumacz żądania na ścisłe mechanizmy natywne dostawcy, jeśli są obsługiwane.
- Sprawdź analizowalność, zgodność ze schematem i poprawność biznesową po wygenerowaniu.
- Używaj wywołań narzędzi do operacji ubocznych.
- Wymagaj autoryzacji, idempotencji i potwierdzenia poza modelem.
- Rejestruj wersję schematu, dostawcę, błędy sprawdzania poprawności, ponowne próby, opóźnienia, koszt i stan działania.
- Zdefiniuj zachowanie awaryjne według poziomu ryzyka przepływu pracy.
- Zachowaj dostępność starych schematów do czasu migracji zależnych automatyzacji.
Praktycznym celem nie jest sprawienie, aby każdy model zachowywał się identycznie. Ma dać twórcom aplikacji jedną stabilną umowę, podczas gdy brama uczciwie radzi sobie z różnicami dostawców. Ustrukturyzowane dane wyjściowe są niezbędną infrastrukturą do niezawodnej automatyzacji sztucznej inteligencji, ale granica produkcyjna to walidator i warstwa zasad, która decyduje, czy obiekt jest bezpieczny w użyciu.