KI-Verbrauch und OpenAI-Decisions-Pilot
Bestehende Installation aktualisieren
Die Erweiterung benötigt 20261115--ai-usage-events.sql; die persistente Budgetabschluss-Outbox ergänzt 20261115--shared-budget-outbox.sql (Migration 77).
Installieren Sie die Projektabhängigkeiten in Ihrer bestehenden Umgebung und
führen Sie dort vor dem Neustart den üblichen Migrationsbefehl aus:
flask --app codehelp migrate
Das Migrationswerkzeug erstellt vorher eine Sicherung. Für eine bestehende
Installation nicht initdb verwenden. Die Migration ergänzt ein neues
Protokoll; frühere Aufrufe werden nicht rückwirkend als vollständig erfasst
ausgegeben. Die Entwicklung und die automatisierten Tests dieser Erweiterung
aktivieren keinen produktiven Pilot und verändern keine vorhandene Instanz.
Was erfasst wird
Unter Admin → KI-Verbrauch (/admin/usage/) stehen eine Datumsansicht und ein
CSV-Export zur Verfügung. Die Ansicht ist ausschließlich für Systemadministratoren
zugänglich. Start und Ende beziehen sich auf UTC; der Endtag ist eingeschlossen.
Voreingestellt ist der aktuelle Kalendermonat. Für den eigenen Abrechnungszyklus
setzen Sie Start und Ende passend; die App liest keinen Kontostand aus OpenAI aus.
Jeder Modellaufruf erhält vor dem Versand einen eigenen Eintrag. Erfasst werden:
- Dienst, Anbieter, API-Art, angefragtes und zurückgemeldetes Modell;
- Zweck, Beginn, Ende, Dauer und gegebenenfalls Kurs- und Benutzerzuordnung;
- bei Programmierhilfe und Tutor die Kennung der zugehörigen Anfrage bzw. des Chats;
- gemeldete Eingabe-, Ausgabe-, Cache- und Reasoning-Tokens;
- Ergebnisstatus, fehlende Verbrauchsdaten und eine optionale Kostenschätzung.
Dies umfasst die Hauptantwort, die Prüfung ausreichender Angaben, eine eventuelle Überarbeitung, die Themenanalyse, Tutor-Antworten und deren zusätzliche Analyse, die Vorbereitung von Lernzielen/Fragen/Eröffnungsnachrichten, Sprachhilfe, Ideenfindung und Modell-Verbindungstests. Die optionalen OpenAI-Decisions-Aufrufe verwenden dasselbe Protokoll.
Ein query_token in Gen-Ed bleibt ein Nutzungsvorgang und ist kein OpenAI-Token.
Die neuen Messwerte werden davon unabhängig erfasst. Die Untergruppen Cache und
Reasoning werden nicht nochmals zu den Gesamttokens addiert.
Fehlende oder ungültige Zähler bleiben unbekannt. Bekannte Werte und die Anzahl der Aufrufe mit Messlücken werden getrennt angezeigt. Bei unterbrochenen Streams, Timeouts oder API-Fehlern kann der Anbieter bereits Verbrauch berechnet haben, ohne ihn mitzuteilen. Das Protokoll behauptet dann keinen Verbrauch von null. Nach einem Prozessabsturz kann ein Eintrag offen bleiben. Solche Einträge zählen ebenfalls als unvollständig. Verdeckte automatische Wiederholungen des OpenAI-SDK sind deaktiviert; erneutes Anfordern erzeugt einen neuen protokollierten Aufruf.
Kann vor dem Versand kein Eintrag angelegt werden, wird kein unprotokollierter Aufruf gestartet. Scheitert die abschließende Speicherung nach einem API-Aufruf, bleibt der ursprüngliche offene Eintrag als sichtbare Lücke bestehen. Wenden Sie die Migration an und prüfen Sie Datenbankzugriff und freien Speicherplatz.
Das Protokoll speichert keine Prompts, Lernendenprogramme, Antworttexte, API-Schlüssel oder vollständigen Fehlermeldungen des Anbieters. Die bisherigen fachlichen Anfrage- und Chatverläufe bleiben die dafür vorgesehenen Datenquellen. Beim Löschen zugeordneter Benutzer/Kurse verlieren die Verbrauchseinträge ihre entsprechende Zuordnung. Die Admin-CSV enthält keine Benutzer-IDs oder Rohmetadaten.
Kosten konfigurieren
Ohne konfigurierte Preise werden Tokens erfasst; Geldbeträge bleiben unbekannt.
AI_USAGE_PRICES enthält ein JSON-Objekt. Schlüssel haben die Form
Anbieter:API-Art:angefragtes-Modell. Die Preise gelten in US-Dollar pro Million
Tokens. Unterstützte Preisfelder sind input, output, cached_input und
cache_write_input. Die Preisgrundlage wird pro Aufruf festgehalten, damit eine
spätere Preisänderung alte Einträge nicht umrechnet.
Das folgende Beispiel verwendet nur den dokumentierten Decisions-Grundpreis für ungecachte Eingaben, ohne regionale oder andere Zuschläge (Stand 15.11.2026):
AI_USAGE_SERVICE=gen-ed
AI_USAGE_PRICES='{"OpenAI:decisions:gpt-6-luna":{"input":0.10,"output":0}}'
Für Aufrufe mit gemeldeten Cache-Tokens benötigt die Schätzung zusätzlich die passenden Cache-Preise. Werden unterschiedliche Cache-Preise konfiguriert, aber die benötigten Zähler nicht geliefert, bleibt die Schätzung unbekannt. Ohne Cache-Preise und ohne gemeldete Cache-Nutzung wird der volle Eingabepreis als Schätzung verwendet. Reasoning-Tokens sind bereits Teil der Ausgabetokens.
Ergänzen Sie für die tatsächlich eingesetzten generativen Modelle deren aktuelle Preise. Die Anzeige ist eine geschätzte Teilsumme der bepreisten Aufrufe, keine Rechnung und kein Guthaben. Verbindlich bleiben die Abrechnung und Gutschriften des jeweiligen Anbieters. Quellen: OpenAI-Preise und Decisions-Preise.
Gemeinsames Budget und nachholbare Abschlüsse
Gen-Ed und die KI-Feedbackdienste beider Jobe-Systeme sind bereits an die zentrale Budgeterfassung angebunden. Der Betriebsmodus ist observe: Erfassung und Reservierung sind aktiv, eine Budgetsperre ist nicht eingeschaltet. Historische Kosten vor Beginn dieser Erfassung bleiben unbekannt. Reine Jobe-Codeausführung ist selbst kein OpenAI-Aufruf; kostenpflichtiges Jobe-KI-Feedback wird gesondert erfasst.
Budgetabschlüsse erhalten mit Migration 77 eine persistente Outbox und begrenzte idempotente Wiederholungen. Wiederholt wird ausschließlich die Übermittlung bereits vorhandener Abschlussdaten an den Budgetdienst, niemals eine Modellanfrage. Der lokale Verbrauchsabschluss bleibt von einem vorübergehenden Budget-HTTP-Fehler getrennt; ein ausstehender Abschluss wird nicht als Verbrauch von null ausgegeben.
Der zentrale Dienst unterscheidet pending (Abschluss steht aus) und unknown (Abschluss vorhanden, aber nicht belastbar bepreisbar). Unbekannte Fälle erhalten feste Gründe: legacy_unknown, missing_usage, invalid_usage, missing_price, missing_cache_usage oder unsupported_cache_price. Ein zunächst unbekannter Abschluss kann mit vollständigen Nachweisen später auf complete wechseln; bereits vollständige Abschlüsse bleiben unveränderlich. Bis zur belastbaren Abrechnung bleiben konservative Reservierungen bestehen. Diese technische Nachholbarkeit bestätigt weder eine bereits erfolgte Live-Bereinigung noch nachträglich bekannte historische Kosten.
Entwicklungswerkzeuge außerhalb der Webanwendung benötigen weiterhin ihre eigene Instrumentierung. Geldbeträge und Prognosen beruhen auf erfassten, bepreisten Daten und sind keine Anbieterrechnung.
CodeHelp-Folgeversuche mit Responses erproben
Für einen Testkurs mit GPT-5.6 Luna kann der Haupthinweis die Responses API
verwenden. Der Kurs verwendet seinen vorhandenen OpenAI-Schlüssel am offiziellen
Endpunkt. Führen Sie vor der Aktivierung flask --app codehelp migrate aus. Die
Migration 20261120--codehelp-reasoning-history.sql ergänzt ein Feld für den Verlauf.
| Einstellung | Standard | Wirkung |
|---|---|---|
CODEHELP_RESPONSES_CLASS_IDS |
leer | Freigegebene CodeHelp-Kurs-IDs, durch Kommas getrennt |
CODEHELP_RESPONSES_REUSE_REASONING |
on |
all_turns übernimmt früheres Reasoning. off nutzt current_turn bei gleichem Gesprächsverlauf. |
CODEHELP_RESPONSES_OPENAI_ORG_ID |
leer | OpenAI-Organisations-ID für Responses-Anfragen der Pilotkurse |
CODEHELP_RESPONSES_OPENAI_PROJECT_ID |
leer | OpenAI-Projekt-ID für Responses-Anfragen der Pilotkurse |
Wenn OpenAI api.responses.write trotz sichtbarer Berechtigung verweigert,
können Sie die Organisation und das Projekt des Schlüssels für den Pilot
explizit setzen. Alle freigegebenen Kurse müssen dann Schlüssel dieses Projekts
verwenden. Die Einstellung gilt für den Haupthinweis über Responses.
Die Aufgabe braucht eine Aufgabenkennung und eine Version des Lernmaterials. Eigenen Versuch überarbeiten übernimmt nur den eigenen Verlauf derselben Aufgabe im selben Kurs. Code, Laufdaten und Hilfestufe des aktuellen Versuchs werden angehängt. Ein älterer Versuch ohne Responses-Verlauf liefert weiterhin den sichtbaren Hinweis und den früheren Code als Ausgangspunkt. Frühere sichtbare CodeRunner- und Jobe-Ausgaben dienen im Pilotkurs als Vergleich. Bei kleinen Änderungen ergänzt CodeHelp einen begrenzten Textvergleich für die Hinweiserstellung. Nach Änderungen am Lernmaterial beginnt CodeHelp einen neuen Responses-Verlauf. Wenn das Modell einen Hinweis ohne Reasoning erzeugt, wird er wie gewohnt angezeigt. Beim nächsten Versuch steht der sichtbare Hinweis als Kontext bereit.
CodeHelp sendet store:false. Den begrenzten Verlauf einschließlich von OpenAI
verschlüsselter Reasoning-Elemente speichert die Anwendung in der eigenen
Datenbank. Eine abgelehnte oder umgeschriebene Antwort dient nicht als Grundlage
für die Weitergabe von Reasoning. Bei einer Löschung des Benutzers oder Kurses
wird der gespeicherte Verlauf gelöscht. store:false ist eine Einstellung des
API-Aufrufs. Die Datenaufbewahrung für das Projekt richtet sich nach den
OpenAI-Datenkontrollen.
Für einen Vergleich verwenden Sie einen synthetischen Ausgangsversuch und senden
dieselbe Überarbeitung mit beiden Werten von CODEHELP_RESPONSES_REUSE_REASONING.
Prüfen Sie, ob die Antwort die beobachtete Ausgabe und die verlangte Hilfestufe
trifft. Vergleichen Sie Laufzeit, Reasoning-Tokens und Kosten für
responses / codehelp.main. Verwenden Sie dafür den Preisschlüssel
OpenAI:responses:gpt-5.6-luna in der lokalen und gegebenenfalls in der zentralen
Budgetkonfiguration. Betreiben Sie den Pilot mit abgeschaltetem HTTP-Debuglogging.
Decisions kontrolliert erproben
Die OpenAI-Decisions-API prüft zunächst: Reichen die Angaben
für einen hilfreichen ersten Hinweis, ohne Informationen zu erfinden?
Die Optionen heißen sufficient und missing. Die Erklärungen erzeugt weiter
das gewählte Kursmodell. Die Hauptantwort startet weiterhin parallel zur
Vorprüfung; eine unvollständige Anfrage verhindert ihren Aufruf nicht.
| Einstellung | Standard | Bedeutung |
|---|---|---|
OPENAI_DECISIONS_MODE |
off |
off, shadow oder active |
OPENAI_DECISIONS_LEARNING_MODE |
off |
Separater Modus für Hilfestrategie und Hinweisprüfung: off, shadow oder active |
OPENAI_DECISIONS_API_KEY |
leer | Eigener OpenAI-Projektschlüssel |
OPENAI_DECISIONS_CLASS_IDS |
leer | Erlaubte numerische Kurs-IDs, durch Kommas getrennt |
OPENAI_DECISIONS_CONFIDENCE_THRESHOLD |
0.90 |
Schwelle für Confidence und Wahrscheinlichkeit der verwendeten Entscheidung |
OPENAI_DECISIONS_TIMEOUT_SECONDS |
3.0 |
Asynchrone Transportfrist, höchstens drei Sekunden |
Die optionale Lernunterstützung ergänzt zwei begrenzte Aufgaben:
- Hilfestrategie: Vor der Hauptantwort wählt Decisions zwischen Vorhersagen/
Nachvollziehen (
predict), Begriff klären (concept) und relevante Stelle untersuchen (locate). Nur eine gültige Entscheidung mit mindestens0.90Confidence und Wahrscheinlichkeit der gewählten Option ergänzt eine feste Lehranweisung im Prompt. Das Kursmodell und die gewählte Hilfestufe bleiben maßgeblich. Unsicherheit erhält den gewöhnlichen Prompt. - Hinweisprüfung vor Anzeige: Im aktiven Pilotkurs 2 prüft ein Decisions-Request drei getrennte Risikoprädikate: Gibt der Hinweis die Aufgabenreparatur vor? Überschreitet er die gewählte Hilfestufe? Verlangt er eine ausdrücklich unzulässige Methode? Hilfestufe 1 verlangt genau eine kurze Leitfrage. Ein fehlender Eintrag in einem knappen Kontext allein belegt keine unbehandelte Methode.
Im aktiven Pilot gilt die gewählte Betriebsweise: Klare Verstöße überarbeiten; unsichere Hinweise gezielt kürzen, ohne automatische Sperre. Ein klar beanstandeter oder zunächst unklar bewerteter Hinweis erhält höchstens eine Kurzüberarbeitung durch das Kursmodell (codehelp.cleanup); auch die vorhandene Erkennung offensichtlicher Lösungsblöcke nutzt dieses gemeinsame Limit. Danach wird die neue Fassung erneut geprüft. Ein weiterhin klar beanstandeter Hinweis, ein unzulässiger Codeblock oder eine fehlgeschlagene Generierung wird durch eine feste Rückfrage ersetzt. Bloße Unsicherheit nach der Kurzüberarbeitung sperrt die Antwort nicht und ist kein Qualitätssiegel. Eine zweite Überarbeitung findet nicht statt. Budgetablehnungen lösen keinen kostenpflichtigen Ersatzaufruf aus.
Die Regeln gelten gemeinsam für alle vier Hilfestufen, auch nach der Kurzüberarbeitung:
| Stufe | Erlaubter Hinweisrahmen |
|---|---|
| 1 · Denkhinweis | Genau eine kurze Leitfrage, ohne ausgearbeitete Erklärung oder Aufgabenreparatur. |
| 2 · Relevante Stelle | Stelle oder Konzept eingrenzen beziehungsweise diagnostisch fragen; keine vollständige Reparatur. |
| 3 · Syntax an anderem Beispiel | Ein kleines unabhängiges Syntaxbeispiel mit anderer Aufgabe ist erlaubt, auch als Codeblock und auch nach einer Überarbeitung. Eine pauschale Codeblocksperre gilt hier nicht. Eine klar beanstandete Aufgabenlösung führt weiterhin zur festen Rückfrage. |
| 4 · Eigener Versuch | Einen eigenen kleinen Versuch mit Begründung anregen; keinen korrigierten Aufgabencode liefern. |
Auch eine vom generativen Suffizienzprüfer erzeugte Rückfrage wird im aktiven Pilot nicht ungeprüft ausgegeben: Bei fehlender ausreichender Information wird eine feste Rückfrage verwendet. Das Kursmodell erzeugt weiterhin die eigentlichen Hinweise. Der zusätzliche Prüfweg ist keine vollständige Faktenprüfung und keine Kompetenzbewertung. Die Anzeige eines Hinweises bedeutet keinen Nachweis fachlicher Richtigkeit.
OPENAI_DECISIONS_LEARNING_MODE=shadow protokolliert die Entscheidungen, ohne Prompt oder Hinweis dadurch zu ändern. active nutzt sie nur im ausdrücklich freigegebenen, angemeldeten Kurs für die beschriebene Überarbeitung und Nachprüfung. off und fehlende Kursfreigabe erhalten den gewöhnlichen Ablauf einschließlich der Codeblockerkennung. Die generative Vorprüfung wird weiterhin allein über OPENAI_DECISIONS_MODE gesteuert. Zusätzliche Prüf- und gegebenenfalls Überarbeitungsaufrufe verlängern die Antwortzeit und werden getrennt erfasst.
Der Prüfstand umfasst 20 synthetische Hinweisprüffälle mit zehn erwarteten Beanstandungen und zehn angemessenen Gegenbeispielen, 16 vollständige Pipelinefälle sowie zehn unabhängige Holdout-Fälle. Ergebnisse, Konfiguration und endgültig angezeigte Texte werden pro Lauf separat protokolliert. Vorhandene Tests und Fixture-Erwartungen allein belegen keine fachliche Qualität oder Unterrichtseignung. Ablauf und Grenzen beschreibt Deutsches Unterrichtsfeedback prüfen. Eine vollständige E2E-Livemessung über alle vier Stufen benötigt eine gesonderte technische und fachliche Abnahme; dieses Dokument behauptet deren Bestehen nicht.
Die neuen Aufrufe haben getrennte Zwecke im Verbrauchsprotokoll:
codehelp.strategy und codehelp.hint_review. Gespeichert werden ausschließlich
Verbrauchszähler, begrenzte Entscheidungswerte, Confidence/Wahrscheinlichkeit
und Rückfallgrund. Hinweistext, Code, öffentlicher Kontext, Lehrkraftnotizen,
Musterlösungen und rohe Anbieterantworten werden dort nicht abgelegt. Die
Hinweisprüfung erhält zusätzlich den erzeugten Hinweis und die gewählte
Hilfestufe; beide Aufgaben erhalten nur die ohnehin freigegebenen
öffentlichen Lern- und Laufdaten. Ob die Kurskonfiguration vertrauliche Felder
enthält, ändert diese Positivliste nicht.
Vor jedem tatsächlich versendeten Zusatzaufruf erfolgt die konfigurierte
gemeinsame Budgetprüfung. Ein abgelehnter Budgetabruf wird weitergereicht und
löst keinen kostenpflichtigen Ersatzaufruf aus. Decisions liefert strukturierte
Entscheidungen statt generierter Ausgabetokens; die Budgetreservierung setzt
deshalb für diese Aufrufe output_tokens=0. Hauptantwort, Vorprüfung und
gegebenenfalls Überarbeitung nutzen weiterhin die konfigurierte generative
Ausgabegrenze (standardmäßig 4096 Tokens bei aktivierter Budgetanbindung).
Der feste Endpunkt ist https://api.openai.com/v1/decisions, das Modell
gpt-6-luna. Die Anbindung verwendet einen eigenen asynchronen HTTP-Adapter,
weil das vorhandene OpenAI-SDK die Schnittstelle noch nicht anbietet. Redirects
werden nicht verfolgt; Anfrage- und Antwortkörper sind jeweils auf 64 KiB begrenzt.
Die Frist beendet auch eine stockende oder langsam eintreffende HTTP-Antwort.
Die DNS-Auflösung des Betriebssystems kann jedoch länger dauern und das Beenden
der Anfrage verzögern. Drei Sekunden sind daher keine garantierte Obergrenze
für die gesamte Antwortzeit bei Netzwerkstörungen.
- Beginnen Sie mit
shadowund einer ausdrücklich ausgewählten Kursliste. Die Entscheidung wird zusätzlich protokolliert. Die vorhandene generative Vorprüfung läuft trotzdem; die Lernenden erhalten weiterhin deren Ergebnis. - Prüfen Sie repräsentative deutschsprachige Anfragen, insbesondere knappe, mehrdeutige und dennoch ausreichend konkrete Fragen. In der Admin-Ansicht sehen Sie Modus, Entscheidung, Wahrscheinlichkeit, Confidence und Rückfallgrund. Die zugehörigen fachlichen Fälle öffnen Sie über die Anfrage-/Chatverknüpfung. Der CSV-Export enthält diese freigegebenen Entscheidungsfelder auch für ältere Aufrufe außerhalb der letzten 50 Einträge. Die Anfragekennung verbindet die Decisions-Prüfung mit der generativen Vorprüfung desselben Falls.
- Wechseln Sie erst nach der fachlichen Prüfung zu
active. Nur ein vollständig gültiges, hinreichend sicheressufficientersetzt die generative Vorprüfung.missing, Unsicherheit, Ablehnung, fehlerhafte Antworten und Dienstfehler führen zum Rückfragepfad; im aktiven Lernpilot erscheint dessen feste Rückfrage. - Mit
offbeenden Sie den OpenAI-Pilot. Die generative Vorprüfung übernimmt dann wieder alle Anfragen.
Die Entscheidungsschnittstelle ist ausschließlich die OpenAI-Decisions-API. Bei fehlender Kursfreigabe oder ungültiger Konfiguration bleibt die generative Vorprüfung erhalten. Die OpenAI-Anbindung verwendet niemals automatisch den System- oder Kurs-Schlüssel; ein Kurs kann weiterhin einen anderen Modellanbieter für seine Erklärungen verwenden.
Übertragen werden nur der bereits freigegebene Kontext, Lernendencode, Frage, Fehlermeldung und sichtbare Laufdaten. Lehrkraftnotizen und Musterlösungen gehören nicht dazu. Personenbezogene Angaben, die jemand selbst in Code oder Fragen einträgt, werden durch diese Erweiterung nicht automatisch entfernt.
Die Entscheidung vergibt keine Punkte, Lernbelege oder Zugriffsrechte. Confidence ist eine Modelleinschätzung und kein zugesicherter Genauigkeitswert. Die automatisierten Tests verwenden künstliche Antworten; die Qualität deutscher Unterrichtsfragen muss im Pilot praktisch geprüft werden.
Offizielle Schnittstelle: Decisions-Leitfaden und API-Referenz.