Site Chatbot (TYPO3 v13)

Ein produktionsreifer RAG‑Chatbot für TYPO3 v13 mit MariaDB FULLTEXT. Antwortet ausschließlich anhand indexierter Website‑Inhalte und liefert immer Quellen.

Features

• RAG mit MariaDB InnoDB FULLTEXT (keine Vector‑DB, kein Redis, kein externer Storage)
• Skalierbares Chunking (Größe + Overlap konfigurierbar)
• Answerability‑Gate (bei zu niedrigem Score: keine LLM‑Antwort)
• Quellenpflicht: Titel + URL am Ende jeder Antwort
• Backend‑Modul für Status und Reindex
• CLI‑Command + Scheduler‑Task (Full/Incremental)
• Security: CSRF‑Schutz, Rate‑Limiting, Input‑Limits
• Optionales Chat‑Logging (opt‑in)
• Query‑Expansion (Synonyme) für bessere Treffer
• Automatische Singular/Plural‑Erweiterung für Queries
• Abschnitts‑Anker aus Überschriften (z. B. „Meine Arbeiten“ → #meine-arbeiten)
• Extractive‑Fallback (antwortet aus Website‑Text, falls OpenAI ausfällt)
• Custom‑Index‑Sources (eigene Tabellen/Felder, rekursiv, backend‑pflegbar)

---

Voraussetzungen

• TYPO3 13.4+
• PHP 8.2+
• MariaDB 10.11.x (InnoDB FULLTEXT verfügbar)
• DDEV (optional empfohlen)

---

Installation

1) Extension installieren

Lege die Extension in dein TYPO3‑Projekt und aktiviere sie:

/packages/site_chatbot

Backend → Admin Tools → Extensions → site_chatbot aktivieren.

2) Datenbank aktualisieren

Backend → Admin Tools → Maintenance → Analyze Database Structure
Alle neuen Tabellen/Indizes (inkl. FULLTEXT) übernehmen.

---

Konfiguration (Backend)

Backend → Admin Tools → Settings → Extension Configuration → site_chatbot

Pflicht:

• openaiApiKey – OpenAI API Key (nur Backend, niemals im Frontend)

Wichtige Retrieval‑Parameter:

• retrievalTopK (Default 12)
• maxSources (Default 5)
• chunkSize (Default 2500 Zeichen)
• chunkOverlap (Default 400 Zeichen)
• minFulltextScore (Default 0.0)
• maxContextChars (Default 8000)

Index‑Konfiguration:

• excludePageIds (kommasepariert, inkl. Unterseiten)
• excludeDoktypes (z. B. 3,4,254,255)

LLM/Fallback:

• enableExtractiveFallback (Default 1)
• forceLlmOnHits (Default 0) – LLM auch bei niedrigen Scores erzwingen

Security:

• rateLimitWindow (Sekunden)
• rateLimitMaxRequests

Optional:

• enableChatLog (0/1)
• enableDebug (0/1) – Debug‑Output (LLM vs Fallback)

---

Indexierung

Backend‑Modul

System → Site Chatbot

• Full reindex: kompletter Neuaufbau
• Incremental reindex: nur geänderte Seiten
• Search Preview: Teste Retrieval direkt im Modul
• Preview (Page ID): Vorschau des extrahierten Inhalts
• Quick‑Chips (global): Buttons im Frontend pflegen
• Index Sources (Custom Tables): Eigene Tabellen/Felder hinzufügen, inkl. rekursiver Child‑Records (max 5 Ebenen)

CLI

ddev typo3 sitechatbot:index --mode=full
ddev typo3 sitechatbot:index --mode=incremental

Scheduler

Task “Site Chatbot Indexing” anlegen
Mode: incremental oder full

---

Frontend Einbindung

1. Neue Seite oder vorhandene Seite öffnen
2. Content‑Element → Plugin → Site Chatbot
3. Speichern, Cache leeren

Der AJAX‑Endpoint ist standardmäßig über type=168486 erreichbar.
Anpassung in TypoScript möglich:

plugin.tx_sitechatbot_chatbot.settings.apiTypeNum = 168486

Quick‑Chips (global im Backend‑Modul)

Backend‑Modul → Quick‑Chips (global)

Format (eine Zeile pro Chip):

Label|Frage

• Frage optional (fällt auf Label zurück)
• Reihenfolge entspricht der Zeilenreihenfolge

Beispiel:

Meine Arbeiten|Zeig mir die Projekte aus dem Portfolio.
Leistungen|Welche Leistungen bieten Sie?
Kontakt|Wie kann ich Kontakt aufnehmen?

---

Custom Index Sources (Backend)

Im Backend‑Modul kannst du zusätzliche Tabellen/Felder indexieren – ohne Code‑Änderungen.

Spalten (Kurzbeschreibung):

• Table – Tabellenname (z. B. tx_mask_project)
• Fields – Kommagetrennte Felder (z. B. title,description)
• PID field – PID‑Feld der Tabelle (meist pid)
• PID list – Optional: feste PIDs (z. B. 25,26), überschreibt PID field
• Target page IDs – Optional: nur auf diesen Seiten wird der Source hinzugefügt (z. B. 24)
• Language field – Sprachfeld (meist sys_language_uid)
• Context label – Optionaler Kontext‑Header pro Record (z. B. Job)
• Parent table/field – Für verschachtelte Records (IRRE)

Hinweise:

• Rekursion ist auf 5 Ebenen begrenzt.
• Mask‑Helper zeigt erkannte tx_mask_* Tabellen und Text‑Felder zur schnellen Übernahme.

---

Verhalten & Sicherheitslogik

• Answerability‑Gate: Wenn keine Treffer oder Score < minFulltextScore →
  Antwort:

  „Ich kann das anhand der Website‑Inhalte nicht sicher beantworten.“
  plus 3–5 Seitenvorschläge.

• Force LLM: Mit forceLlmOnHits=1 wird bei Treffern trotzdem der LLM genutzt.

• Quellenpflicht: Jede Antwort enthält eine Quellenliste (Titel + URL).

• Keine Halluzinationen: Modell darf ausschließlich den Kontext nutzen.

• Abschnitts‑Links: Quellen können direkt zu Abschnitt‑Ankern führen (z. B. #meine-arbeiten).

---

FULLTEXT Hinweise (MariaDB)

MariaDB InnoDB FULLTEXT ignoriert sehr kurze Wörter.
Für präzise Ergebnisse kann es sinnvoll sein, in MariaDB die Token‑Größen anzupassen:

• innodb_ft_min_token_size
• ft_min_word_len

Nach Änderungen: FULLTEXT neu aufbauen (Full Reindex).

---

Dateien/Architektur (Kurzüberblick)

• Classes/Indexing/*
  Extraktion, Chunking, Index‑Service

• Classes/Retrieval/*
  FULLTEXT‑Query, Answerability‑Gate, Kontextaufbau

• Classes/Service/*
  OpenAI‑Client, ChatService

• Classes/Controller/ChatbotController.php
  Frontend‑UI + JSON‑API

• Classes/Controller/Backend/IndexController.php
  Backend‑Status & Reindex

• Classes/Utility/QueryExpander.php
  Synonyme und Query‑Expansion

---

Typische Fehler & Lösungen

Antworten kommen immer leer

• Indexierung durchgeführt?
• openaiApiKey gesetzt?
• FULLTEXT Index in DB vorhanden?
• enableDebug=1 aktivieren, um LLM/Fallback zu sehen

Zu viele „Nicht sicher“ Antworten

• minFulltextScore senken
• chunkSize erhöhen (z. B. 2500–3000)
• Reindex durchführen
• Optional: forceLlmOnHits=1 testen

Keine Ergebnisse bei kurzen Fragen

• MariaDB Token‑Limit prüfen (innodb_ft_min_token_size, ft_min_word_len)

---

Sicherheit

• API Key liegt nur in Extension Configuration
• CSRF‑Token erforderlich
• Rate‑Limiting (IP + Zeitfenster)
• Optionales Logging (opt‑in)

---

Lizenz

GPL‑2.0‑or‑later