Salt la conținutul principal
Română— Alege o limbă
Meniu

Activarea modului JSON

Lecția 4 din 12 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Cum funcționează modul JSON
  2. Activarea în Python
  3. Activarea în TypeScript
  4. Instrucțiunile explicite nu sunt opționale
  5. Mutarea instrucțiunilor de format în promptul de sistem
  6. Parsarea răspunsului
  7. Puncte cheie

Actualizat la 3 noiembrie 2026: Exemplele TypeScript importau anterior Mistral ca export implicit (import Mistral from …), dar SDK oferă doar un export numit: import { Mistral } from "@mistralai/mistralai". De asemenea, acestea transmiteau un conținut tipat string | ContentChunk[] direct către JSON.parse și hardcodau cheia API în codul sursă. Verificat prin compilare cu SDK 3.5.0 și TypeScript 7.0.2. Sursă: Mistral TypeScript SDK.

Cum funcționează modul JSON

Modul JSON este cel mai simplu mecanism pentru a obține un output structurat de la Mistral. Prin activarea unui singur parametru, garantați că răspunsul modelului va fi un JSON valid. Nu este nevoie să definiți o schemă și nici să scrieți un model de date—doar JSON sintactic corect la fiecare apel.

Activarea în Python

Activați acest lucru prin parametrul response_format în metoda client.chat.complete(). Rețineți că promptul în sine trebuie să descrie structura așteptată—vă vom explica imediat de ce acest lucru nu este opțional.

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)

Output-ul va fi un JSON valid, gata de utilizare imediat:

{
  "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."
    }
  ]
}

Activarea în TypeScript

SDK-ul TypeScript urmează exact aceeași logică, cu denumiri în camelCase: parametrul este responseFormat, iar parsarea folosește JSON.parse(). Se aplică o precauție suplimentară: SDK tipizează content ca string | ContentChunk[], astfel încât JSON.parse va accepta valoarea doar după ce verificați că este într-adevăr un șir de caractere.

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);

Instrucțiunile explicite nu sunt opționale

Iată punctul pe care mulți dezvoltatori îl ratează și motivul majorității dezamăgirilor legate de modul JSON: activarea parametrului nu este suficientă. Modul garantează sintaxa, nu conținutul. Trebuie să instruiți explicit modelul, în interiorul promptului, cu privire la formatul pe care îl așteptați.

Comparați următoarele două apeluri. În primul caz, nu se oferă nicio îndrumare structurală: modelul va produce JSON, dar cheile, numele acestora și imbricarea lor vor varia de la un apel la altul, lăsând codul downstream fără puncte de ancorare stabile.

# Practică proastă — nicio instrucțiune JSON în prompt
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "What are the advantages of cloud?"}
    ],
    response_format={"type": "json_object"}
)
# Modelul va produce JSON, dar structura va fi imprevizibilă

În al doilea caz, un schelet structural este inserat direct în prompt. Modelul are acum o țintă de imitat, făcând output-ul predictibil între apeluri.

# Practică bună — instrucțiune clară în prompt
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"}
)

Includerea unui exemplu de structură în prompt ghidează modelul către formatul dorit. Aceasta nu este o garanție absolută precum Output-urile Structurate Personalizate, dar este mai mult decât suficient pentru majoritatea cazurilor de utilizare.

Mutarea instrucțiunilor de format în promptul de sistem

Odată ce același proces se repetă pentru sute de intrări, lăsarea instrucțiunilor de format în mesajul utilizatorului devine ingestionabilă: le copiați la fiecare apel și se amestecă cu conținutul de procesat. Mutarea lor în promptul de sistem este soluția.

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"}
)

Această separare—instrucțiunile de format preluate de rolul system, iar conținutul de procesat de rolul user—face codul dumneavoastră semnificativ mai ușor de întreținut: modificarea formatului se face într-un singur loc.

Parsarea răspunsului

Un ultim obicei de adoptat: răspunsul în modul JSON este întotdeauna un șir JSON în interiorul message.content, niciodată un obiect. Parsarea vă revine dumneavoastră, în ambele limbaje.

import json

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

# Accesarea datelor
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}`);
});

Puncte cheie

  • Activați modul JSON cu response_format: {"type": "json_object"}
  • Folosiți client.chat.complete() (nu parse())
  • Întotdeauna instruiți modelul în prompt cu privire la structura JSON așteptată
  • Răspunsul este un șir JSON—parsați-l cu json.loads() sau JSON.parse()
  • Plasați instrucțiunile de format în promptul de sistem pentru pipeline-urile repetitive