Azure-Phonemwerte in Versuchen sichern, schwache Laute im Fortschritt und Flowise-Kontext auswerten und die Web-Anzeige ergänzen. README dokumentiert Datenfluss, Betrieb und Grenzen der Funktion.
Speech Learning App
Sprachlern-App für Ausspracheübungen auf A1-Niveau. Die Web-App nimmt Sprache auf und zeigt Übungen sowie Bewertungen an. Die Go-API steuert den Ablauf, speichert den Lernverlauf in PostgreSQL, lässt Flowise neue Übungen erzeugen und ruft Azure Speech zur Aussprachebewertung auf.
Aktueller Funktionsumfang
- Registrierung, Login und Lernerprofil mit Zielsprache, Oberflächensprache und Tagesziel
- Kurze englische
repeat_sentence-Übungen aus Flowise; Seed-Übungen als Fallback - Audioaufnahme im Browser und Aussprachebewertung über Azure Speech
- Gesamt-, Wort- und bei echten Azure-Antworten auch Phonemwerte
- Feedback zum Versuch sowie Fortschrittsansicht mit schwachen Wörtern und Lauten
- Mock-Modus für lokale Entwicklung ohne Azure-Zugang
Weitere Übungstypen, ein evaluate_attempt-Flowise-Task und ein langfristiges Fähigkeitsmodell pro Wort sind noch nicht implementiert.
Architektur und Datenfluss
Browser/Web-App ──► Go-API ──► Flowise (nächste Übung)
│
├──────► Azure Speech (Aussprachebewertung, TTS)
├──────► PostgreSQL (Profile, Übungen, Versuche)
└──────► Redis
Der Browser spricht nur mit der Go-API. API-Schlüssel für Flowise und Azure bleiben serverseitig. Die Go-API authentifiziert Nutzer, prüft Flowise-Antworten und entscheidet, was dauerhaft gespeichert wird. PostgreSQL ist die verbindliche Quelle für Übungen und Lernverlauf. Flowise erzeugt didaktisch passende Aufgaben, ändert aber keinen Lernstatus in PostgreSQL.
Eine Übungsrunde läuft so ab:
- Die Web-App lädt das Dashboard oder fordert über
POST /lessons/nexteine neue Übung an. - Die Go-API liest Profil und letzte Versuche aus PostgreSQL. Sie erstellt daraus einen kompakten Kontext und sendet
task: "next_exercise"an Flowise. - Die Go-API prüft die erzeugte
repeat_sentence-Übung und speichert sie. Falls Flowise ausfällt oder keine gültige Übung liefert, verwendet die API eine Seed-Übung. - Die Web-App zeigt den Satz, nimmt Sprache auf und sendet Audio und
exercise_idanPOST /practice/attempts. - Die Go-API schickt das Audio mit dem Referenzsatz an Azure Speech, verarbeitet die Bewertung und speichert den Versuch in PostgreSQL.
- Die Web-App zeigt Ergebnis und Lehrerfeedback.
GET /progressliefert die letzten Versuche sowie daraus berechnete schwache Wörter und Laute.
Flowise wird bei der unmittelbaren Bewertung eines Versuchs derzeit nicht aufgerufen. Das Lehrerfeedback entsteht in der Go-API anhand der Azure-Werte. Insbesondere entscheidet Flowise weder über „gemeistert“ noch über einen Niveauwechsel.
Aussprachebewertung auf Phonemebene
Die Go-API fordert Azure Pronunciation Assessment mit Granularity: "Phoneme", GradingSystem: "HundredMark" und PhonemeAlphabet: "IPA" an. Azure kann dabei neben Satz- und Wortwerten auch Genauigkeitswerte für einzelne Laute liefern. Die API übernimmt nur tatsächlich vorhandene Phonemwerte; ein fehlender Wert wird nicht als 0 interpretiert. Ein echter Wert 0 bleibt dagegen erhalten.
Ein vereinfachter Ausschnitt aus einem gespeicherten Versuch und der Antwort von POST /practice/attempts:
{
"word_scores": [
{
"word": "water",
"accuracy": 72,
"phonemes": ["w", "ɔ", "t", "ə"],
"phoneme_scores": [
{ "phoneme": "w", "accuracy": 91, "highlight": "good" },
{ "phoneme": "t", "accuracy": 58, "highlight": "weak" }
],
"highlight": "weak"
}
]
}
phonemes enthält die von Azure gelieferten Lautbezeichnungen. phoneme_scores enthält nur Laute, für die Azure auch einen Genauigkeitswert geliefert hat. Die Beispielzahlen oben sind illustrativ und keine erwarteten Werte für „water“.
Die Einstufung in der aktuellen App ist eine einfache Anzeigeregel: unter 75 = weak, 75 bis unter 85 = ok, ab 85 = good. Das ist keine Aussage darüber, welcher konkrete Artikulationsfehler vorlag. Die Lautanalyse nach einem Versuch zeigt die bewerteten Laute pro Wort. Bei einem gemessenen schwachen Laut kann das Lehrerfeedback das Wort, das Phonem und dessen Punktzahl nennen; bei sehr hohen Satzwerten empfiehlt es eine neue Übung.
PostgreSQL speichert phoneme_scores als Teil des bestehenden attempts.word_scores_json-Felds. Dafür ist keine neue Tabelle und keine Migration nötig. Alte Versuche enthalten diese Werte nicht rückwirkend. Der Mock-Modus liefert derzeit nur Wortwerte; dort zeigt die Web-App entsprechend an, dass keine Lautwerte verfügbar sind.
Schwache Laute im Fortschritt
GET /progress enthält zusätzlich weak_phonemes. Die Go-API berechnet diese Liste aus den letzten 20 Versuchen; bei der nächsten Übung betrachtet sie die letzten 10. Pro Kombination aus Wort und Laut zählt der neueste bewertete Versuch. Wird derselbe Laut in diesem Versuch mehrfach bewertet, zählt der niedrigste Wert. Ein neuerer guter Wert entfernt damit eine ältere Schwäche aus dem betrachteten Fenster. Ausgelassene Wörter (Omission) werden für die Lautliste übersprungen. Die Liste ist nach niedrigstem Wert sortiert und auf 12 Einträge begrenzt.
{
"weak_phonemes": [
{ "word": "water", "phoneme": "t", "accuracy": 58 }
]
}
Das ist eine Momentaufnahme aus den letzten Versuchen, keine dauerhafte Diagnose oder ein über alle Zeiten berechneter Beherrschungsgrad. Schwache Wörter werden unabhängig davon ebenfalls aus dem jüngsten Wortwert im betrachteten Fenster berechnet.
Flowise-Anbindung
Die Go-API ruft POST /api/v1/prediction/{FLOWISE_CHATFLOW_ID} auf. Das Feld question enthält den Lernkontext als JSON-String; overrideConfig.sessionId ordnet die Anfrage der Übungssitzung zu. Der derzeit unterstützte Task heißt next_exercise.
Zum Kontext gehören unter anderem profile, progress, recent_weak_words, recent_weak_phonemes, preferred_type und die zuletzt benutzten Sätze unter avoid_reference_texts. Einzelne rohe phoneme_scores aus allen jüngsten Versuchen werden vor dem Flowise-Aufruf entfernt; die kompakte Liste recent_weak_phonemes transportiert den relevanten Lautfokus. Flowise soll einen anderen Satz als die zuletzt verwendeten erzeugen, kann aber dasselbe Zielwort erneut üben.
Der Flowise-Flow braucht weiterhin einen Learning Planner und einen Exercise Generator. In der bestehenden Flowise-Oberfläche ist die Eingabe als {{question}} verfügbar. Ergänze im Planner-Prompt sinngemäß diese Regel:
Lies recent_weak_phonemes aus dem Eingabe-JSON. Wenn dort gemessene niedrige Werte stehen, darfst du das zugehörige Wort für eine Ausspracheübung wählen. Nenne einen konkreten Laut nur, wenn er mit Messwert übergeben wurde. Ein niedriger Wortwert allein belegt keinen bestimmten Lautfehler. Erfinde keine Lautprobleme, Trends oder abgeschlossenen Lernstufen.
Der Generator soll das vom Planner gewählte Zielwort in einen kurzen natürlichen A1-Satz aufnehmen. focus_points dürfen einen konkreten Laut nur nennen, wenn der Planner ihn aus einem gemessenen recent_weak_phonemes-Eintrag übernommen hat. Das Antwortschema bleibt unverändert:
{
"exercise_type": "repeat_sentence",
"target_language": "en-US",
"cefr_level": "A1",
"reference_text": "I drink water every day.",
"display_prompt": "Sprich den Satz nach. Achte besonders auf water.",
"tts_text": "I drink water every day.",
"focus_points": ["water"],
"success_criteria": ["Sprich den vollständigen Satz gut verständlich nach."],
"reason_for_choice": "Water wurde in den übergebenen Daten als schwierig bewertet."
}
Die Go-API validiert die Antwort und vergibt selbst die Übungs-ID. Die Flowise-Prompts werden in der Flowise-Oberfläche verwaltet; eine Änderung am Go-Code aktualisiert die dort gespeicherten Prompts nicht automatisch. Weitere Hinweise stehen in flowise/README.md und flowise/agentflow-v2-setup.md.
Start auf dem VPS
Die Standard-Compose-Datei ist für den VPS vorgesehen. speech-web und speech-api hängen am vorhandenen Docker-Netzwerk web; die Datenbank liegt auf einem persistenten Docker-Volume.
docker compose up -d --build
- Web-App: https://speech.v2202510301049387828.goodsrv.de
- API-Healthcheck: https://speech.v2202510301049387828.goodsrv.de/api/health
- Flowise: vorhandene Instanz über
FLOWISE_BASE_URL
Nach einem Git-Update, das API und Web-App ändert, die beiden Dienste neu bauen:
git pull
docker compose up -d --build speech-api speech-web
Für echte Phonemwerte müssen in .env AZURE_SPEECH_KEY und AZURE_SPEECH_REGION gesetzt sein sowie AZURE_ENABLE_MOCK=false. Fehlt ein Azure-Schlüssel oder die Region, schaltet die API auch bei deaktiviertem Mock-Schalter auf Mock-Bewertung um. Für Flowise müssen FLOWISE_BASE_URL und FLOWISE_CHATFLOW_ID auf den verwendeten Flow zeigen.
Lokale Entwicklung
cp .env.example .env
docker compose -f docker-compose.dev.yml up --build
- Web-App: http://localhost:5173
- API-Healthcheck: http://localhost:8080/health
- Flowise: http://localhost:3000
Mit AZURE_ENABLE_MOCK=true funktioniert die Wortbewertung ohne Azure-Zugang; Lautwerte gibt es dann nicht. Für echte Bewertungen Azure-Zugangsdaten setzen und AZURE_ENABLE_MOCK=false verwenden.
Prüfung nach dem Deployment
- Einloggen und eine neue Übung öffnen. In den API-Logs sollte für eine von Flowise angenommene Übung
source: "flowise"erscheinen; bei einem Fehler wird eine Seed-Übung verwendet. - Den Satz aufnehmen. Nach dem Absenden sollten Gesamt- und Wortwerte sowie unter Lautanalyse bewertete IPA-Laute erscheinen.
- Fortschritt öffnen. Ein Laut unter
75sollte unter Schwierige Laute auftauchen. Nach einer neueren guten Bewertung desselben Lauts im selben Wort sollte er dort verschwinden, sofern er noch im betrachteten Versuchsfenster liegt. - Wenn Lautanalyse „keine Lautwerte verfügbar“ zeigt, zunächst Azure-Konfiguration und
providerin der Antwort vonPOST /practice/attemptsprüfen.provider: "mock"hat keine Phonemwerte. Auch echte Azure-Antworten können für einzelne Laute keinen Wert liefern.
API-Logs auf dem VPS:
docker compose logs --since=10m speech-api
Tests und Web-Build im Quellverzeichnis:
cd apps/api && go test ./...
cd ../web && npm run build
Debug
Debug-Endpunkte und der Navigationspunkt Debug lassen sich über .env aktivieren:
DEBUG_ENABLED=true
LOG_LEVEL=debug
Danach die API neu erstellen:
docker compose up -d --force-recreate speech-api
Die Debug-Ausgaben sind maskiert und geben keine Zugangsschlüssel aus.