Files
Speech/README.md
T
Eugenius Naumenko 82d8768a99 Phonembewertung speichern und anzeigen
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.
2026-10-10 17:59:44 +00:00

182 lines
11 KiB
Markdown

# 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
```text
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:
1. Die Web-App lädt das Dashboard oder fordert über `POST /lessons/next` eine neue Übung an.
2. Die Go-API liest Profil und letzte Versuche aus PostgreSQL. Sie erstellt daraus einen kompakten Kontext und sendet `task: "next_exercise"` an Flowise.
3. 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.
4. Die Web-App zeigt den Satz, nimmt Sprache auf und sendet Audio und `exercise_id` an `POST /practice/attempts`.
5. Die Go-API schickt das Audio mit dem Referenzsatz an Azure Speech, verarbeitet die Bewertung und speichert den Versuch in PostgreSQL.
6. Die Web-App zeigt Ergebnis und Lehrerfeedback. `GET /progress` liefert 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`:
```json
{
"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.
```json
{
"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:
```text
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:
```json
{
"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](flowise/README.md) und [flowise/agentflow-v2-setup.md](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.
```bash
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:
```bash
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
```bash
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
1. 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.
2. Den Satz aufnehmen. Nach dem Absenden sollten Gesamt- und Wortwerte sowie unter **Lautanalyse** bewertete IPA-Laute erscheinen.
3. **Fortschritt** öffnen. Ein Laut unter `75` sollte 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.
4. Wenn **Lautanalyse** „keine Lautwerte verfügbar“ zeigt, zunächst Azure-Konfiguration und `provider` in der Antwort von `POST /practice/attempts` prüfen. `provider: "mock"` hat keine Phonemwerte. Auch echte Azure-Antworten können für einzelne Laute keinen Wert liefern.
API-Logs auf dem VPS:
```bash
docker compose logs --since=10m speech-api
```
Tests und Web-Build im Quellverzeichnis:
```bash
cd apps/api && go test ./...
cd ../web && npm run build
```
## Debug
Debug-Endpunkte und der Navigationspunkt **Debug** lassen sich über `.env` aktivieren:
```env
DEBUG_ENABLED=true
LOG_LEVEL=debug
```
Danach die API neu erstellen:
```bash
docker compose up -d --force-recreate speech-api
```
Die Debug-Ausgaben sind maskiert und geben keine Zugangsschlüssel aus.