Obsługa danych uporządkowanych w interfejsie Prompt API

Thomas Steiner

Data publikacji: 13 maja 2025 r.

Duże modele językowe (LLM) są znane z czasami długich odpowiedzi. Nawet jeśli powiesz modelowi, aby odpowiedział tylko „true” lub „false”, model może odpowiedzieć przyjaźnie i bardziej szczegółowo, niż oczekujesz, np.: „Odpowiedź to: true”.

Aby rozwiązać ten problem, interfejs API Prompt umożliwia określenie formatu wyjściowego JSON odpowiedzi modelu przez przekazanie schematu JSON do metod LanguageModel.prompt() i LanguageModel.promptStreaming(). Obsługa danych ustrukturyzowanych jest dostępna od wersji 137.

Co to jest schemat JSON

Schemat JSON to zbiór reguł, który zapewnia spójność, poprawność i interoperacyjność danych JSON na dużą skalę. Jeśli chodzi o wymianę danych, schemat JSON jest potężnym standardem definiowania struktury i zasad danych w formacie JSON. Do definiowania właściwości danych używa zestawu słów kluczowych.

Schemat JSON to standard branżowy zapewniający uporządkowany wynik, używany m.in. przez interfejs OpenAI API i interfejs Gemini API.

Możesz na przykład poprosić model o przypisanie maksymalnie 3 hashtagów do posta w sieci społecznościowej, takiej jak Mastodon. Idealne dane wyjściowe mogą wyglądać tak:

{
  "hashtags": [
    "#pottery",
    "#dyi"
  ] 
}

Odpowiadający mu schemat JSON dla żądanego kształtu obiektu wyjściowego będzie wyglądał tak:

{
  "type": "object",
  "properties": {
    "hashtags": {
      "type": "array",
      "maxItems": 3,
      "items": {
        "type": "string",
        "pattern": "^#[^\\s#]+$"
      }
    }
  },
  "required": ["hashtags"],
  "additionalProperties": false
}

Ten schemat JSON definiuje strukturę obiektu, który musi zawierać pole hashtags z tymi ograniczeniami:

  • "type": "object": wartość katalogu głównego musi być obiektem JSON.
  • "properties": { "hashtags": ... }: obiekt może (a w tym przypadku musi) mieć właściwość o nazwie hashtags.

  • "hashtags":

    • "type": "array": wartość musi być tablicą.
    • "maxItems": 3: tablica może zawierać maksymalnie 3 elementy.
    • "items": { "type": "string", "pattern": "^#[^\\s#]+$" }: każdy element tablicy musi być ciągiem znaków pasującym do podanego wzorca wyrażenia regularnego: ^#[^\\s#]+$:
      • ^# → musi zaczynać się od #.
      • [^\\s#]+ → po którym następuje co najmniej 1 znak, który nie jest spacją (\s) ani innym #.
      • $ → musi się tam kończyć.

  • "required": ["hashtags"]: obiekt musi zawierać właściwość hashtags.

  • "additionalProperties": false: dozwolone są tylko hashtagi.

Pełny opis możliwości tego formatu znajdziesz w dokumentacji JSON Schema – podstawy.

Modele LLM bardzo dobrze radzą sobie z tworzeniem schematów JSON. Wystarczy, że w prośbie opiszesz ograniczenia w języku naturalnym i podasz prawidłowy przykład obiektu JSON. Następnie możesz zweryfikować obiekty JSON pod kątem zgodności z wygenerowanym schematem JSON za pomocą jednego z weryfikatorów schematu JSON, np. internetowego narzędzia Newtonsoft JSON Schema Validator.

walidacja obiektu JSON na podstawie schematu JSON w walidatorze schematu JSON;

Przekazywanie schematu JSON do interfejsu Prompt API

Aby mieć pewność, że model będzie przestrzegać żądanego schematu JSON, musisz przekazać ten schemat jako argument metody prompt() lub obiektu opcji metody promptStreaming() jako wartość pola responseConstraint.

Oto bardzo podstawowy przykład schematu JSON, który sprawia, że model odpowiada albo true, albo false, klasyfikując, czy dana wiadomość, np. wiadomość na Mastodonie, dotyczy ceramiki.

const session = await LanguageModel.create();

const schema = {
  "type": "boolean"
};

const post = "Mugs and ramen bowls, both a bit smaller than intended- but that's
how it goes with reclaim. Glaze crawled the first time around, but pretty happy
with it after refiring.";

const result = await session.prompt(  
  `Is this post about pottery?\n\n${post}`,  
  {  
    responseConstraint: schema,  
  }  
);  
console.log(JSON.parse(result));  
// true

Obsługa przewidywalnych danych wyjściowych

Obsługa danych wyjściowych w formacie uporządkowanym w przypadku interfejsu Prompt API sprawia, że odpowiedzi LLM są bardziej przewidywalne. Zamiast wyodrębniać obiekt z odpowiedzi w formacie Markdown lub stosować inne metody przetwarzania, deweloperzy mogą teraz założyć, że odpowiedź modelu to prawidłowy JSON.

Dzięki temu wbudowana AI jest o krok bliżej interfejsów API w chmurze i wszystkich korzyści płynących z uruchomienia AI po stronie klienta.