JSON-Modus aktivieren — Strukturierte Ausgabe: JSON und Schemata

Aktualisiert am 3. November 2026: Die TypeScript-Beispiele importierten zuvor Mistral als Standardexport (import Mistral from …), doch das SDK bietet nur einen benannten Export: import { Mistral } from "@mistralai/mistralai". Zudem wurde ein Inhalt vom Typ string | ContentChunk[] direkt an JSON.parse übergeben und der API-Schlüssel im Quellcode fest codiert. Dies wurde mit der SDK-Version 3.5.0 und TypeScript 7.0.2 durch die Kompilierung bestätigt. Quelle: Mistral TypeScript SDK.

Funktionsweise des JSON-Modus

Der JSON-Modus ist der einfachste Mechanismus, um vom Mistral-Modell strukturierte Ausgaben zu erhalten. Durch die Aktivierung eines einzelnen Parameters wird garantiert, dass die Antwort des Modells gültiges JSON ist. Es ist kein Schema zu definieren und kein Datenmodell zu schreiben – bei jedem Aufruf erhalten Sie syntaktisch korrektes JSON.

Aktivierung in Python

Sie aktivieren dies über den Parameter response_format in der Methode client.chat.complete(). Beachten Sie, dass der Prompt selbst die erwartete Struktur beschreiben muss – wir erklären kurz, warum dies nicht optional ist.

from mistralai.client import Mistral

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

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "user",
            "content": "Beschreiben Sie die 3 Hauptvorteile des Cloud-Computings. Geben Sie das Ergebnis als JSON zurück, mit dem Schlüssel 'advantages', der eine Liste von Objekten mit 'title' und 'description' enthält."
        }
    ],
    response_format={"type": "json_object"}
)

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

Die Ausgabe ist gültiges JSON und kann sofort verwendet werden:

{
  "advantages": [
    {
      "title": "Skalierbarkeit",
      "description": "Dynamische Anpassung der Ressourcen basierend auf der Nachfrage."
    },
    {
      "title": "Kostensenkung",
      "description": "Keine Investition in physische Infrastruktur erforderlich."
    },
    {
      "title": "Zugänglichkeit",
      "description": "Zugriff auf Dienste von überall."
    }
  ]
}

Aktivierung in TypeScript

Das TypeScript SDK folgt der exakt gleichen Logik, jedoch mit camelCase-Namensgebung: Der Parameter lautet responseFormat und das Parsing erfolgt mit JSON.parse(). Es gilt eine zusätzliche Vorsichtsmaßnahme: Das SDK typisiert content als string | ContentChunk[], sodass JSON.parse den Wert nur akzeptiert, nachdem Sie überprüft haben, dass es sich tatsächlich um einen String handelt.

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: "Listen Sie 3 populäre JavaScript-Frameworks in JSON auf, mit 'name' und 'useCase'."
    }
  ],
  responseFormat: { type: "json_object" },
});

const contenu = response.choices[0]?.message?.content;
if (typeof contenu !== "string") {
  throw new Error("Die Antwort enthält keinen JSON-Text.");
}
const data = JSON.parse(contenu);
console.log(data);

Explizite Anweisungen sind nicht optional

Hier liegt der Punkt, den viele Entwickler übersehen, und der Grund für die meisten Enttäuschungen mit dem JSON-Modus: Die Aktivierung des Parameters reicht nicht aus. Der Modus garantiert die Syntax, nicht den Inhalt. Sie müssen dem Modell innerhalb des Prompts explizit anweisen, welches Format Sie erwarten.

Vergleichen Sie die folgenden beiden Aufrufe. Im ersten wird keine strukturelle Anleitung gegeben: Das Modell erzeugt zwar JSON, aber die Schlüssel, ihre Namen und ihre Verschachtelung variieren von Aufruf zu Aufruf, sodass Ihr nachgelagerter Code keine stabilen Ankerpunkte hat.

# Schlechte Praxis – keine JSON-Anweisung im Prompt
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "Was sind die Vorteile von Cloud?"}
    ],
    response_format={"type": "json_object"}
)
# Das Modell erzeugt JSON, aber die Struktur ist unvorhersehbar

Im zweiten wird ein strukturelles Gerüst direkt in den Prompt eingefügt. Das Modell hat nun ein Ziel, dem es nachahmen kann, wodurch die Ausgabe über Aufrufe hinweg vorhersehbar wird.

# Gute Praxis – klare Anweisung im Prompt
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "user",
            "content": """Was sind die Vorteile des Cloud-Computings?

Geben Sie Ihre Antwort in JSON mit der folgenden Struktur zurück:
{
  "topic": "string",
  "advantages": [
    {"title": "string", "description": "string"}
  ]
}"""
        }
    ],
    response_format={"type": "json_object"}
)

Das Einbeziehen eines Strukturbeispiels in Ihren Prompt lenkt das Modell in Richtung des gewünschten Formats. Dies ist keine absolute Garantie wie bei den benutzerdefinierten strukturierten Ausgaben, aber für die meisten Anwendungsfälle mehr als ausreichend.

Verschiebung der Formatanweisungen in den System-Prompt

Sobald die gleiche Verarbeitung über Hunderte von Eingaben hinweg wiederholt wird, wird das Hinterlassen von Formatanweisungen in der Benutzer-Nachricht unübersichtlich: Sie müssen sie bei jedem Aufruf kopieren, und sie vermischen sich mit dem zu verarbeitenden Inhalt. Verschieben Sie sie stattdessen in den System-Prompt.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": "Sie sind ein Assistent zur Datenextraktion. Sie geben Ihre Antworten IMMER in JSON zurück mit den Schlüsseln 'entities', 'confidence' und 'source'."
        },
        {
            "role": "user",
            "content": "Extrahieren Sie Informationen aus diesem Text: 'Acme Corp, gegründet 2019 in Lyon, beschäftigt 250 Personen.'"
        }
    ],
    response_format={"type": "json_object"}
)

Diese Trennung – Formatanweisungen, die vom system-Rolle getragen werden, und der zu verarbeitende Inhalt, der von der user-Rolle getragen wird – macht Ihren Code deutlich wartbarer: Änderungen am Format erfolgen nur an einer Stelle.

Parsing der Antwort

Eine letzte Gewohnheit, die Sie sich aneignen sollten: Die Antwort des JSON-Modus ist immer ein JSON-String innerhalb von message.content, niemals ein Objekt. Das Parsing ist Ihre Verantwortung, in beiden Sprachen.

import json

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

# Zugriff auf die Daten
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("Die Antwort enthält keinen JSON-Text.");
}
const data = JSON.parse(contenu);

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

Kernaussagen

Aktivieren Sie den JSON-Modus mit response_format: {"type": "json_object"}
Verwenden Sie client.chat.complete() (nicht parse())
Immer weisen Sie dem Modell im Prompt die erwartete JSON-Struktur an
Die Antwort ist ein JSON-String – parsen Sie sie mit json.loads() oder JSON.parse()
Platzieren Sie Formatanweisungen im System-Prompt für wiederkehrende Pipelines