Steuerung des Denkaufwands bei Reasoning-Modellen (Chat Completions)

Endpunkt-Beschreibung

Basierend auf einem Prompt gibt das Modell eine oder mehrere vorhergesagte Vervollständigungsantworten zurück (unterstützt die Steuerung des Denkaufwands für Reasoning-Modelle).

Offizielle Dokumentation: OpenAI Reasoning Guides
Status des Endpunkts: Veröffentlicht (released)

Anfrage-Spezifikationen (Request)

HTTP-Methode: POST
Endpunkt-URL: https://api.codingplanx.ai/v1/chat/completions

Anfrage-Header (Headers)

Parameter	Erforderlich	Typ	Beispielwert	Beschreibung
`Content-Type`	Ja	`string`	`application/json`	Datenformat
`Accept`	Ja	`string`	`application/json`	Akzeptiertes Format
`Authorization`	Nein	`string`	`Bearer {{YOUR_API_KEY}}`	Authentifizierungsnachweis (Credential)

Anfrage-Body-Parameter (Body)

Datenformat: application/json

Parameter	Erforderlich	Typ	Beschreibung
`model`	Ja	`string`	Die ID des zu verwendenden Modells (z. B. `o4-mini` usw.).
`messages`	Ja	`array`	Eine Liste der bisherigen Nachrichten in der Konversation. Enthält `role` (z. B. user/assistant) und `content` (Nachrichteninhalt).
`tools`	Ja	`array`	Eine Liste von Werkzeugen (Funktionen), die das Modell aufrufen kann. Dient zur Bereitstellung von Funktionen, für die das Modell JSON-Eingaben generieren kann.
`tool_choice`	Ja	`object`	Steuert, welche Funktion das Modell aufruft. `none` bedeutet kein Aufruf, `auto` bedeutet automatische Auswahl.
`reasoning_effort`	Nein	`string`	Kernparameter: Steuert den Denkaufwand (die Tiefe der Überlegungen) des Reasoning-Modells bei der Generierung einer Antwort. Häufige Optionen sind `low`, `medium`, `high`.
`temperature`	Nein	`number`	Sampling-Temperatur, zwischen 0 und 2. Höhere Werte (wie 0.8) machen die Ausgabe zufälliger, niedrigere Werte (wie 0.2) machen sie fokussierter und deterministischer. Es wird empfohlen, nur diesen Wert oder `top_p` zu ändern, nicht beide.
`top_p`	Nein	`number`	Nucleus-Sampling. 0.1 bedeutet, dass nur die Tokens berücksichtigt werden, die die obersten 10 % der Wahrscheinlichkeitsmasse ausmachen. Es wird empfohlen, nur diesen Wert oder `temperature` zu ändern.
`n`	Nein	`integer`	Standardwert ist 1. Legt fest, wie viele Chat-Vervollständigungsoptionen für jede Eingabenachricht generiert werden sollen.
`stream`	Nein	`boolean`	Standardwert ist false. Wenn auf true gesetzt, werden teilweise Nachrichten-Deltas als Server-Sent Events (SSE) gesendet und der Stream wird mit `data: [DONE]` beendet.
`stop`	Nein	`string`	Ein String aus bis zu 4 Sequenzen, bei denen die API die weitere Generierung von Tokens stoppt.
`max_tokens`	Nein	`integer`	Die maximale Anzahl an Tokens, die bei der Chat-Vervollständigung generiert werden sollen. Die Gesamtlänge von Eingabe- und generierten Tokens wird durch die Kontextlänge des Modells begrenzt.
`presence_penalty`	Nein	`number`	Eine Zahl zwischen -2.0 und 2.0. Positive Werte bestrafen neue Tokens basierend darauf, ob sie im bisherigen Text bereits aufgetreten sind, und erhöhen die Wahrscheinlichkeit, dass das Modell über neue Themen spricht.
`frequency_penalty`	Nein	`number`	Eine Zahl zwischen -2.0 und 2.0. Positive Werte bestrafen neue Tokens basierend auf ihrer bisherigen Häufigkeit im Text und verringern die Wahrscheinlichkeit, dass derselbe Inhalt wiederholt wird.
`logit_bias`	Nein	`object`	Akzeptiert ein JSON-Objekt, das Token-IDs auf Bias-Werte (-100 bis 100) abbildet, um die Wahrscheinlichkeit zu ändern, dass die angegebenen Tokens in der Vervollständigung erscheinen.
`user`	Nein	`string`	Ein eindeutiger Identifikator, der den Endbenutzer repräsentiert und hilft, Missbrauch zu überwachen und zu erkennen.
`response_format`	Nein	`object`	Gibt das Format an, das das Modell ausgeben muss. Beispielsweise aktiviert `{"type": "json_object"}` den JSON-Modus.
`seen`	Nein	`integer`	Beta-Funktion (ähnlich wie Seed). Wenn angegeben, wird das System nach besten Kräften deterministisch samplen, sodass dieselben Parameter dieselben Ergebnisse liefern.

Anfrage-Beispiel

{
  "model": "o4-mini",
  "max_tokens": 500,
  "messages": [
    {
      "role": "user",
      "content": "Hallo, bitte erkläre die Prinzipien des Quantencomputings im Detail."
    }
  ],
  "temperature": 1.0,
  "stream": false,
  "reasoning_effort": "medium"
}

Antwort-Spezifikationen (Response)

Antwort-Body-Parameter

Datenformat: application/json

Parameter	Typ	Beschreibung
`id`	`string`	Eindeutiger Identifikator für diese Anfrage.
`object`	`string`	Objekttyp, normalerweise `chat.completion`.
`created`	`integer`	Zeitstempel der Erstellung (Unix-Zeit).
`choices`	`array`	Liste der Vervollständigungsergebnisse.
└ `index`	`integer`	Der Index der aktuellen Auswahl in der Liste.
└ `message`	`object`	Das vom Modell generierte Nachrichtenobjekt der Antwort. Enthält `role` und `content`.
└ `finish_reason`	`string`	Der Grund, warum die Generierung gestoppt wurde (z. B. `stop`, `length`).
`usage`	`object`	Statistiken zum Token-Verbrauch.
└ `prompt_tokens`	`integer`	Anzahl der für den Prompt verbrauchten Tokens.
└ `completion_tokens`	`integer`	Anzahl der für die Generierung durch das Modell verbrauchten Tokens.
└ `total_tokens`	`integer`	Gesamtzahl der verbrauchten Tokens.

Antwort-Beispiel (HTTP 200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

FAQs (Häufig gestellte Fragen)

1. Welche Funktion hat der Parameter `reasoning_effort`?

reasoning_effort wird verwendet, um zu steuern, wie viel Rechenressourcen und Zeit Modelle mit fortgeschrittenen logischen Fähigkeiten (Reasoning, wie die o1/o4-Serien von OpenAI) aufwenden, um intern nachzudenken, bevor sie die endgültige Antwort geben. Es werden typischerweise drei Stufen unterstützt: low, medium und high. Bei der Einstellung high führt das Modell tiefere logische Ableitungen durch, was für die Lösung komplexer mathematischer oder programmiertechnischer Probleme geeignet ist; jedoch verlängert sich entsprechend auch die Reaktionszeit.

2. Warum erhalte ich nach Aktivierung von `stream: true` keine Standard-JSON-Antwort?

Wenn das Streaming (stream: true) aktiviert ist, gibt die API mithilfe des Server-Sent Events (SSE)-Protokolls kontinuierlich Datenblöcke (Chunks) zurück. Jeder Datenblock wird in der Form data: {...} gesendet. Sobald der gesamte Inhalt übertragen wurde, wird eine data: [DONE]-Nachricht gesendet. Entwickler müssen die Zeilen einzeln lesen und den JSON-String hinter data: parsen, um die vollständige Antwort zusammenzusetzen.

3. In der Dokumentation wird empfohlen, nur entweder `temperature` oder `top_p` zu ändern. Warum?

Beide Parameter dienen dazu, die Zufälligkeit und Vielfalt der Modellausgabe zu steuern. temperature verändert die Wahrscheinlichkeitsverteilung durch Skalierung der Logits, während top_p (Nucleus-Sampling) den Kandidatenpool einschränkt, indem es Vokabeln mit geringer kumulativer Wahrscheinlichkeit abschneidet. Das gleichzeitige Anpassen beider Parameter macht das Verhalten des Modells schwer vorhersehbar und kontrollierbar. Daher ist die Best Practice, einen der Parameter festzulegen (normalerweise auf dem Standardwert zu belassen) und nur den anderen anzupassen, um die gewünschte Kontrolle über die "Zufälligkeit" zu erreichen.

4. Was bedeutet es, wenn `finish_reason` den Wert `"length"` zurückgibt?

Dies bedeutet, dass die Antwort des Modells zwangsweise abgeschnitten wurde. Es gibt typischerweise zwei Gründe dafür: Erstens, die Anzahl der generierten Tokens hat das in den Anfrageparametern festgelegte Limit max_tokens erreicht; zweitens, die Gesamtanzahl der Tokens aus Ihrem Prompt und der generierten Antwort überschreitet das maximal zulässige Kontextfenster des Modells. In diesem Fall wird empfohlen, den bisherigen Gesprächsverlauf zu kürzen oder den Parameter max_tokens zu erhöhen.

5. Wie zwinge ich das Modell, Daten im JSON-Format zurückzugeben?

Sie können den JSON-Modus aktivieren, indem Sie "response_format": {"type": "json_object"} im Anfrage-Body übergeben. Sehr wichtig: Gleichzeitig mit der Aktivierung dieses Modus müssen Sie in messages (normalerweise im System- oder User-Prompt) ausdrücklich in natürlicher Sprache anfordern, dass das Modell JSON ausgibt. Andernfalls könnte das Modell in eine Endlosschleife geraten, in der es kontinuierlich Leerzeichen generiert, bis das Token-Limit erreicht ist.