API-Dokumentation: Strukturierte Ausgaben erstellen

API-Beschreibung

Basierend auf einem gegebenen Prompt (Eingabeaufforderung) gibt das Modell eine oder mehrere vorhergesagte Vervollständigungen (Completions) zurück und unterstützt die Erzwingung, dass das Modell strukturierte Daten nach einem bestimmten JSON-Schema ausgibt.

Offizielle Referenzdokumentation: OpenAI Structured Outputs

Basisinformationen der API

• HTTP-Methode: POST
• Endpunkt (URL): https://api.codingplanx.ai/v1/chat/completions
• Datenformat: application/json

---

Header der Anfrage (Request Headers)

---

Anfragetext (Request Body)

Anfragebeispiel (Request Example)

{
  "model": "gpt-4.1-2025-04-14",
  "messages": [
    {
      "role": "system",
      "content": "Determine if the user input violates specific guidelines and explain if they do."
    },
    {
      "role": "user",
      "content": "How do I prepare for a job interview?"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "content_compliance",
      "description": "Determines if content is violating specific moderation rules",
      "schema": {
        "type": "object",
        "properties": {
          "is_violating": {
            "type": "boolean",
            "description": "Indicates if the content is violating guidelines"
          },
          "category": {
            "type": ["string", "null"],
            "description": "Type of violation, if the content is violating guidelines. Null otherwise.",
            "enum": ["violence", "sexual", "self_harm"]
          },
          "explanation_if_violating": {
            "type": ["string", "null"],
            "description": "Explanation of why the content is violating"
          }
        },
        "required": ["is_violating", "category", "explanation_if_violating"],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

---

Antwortkörper (Response Body)

Antwortbeispiel (Response Example)

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

---

Häufig gestellte Fragen (FAQs)

1. Was ist response_format und wie kann eine strikte JSON-Ausgabe des Modells garantiert werden?

Der Parameter response_format ermöglicht es Ihnen, das Modell aufzufordern, Daten in einem bestimmten Format zurückzugeben. Wenn Sie "Strukturierte Ausgaben" (Structured Outputs) verwenden möchten, müssen Sie dies auf {"type": "json_schema"} setzen, Ihr JSON-Schema darin definieren und strict: true aktivieren. Dies stellt sicher, dass das Modell zu 100 % gemäß den von Ihnen definierten Feldern und Datentypen ausgibt, ohne dass Sie in Ihrem Code zusätzliche fehlertolerante JSON-Parsing-Schritte durchführen müssen.

2. Warum wurde meine JSON-Ausgabe abgeschnitten?

Wenn der Wert von choices[0].finish_reason in Ihren Antwortdaten length lautet, bedeutet dies, dass der generierte Text das Limit max_tokens erreicht hat oder das maximale Kontextlängenlimit des Modells überschritten hat. Es wird empfohlen, den Wert des Parameters max_tokens in der Anfrage zu erhöhen.

3. Was ist der Unterschied zwischen den Parametern temperature und top_p? Welchen sollte ich anpassen?

Beides sind Parameter zur Steuerung der Zufälligkeit der Modellausgabe:

• temperature skaliert die Ausgabewahrscheinlichkeitsverteilung des Modells. Je niedriger der Wert, desto strikter und deterministischer ist die Ausgabe; je höher der Wert, desto divergenter ist die Ausgabe.
• top_p (Nucleus Sampling) beschränkt das Modell darauf, nur aus den häufigsten Vokabeln auszuwählen, deren kumulative Wahrscheinlichkeit p erreicht. Offizielle Empfehlung: Passen Sie nur einen dieser Parameter an, ändern Sie nicht temperature und top_p gleichzeitig.

4. Was passiert, wenn stream: true aktiviert wird?

Wenn stream: true gesetzt ist, wartet die API nicht, bis die gesamte Antwort generiert ist, um sie zurückzugeben, sondern gibt Datenfragmente in Echtzeit als Stream zurück, ähnlich wie bei einer Schreibmaschine. Das zurückgegebene Datenformat ändert sich zu Server-Sent Events (SSE). Der Client muss den Datenstrom abhören, um delta.content zusammenzusetzen, bis das [DONE]-Zeichen empfangen wird, das das Ende signalisiert.

5. Wie garantiere ich, dass bei jedem Aufruf desselben Prompts exakt dieselbe Antwort zurückgegeben wird?

Obwohl große Sprachmodelle inhärent zufällig sind, können Sie eine maximale deterministische Ausgabe erreichen, indem Sie einen bestimmten seed-Parameter übergeben und die temperature auf 0 setzen. Wenn Sie feststellen, dass sich der system_fingerprint in den zurückgegebenen Ergebnissen ändert, bedeutet dies, dass die Konfiguration des Backend-Modells feinabgestimmt wurde. In diesem Fall kann das Ergebnis trotz desselben Seeds geringfügige Unterschiede aufweisen.