Fit4KI Themenmodul 4 — FAQ-Sprachassistent (Self-Hosted)

Dieses Repository enthaelt alle Dateien, die du brauchst, um den selbst gehosteten FAQ-Sprachassistenten aus Themenmodul 4 ("Entwickle deine eigene KI-Sprachassistenz") lokal oder auf einem Server einzurichten.

Was ist das?

Ein komplett selbst gehosteter Sprachassistent, der FAQ-Fragen per Sprache beantwortet — ohne externe API-Aufrufe, ohne Cloud-Dienste. Du sprichst ins Mikrofon, der Assistent antwortet mit einer Sprachnachricht. Alle Daten bleiben auf deinem eigenen Server.

Die Pipeline:

Nutzer spricht ins Mikrofon (Website)
    → Audio wird an N8N-Webhook gesendet
    → Whisper transkribiert Sprache zu Text
    → KI-Agent verarbeitet den Text mit Ollama LLM
    → Piper TTS wandelt die Antwort in Sprache um
    → Audioantwort wird im Browser abgespielt

Voraussetzungen

• Docker Desktop installiert und gestartet (Download)
• Docker Compose (ist bei Docker Desktop dabei)
• Mindestens 8 GB RAM verfuegbar
• Ca. 5 GB freier Speicher fuer die Docker-Images und Modelle

Hinweis: Wenn du Themenmodul 3 von Fit4KI bereits abgeschlossen hast, kennst du Docker und N8N schon. Dieses Setup baut darauf auf.

Schnellstart

# 1. Repository klonen
git clone https://github.com/n3xtcoder/voice-assistant-fit4ki-tm4.git
cd voice-assistant-fit4ki-tm4

# 2. Setup ausfuehren (startet Container + laedt Modelle herunter)
bash setup.sh

Das Setup dauert beim ersten Mal ca. 10-15 Minuten (abhaengig von deiner Internetverbindung), weil folgende Modelle heruntergeladen werden:

• gemma3:4b (~2.5 GB) — das LLM fuer die FAQ-Antworten
• de_DE-thorsten-high (~50 MB) — die deutsche TTS-Stimme

Nach dem Setup

1. N8N einrichten

Oeffne http://localhost:5678 im Browser und erstelle dein N8N-Konto.

2. Workflow importieren

1. Gehe in N8N zu Menu → Import from File
2. Waehle die Datei FAQ_Voice_Assistant_SelfHosted.json aus diesem Ordner
3. Der Workflow wird mit allen Knoten importiert

3. Ollama-Zugangsdaten konfigurieren

1. Klicke im Workflow auf den Knoten "Ollama Chat Model"
2. Klicke auf "Neue Anmeldedaten erstellen"
3. Setze die Basis-URL auf: http://ollama:11434
4. Klicke auf Speichern

4. FAQ-Systemaufforderung anpassen

Klicke auf den Knoten "FAQ Voice Agent" und passe die Systemaufforderung (System Message) mit den FAQ deiner Organisation an. Eine Vorlage ist bereits enthalten.

Tipp: Halte die Systemaufforderung kurz (unter 500 Woerter). Kleine Modelle wie gemma3:4b arbeiten am besten mit kurzen, klaren Anweisungen im einfachen Frage-Antwort-Format.

5. Workflow aktivieren

Schalte den Workflow auf "Aktiv" (Schalter oben rechts) oder klicke auf "Publish".

6. Sprach-Oberflaeche testen

Starte einen lokalen Webserver fuer die HTML-Seite:

python3 -m http.server 3000

Oeffne http://localhost:3000/voice_assistant_website.html im Browser und trage als Webhook-URL ein:

http://localhost:5678/webhook/voice-assistant

Klicke auf das Mikrofon und stelle eine Frage!

Dateien in diesem Repository

Datei	Beschreibung
docker-compose.yml	Docker-Compose-Datei fuer alle 4 Container (N8N, Ollama, Whisper, TTS)
setup.sh	Setup-Skript: startet Container und laedt alle Modelle herunter
FAQ_Voice_Assistant_SelfHosted.json	N8N-Workflow zum Importieren
voice_assistant_website.html	Sprach-Oberflaeche (HTML-Seite mit Mikrofon-Aufnahme)
tts-config/voice_to_speaker.yaml	Konfiguration fuer die deutschen TTS-Stimmen

Was laeuft auf deinem Rechner?

Container	Image	Port	Zweck
n8n	n8nio/n8n	5678	Workflow-Engine
ollama	ollama/ollama	11434	LLM (gemma3:4b)
whisper	onerahmet/openai-whisper-asr-webservice	9000	Sprache → Text
tts	ghcr.io/matatonic/openedai-speech-min	8000	Text → Sprache

Fehlerbehebung

Container starten nicht: Stelle sicher, dass Docker Desktop laeuft (Wal-Symbol in der Menueleiste).

Whisper gibt leeren Text zurueck: Sprich laut und deutlich fuer mindestens 2-3 Sekunden. Sehr kurze Aufnahmen werden manchmal nicht erkannt.

TTS gibt keine Audiodatei zurueck (78 Bytes): Die Stimm-Modelle wurden nicht heruntergeladen. Fuehre das Setup-Skript erneut aus: bash setup.sh

LLM antwortet "Dazu habe ich keine Informationen" obwohl die Frage in den FAQ steht: Aendere im Knoten "Einfacher Speicher" den Session-Key (z.B. von voice-session auf voice-session-2). Alte fehlgeschlagene Testlaeufe koennen den Kontext verschmutzen.

"Failed to fetch" oder CORS-Fehler: Oeffne die HTML-Datei nicht direkt (file://...), sondern starte einen lokalen Webserver: python3 -m http.server 3000

Alles stoppen:

docker compose down

Fuer die Bereitstellung auf einem Server

Wenn du den Assistenten auf einem oeffentlichen Server bereitstellen willst (z.B. Hetzner, IONOS), brauchst du zusaetzlich:

• HTTPS (via Nginx + Certbot) — der Browser erlaubt Mikrofonzugriff nur ueber HTTPS
• Eine Domain die auf deinen Server zeigt
• Die Schritte dafuer findest du im Tutorial (Themenmodul 4, Kapitel 2)

Links

• Fit4KI Themenmodul 3 — Grundlagen: Docker, N8N, Ollama
• Fit4KI Themenmodul 4 — Das vollstaendige Tutorial zu diesem Repository
• Civic Coding Initiative — Innovationsnetzwerk fuer KI im oeffentlichen Interesse