Aktywuj tryb JSON
Na tej stronie
Zaktualizowano 3 listopada 2026: Przykłady w TypeScript wcześniej importowały
Mistraljako eksport domyślny (import Mistral from …), ale SDK udostępnia wyłącznie eksport nazwany:import { Mistral } from "@mistralai/mistralai". Przekazywały również zawartość typustring | ContentChunk[]bezpośrednio doJSON.parsei 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 nieparse()) - Zawsze instruuj model w prompcie dotyczący oczekiwanej struktury JSON
- Odpowiedź to ciąg znaków JSON – sparsuj go za pomocą
json.loads()lubJSON.parse() - Umieszczaj instrukcje formatu w prompcie systemowym dla powtarzalnych potoków przetwarzania