JSON gwarantowany schematem
Na tej stronie
Dlaczego ustrukturyzowane dane wyjściowe zmieniają wszystko
Gdy używasz modelu językowego w środowisku produkcyjnym, potrzebujesz odpowiedzi, z których może korzystać kod. Nie chodzi o swobodny tekst ani przybliżony JSON – potrzebujesz JSON-a gwarantowanie zgodnego ze zdefiniowanym przez Ciebie schematem. Dokładnie to oferują ustrukturyzowane dane wyjściowe API Grok.
Zasada jest prosta: dostarczasz modelowi schemat JSON, a API gwarantuje, że odpowiedź będzie dokładnie odpowiadać tej strukturze. Koniec z chaotycznym parsowaniem, kruchymi wyrażeniami regularnymi czy blokami try/catch obsługującymi przypadki, w których model wymyśla własny format.
Jak to działa
Ustrukturyzowane dane wyjściowe opierają się na mechanizmie ograniczeń stosowanym w trakcie generowania tekstu. Przy każdym wytwarzanym tokenie model jest ograniczony do generowania wyłącznie tokenów kompatybilnych z dostarczonym schematem. Rezultat? JSON, który jest zawsze poprawny i zawsze zgodny.
Spójrzmy na konkretny przykład. Chcesz wyodrębnić dane kontaktowe z e-maila:
from pydantic import BaseModel
class Contact(BaseModel):
nom: str
email: str
entreprise: str
telephone: str | None
# Odpowiedź ZAWSZE będzie prawidłowym obiektem Contact
Bez ustrukturyzowanych danych wyjściowych model mógłby zwrócić numer telefonu pod kluczem "tel", "phone" lub "numéro". Dzięki schematowi pole będzie zawsze nazywać się telephone, a jego wartością będzie zawsze ciąg znaków lub null.
Dostępność
Ustrukturyzowane dane wyjściowe są obsługiwane przez wszystkie modele językowe xAI: Grok 4.5, Grok 4.3, warianty grok-4.20 i nowsze wersje. Niezależnie od wybranego modelu, funkcja ta jest dostępna bez dodatkowych kosztów czy konfiguracji.
Bez ustrukturyzowanych danych wyjściowych vs z nimi
Oto co otrzymujesz bez tej funkcji, a co z nią:
Bez ustrukturyzowanych danych wyjściowych:
- Model może zwrócić swobodny tekst, częściowy JSON lub nieoczekiwany format
- Musisz ręcznie parsować dane i obsługiwać błędy
- Nazwy pól mogą się różnić między poszczególnymi żądaniami
- Twój potok danych przestaje działać, gdy tylko model zmieni format
Z ustrukturyzowanymi danymi wyjściowymi:
- JSON jest zawsze syntaktycznie poprawny
- Struktura dokładnie odpowiada dostarczonemu schematowi
- Typy są przestrzegane (ciąg znaków, liczba, wartość logiczna itp.)
- Twój kod może bezpośrednio konsumować odpowiedź
Dwa dostępne podejścia
API Grok oferuje dwie metody korzystania z ustrukturyzowanych danych wyjściowych:
parse(): Metoda automatyczna, która zwraca bezpośrednio typowany obiekt. Idealna w większości przypadków.response_format: Metoda ręczna, która zwraca ciąg JSON. Daje większą kontrolę, ale to Ty musisz zadbać o parsowanie.
Szczegółowo poznasz obie te metody w nadchodzących lekcjach.
Kluczowe wnioski
- Ustrukturyzowane dane wyjściowe gwarantują JSON zgodny z Twoim schematem przy każdym wywołaniu
- Ograniczenie jest stosowane podczas generowania, a nie po nim
- Wszystkie modele językowe xAI obsługują tę funkcję
- Dostępne są dwie metody:
parse()(automatyczna) iresponse_format(ręczna) - To fundament każdego niezawodnego potoku produkcyjnego opartego na API Grok