Architektur

KI-Umfrage ist als monolithische Python-Anwendung mit einer Web-Oberfläche konzipiert, die in einem einzelnen Container betrieben wird. Die innere Struktur folgt einer klaren Schichtentrennung zwischen Bedien-Oberfläche, Orchestrierung des Umfrage-Ablaufs, der LLM-Pipeline und einem darunterliegenden Konfigurations- und Persistenz-Layer. Aufrufe an das Sprachmodell sind asynchron implementiert, mit Timeouts und Wiederholungs-Logik abgesichert und durch deterministische Fallback-Pfade gegen Ausfälle abgesichert.

Auf einen Blick

• Schichtenarchitektur: UI-Schicht (Tab-basiert), Orchestrierungs-Schicht (Conversation Manager), Pipeline-Schicht (Survey Agent mit drei LLM-Stufen), Infrastruktur-Schicht (LLM-Client, Konfiguration, Persistenz).
• Asynchrone LLM-Aufrufe mit konfigurierbarem Timeout, Retry-Logik und JSON-Mode für strukturierte Antworten.
• Strukturierte Datentypen für alle Pipeline-Übergänge; Validierung der LLM-Ausgaben gegen erlaubte Wertebereiche.
• Konfiguration über YAML-Dateien mit zusätzlichen Überschreibungen via Umgebungsvariablen.
• Persistenz von Sessions, Konversationsverläufen und finalen Antworten als JSON; Logging in eigene Log-Datei.
• Containerisiert über Docker; einzelner Web-Port nach außen, Health-Check enthalten.
• Mehrstufige Fallback-Mechanismen auf Prompt-, Pipeline- und Verarbeitungsebene.

Architekturüberblick

Die Anwendung gliedert sich in vier Schichten:

Bedienoberfläche. Die Oberfläche wird mit Gradio aufgebaut und gliedert sich in sechs Tabs (Playground, Prompt-Engineering, Batch-Testing, Fragen-Editor, Session-Demo, Performance). Der UI-Code ist in einer zentralen GradioInterface-Klasse gebündelt; Handler-Funktionen vermitteln zwischen Bedien-Ereignissen und der Orchestrierungs-Schicht.

Orchestrierung. Der ConversationManager startet Sessions, hält den Zustand der aktuellen Frage und reicht Nutzer-Antworten an den Survey Agent weiter. Eine Session bündelt sämtliche Interaktionen einer Umfrage und ist die Basis für die spätere Persistenz.

Pipeline (Survey Agent). Der Agent kapselt drei voneinander unabhängige LLM-Stufen — Antwort-Bewertung, Nachfragen-Generierung und Antwort-Strukturierung. Jede Stufe ruft den LLM-Client mit einem eigenen Prompt-Template auf, parst das JSON-Ergebnis, validiert es und reicht ein typisiertes Ergebnis-Objekt weiter. Bei Fehlern oder Timeouts greift eine regelbasierte Ersatz-Logik.

Infrastruktur. Der LLMClient kapselt die OpenAI-kompatible HTTP-Kommunikation inklusive Timeouts, Retries und JSON-Parsing. Der ConfigLoader lädt YAML-Konfiguration und Umfragedefinition und bindet Umgebungsvariablen ein. Ergebnisse werden als JSON-Dateien abgelegt; Logs schreibt Loguru.

Workflow

flowchart TD
    User[Nutzer]
    UI[Gradio Tabs]
    CM[Conversation Manager]
    Agent[Survey Agent]
    Eval[Stufe 1: Bewertung]
    Follow[Stufe 2: Nachfrage]
    Struct[Stufe 3: Strukturierung]
    Prompts[Prompt Templates]
    LLM[LLM Client]
    Fallback[Regelbasierter Fallback]
    LLMAPI[OpenAI-kompatible API]
    Config[YAML Konfiguration]
    Store[JSON Ergebnis-Ablage]
    Log[Log Datei]

    User --> UI
    UI --> CM
    CM --> Agent
    Agent --> Eval
    Eval -->|niedriger Klarheits-Score| Follow
    Eval -->|ausreichend klar| Struct
    Follow --> CM
    CM -->|naechste Antwort| Agent
    Agent --> Struct
    Struct --> CM
    CM --> Store

    Eval -.-> Prompts
    Follow -.-> Prompts
    Struct -.-> Prompts
    Prompts --> LLM
    LLM --> LLMAPI
    LLM -.->|Timeout / Fehler| Fallback
    Fallback --> Agent

    Config --> CM
    Config --> Agent
    Config --> LLM
    Agent --> Log
    LLM --> Log

Der Ablauf beginnt mit einer Frage, die der Conversation Manager an den Survey Agent übergibt. Stufe 1 (Bewertung) ruft den LLM-Client mit dem Bewertungs-Prompt auf und erhält einen Klarheits-Score samt Begründung und Problemtypen. Liegt der Score unterhalb der konfigurierten Schwelle und ist die maximale Nachfrage-Tiefe noch nicht erreicht, generiert Stufe 2 eine konkrete Nachfrage. Diese läuft als neue Antwort-Runde durch den Conversation Manager zurück in den Agenten. Sobald eine Antwort als ausreichend klar bewertet wird oder die Nachfrage-Tiefe erschöpft ist, fasst Stufe 3 die gesamte Konversation zu einer strukturierten Endantwort mit Hauptkategorie, spezifischen Begriffen und Konfidenzwert zusammen.

Rolle des LLM in der Pipeline

Das Sprachmodell wird in jeder Pipeline-Stufe für eine klar abgegrenzte Aufgabe genutzt: Bewertung, Generierung einer Nachfrage und Strukturierung. Alle Aufrufe verwenden eine niedrige Temperature für deterministische Ergebnisse und werden im JSON-Mode geführt, sodass die Ausgaben unmittelbar in typisierte Datenobjekte überführbar sind. Die Anwendung hält an einer strikten Trennung zwischen Modell-Antwort und Geschäftslogik fest: Werte werden gegen erlaubte Bereiche validiert (Klarheits-Score auf 0–1 begrenzt, Problemtypen gegen eine Whitelist abgeglichen), und ungültige oder fehlende Felder werden ersetzt, ohne die nachgelagerte Verarbeitung zu blockieren.

Nebenläufigkeit und Robustheit

Sämtliche LLM-Aufrufe laufen asynchron und sind durch einen pro Aufruf konfigurierbaren Timeout begrenzt. Eine Retry-Logik fängt vorübergehende Fehler des Endpoints ab. Schlägt eine Stufe endgültig fehl, übernehmen regelbasierte Fallbacks die Verarbeitung — etwa eine heuristische Klarheits-Bewertung anhand von Wortzahl und bekannten Indikator-Begriffen oder eine vorgefertigte Nachfrage. Dadurch bleibt der Ablauf für den Nutzer auch bei instabilen LLM-Verbindungen unterbrechungsfrei. Performance-Metriken werden pro Operation und Phase aufgezeichnet und in der Bedien-Oberfläche aggregiert dargestellt.

Konfiguration und Deployment

Die Konfiguration ist in zwei YAML-Dateien aufgeteilt: eine zentrale Datei für LLM-Verbindung, Bewertungs-Schwellen, Logging und Persistenz; eine zweite für die Definition der Umfrage selbst. Umgebungsvariablen mit dem Präfix SURVEY_ können einzelne Werte zur Laufzeit überschreiben. Die Anwendung wird als Docker-Container ausgeliefert, der einen einzelnen HTTP-Port (Gradio, 7860) freigibt und einen periodischen Health-Check auf den Wurzelpfad ausführt.

Technologie-Übersicht

• Sprache und Laufzeit: Python 3.11.
• Web-Oberfläche: Gradio (Tab-Layout, Chatbot-Komponente, Live-Updates).
• Datenmodelle und Validierung: Pydantic.
• LLM-Anbindung: OpenAI Python SDK gegen eine OpenAI-kompatible Chat-Completion-API; asynchrone Aufrufe über asyncio.
• Konfiguration: YAML (PyYAML), python-dotenv für Umgebungsvariablen.
• Logging: Loguru, mit Rotation und Retention.
• Containerisierung: Docker; einzelner Container, Health-Check auf den Web-Port.
• Persistenz: JSON-Dateien für Sessions und finale Antworten, Log-Datei für Verlaufsinformationen.