Przejdź do głównej treści
Polski— Wybierz język
Menu

Aktywuj tryb JSON

Lekcja 4 z 12 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Jak działa tryb JSON
  2. Włączanie w Pythonie
  3. Włączanie w TypeScript
  4. Jawne instrukcje nie są opcjonalne
  5. Przenoszenie instrukcji formatu do promptu systemowego
  6. Parsowanie odpowiedzi
  7. Kluczowe wnioski

Zaktualizowano 3 listopada 2026: Przykłady w TypeScript wcześniej importowały Mistral jako eksport domyślny (import Mistral from …), ale SDK udostępnia wyłącznie eksport nazwany: import { Mistral } from "@mistralai/mistralai". Przekazywały również zawartość typu string | ContentChunk[] bezpośrednio do JSON.parse i hardkodowały klucz API w kodzie źródłowym. Zweryfikowano poprzez kompilację z SDK 3.5.0 i TypeScript 7.0.2. Źródło: Mistral TypeScript SDK.

Jak działa tryb JSON

Tryb JSON to najprostszy mechanizm uzyskiwania ustrukturyzowanych danych wyjściowych od Mistral. Włączając pojedynczy parametr, gwarantujesz, że odpowiedź modelu będzie poprawnym kodem JSON. Nie musisz definiować schematu ani pisać modelu danych – przy każdym wywołaniu otrzymujesz jedynie syntaktycznie poprawny JSON.

Włączanie w Pythonie

Włączasz to za pomocą parametru response_format w metodzie client.chat.complete(). Pamiętaj, że sam prompt musi opisywać oczekiwaną strukturę – wkrótce wyjaśnimy, dlaczego nie jest to opcjonalne.

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "user",
            "content": "Opisz 3 główne zalety chmury obliczeniowej. Zwróć wynik jako JSON z kluczem 'advantages' zawierającym listę obiektów z polami 'title' i 'description'."
        }
    ],
    response_format={"type": "json_object"}
)

print(response.choices[0].message.content)

Wynik będzie poprawnym kodem JSON, gotowym do użycia bez zmian:

{
  "advantages": [
    {
      "title": "Skalowalność",
      "description": "Dynamiczna adjustacja zasobów w zależności od popytu."
    },
    {
      "title": "Redukcja kosztów",
      "description": "Brak konieczności inwestowania w infrastrukturę fizyczną."
    },
    {
      "title": "Dostępność",
      "description": "Dostęp do usług z dowolnego miejsca."
    }
  ]
}

Włączanie w TypeScript

SDK dla TypeScript działa według dokładnie tej samej logiki, stosując konwencję camelCase: parametr to responseFormat, a parsowanie odbywa się przez JSON.parse(). Obowiązuje jedna dodatkowa zasada ostrożności: SDK typuje pole content jako string | ContentChunk[], więc JSON.parse zaakceptuje wartość dopiero po upewnieniu się, że jest to faktycznie ciąg znaków.

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const response = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [
    {
      role: "user",
      content: "Wymień 3 popularne frameworki JavaScript w formacie JSON z polami 'name' i 'useCase'."
    }
  ],
  responseFormat: { type: "json_object" },
});

const contenu = response.choices[0]?.message?.content;
if (typeof contenu !== "string") {
  throw new Error("Response does not contain JSON text.");
}
const data = JSON.parse(contenu);
console.log(data);

Jawne instrukcje nie są opcjonalne

Oto punkt, który wielu programistów pomija, będący przyczyną większości rozczarowań trybem JSON: włączenie parametru nie wystarczy. Tryb ten gwarantuje składnię, a nie treść. Musisz wyraźnie poinstruować model wewnątrz promptu dotyczący oczekiwanego formatu.

Porównaj poniższe dwa wywołania. W pierwszym nie podano żadnych wskazówek strukturalnych: model wygeneruje JSON, ale klucze, ich nazwy i zagnieżdżenie będą się różnić przy każdym wywołaniu, pozostawiając kod downstreamowy bez stabilnych punktów odniesienia.

# Zła praktyka — brak instrukcji JSON w prompcie
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "Jakie są zalety chmury?"}
    ],
    response_format={"type": "json_object"}
)
# Model wygeneruje JSON, ale struktura będzie nieprzewidywalna

W drugim przypadku szkielet strukturalny zostaje wstawiony bezpośrednio do promptu. Model ma teraz cel do naśladowania, co sprawia, że wynik jest przewidywalny przy kolejnych wywołaniach.

# Dobra praktyka — jasna instrukcja w prompcie
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "user",
            "content": """Jakie są zalety chmury obliczeniowej?

Zwróć odpowiedź w formacie JSON o następującej strukturze:
{
  "topic": "string",
  "advantages": [
    {"title": "string", "description": "string"}
  ]
}"""
        }
    ],
    response_format={"type": "json_object"}
)

Dołączenie przykładu struktury w prompcie kieruje model ku pożądanemu formatowi. Nie jest to absolutna gwarancja, jaką oferują Niestandardowe Ustrukturyzowane Dane Wyjściowe (Custom Structured Outputs), ale w większości przypadków zastosowań jest to w zupełności wystarczające.

Przenoszenie instrukcji formatu do promptu systemowego

Gdy ten sam proces powtarza się setki razy dla różnych danych wejściowych, pozostawianie instrukcji formatu w wiadomości użytkownika staje się niezarządzalne: kopiujesz je przy każdym wywołaniu i mieszają się one z treścią do przetworzenia. Zamiast tego przenieś je do promptu systemowego.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": "Jesteś asystentem ekstrakcji danych. ZAWSZE zwracasz odpowiedzi w formacie JSON z kluczami 'entities', 'confidence' oraz 'source'."
        },
        {
            "role": "user",
            "content": "Wyodrębnij informacje z tego tekstu: 'Acme Corp, założona w 2019 roku w Lyonie, zatrudnia 250 osób.'"
        }
    ],
    response_format={"type": "json_object"}
)

To rozdzielenie – instrukcje formatu przeniesione do roli system, a treść do przetworzenia do roli user – sprawia, że Twój kod jest znacznie łatwiejszy w utrzymaniu: zmiana formatu odbywa się tylko w jednym miejscu.

Parsowanie odpowiedzi

Ostatni nawyk, który warto wyrobić: odpowiedź w trybie JSON to zawsze ciąg znaków JSON znajdujący się w message.content, nigdy obiekt. To Ty odpowiadasz za jego parsowanie, w obu językach.

import json

raw = response.choices[0].message.content
data = json.loads(raw)

# Dostęp do danych
for advantage in data["advantages"]:
    print(f"- {advantage['title']}: {advantage['description']}")
const contenu = response.choices[0]?.message?.content;
if (typeof contenu !== "string") {
  throw new Error("Response does not contain JSON text.");
}
const data = JSON.parse(contenu);

data.advantages.forEach((adv: any) => {
  console.log(`- ${adv.title}: ${adv.description}`);
});

Kluczowe wnioski

  • Włącz tryb JSON za pomocą response_format: {"type": "json_object"}
  • Używaj client.chat.complete() (a nie parse())
  • Zawsze instruuj model w prompcie dotyczący oczekiwanej struktury JSON
  • Odpowiedź to ciąg znaków JSON – sparsuj go za pomocą json.loads() lub JSON.parse()
  • Umieszczaj instrukcje formatu w prompcie systemowym dla powtarzalnych potoków przetwarzania