Voraussetzung für die KI-Integration: Ihr KI-Anbieter muss strikte strukturierte Ausgaben (response_format: json_schema) unterstützen

Hintergrund

In preeco | datenschutz und preeco | informationssicherheit hinterlegen Sie den KI-Anbieter selbst: Unter Einstellungen → Integrationen → KI-Anbieter wählen Sie zwischen OpenAI, Langdock und Benutzerdefiniert (OpenAI-kompatibel) und tragen API-Key, Modell und – beim benutzerdefinierten Anbieter – den API-Endpunkt ein. So bleiben Vertragsverhältnis, Modellauswahl und Datenfluss bei Ihnen.

Damit das funktioniert, genügt es nicht, dass ein Endpunkt „OpenAI-kompatibel“ ist. Er muss eine bestimmte Fähigkeit unterstützen: strikte strukturierte Ausgaben über response_format: json_schema („Strict Structured Outputs“). Unterstützt der Endpunkt oder das Modell das nicht, schlägt die KI-Integration fehl – und zwar bereits beim Speichern der Einstellungen.

Die technische Voraussetzung

preeco ruft ausschließlich den Chat-Completions-Pfad Ihres Endpunkts auf, also {Ihre Basis-URL}/chat/completions. Jede einzelne KI-Anfrage – ohne Ausnahme – enthält dabei ein Antwortformat mit striktem JSON-Schema:

{
  "model": "…",
  "messages": [ … ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "…",
      "schema": { … },
      "strict": true
    }
  }
}

Der Endpunkt muss dieses Feld akzeptieren und das Modell muss die Antwort tatsächlich schemakonform erzeugen. Beides ist erforderlich:

• Der Endpunkt darf response_format nicht ablehnen und auch nicht stillschweigend ignorieren.
• Das Modell muss strikte strukturierte Ausgaben beherrschen. Ein reiner „JSON-Modus“ (response_format: {"type": "json_object"}) ist nicht ausreichend – er garantiert nur gültiges JSON, nicht die vorgegebene Struktur.
• Ein Modell, das das Schema lediglich per Anweisung im Prompt „nachbaut“, genügt ebenfalls nicht.

Warum preeco das verlangt

Die KI-Ergebnisse landen in preeco nicht als Fließtext in einem Chatfenster, sondern direkt in strukturierten Feldern – etwa in Risikoanalysen, Schutzmaßnahmen, TOMs, Richtlinien, Datenschutzerklärungen und der Beurteilung von Datenschutzverletzungen. Jedes dieser Felder hat einen festen Aufbau.

Deshalb sendet preeco das erwartete Schema mit der Anfrage und prüft die Antwort anschließend noch einmal serverseitig gegen dasselbe Schema. Weicht die Antwort ab, wird sie verworfen, statt unvollständige oder falsch einsortierte Inhalte in Ihre Dokumentation zu schreiben. Ein Anbieter ohne strikte Schema-Unterstützung fällt spätestens an dieser zweiten Prüfung durch.

Vor der Einrichtung prüfen

Ob Ihr Wunsch-Endpunkt geeignet ist, lässt sich mit einem einzigen Aufruf feststellen. Ersetzen Sie Basis-URL, API-Key und Modellnamen und führen Sie den folgenden Befehl aus:

curl -s https://ihr-endpunkt.example.com/v1/chat/completions \
  -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "IHR_MODELL",
    "messages": [{"role": "user", "content": "Return the status."}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "status_check",
        "schema": {
          "type": "object",
          "properties": {"status": {"type": "string", "enum": ["ok"]}},
          "required": ["status"],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  }'

Geeignet ist der Endpunkt, wenn die Antwort als Inhalt exakt {"status":"ok"} enthält.

Nicht geeignet ist er, wenn stattdessen ein Fehler wie „response_format is not supported“, „unknown parameter“ oder „strict is not supported“ zurückkommt – oder wenn das Modell mit erklärendem Fließtext antwortet statt mit dem JSON-Objekt. In diesen Fällen wird die KI-Integration in preeco nicht funktionieren; das lässt sich anwendungsseitig nicht umgehen.

Weitere Anforderungen an einen benutzerdefinierten Endpunkt

• HTTPS ist Pflicht. HTTP-Endpunkte werden abgelehnt.
• Keine internen oder privaten Netzwerkadressen. Der Endpunkt muss öffentlich erreichbar sein.
• Nur die Basis-URL eintragen, zum Beispiel https://api.example.com/v1/. Fügen Sie versehentlich den vollständigen Pfad mit /chat/completions ein, entfernt preeco ihn automatisch und weist Sie darauf hin – den Pfad hängt die Anwendung selbst an.
• Der Modellname muss exakt der Modell-ID des Anbieters entsprechen, inklusive Schreibweise und Version. Ein Anzeigename aus einer Bedienoberfläche funktioniert in der Regel nicht.
• Der API-Key benötigt Schreibrechte für Chat Completions. Ein Schlüssel, der nur Modelle auflisten darf, genügt nicht.

Was passiert, wenn die Voraussetzung nicht erfüllt ist

preeco führt beim Speichern der KI-Einstellungen einen echten Testaufruf gegen Ihren Endpunkt aus. Die Einstellungen werden nur gespeichert, wenn dieser Test erfolgreich war – eine nicht funktionsfähige Konfiguration lässt sich also gar nicht erst hinterlegen.

Antwortet das Modell nicht schemakonform, erscheint direkt im Formular die Meldung: „Das Modell hat nicht im erwarteten Format geantwortet. Bitte stellen Sie sicher, dass das Modell strukturierte JSON-Ausgaben unterstützt. Eventuell müssen Sie die Konfiguration oder das Modell anpassen.“

Ändert ein bereits konfigurierter Anbieter später sein Verhalten – etwa nach einem Modellwechsel beim Anbieter –, schlagen die betroffenen KI-Aktionen zur Laufzeit fehl. Sie erkennen das im Abschnitt KI-Aktivitäten auf derselben Einstellungsseite: Dort ist jeder KI-Aufruf mit Modell, Status, Dauer, Tokenverbrauch und Fehlerart protokolliert.

Fehlerbilder und ihre Ursachen

• „Das Modell hat nicht im erwarteten Format geantwortet …“ – Endpunkt oder Modell unterstützt keine strikten strukturierten Ausgaben. Wählen Sie ein anderes Modell oder einen Anbieter mit Unterstützung für strukturierte Ausgaben.
• „Der Endpunkt wurde nicht gefunden.“ – Unter der angegebenen Basis-URL existiert kein Pfad /chat/completions. Prüfen Sie, ob die Versionskennung (zum Beispiel /v1/) fehlt.
• „Der Endpunkt ist nicht erreichbar.“ – Falscher Hostname, DNS-Problem oder eine Firewall blockiert die Verbindung.
• „Der API-Endpunkt muss HTTPS verwenden.“ beziehungsweise „… darf nicht auf interne oder private Netzwerkadressen verweisen.“ – Der Endpunkt erfüllt die Sicherheitsanforderungen nicht.
• Authentifizierungsfehler – Der API-Key ist ungültig, abgelaufen oder verfügt nicht über die nötigen Berechtigungen.
• Rate-Limit-Fehler – Das Kontingent des Anbieters ist erschöpft. preeco wiederholt solche Aufrufe automatisch; ein dauerhaft erschöpftes Kontingent müssen Sie jedoch beim Anbieter erhöhen.

Empfehlung

Klären Sie die Unterstützung von response_format: json_schema mit strict: true vor der Beschaffung oder Freigabe eines KI-Endpunkts mit Ihrem Anbieter beziehungsweise Ihrem IT-Betrieb ab – idealerweise mit dem oben gezeigten Testaufruf. Das ist das einzige harte Ausschlusskriterium: Alles Weitere wie Modellgröße, Region oder Preis ist Ihre freie Entscheidung, diese eine Fähigkeit ist Voraussetzung.

Ein praktischer Hinweis für den Betrieb: Hinterlegen Sie beim Anbieter einen API-Key mit eingeschränkten Berechtigungen und einem monatlichen Budgetlimit. So behalten Sie die Kostenkontrolle, ohne die Funktion einzuschränken.

Stichwörter: KI-Integration, KI-Anbieter, OpenAI-kompatibel, response_format, json_schema, Strict Structured Outputs, strukturierte Ausgabe, API-Endpunkt, benutzerdefinierter Anbieter, Langdock, Modell, API-Key, Einstellungen, Integrationen, Verbindungstest

Zusammenfassung: preeco sendet jede KI-Anfrage an den Pfad /chat/completions Ihres Endpunkts und verlangt dabei eine strikte strukturierte Ausgabe über response_format: json_schema mit strict: true; die Antwort wird anschließend erneut gegen dasselbe Schema geprüft. Ein OpenAI-kompatibler Endpunkt ist deshalb nur dann verwendbar, wenn Endpunkt und Modell strikte strukturierte Ausgaben unterstützen – ein reiner JSON-Modus genügt nicht. Ob das der Fall ist, lässt sich vorab mit einem einzelnen curl-Aufruf prüfen. Andernfalls verweigert preeco bereits das Speichern der Einstellungen mit dem Hinweis, dass das Modell nicht im erwarteten Format geantwortet hat.