ah-admin
6eec3ac437
- N8N: Workflow serverseitig in DB eingespielt (Webhook mp-assist, Code-Node mit Kimi-Tool-Calling, keine Credentials), E2E live verifiziert - Formulare: shared FormSection-Komponente (2 gleich breite Spalten, Wide fuer Volllbreiten-Felder), 10 Formulare umgebaut, Dialoge verbreitert - Design: Inter + Sora Fonts, Teal-Akzente, Icons in Sektionskoepfen
86 lines
4.6 KiB
Markdown
86 lines
4.6 KiB
Markdown
# KI-Assistent (v1.37) – Einrichtung N8N + Kimi
|
||
|
||
Der Assistent läuft so: **Portal-Chat → N8N-Webhook → Kimi (Moonshot API) mit 6 Portal-Tools → Antwort zurück ins Portal.**
|
||
|
||
> **Stand: Der Workflow ist auf dem Produktivsystem (hocks.eu) bereits serverseitig eingerichtet und aktiv.**
|
||
> Die Datei `assist-workflow.json` in diesem Ordner ist die dokumentierte Referenz-Version.
|
||
> Der produktive Workflow wurde direkt in die N8N-Datenbank eingespielt, weil die lokale
|
||
> N8N-API in Version 2.x keinen zuverlässigen programmatischen Import erlaubt (401-Problem).
|
||
> Bei einem Re-Import auf einem anderen System müssen die drei Platzhalter im Code-Node belegt werden.
|
||
|
||
## 1. Architektur des Workflows
|
||
|
||
Ein einzelner Workflow **„Mieterportal – KI-Assistent (Kimi)"**, Webhook `POST mp-assist`, drei Nodes:
|
||
|
||
1. **Webhook Portal** (`n8n-nodes-base.webhook`, typeVersion 2, responseMode `responseNode`)
|
||
– produktive URL: `http://n8n:5678/webhook/mp-assist` (internes Docker-Netz `npm_default`).
|
||
– Wichtig: Der Node braucht die Property **`webhookId`** (gleich der Node-ID) auf Root-Ebene,
|
||
sonst registriert n8n den Webhook bei `responseMode: responseNode` nicht (404 „not registered").
|
||
2. **Assistent (Kimi + Tools)** (`n8n-nodes-base.code`, typeVersion 2, runOnceForAllItems)
|
||
– Prüft den Header `x-assist-secret` selbst gegen das Shared Secret.
|
||
– Ruft `https://api.moonshot.ai/v1/chat/completions` (Modell `kimi-k2.6`) per
|
||
`this.helpers.httpRequest` auf, mit OpenAI-kompatiblem **Tool-Calling** für genau die
|
||
6 Portal-Endpunkte unter `/api/assist/tools/…` (Schleife, max. 6 Runden).
|
||
– **Kein `temperature`-Parameter** senden – `kimi-k2.6` akzeptiert nur `temperature: 1`,
|
||
sonst 400 „invalid temperature".
|
||
– **Kein `URLSearchParams`** im Sandbox-Code verwenden – nicht verfügbar; Query-Strings
|
||
manuell mit `encodeURIComponent` bauen.
|
||
– 429 (Rate-Limit) wird abgefangen und als freundliche Meldung zurückgegeben.
|
||
3. **Antwort an Portal** (`n8n-nodes-base.respondToWebhook`, typeVersion 1.1)
|
||
– `respondWith: json`, Body `={{ { antwort: $json.antwort } }}`.
|
||
|
||
Der langchain-basierte Entwurf (AI-Agent-Node) wurde verworfen: Die `@n8n/n8n-nodes-langchain`-
|
||
Nodes liefen auf diesem Server nicht zuverlässig. Der Code-Node-Ansatz hat keine externen
|
||
Abhängigkeiten und keine Credentials (alle Geheimnisse als Literale im Code-Node).
|
||
|
||
## 2. Geheimnisse (Platzhalter im Workflow-JSON)
|
||
|
||
| Platzhalter im Code-Node | Bedeutung | Wo konfiguriert |
|
||
|---|---|---|
|
||
| `<ASSIST_SHARED_SECRET>` | Header `x-assist-secret` zwischen Portal und n8n | `portal.env` (ASSIST_SHARED_SECRET) |
|
||
| `<ASSIST_KEY>` | Header `x-assist-key` für die 6 Tool-Endpunkte | `portal.env` (ASSIST_API_KEY) |
|
||
| `<KIMI_API_KEY>` | Moonshot-API-Key (`sk-…`) | Code-Node, Konstante ganz oben |
|
||
|
||
## 3. Portal-Env auf dem Server
|
||
|
||
In `/opt/mieterportal/portal.env` (nur auf dem VPS, gitignored):
|
||
|
||
```bash
|
||
N8N_ASSIST_WEBHOOK=http://n8n:5678/webhook/mp-assist
|
||
ASSIST_SHARED_SECRET=<langes-zufaelliges-geheimnis-1>
|
||
ASSIST_API_KEY=<langes-zufaelliges-geheimnis-2>
|
||
```
|
||
|
||
Danach: `cd /opt/mieterportal && docker compose up -d`.
|
||
|
||
## 4. Kosten
|
||
|
||
Kimi `kimi-k2.6`: ~0,4 US-Cent pro Frage (Systemprompt + Tool-Schleife). Bei 20 Fragen/Tag
|
||
typisch unter 5 €/Monat. Aufladung des Moonshot-Kontos ab ~5 $.
|
||
|
||
## 5. Test
|
||
|
||
Im Portal als Verwaltung: **KI-Assistent** in der Navigation → „Welche Wohnungen stehen leer?"
|
||
Der erste Aufruf dauert ggf. 10–60 s (Tool-Schleife).
|
||
|
||
Serverseitig direkt testbar:
|
||
|
||
```bash
|
||
docker exec mp-api node -e "fetch('http://n8n:5678/webhook/mp-assist',{method:'POST',headers:{'Content-Type':'application/json','x-assist-secret':'<SECRET1>'},body:JSON.stringify({frage:'Welche Wohnungen stehen leer?',verlauf:[],benutzer:'E2E'})}).then(async r=>console.log(r.status,await r.text()))"
|
||
```
|
||
|
||
## Fehlerbilder
|
||
|
||
| Fehlermeldung | Ursache |
|
||
|---|---|
|
||
| „not registered" (404) | Workflow nicht aktiv, `webhookId` am Webhook-Node fehlt, oder n8n neu gestartet ohne Outbox-Eintrag |
|
||
| „invalid temperature" (400) | `temperature != 1` im Kimi-Payload |
|
||
| „Assistent antwortet nicht (N8N Status 500)" | Kimi 429 (Rate-Limit, kurz warten) oder Code-Fehler – Executions in n8n prüfen |
|
||
| Antwort „Tool … nicht erreichbar" | Portal-Tool-Endpunkte nicht erreichbar (Netz `npm_default`, `x-assist-key`) |
|
||
|
||
## Datenschutz-Hinweis
|
||
|
||
Das Tool `mieter_kontakt` liefert personenbezogene Daten an Kimi (Serverstandort Singapur,
|
||
Training laut Anbieter-AGB möglich). Wer das vermeiden will, entfernt den Tool-Eintrag aus
|
||
dem `TOOLS`-Array im Code-Node – alle anderen Tools liefern nur Bestands- und Zahlen-Daten.
|