Files
Speech/docs/AI_OPERATIONS.md
T
Eugenius Naumenko 16cceae28a Muttersprache koppeln und russischen A1-Kurs ergänzen
GUI und neue Erklärungen verwenden gemeinsam native_language. Deutsch und
Russisch sind die beiden Muttersprachen; Englisch bleibt die Lernsprache.
Kompatibilitätsfelder werden atomar gekoppelt, widersprüchliche Eingaben
abgewiesen und bestehende Profile sowie eingefrorene Inhalte erhalten.

Ergänzt vollständige russische GUI-Kataloge und 840 geprüfte Aufgabenansichten
in sieben Modulen einschließlich A1-Test, mit getrennten Sprachrollen für
Ausgangs- und Lernmaterial. Äquivalente Ansichten teilen ihre Nachweisidentität.
Stabile API-Fehlercodes, neue deterministische Hilfen und Trainingsbegründungen
berücksichtigen die Muttersprache. Dokumentiert das Sprachmodell in AGENTS.md.

Validierung: Go-Race-Suite mit eigener lokaler PostgreSQL-Testdatenbank, go vet,
Web-Build, Offline-Bank-/Variantenaudit, Diff-Prüfung sowie lokale Browser-Smokes
für Sprachen, Kurs, Administration, Aussprache und Aufnahme. Keine Live-Anbieter,
Produktionsprofile, Deployment-Schritte oder historischen Neubewertungen.
2026-11-07 17:02:17 +00:00

238 lines
38 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# A1-Aufgabenbestand und optionale KI-Anbindung
Stand: 1. November 2026. Die API verwendet DeepSeek und Mistral direkt; Flowise ist für den Betrieb nicht mehr erforderlich. Die alten Flowise-Dateien und Adapter bleiben als historische Referenz und für Kompatibilitätstests erhalten, werden in `main.go` aber nicht mehr verdrahtet. Alte `FLOWISE_*`-Umgebungsvariablen werden beim normalen Start ignoriert. Es wird kein bestehender Flowise-Container oder dessen Volume automatisch gelöscht.
## Klare offene Aufgaben und getrennte Bewertungsanzeigen
Revision `en-A1-bank-v2` ersetzt die 140 freien Sprech-/Schreibaufgaben durch konkrete Aufträge und dazu passende Kriterien. `tools/course_bank/open_instructions.json` enthält die redaktionellen Anweisungen. Die 700 übrigen Aufgaben behalten ihre bisherigen v1-Kennungen und Inhalte. Gesamtbestand und Verteilung bleiben 840 Aufgaben. Prüfvermerk und Manifest sind an die Quellen gebunden; dies ist weiterhin keine externe Lehrerzertifizierung.
Bei der bisherigen Aufgabe „Sprich über diese Situation: Ich heiße Jack Hill“ war unklar, ob eine Rolle, ein Beispielsatz oder eine Vorstellung gemeint war. Die neue Aufgabe verlangt ausdrücklich eine Vorstellung mit einem frei gewählten Namen und einer Angabe über Wohnort oder Hobby. Eigene und erfundene Angaben sind erlaubt. Weitere offene Aufgaben benennen ebenfalls die verlangten Angaben; Namen und Werte der Beispielantwort sind keine zusätzlichen Anforderungen.
Der Bankimport deaktiviert ersetzte Vorlagen, ohne zugewiesene Aufgaben, abgeschlossene Tests, Antworten oder Noten umzuschreiben. Die geänderten Aufgaben erhalten neue IDs. Nach dem gemeinsamen API-/Web-Neubau eine **neue Aufgabe** anfordern; eine wieder aufgerufene alte Aufgabe behält ihren ursprünglichen Text. Der aktive Bestand bleibt 840, die Datenbank kann wegen archivierter Vorlagen mehr Einträge enthalten.
Freies Sprechen wird dem Modell ausdrücklich mit `evaluation_scope=content_and_language` und `answer_source=speech_transcript` übergeben. Aufgabe, gespeicherte Rubrik, tatsächlicher erkannter Text und Sprachmessung bleiben enthalten. Der Bewerter soll keine zusätzliche Situation verlangen, Referenznamen nicht zur heimlichen Pflicht machen, keine sichere akustische Namensverwechslung aus einem Transkript ableiten und die separat angezeigte Aussprache nicht in die Inhaltsnote mischen. Automatisch gesetzte Satzzeichen sind kein Beweis für einen Formulierungsfehler. Die UI bezeichnet die KI-Punktzahl als **Inhalt und Sprache**, zeigt den erkannten Text und erhält den separaten Azure-Aussprachewert.
Bestehende fehlerhafte Bewertungen werden nicht still korrigiert. Die Änderung reduziert konkrete Ursachen für Fehlbewertungen, garantiert aber keine fachliche Fehlerfreiheit eines beliebigen Modells. Tests prüfen Bestandsschutz, Datenübergabe, Aufgaben-/Rubrikverträge und die Oberfläche mit lokalen Anbieter-Fixtures. Für die reale Modellqualität ist danach eine neue, bewusst ausgelöste Antwortbewertung erforderlich.
### Gezielt Schreibbewertungen prüfen
Unter Admin → Modellprofile → Antwortbewertung gibt es zusätzlich **Schreibbewertung prüfen · 2 kostenpflichtige Testfälle**. Die bestehende Prüfung von have/has bleibt unverändert. Der neue Test prüft eine korrekte Vorstellung mit drei Sätzen und die gemeldete Variante mit `my`, `in city` und `shwiming`. Er erwartet eine korrekte positive Kontrolle und bei der fehlerhaften Variante Hinweise zu Artikel und Rechtschreibung, ohne die falsche Korrektur `City` oder eine erfundene Satzanzahl. Dies sind konservative Regressionstests für bekannte Englischfälle, keine allgemeine Grammatikprüfung durch Go und kein Beweis für die gesamte Modellqualität. Ergebnisse mit weiteren fragwürdigen Aussagen müssen weiterhin inhaltlich gelesen werden.
`POST /admin/ai/quality` akzeptiert optional `suite=writing`; ohne Angabe bleibt `grammar` Standard. Andere Werte werden vor dem Modellaufruf abgewiesen. Jede Suite umfasst genau zwei explizit gestartete Aufrufe mit separatem Auftragskontext, vorhandenen Profil-/Budgetgrenzen und Verbrauchsprotokollierung. Eine Wiederholung derselben Suite/Request-ID verwendet gespeicherte Antworten erneut. Qualitätsprüfungen verändern keine Lernantworten und schalten Modelle nicht automatisch ein oder aus. Die hier verwendeten lokalen Prüfungen verwenden nur Anbieter-Fixtures; keine echten bezahlten Aufrufe wurden gestartet.
Der Bewerterprompt unterscheidet die Zielsprache von der Feedbacksprache: Englisch `city` bleibt im Satz klein, `I live in city` benötigt hier einen Artikel, und drei kurze Sätze erfüllen einen Auftrag mit zwei oder drei Sätzen. Eine allgemeine Fehlerfreiheit eines kleinen Modells folgt aus dem Prompt nicht. Bestehende Bewertungen werden nicht umgeschrieben; für die neue Promptversion neue Aufträge erzeugen.
## Gemeinsames Ausspracheprofil und Trainingsstrategie
Dieser Abschnitt ersetzt im statistischen Modus die unten dokumentierte Auswahl des schlechtesten Einzelwerts aus zehn Versuchen. Standard ist `PRONUNCIATION_STRATEGY=statistical`; `recent` behält die frühere Auswahl für Vergleich/Rückkehr. Der A1-Bankmodus bleibt davon unabhängig. Die Statistik selbst ruft weder Azure noch ein Modell auf. Neue Sätze verwenden weiterhin genau das vorhandene Profil `next_exercise`, mit den bisherigen Kostenlimits und höchstens einem Korrekturversuch.
### Messgrundlage und Herkunft
Neue Ausspracheversuche speichern Anbieter und vollständige Messmetadaten. `pronunciation_assessments` und `pronunciation_observations` erfassen Originalquelle, Originalversuch, Locale, Lautalphabet, Bewertungsverfahren, Messversion, Zeit und Wort-/Phonempositionen. Die Aufnahme und die Beobachtungen werden gemeinsam transaktional gespeichert. Der neue Lernauftrag liegt in `pronunciation_plans`; erfolgreiche Zuweisung und erzeugte Aufgabe werden ebenfalls gemeinsam gespeichert. Ein Replay derselben Zuweisung liefert dieselbe Aufgabe.
Berücksichtigt werden nur echte Azure-Nachsprechmessungen (`scripted`) aus Aussprache und Kurs. Kursantworten dürfen noch unbenotet sein: Die Inhaltsbewertung ist kein Aussprachemesswert. Freies Sprechen und Demo-Ergebnisse bleiben ausgeschlossen. Prüfungsaufnahmen sind erst nach Teststatus `completed` im Profil sichtbar. Importierte Kopien historischer Ausspracheversuche sind kein zweiter Nachweis.
Beim Start werden bisherige echte Kurs-Nachsprechmessungen mit belegtem Anbieter wiederholbar übernommen. Alte Ausspracheversuche erhalten die Herkunft `unknown`, bleiben erhalten und werden als unbestätigte Historie gezählt. Aus alten hohen Punkten wird kein nachträglicher Anbieterbeweis abgeleitet. Die Migration ist additiv und überschreibt keine Punkte oder Antworten. Die Tabellen werden beim nächsten API-Start eingerichtet; diese lokale Implementierung hat keine Produktionsmigration ausgeführt.
Fehlende Wortwerte werden bei neuen Azure-Antworten ausdrücklich markiert und nicht zu null Punkten erklärt. Auslassungen sind gesonderte Vollständigkeitsereignisse; für sie werden keine Phonemfehler abgeleitet. Insertions werden nicht als Lautnachweis verwendet. Benannte Phoneme werden nur mit geliefertem Symbol und bekanntem Lautalphabet übernommen. Der Azure-Aufruf verwendet IPA für en-US und SAPI für zh-CN; andere Locales bleiben ohne erratene Phonemnamen auf Wortebene nutzbar.
### Berechnung: pronunciation-v1
- Ein Profil gilt nur für einen Nutzer und seine gewählte Zielsprache. Zielkennung: Typ + Locale + Alphabet + Unicode-NFC-normalisiertes Symbol. Unterschiedliche IPA-Symbole werden nicht sprachlich gleichgesetzt.
- Zeitfenster 90 Tage, maximal 30 unabhängige Beobachtungen je Ziel. Neuere Werte haben ein Gewicht mit Halbwertszeit 14 Tage. Die Rohhistorie bleibt gespeichert.
- Pro Ziel, Aufgabe und UTC-Tag zählt die neueste tatsächlich gemessene Aufnahme. Fehlt ein Lautwert in einer neuen Aufnahme, löscht das keine vorherige Messung. Mehrfachvorkommen im selben Wort werden durch ihren Median zusammengefasst.
- Der Lautdurchschnitt und Schwächenanteil sind Mittelwerte der gewichteten Wortkontexte. Damit verdrängen zehn Wiederholungen eines Wortes nicht die Evidenz anderer Wörter. Eine Beobachtung ist keine formal unabhängige wissenschaftliche Stichprobe; die Bezeichnung dient der Begrenzung von Wiederholungsgewicht.
- Schwach: unter 75. Ein wiederkehrendes Muster benötigt mindestens drei Beobachtungen, mindestens zwei schwache und bei Lauten mindestens zwei Wortkontexte; bei einem Mittelwert unter 85 lautet der Zustand `needs_practice`. Vorher bleibt es `limited`, sonst `observed`.
- Drei aufeinanderfolgende Beobachtungen ab 85, bei Lauten aus mindestens zwei Wortkontexten, ergeben `improved`. Fällige erfolgreiche Wiederholungen führen durch Abstände von 1, 3, 7 und 14 Tagen. Danach lautet der Zustand `stable`, mit weiteren Wiederholungen nach 30 Tagen. Eine neue Beobachtung unter 75 setzt die Folge zurück.
- Entwicklung: neueste gegen vorherige Gruppe mit jeweils 3–5 Beobachtungen; ab fünf Punkten Unterschied `improving` oder `declining`, ansonsten `steady`. Bei weniger Nachweisen `insufficient`.
- Priorität innerhalb einer Evidenzgruppe: 50 % niedriger Durchschnitt, 30 % Schwächenanteil, 20 % Nachweisdichte. Dichte steigt bis fünf Beobachtungen; bei Lauten zusätzlich bis drei Wortkontexten. Bestätigte Muster haben Vorrang vor Einzelbeobachtungen, fällige Wiederholungen werden nach Termin sortiert.
Dies sind versionierte Lernheuristiken, keine kalibrierten Konfidenzwerte, keine klinische Diagnose und keine Zertifizierung. Die unveränderten Azure-Punkte bleiben von diesen Lernentscheidungen getrennt.
### Auswahl und KI-Vertrag
Der Mix strebt 60 % aktuelle Schwierigkeiten/Nachprüfung, 25 % fällige Wiederholung und 15 % neue Wortkontexte an. Go wählt die verfügbare Kategorie mit dem größten Defizit gegenüber diesen Anteilen. Gezählt werden gespeicherte Zuweisungen sowie kurzzeitig laufende Reservierungen gegen konkurrierende Anfragen; fehlgeschlagene Reservierungen zählen nicht und verwaiste werden nach fünf Minuten freigegeben. Übersprungene Übungen ändern keine Messwerte. Nach zweimal demselben Ziel wird eine Alternative gewählt oder eine allgemeine Übung angeboten.
Die KI erhält ausschließlich den gespeicherten Auftrag mit Algorithmusversion, Kategorie, Zielstatistik und höchstens drei detaillierten Wortbeispielen, bekannten Wortkontexten und der Satzsperrliste. Sie bekommt keine rohe Versuchshistorie und berechnet keine eigenen Messwerte. `required_practice_words` und TTS-/Referenzgleichheit werden wie bisher geprüft.
Transferaufträge (`mode=transfer`) erlauben ein neues Wort, das als `candidate_word` zusätzlich zur bisherigen Ausgabe zurückgegeben werden muss. Es darf nicht in `known_words` vorkommen und muss im Satz und in `focus_points` stehen. Die Zuordnung bleibt `unconfirmed`. Eine spätere echte Phonemmessung im Kandidatenwort kann sie auf `confirmed` setzen; gemessene andere Laute ergeben `measured_without_target`. Das bestätigt nur die Zuordnung, keine Beherrschung. Jede reale Messung zählt ausschließlich für die tatsächlich gelieferten Wörter und Laute. Eine spätere Verwendung eines Reasoning-Modells benötigt keinen zweiten Planungsagenten.
### Anzeige und API
`GET /pronunciation/profile` ist authentifiziert und liefert ausschließlich das Profil des angemeldeten Nutzers in seiner aktiven Zielsprache: Algorithmus, Zeitfenster, bestätigte/unbestätigte Nachweise sowie Ziele mit Beispielen, Zustand, Entwicklung und Wiederholungstermin. Die App zeigt das unter Fortschritt. Alte Durchschnittswerte heißen historischer Durchschnitt. Bei Ausspracheübungen erscheinen zusätzlich `training_reason` und `training_category`; die Begründung stammt aus dem gespeicherten Go-Auftrag.
Die bisherigen Kurs-/Ausspracheendpunkte und historischen Antwortfelder bleiben nutzbar. Die neue Statistik entscheidet keine Kursabschlüsse und aktiviert kein Modellprofil. API und Web müssen für diese Änderung gemeinsam neu gebaut werden. Für reine Statistikvorschau ohne neue Auswahl `PRONUNCIATION_STRATEGY=recent` verwenden; das muss der neu gestarteten API übergeben werden.
## Muttersprache und Aufgabenvarianten
Muttersprache bezeichnet gemeinsam Oberfläche und Erklärungen. Deutsch und Russisch
haben jeweils den vollständigen Bestand von 840 Englischaufgaben in sieben Modulen
und den internen A1-Test. Weitere Details: [README](../README.md#mehrsprachigkeit).
Die Sprachwahl löst keinen Modellaufruf aus und aktiviert keine Profile.
Aufträge frieren die Muttersprache beim Einreihen ein. Aufgaben speichern Variante,
Revision, Kriterien und Lösung. Sprachwechsel verändern keine historischen Daten.
Äquivalente Übersetzungen teilen die Nachweisidentität; Versuche bleiben getrennt.
Ein Modell darf keine Varianten- oder Nachweisidentität setzen. Englische Lerntexte
und Azure-Messwerte bleiben unverändert. Fehlende Varianten führen zu einem
Verfügbarkeitshinweis, ohne deutschen Ersatz. Offene Antworten benötigen weiterhin
ein Bewertungsprofil oder bleiben unbenotet. Der alternative KI-Modus erhält die
Muttersprache über das kompatible Eingabefeld `ui_language`; seine fachliche
Live-Qualität ist durch Fixturetests nicht nachgewiesen.
## Standardbetrieb mit geprüftem Bestand
`COURSE_TASK_MODE=bank` ist der Standard; `ai` erhält den bisherigen KI-Generator. Die Compose-Dateien reichen den Wert an die API durch. Für den Bankbetrieb sind keine Modellschlüssel und kein LLM-Budget nötig. Ein eingerichtetes Bewertungsprofil kann offene Antworten optional bewerten; es wird nicht automatisch aktiviert. Der separate Aussprachebereich `next_exercise` ist von dieser Kursauswahl unabhängig.
840 Einträge in 42 JSON-Dateien: sieben Module × sechs Bereiche × 20 Aufgaben. Pro Bereich acht leichte, acht mittlere und vier festigende Aufgaben. Der Sprach-/Kurskontext bleibt `en-US` / `a1-v2`; weitere Sprachpakete bleiben getrennt. Editorialquellen, Offline-Build, Audit und Prüfvermerk liegen unter `tools/course_bank/`. Der Build verweigert geänderte Quellen ohne aktualisierten redaktionellen Prüfvermerk. Diese redaktionelle Durchsicht ist keine externe Lehrerzertifizierung.
```bash
python tools/course_bank/build.py
python tools/course_bank/audit.py
```
Beim API-Start werden Manifest, Prüfsummen, Verteilung, Lösungen und Rendererfelder geprüft und der Bestand transaktional importiert. Ein unveränderter Import ist wiederholbar. Eine vorhandene Eintrags-ID mit anderem Inhalt wird abgelehnt: Korrekturen erhalten neue Revisions-IDs. Nur Vorlagen werden aktiviert/deaktiviert; bereits zugewiesene Aufgaben und Tests bleiben unverändert. Keine alte Bewertung wird überschrieben.
`course_v2_bank` enthält die versionierten Vorlagen, Lernziele und Schwierigkeiten. Die Auswahl erstellt persönliche Kopien in `course_v2_tasks` mit Herkunft `curated`, `bank_entry_id`, Präsentationszeit und Präsentationszähler. Gleichzeitige Auswahlaufträge werden pro Nutzer/Sprachprofil serialisiert. Eine Wiederaufnahme nach Abbruch liefert dieselbe bereits zugewiesene Aufgabe. Der vorhandene Aufgabenverlauf funktioniert weiter.
Neue Aufgaben haben Vorrang. Innerhalb dieser Gruppe werden passende noch neue Lernziele aus schwachen Bewertungen bevorzugt, ohne dafür über die Zielschwierigkeit hinauszugehen. Die letzten fünf echten bewerteten Antworten steuern die Schwierigkeit: nach mindestens drei verschiedenen Aufgaben ab Ø 85 eine Stufe erhöhen, nach mindestens zwei verschiedenen Aufgaben unter Ø 60 eine Stufe senken, jeweils innerhalb 1–3. Sonst bleibt die zuletzt bearbeitete Stufe. Bei erschöpftem Bestand folgen zuletzt schwach gelöste und länger nicht gezeigte Aufgaben; unmittelbare Wiederholungen werden vermieden, sofern Alternativen existieren. Unbenotete oder Demo-Antworten sind kein Fehlernachweis.
### Offene Antworten und A1-Test
Ohne verfügbaren Evaluator werden Text-/Sprachantworten mit Status `ungraded` gespeichert. Es entsteht keine erfundene Note und kein bewerteter Fortschritt. Bei Übungen zeigt die App nach Abgabe Beispielantwort und Rubrik zum Selbstvergleich. Echte Azure-Messwerte bleiben eigenständige Messwerte und ersetzen keine inhaltliche Benotung. Kein Modellaufruf für Analyse, Planung, Erstellung oder Testzusammenfassung im Bankbetrieb.
Vorhandene Retry-Endpunkte können die Bewertung später ausdrücklich anfordern; ohne eingerichteten Evaluator oder verfügbares Budget antworten sie im Bankbetrieb mit HTTP 409 und lassen die Antwort unverändert. Wird die optionale Bewertung eingerichtet, verarbeitet die bestehende Queue sie anhand der eingefrorenen Aufgabe/Rubrik.
Der A1-Test verwendet zwölf gespeicherte Aufgaben, zwei je Bereich und alle sechs Lernmodule. Nach zwölf Abgaben ohne zwölf Bewertungen lautet sein Status `submitted`. Bis zur vollständigen Bewertung bleiben Lösungen, Einzelbewertungen und Gesamtergebnis verborgen. Spätere Bewertungen schließen denselben Test ab. Die fertige Bank-Auswertung verwendet gespeicherte Bereichswerte und benötigt keinen KI-Zusammenfassungsaufruf.
### Kompatible Schnittstellenergänzungen
Die bisherigen Kursrouten bleiben erhalten. `/course/catalog` ergänzt `task_mode`, `grading_available` und `bank` mit Bestands-/Ungesehen-Zahlen je Modul und Bereich. Aufgaben ergänzen die Herkunft `curated`, Antworten den Status `ungraded`, Tests den Status `submitted`. Die festen Altaufgaben und historischen KI-Aufgaben bleiben erhalten. Aktualisierte Web-App und API gemeinsam ausrollen.
## Einrichtung des optionalen KI-Betriebs
1. Serverkonfiguration um `DEEPSEEK_API_KEY` und/oder `MISTRAL_API_KEY` ergänzen. Die echte `.env` wurde durch diesen Umbau nicht geändert. Die normalen Compose-Dateien reichen diese Schlüssel an die API durch; die Entwicklungs-Compose-Datei startet keinen Flowise-Dienst mehr.
2. Nach einem ausdrücklich autorisierten Neubau/Start als Admin anmelden. Bestehende Konten und Rollen bleiben erhalten. Ohne Admin: eigenes Konto wie in der Haupt-README beschrieben über PostgreSQL zum Admin machen.
3. Im Adminbereich unter **KI-Einstellungen und Verbrauch** ein positives Monatsbudget in USD speichern. `0` sperrt Modellaufrufe. Ein Tageslimit ist optional; dort bedeutet `0` kein zusätzliches Tageslimit.
4. Für jeden benötigten Arbeitsschritt ein Profil konfigurieren: Anbieter, genaue Modell-ID, maximale Ausgabe, Kontextbudget, Zeitlimit und aktuelle Preise. Alle Profile beginnen deaktiviert, ohne Modell und ohne freigegebene Preise. Modelllisten/Verbindungstest verwenden nur den jeweiligen Modelle-Endpunkt, keine Textgenerierung.
5. Eingabe-, Cache-Eingabe- und Ausgabepreise werden als USD je Million Tokens eingegeben. Es gibt keine automatisch angenommenen oder hartcodierten Anbieterpreise. Preise explizit prüfen und bestätigen; für einen tatsächlich kostenlosen Tarif sind bestätigte Nullpreise möglich. Ein fehlender Cache-Nachweis wird zum normalen Eingabepreis geschätzt.
6. Zuerst das gespeicherte Bewertungsprofil mit den zwei eingebauten Qualitätsfällen testen. Der Test prüft eine richtige und eine falsche Verbform. Ein bestandener Test ist eine begrenzte Stichprobe, keine Garantie für alle Sprachen oder Aufgaben. Testaufrufe sind kostenpflichtig und werden erfasst; sie verändern keine Kursantworten oder Lernstände. Danach weitere Fälle je Sprache im freien Testfeld prüfen und die gewünschten Profile aktivieren.
Verwendet werden `https://api.deepseek.com/chat/completions` bzw. `https://api.mistral.ai/v1/chat/completions`; Modelllisten unter `/models` am jeweiligen Basisendpunkt. Die produktiven Endpunkte werden nicht aus Browser-Eingaben oder alten Flowise-Konfigurationen übernommen. Anbieterzugänge sind direkte API-Zugänge, keine OpenRouter-Verbindungen.
## Profile und Prompts
Neun Arbeitsschritte besitzen unabhängige Profile:
- Lernanalyse und Aufgabenplanung
- Aufgabenautor und unabhängiger Prüfer für eine Aufgabe
- Testautor und unabhängiger Prüfer für zwölf Aufgaben
- Antwortbewertung und Testzusammenfassung
- Generierung einer Nachsprechübung im bisherigen Aussprachebereich
Analyse, Planung und Bewertung haben getrennte Systemprompts. Prompts und Schemas liegen unter `apps/api/internal/services/aiprompts/` und werden in das Go-Binary eingebettet; auch das Scratch-Containerimage benötigt keine zusätzlichen Laufzeitdateien. Die Adminansicht zeigt den jeweiligen Prompt, das Schema und die Versionskennung. Promptänderungen erfolgen über das Repository und einen späteren Neubau, nicht über einen zweiten unversionierten Browsereditor.
Beim ersten Bearbeitungsschritt eines Auftrags speichert `ai_operations` alle Profilversionen, Promptinhalte und Schemas. Laufende und wiederaufgenommene Aufträge verwenden diese gespeicherten Daten, auch wenn zwischenzeitlich Profile geändert oder ein neues Binary installiert werden. Eine gespeicherte erfolgreiche Modellantwort desselben Auftrags, Arbeitsschritts und Eingabehashs wird wiederverwendet. Eine ausdrücklich angeforderte Wiederholung eines fehlgeschlagenen Kursauftrags beginnt eine neue KI-Auftragsrevision mit aktuellen Profilen. Die gespeicherte Antwort bleibt erhalten. Wiederaufnahme nach Prozessabbruch verwendet dagegen dieselbe Revision und Konfiguration. Admin-Testaufrufe mit derselben Request-ID behalten ihre ursprüngliche Konfiguration; für eine neue Konfiguration einen neuen Test starten.
Die maximale Anzahl kostenpflichtiger Aufrufe ist zwei pro Arbeitsschritt und KI-Auftragsrevision, einschließlich ungültiger Antworten und automatischer Wiederaufnahme. Eine ausdrückliche Wiederholung eines fehlgeschlagenen Auftrags durch den Nutzer erzeugt eine neue Revision; deren zusätzliche Aufrufe werden ebenfalls erfasst. Unklare Verbindungsabbrüche werden nicht blind automatisch wiederholt; ein explizit wiederaufgenommener Auftrag kann den zweiten Aufruf verwenden. Nach Ausschöpfen der zwei Aufrufe liefert Aufgabenerzeugung eine Reserve; eine offene Antwort bleibt erhalten und wird als fehlgeschlagen angezeigt. Eine bereits abgeschlossene historische Bewertung wird durch einen administrativen Test nicht korrigiert.
Temperatur wird nur gesendet, wenn ausdrücklich gesetzt; im eingeschalteten DeepSeek-Denkmodus wird sie weggelassen. Denkaufwand nur für unterstützte Modelle setzen. DeepSeek verwendet JSON-Modus mit anschließender Go-Vertragsprüfung. Für unterstützte Mistral-Modelle kann zusätzlich nativer JSON-Schemamodus aktiviert werden. Der Transport entfernt dort nicht unterstützte bedingte Schemaoperatoren und begrenzt Aufgabenanzahl sowie Rendererfelder anhand des gespeicherten Auftrags. Das vollständige Originalschema bleibt versioniert; Go prüft weiterhin alle technischen Bedingungen. Im normalen JSON-Modus wird das vollständige Schema dem Systemprompt beigefügt. Parameterfähigkeit muss mit Modellliste/Anbieterdokumentation und Testlauf geprüft werden; fehlerhafte Parameter ergeben einen sichtbaren Anbieterfehler statt still geänderter Einstellungen. Providerfehlerdetails werden im Admin-Aufrufprotokoll gespeichert, bekannte API-Schlüssel werden dabei maskiert.
Das Kontextbudget ist eine harte lokale Grenze für Ein- und Ausgabe. Vor dem Versand wird die vollständige serialisierte Anfrage konservativ anhand ihrer UTF-8-Bytes plus Protokollreserve begrenzt. Deshalb kann eine Anfrage früher als bei einer exakten Tokenizerzählung abgelehnt werden. Das Budget muss zum Modell passen und groß genug für Prompts, Lernstand und Ausgabe sein. Zwölfteilige Tests brauchen deutlich mehr Platz als eine einzelne Auswahlaufgabe. Standardausgabe: 4096 Tokens, beim Testautor/-prüfer 16384; Standardkontext: 32768. Diese Startwerte sind keine Empfehlung für jedes Modell. Zeitlimit 5–90 Sekunden pro Aufruf; der bestehende Gesamtzeitrahmen der Hintergrundaufträge bleibt bestehen.
Der Autor erzeugt Aufgaben. Der unabhängige Prüfer erhält den ursprünglichen Auftrag und den Entwurf; bei Auswahlaufgaben werden Lösungsschlüssel und Erklärung absichtlich ausgeblendet. Er löst die sichtbare Frage selbst und meldet in `choice_checks` je `task_index` für jede Option deren `option_id`, `is_correct` und eine kurze Begründung. Go prüft die vollständige, eindeutige Abdeckung aller Optionen und zählt die als richtig eingestuften Antworten. Go akzeptiert nur genau eine unabhängig ermittelte Lösung, die mit der gespeicherten Autorenlösung übereinstimmt. Fehlende, doppelte, mehrdeutige oder abweichende Prüfungen führen zur Ablehnung. Offene Aufgaben behalten ihre Rubrik für die fachliche Prüfung. Der Prüfer liefert ausschließlich eine Entscheidung und kann keine Aufgaben umschreiben. Dieser direkte KI-Vertrag liegt in `aiprompts/review.json`; das historische Flowise-Generatorschema bleibt davon getrennt. Go prüft Kontext, Renderer und technische Verträge, keine englischen Satzmuster. Nach erfolgreicher Speicherung lautet die Herkunft `ai` und die Web-App zeigt „Mit KI erstellt“. Historische `flowise`-Einträge bleiben unverändert erkennbar. Eine Ablehnung, fehlende Einrichtung oder Budgetsperre führt zu sprach-/modul-/bereichsgleichen Reserven. Offene Reserveantworten benötigen weiterhin ein aktiviertes Bewertungsprofil.
## Tokenverbrauch und Kosten
Jeder HTTP-Modellaufruf erzeugt vor dem Versand einen Eintrag in `ai_calls`, einschließlich Testaufrufen. Gespeichert werden Auftrag/Nutzer, Arbeitsschritt, Anbieter, angeforderte Modell-ID, Profil- und Promptversion, Eingabehash, Versuch, Status, Dauer und Anbieter-Verbrauch. Die Admin-Einzeldetailansicht enthält die gesendeten System-/User-Nachrichten ohne Authorization-Header und die Antwort. Diese Inhalte können Lerndaten enthalten und sind ausschließlich für Admins erreichbar. Nutzerlisten und reguläre API-Logs enthalten diese Nachrichten nicht.
- Eingabe- und Ausgabetokens stammen aus `usage.prompt_tokens` und `usage.completion_tokens`.
- Cache- und Reasoning-Details werden übernommen, wenn geliefert. Sie sind Teilmengen der Eingabe/Ausgabe und werden nicht zusätzlich als Gesamttokens addiert.
- Fehlende Usage-Felder bleiben unbekannt, nicht nullverbrauchend. Auch gültige Aufgaben ohne Usage behalten eine offene Kostenreservierung.
- Eine wegen abgeschnittenem JSON oder falschem Vertrag abgelehnte Antwort kann dennoch abgerechnet worden sein; ihre Usage wird erfasst.
- 4xx-Ablehnungen vor einer Generierung werden mit null geschätzten Generierungskosten geführt. HTTP 429 wird nicht sofort identisch wiederholt; die Meldung des Anbieters (auch Mistrals oberstes `message`-Feld) bleibt im Adminprotokoll erhalten. Bei Serverfehlern, Abbrüchen oder unklarer Antwort bleibt die Reservierung bestehen.
- Anzeige und Filter sind nach Zeitraum, Anbieter, angeforderter Modell-ID, Nutzer-ID und Arbeitsschritt verfügbar, mit 50 Einträgen je Seite. Modellaliasnamen können beim Anbieter auf neue Modellversionen zeigen; für reproduzierbarere Konfiguration möglichst konkrete Modellversionen verwenden.
Preisrechnung erfolgt ganzzahlig in Mikro-USD, mit Aufrunden pro Tokenklasse. Der Datensatz verwendet seine beim Start gespeicherte Preisliste; spätere Preisänderungen schreiben frühere Schätzungen nicht um. Rechnung und Guthaben des Anbieters bleiben verbindlich. Azure-Speech-Kosten sind nicht Teil dieses LLM-Budgets.
## Budget und Wiederaufnahme
Tages-/Monatsgrenzen werden in UTC anhand des Beginns des jeweiligen Aufrufs zugeordnet. Vor jedem Aufruf sperrt eine PostgreSQL-Transaktion die globale Budgetzeile und reserviert das vollständige konfigurierte Kontextbudget zum höheren Ein-/Ausgabepreis plus Rundungsreserve. Die konservative Eingabebegrenzung und das Ausgabelimit begrenzen die mögliche Tokenmenge. Das ist bewusst vorsichtiger als eine optimistische Zeichenschätzung. Auch ein kleiner tatsächlicher Aufruf kann vorübergehend eine relativ große Reservierung benötigen. Reicht das verfügbare Budget nicht für diese Obergrenze, wird er nicht gesendet.
Nach einer Antwort mit vollständiger Usage wird die Reservierung durch die tatsächliche Kostenschätzung ersetzt. Ohne sichere Usage bleibt sie offen. Mehrere Worker/API-Prozesse können dasselbe Budget nicht unabhängig ausgeben. Ab 80 Prozent eines Limits erscheint eine Warnung; bei fehlendem oder ausgeschöpftem Monatsbudget sind neue Aufrufe gesperrt. Bereits laufende Aufrufe werden nicht rückwirkend abgebrochen.
Nach einem Prozessabbruch werden länger als fünf Minuten laufende Aufrufeinträge als unbekannt gekennzeichnet, ohne Geld freizugeben. Admins können unbekannte Einträge mit dokumentierten Kosten und Begründung anhand der Anbieterrechnung abgleichen. Der Abgleich bleibt am Aufruf sichtbar und kann nicht still ein zweites Mal überschrieben werden. Nicht mehr benötigte Reservierungen nicht ohne Abgleich als null verbuchen.
Tabellen werden additiv beim API-Start angelegt: `ai_profiles`, `ai_profile_versions`, `ai_budget`, `ai_budget_history`, `ai_operations`, `ai_calls`. Die Herkunftsbeschränkung für neue Kursaufgaben wird um `ai` erweitert. Bestehende Aufgaben, Antworten und Fehlerbewertungen bleiben unverändert. Eine historische falsche Bewertung muss separat überprüft werden; neue Prompts reparieren sie nicht rückwirkend.
## Admin-API
Alle Endpunkte benötigen den aktuell geprüften Adminstatus:
| Methode / Pfad | Aufgabe |
|---|---|
| `GET /admin/ai/settings` | Profile, Budget, konfigurierte Anbieter, Prompt-/Schemaansicht |
| `PUT /admin/ai/profiles/{action}` | Profil mit bisheriger `version` speichern; Konflikte HTTP 409 |
| `PUT /admin/ai/budget` | `monthly_limit_microusd`, `daily_limit_microusd` |
| `GET /admin/ai/providers/{provider}/models` | Modellliste / Verbindung prüfen |
| `POST /admin/ai/test` | `{request_id,action,input}`; syntaktisch/technisch geprüfter Test ohne Fortschrittsänderung |
| `POST /admin/ai/quality` | `{request_id,suite?}`; `grammar` (Standard) oder `writing`, jeweils zwei feste Bewertungsfälle mit `passed` je Fall |
| `GET /admin/ai/usage` | Filter `from`, `to` als RFC3339, `provider`, `model`, `user`, `action`, `offset` |
| `GET /admin/ai/calls/{id}` | Einstellungen, tatsächlich gesendete Eingabe, Ausgabe und Verbrauch |
| `POST /admin/ai/calls/{id}/resolve` | `{cost_microusd,reason}` für den dokumentierten Abgleich |
Eine Million Mikro-USD entsprechen einem USD. Die Profilfelder `input_microusd_per_million`, `cached_input_microusd_per_million` und `output_microusd_per_million` enthalten Preise in Mikro-USD je Million Tokens. Die Browseroberfläche rechnet die Formulareingabe in USD um. Testaufrufe liefern ihr Ergebnis mit `ok` bzw. `passed`; HTTP 200 bedeutet allein noch keine fachlich richtige Modellantwort.
Die beiden Qualitätsprüfungen werden ausdrücklich im Adminbereich gestartet und
verursachen jeweils bis zu zwei kostenpflichtige Modellaufrufe. Die Schreibsuite
prüft eine korrekte Vorstellung sowie Artikel- und Rechtschreibfehler; die
Grammatiksuite prüft korrekte und falsche Verwendung von `has got`. Erfolgreiche
Fälle belegen diese begrenzten Szenarien, keine allgemeine Bewertungszuverlässigkeit.
`GET /debug/ai` zeigt Einrichtung und Budget ohne kostenpflichtige Generierung. `/debug/flowise` bleibt als veralteter, rein lesender Alias für den KI-Status vorhanden; er kontaktiert kein Flowise. Die regulären Kurs- und Ausspracheendpunkte bleiben kompatibel.
## Prüfungen
```bash
cd apps/api
COURSE_TEST_DATABASE_URL='postgres://.../wegwerfbare_testdatenbank' go test -race ./...
go vet ./...
```
Ohne ausdrücklich gesetzte Testdatenbank werden PostgreSQL-Integrationstests übersprungen. Sie verwenden jeweils zufällige Schemas und entfernen diese anschließend. Providerantworten kommen aus lokalen HTTP-Testservern, echte Schlüssel und Live-Modelle werden nicht benutzt.
Browserprüfung: [apps/web/tests/README.md](../apps/web/tests/README.md). Live-Modellqualität ist erst nach explizit ausgelösten und erfassten Testaufrufen bestätigt. Die eingebauten Regressionstests prüfen insbesondere korrekte/falsche Verbformen, Token-/Cacheabrechnung, Budgetkonkurrenz, Antwortwiederverwendung, Profile während laufender Aufträge, Fehler-/Timeoutfälle, Adminschutz und direkte Aufgabengenerierung.
## Modellprüfung am 26. Oktober 2026
Live-Tests verwenden ausschließlich Mistral und ein separates Testkonto. Das globale Testlimit bleibt bei 0,25 USD pro Monat und Tag. API-Schlüssel und persönliche Lernantworten werden nicht verändert. Mehrere Ministral-Modelle antworten; eine erfolgreiche Modellliste allein bestätigt weder freie Generierungskapazität noch fachliche Zuverlässigkeit. Mistral Small/Medium und teilweise auch Ministral melden HTTP 429, darunter ausdrücklich fehlende Kapazität. Bei Zeitüberschreitungen bleibt der mögliche Verbrauch reserviert und muss anhand der Anbieterabrechnung abgeglichen werden.
Die bisherige reine Freigabe des Autoren-Lösungsschlüssels erwies sich als unzureichend: kleine Modelle bestätigten falsche Lösungen oder mehrere richtige Optionen. Deshalb erfolgt die neue unabhängige Lösungsermittlung ohne den Auswahl-Lösungsschlüssel. Auch diese Prüfung ist eine Modellentscheidung und keine mathematische Garantie fachlicher Richtigkeit; bewusst falsche und mehrdeutige Kandidaten gehören zur Modellabnahme. Ein einzelner bestandener Test reicht nicht zur Freigabe aller Rollen.
Der kürzere Bewertungsauftrag wurde mit echten Modellantworten für richtige Sätze, richtige Alternativen, Verbfehler, fehlendes Verb, Wiederholung und eine Anweisung im Antworttext geprüft. Bestehende falsche historische Bewertungen werden dabei nicht umgeschrieben. Änderungen an eingebetteten Prompts und dem Transport benötigen einen Neubau der API; reine Profiländerungen benötigen keinen Neustart. Rollen erst nach erfolgreicher Abnahme mit der neuen Promptversion aktivieren. Alte eingefrorene Auftragsrevisionen verwenden weiterhin ihre gespeicherten Inhalte; nach einem Vertragswechsel gegebenenfalls einen neuen Auftrag starten.
Abnahmeergebnis: In der isolierten Testinstanz wurden echte Mistral-Aufträge durch Analyse, gespeicherten Lernauftrag, Erstellung, Prüfung und PostgreSQL bis zum Browser ausgeführt. Eine tatsächlich erzeugte Wortschatzaufgabe ließ sich korrekt beantworten und nach Neuladen wiederherstellen. Eine offene Familienbeschreibung wurde asynchron mit 100 Punkten bewertet. Die sechs gezielten Bewertungsfälle bestanden; bei generierten Aufgaben und Prüferentscheidungen traten weiterhin fachliche Fehler auf, darunter fehlender Bildkontext und falsch beurteilte Grammatik. Deshalb sind alle neun vorbereiteten Mistral-Profile noch deaktiviert. Die Modellabnahme ist nicht für sämtliche Rollen bestanden. Die modellgestützte Prüfung ersetzt keine Garantie fachlicher Richtigkeit. Alte Aufgaben und Bewertungen wurden nicht repariert oder gelöscht.
## Gezielte Ausspracheübungen
Der separate Aussprachebereich verwendet `next_exercise` direkt beim konfigurierten Anbieter. Der Auftrag enthält nur Nachweise der angeforderten Zielsprache aus dem aktuellen Aussprachefenster: schwierige Wörter, gemessene schwache Phoneme mit zugehörigem Wort und zu vermeidende Sätze. Neuere erfolgreiche Wort-/Phonemwerte lösen ältere Schwächen ab; ausgelassene Wörter begründen keinen Phonemfehler. Benutzer-/Übungs-IDs und frühere Lehrerkommentare werden nicht an den Generator weitergegeben.
Der Generator soll ein bis zwei belegte Trainingswörter in einem neuen kurzen Satz verwenden. Ohne Nachweise erzeugt er eine allgemeine Einstiegsübung. Azure bleibt für Anhören und Aussprachemessung zuständig. Der Kursmodus `bank` schaltet diese separate Generierung nicht aus.
Zum Einschalten im Adminbereich unter Modellprofile den Arbeitsschritt **Aussprachegenerierung** wählen. Anbieter, verfügbares Modell, Preise und Token-/Zeitgrenzen müssen vollständig gespeichert sein; das Profil muss aktiviert und das vorhandene Budget ausreichend sein. Ein API-Schlüssel allein genügt nicht. Reine Profiländerungen benötigen keinen Neustart; diese Prompt-/Codeänderung benötigt einen API-Neubau. Bei deaktiviertem Profil, fehlendem Budget oder Anbieterfehler bleibt die feste Ersatzaufgabe verfügbar. Die Aktivierung verändert keine anderen Kursprofile.
### Aufgelöste Schwächen und Wiederholungsschutz
Der Aussprachegenerator bekommt keine alte Versuchshistorie mehr. Go ermittelt weiterhin die aktuellen Schwächen aus den letzten gespeicherten Versuchen derselben Sprache, sendet aber nur die aktiven Wort-/Phonemlisten und die Anzahl betrachteter Versuche. Beide Listen sind auch ohne Einträge JSON-Arrays. `training_mode=general` verlangt eine allgemeine Übung ohne persönliche Fehlerdiagnose; `targeted` verlangt Training anhand der übergebenen aktuellen Schwächen. Das verhindert, dass der Prompt alte, inzwischen verbesserte Einzelbewertungen erneut als Beleg anbietet; die inhaltliche Befolgung bleibt eine Modelleigenschaft.
Vor jeder Aussprachegenerierung liest Go zusätzlich die letzten fünf unterschiedlichen gespeicherten Sätze des Nutzers in derselben Zielsprache und Niveaustufe. Dies umfasst erzeugte, noch unbeantwortete Übungen und bearbeitete feste Aufgaben. Die Sätze werden mit der vom Browser übergebenen Sperrliste verbunden und bei der bestehenden Antwortvalidierung berücksichtigt. Dieser Verlauf bleibt nach Neuladen erhalten. Der feste Ersatzbestand bleibt bei Anbieterausfall verfügbar. Keine Schemaänderung; API-Neubau erforderlich.
### Aussprache-Ausgabevertrag
`services/aiprompts/pronunciation.json` beschreibt die Pflichtfelder und Längen des Aussprachegenerators. Im JSON-Modus wird das Schema im Systemprompt mitgesendet, im aktivierten Mistral-Schemamodus als `response_format`. Die Go-Prüfung bleibt verbindlich. Begründungen müssen einzeilig und höchstens 300 Zeichen lang sein; der Prompt verlangt möglichst unter 160 Zeichen. Fehlende, zu lange und mehrzeilige Textfelder werden getrennt diagnostiziert. Der einmalige Korrekturversuch bekommt die konkrete Abweichung und muss erneut ein vollständiges Objekt liefern; danach bleibt der bisherige Seed-Fallback erhalten. Neue Aufträge verwenden die neue Prompt-/Schemaversion nach API-Neubau, bestehende Verbrauchseinträge bleiben unverändert.
### Verbindliches Wort im gezielten Training
Bei `targeted` wählt Go das Wort mit dem niedrigsten aktuellen Wortwert oder den Wortkontext des niedrigsten gemessenen Phonemwerts als `required_practice_words`. Das Wort muss im neuen Referenzsatz und in `focus_points` stehen. Gesperrt werden ganze frühere Sätze, nicht deren einzelne Wörter. Ein Austausch durch ein anderes Wort wird mit konkretem Korrekturhinweis zurückgegeben. Referenz- und TTS-Text müssen übereinstimmen. Diese generische Zielprüfung ersetzt keine fachliche Kontrolle aller Modellformulierungen; insbesondere werden behauptete Lautverwechslungen weiterhin durch den Prompt untersagt, nicht als aus Scores beweisbare Tatsachen behandelt.