Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Ota JSON-tila käyttöön

Oppitunti 4 / 12 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Miten JSON-tila toimii
  2. Käyttöönotto Pythonissa
  3. Käyttöönotto TypeScriptissä
  4. Eksplisiittiset ohjeet eivät ole valinnaisia
  5. Muotoiluohjeiden siirtäminen järjestelmäkehotteeseen
  6. Vastauksen jäsentäminen
  7. Keskeiset asiat

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ät string | ContentChunk[]-tyypitetyn sisällön suoraan funktiolle JSON.parse ja 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() (ei parse())
  • Aina ohjeista mallia kehotteessa odotetusta JSON-rakenteesta
  • Vastaus on JSON-merkkijono – jäsennä se funktioilla json.loads() tai JSON.parse()
  • Sijoita muotoiluohjeet järjestelmäkehotteeseen toistuvissa putkistoissa