Ota JSON-tila käyttöön
Tällä sivulla
Päivitetty 3. marraskuuta 2026: Aiemmat TypeScript-esimerkit toivat
Mistral-luokan oletusvientinä (import Mistral from …), mutta SDK tarjoaa vain nimetyn viennin:import { Mistral } from "@mistralai/mistralai". Ne myös syöttivätstring | ContentChunk[]-tyypitetyn sisällön suoraan funktiolleJSON.parseja kovakoodasivat API-avaimen lähdekoodiin. Varmistettu kääntämällä SDK:n versiolla 3.5.0 ja TypeScriptin versiolla 7.0.2. Lähde: Mistral TypeScript SDK.
Miten JSON-tila toimii
JSON-tila on yksinkertaisin tapa saada jäsenneltyä tulostetta Mistralilta. Kun otat käyttöön yhden parametrin, varmistat, että mallin vastaus on kelvollista JSON-muotoa. Sinun ei tarvitse määritellä skeemaa eikä kirjoittaa datamallia – jokainen kutsu tuottaa syntaktisesti oikean JSONin.
Käyttöönotto Pythonissa
Otat tilan käyttöön response_format-parametrilla metodissa client.chat.complete(). Huomaa, että kehotteen (prompt) itsensä on kuvattava odotettu rakenne – selitämme pian, miksi tämä ei ole valinnaista.
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": "Describe the 3 main advantages of cloud computing. Return the result as JSON with a key 'advantages' containing a list of objects with 'title' and 'description'."
}
],
response_format={"type": "json_object"}
)
print(response.choices[0].message.content)
Tuloste on kelvollista JSONia, valmis käytettäväksi sellaisenaan:
{
"advantages": [
{
"title": "Scalability",
"description": "Dynamic adjustment of resources based on demand."
},
{
"title": "Cost Reduction",
"description": "No investment in physical infrastructure required."
},
{
"title": "Accessibility",
"description": "Access services from anywhere."
}
]
}
Käyttöönotto TypeScriptissä
TypeScript-SDK noudattaa täsmälleen samaa logiikkaa, mutta käyttää camelCase-nimeämistä: parametri on responseFormat, ja jäsentäminen tapahtuu funktiolla JSON.parse(). Yksi lisävarotoimi on tarpeen: SDK määrittelee content-kentän tyypiksi string | ContentChunk[], joten JSON.parse hyväksyy arvon vasta, kun olet varmistanut sen olevan merkkijono.
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: "List 3 popular JavaScript frameworks in JSON with 'name' and '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);
Eksplisiittiset ohjeet eivät ole valinnaisia
Tässä on kohta, jonka monet kehittäjät missaavat, ja se on syynä useimpiin pettymyksiin JSON-tilan kanssa: pelkkä parametrin asettaminen ei riitä. Tila takaa syntaksin, ei sisältöä. Sinun on eksplisiittisesti ohjeistettava mallia kehotteessa haluamastasi muodosta.
Vertaa seuraavia kahta kutsua. Ensimmäisessä rakenteellista ohjausta ei anneta: malli tuottaa JSONia, mutta avaimet, niiden nimet ja sisäkkäisyys vaihtelevat kutsusta toiseen, jättäen jatkokäsittelykoodillesi ilman vakaita ankkuripisteitä.
# Huono käytäntö — ei JSON-ohjeistusta kehotteessa
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "user", "content": "What are the advantages of cloud?"}
],
response_format={"type": "json_object"}
)
# Malli tuottaa JSONia, mutta rakenne on arvaamaton
Toisessa rakenteellinen runko lisätään suoraan kehotteeseen. Mallilla on nyt tavoite, jota jäljitellä, mikä tekee tulosteesta ennustettavan kutsujen välillä.
# Hyvä käytäntö — selkeä ohjeistus kehotteessa
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": """What are the advantages of cloud computing?
Return your answer in JSON with the following structure:
{
"topic": "string",
"advantages": [
{"title": "string", "description": "string"}
]
}"""
}
],
response_format={"type": "json_object"}
)
Rakenne-esimerkin sisällyttäminen kehotteeseen ohjaa mallia kohti haluttua muotoa. Tämä ei ole ehdoton takuu kuten mukautetut jäsennellyt tulosteet (Custom Structured Outputs), mutta se riittää useimpiin käyttötarkoituksiin.
Muotoiluohjeiden siirtäminen järjestelmäkehotteeseen
Kun sama käsittely toistuu sadoille syötteille, muotoiluohjeiden jättäminen käyttäjän viestiin muuttuu hallitsemattomaksi: kopioit ne jokaisessa kutsussa, ja ne sekoittuvat käsiteltävään sisältöön. Siirrä ne sen sijaan järjestelmäkehotteeseen (system prompt).
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "You are a data extraction assistant. You ALWAYS return your responses in JSON with the keys 'entities', 'confidence', and 'source'."
},
{
"role": "user",
"content": "Extract information from this text: 'Acme Corp, founded in 2019 in Lyon, employs 250 people.'"
}
],
response_format={"type": "json_object"}
)
Tämä erottelu – muotoiluohjeet system-roolissa ja käsiteltävä sisältö user-roolissa – tekee koodistasi huomattavasti helpommin ylläpidettävää: muodon muuttaminen tapahtuu vain yhdessä paikassa.
Vastauksen jäsentäminen
Viimeinen tapa, joka sinun tulee omaksua: JSON-tilan vastaus on aina **JSON-merkkijonokentässä message.content`, ei koskaan olio. Jäsentäminen on sinun vastuullasi molemmilla kielillä.
import json
raw = response.choices[0].message.content
data = json.loads(raw)
# Käytä dataa
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}`);
});
Keskeiset asiat
- Ota JSON-tila käyttöön parametrilla
response_format: {"type": "json_object"} - Käytä metodia
client.chat.complete()(eiparse()) - Aina ohjeista mallia kehotteessa odotetusta JSON-rakenteesta
- Vastaus on JSON-merkkijono – jäsennä se funktioilla
json.loads()taiJSON.parse() - Sijoita muotoiluohjeet järjestelmäkehotteeseen toistuvissa putkistoissa