Ein fortschrittliches RAG-System (Retrieval-Augmented Generation) auf Basis von COLPALI mit integrierten Guardrails für sichere und vertrauenswürdige Dokumentenverarbeitung.
GuardRAG kombiniert modernste Vision-Language-Modelle (COLPALI) mit umfassenden Sicherheitsmechanismen (Guardrails), um eine robuste und vertrauenswürdige Lösung für die Analyse wissenschaftlicher Dokumente zu bieten.
- 🔍 COLPALI-Integration: Effiziente visuelle Dokumentenretrieval mit dem
vidore/colqwen2.5-v0.2
Modell - 🛡️ Input Guardrails: Validierung und Filterung eingehender Anfragen
- ✅ Output Guardrails: Überprüfung generierter Antworten auf Faktentreue und Sicherheit
- 📁 File Upload: Unterstützung für PDF, DOCX, TXT, MD, HTML-Dateien
- 🚀 FastAPI-Interface: RESTful API mit automatischer Dokumentation
- 🧠 Hybrid LLM+Regex: Intelligente Content-Validierung mit automatischem Lernen
- 🔒 PII-Schutz: Erkennung und Sanitisierung persönlicher Daten
Benutzeranfrage
↓
[ Input Guardrail ] ─── 🔍 Hybrid LLM+Regex Prüfung:
│ • Profanität & Toxizität
│ • PII-Erkennung (E-Mail, Tel, IBAN)
│ • Gefährliche Inhalte (Drogen, Waffen, Sprengstoff)
│ • Konkurrenten-Erwähnungen
│ • Automatisches Lernen neuer Bedrohungen
↓ (ZUGELASSEN)
[ COLPALI Retrieval ] ── 📊 Visuelle Dokumentensuche:
│ • Layout-bewusste Analyse
│ • OCR-freie Texterkennung
│ • Multimodale Embeddings
↓
[ LLM Generation ] ────── 🤖 Antwortgenerierung basierend auf Quellen
↓
[ Output Guardrail ] ─── ✅ Qualitätsprüfung:
│ • Faktentreue-Abgleich
│ • Halluzinations-Detektion
│ • Sicherheitsprüfung
↓ (GÜLTIG)
Sichere Antwort an Nutzer
Vorher:
- Standard GuardRAG Agent lädt COLPALI-Modell → ~2-4 GB GPU-Speicher
- Enhanced GuardRAG Agent lädt das GLEICHE Modell nochmal → weitere ~2-4 GB GPU-Speicher
- Gesamtspeicher: ~4-8 GB für dasselbe Modell!
Nachher:
COLPALIManager
verwaltet Modell-Instanzen zentral- Beide Agenten teilen sich die gleiche COLPALI-Instanz
- Gesamtspeicher: ~2-4 GB für beide Agenten zusammen!
Neuer COLPALI Manager:
class COLPALIManager:
_instances = {} # Cache für Modell-Instanzen
@classmethod
def get_instance(cls, model_name, device, qdrant_config):
config_key = f"{model_name}_{device}_{qdrant_config.host}_{qdrant_config.port}"
if config_key in cls._instances:
logger.info("♻️ Reusing existing COLPALI instance")
return cls._instances[config_key]
# Erstelle nur wenn noch nicht vorhanden
instance = COLPALIProcessor(model_name, device, qdrant_config)
cls._instances[config_key] = instance
return instance
Angepasste RAG Agents:
# Vorher:
self.colpali = COLPALIProcessor(...)
# Nachher:
self.colpali = COLPALIManager.get_instance(...)
API Endpoints:
GET /colpali-stats
- Zeigt Modell-StatistikenPOST /colpali-clear-cache
- Löscht Modell-Cache
Frontend Integration:
- COLPALI Statistiken im System-Status Tab
- Zeigt Speicherverbrauch und Instanz-Details
Speicher-Optimierung:
- 50% weniger GPU-Speicher bei gleicher Funktionalität
- Vermeidet OOM (Out of Memory) Fehler
- Schnellere Initialisierung beim zweiten Agent
Performance:
- Erster Agent lädt Modell: ~10-30 Sekunden
- Zweiter Agent nutzt Cache: ~1-2 Sekunden
- Weniger CUDA-Fragmentierung
Monitoring:
- Echte Transparenz über Modell-Nutzung
- Debugging von Speicherproblemen
- Proaktive Cache-Verwaltung
# Vor der Optimierung
nvidia-smi # Zeigt ~4-8 GB VRAM-Nutzung
# Nach der Optimierung
nvidia-smi # Zeigt ~2-4 GB VRAM-Nutzung
Logs überprüfen:
python main.py
# Erwartete Ausgabe:
# "🔄 Creating new COLPALI instance: vidore/colqwen2.5-v0.2_cuda_localhost_6333"
# "♻️ Reusing existing COLPALI instance: vidore/colqwen2.5-v0.2_cuda_localhost_6333"
API-Statistiken abrufen:
curl http://localhost:8000/colpali-stats
Vor der Optimierung:
🤖 Standard RAG: COLPALI Model Loading... (15s, 3.2 GB VRAM)
🛡️ Enhanced RAG: COLPALI Model Loading... (15s, 3.2 GB VRAM)
Total: 30s startup, 6.4 GB VRAM
Nach der Optimierung:
🤖 Standard RAG: COLPALI Model Loading... (15s, 3.2 GB VRAM)
🛡️ Enhanced RAG: ♻️ Reusing existing instance (1s, 0 GB additional VRAM)
Total: 16s startup, 3.2 GB VRAM
Speicher-Einsparung: ~50% 🎉
- Python 3.10+
- uv Paketmanager (empfohlen)
- Ollama für lokale LLM-Inferenz
- GPU mit CUDA-Unterstützung (empfohlen)
- Docker (optional, für Services)
git clone <repository-url>
cd GuardRAG
# Mit uv (empfohlen)
uv sync
Bei uv ist folgende Methode für SpaCy Modelle zu nutzen:
uv pip install de_core_news_lg@https://github.com/explosion/spacy-models/releases/download/de_core_news_lg-3.8.0/de_core_news_lg-3.8.0-py3-none-any.whl
# Oder mit pip
.venv\Scripts\activate
pip install -e .
Kopiere .env.example
zu .env
und passe die Werte an:
# LLM Configuration (Ollama)
LLM_ENDPOINT=http://localhost:11434/v1
LLM_API_KEY=ollama
LLM_MODEL=qwen2.5:latest
# COLPALI Configuration
COLPALI_MODEL=vidore/colqwen2.5-v0.2
# Qdrant Configuration
QDRANT_HOST=localhost
QDRANT_PORT=6333
# Guardrails Configuration
ENABLE_INPUT_GUARDRAILS=true
ENABLE_OUTPUT_GUARDRAILS=true
TOXICITY_THRESHOLD=0.3
CONFIDENCE_THRESHOLD=0.7
# Alle Services starten (Ollama + Qdrant + GuardRAG)
docker-compose up -d
# Ollama Modelle pullen
docker exec guardrag-ollama-1 ollama pull qwen2.5:latest
docker exec guardrag-ollama-1 ollama pull granite3.2-vision:2b
# 1. Qdrant starten
docker run -p 6333:6333 -p 6334:6334 -v qdrant_storage:/qdrant/storage:z qdrant/qdrant:latest
# 2. Ollama starten (falls nicht installiert)
# Download von https://ollama.ai und installieren
ollama serve
ollama pull qwen2.5:latest
# 3. GuardRAG starten
.venv\Scripts\activate
python main.py
# Health Check
curl http://localhost:8000/health
# API-Dokumentation
# Swagger UI: http://localhost:8000/docs
# ReDoc: http://localhost:8000/redoc
curl -X POST "http://localhost:8000/upload-document" \
-H "Content-Type: multipart/form-data" \
-F "[email protected]"
Response:
{
"success": true,
"message": "Document processed successfully",
"file_id": "1641234567_document.pdf",
"pages_processed": 15
}
curl -X POST "http://localhost:8000/rag-query" \
-H "Content-Type: application/json" \
-d '{
"query": "Welche Methodik wurde in der Studie verwendet?",
"max_results": 5
}'
Response:
{
"answer": "Basierend auf den bereitgestellten Dokumenten verwendete die Studie eine quantitative Methodik mit...",
"confidence": 0.85,
"processing_time": 2.34,
"sources": [
{
"page_number": 3,
"score": 0.92,
"explanation": "Seite 3 enthält übereinstimmende Begriffe: methodik, studie",
"text_preview": "Die Methodik dieser Studie basiert auf..."
}
],
"warnings": [],
"guardrail_checks": {
"input_validation": {
"result": "accepted",
"reason": "Wissenschaftliche Begriffe gefunden: methodik, studie",
"confidence": 0.8
},
"output_validation": {
"result": "approved",
"reason": "Alle Validierungen bestanden",
"confidence": 0.85
}
}
}
curl -X GET "http://localhost:8000/system-status"
Zweck: Hybrid LLM+Regex Filterung problematischer oder irrelevanter Anfragen
Prüfkategorien:
- Deutsche & englische Schimpfwörter: fuck, scheiße, arschloch, etc.
- Diskriminierende Begriffe: rassistische, sexistische, homophobe Sprache
- Hasssprache: Nazi-Begriffe, Fremdenfeindlichkeit
- Toxische Kommunikationsmuster: Bedrohungen, Beleidigungen
- E-Mail-Adressen: [email protected]
- Telefonnummern: +49 123 456789, deutsche und internationale Formate
- Deutsche Adressen: Musterstraße 123, 12345 Berlin
- Bankdaten: IBAN, Kreditkartennummern
- Personennamen: spaCy-basierte Named Entity Recognition
- Ausweisnummern: Deutsche Steuer-ID, Personalausweis
- Sprengstoff-Chemikalien: Toluol, Schwefel, Salpetersäure, TNT, C4
- Drogen: CBD, THC, Cannabis, Methamphetamine, Kokain, LSD
- Waffen: Pistole, Gewehr, AK47, Munition
- Illegale Aktivitäten: Hacking, Phishing, Geldwäsche
🧠 Hybrid-Ansatz:
- Regex-Trigger erkennen verdächtige Begriffe (schnell)
- LLM analysiert Kontext (intelligent):
- "Puderzucker für Guggelhupf" → ✅ harmlos (Backen)
- "Puderzucker + Salz explodieren" → ❌ gefährlich (Sprengstoff)
- Automatisches Lernen: LLM-erkannte Gefahren ohne Regex → Lern-Log
- Blockierte Anbieter: OpenAI, ChatGPT, Claude, Gemini, Anthropic
- Benutzerdefinierte Listen: Erweiterbar
- Automatische Blockierung: Bei Erwähnung von Konkurrenzprodukten
- PII-Ersetzung: E-Mails → [EMAIL], Telefon → [PHONE]
- Overlap-Resolution: Überlappende Erkennungen bereinigen
- Struktur-Erhaltung: Textformat bleibt erhalten
Zweck: Qualitätssicherung und Sicherheitsprüfung der generierten Antworten
Prüfungen:
- Faktentreue: Abgleich mit Quellendokumenten
- Vollständigkeit: Angemessene Beantwortung der Frage
- Halluzinations-Detektion: Erkennung erfundener Informationen
- Toxizitätsprüfung: Sicherstellung sauberer Ausgaben
- Relevanz-Check: Passende Antwort zur Frage
"Wie funktioniert maschinelles Lernen?"
"CBD Kekse backen - welche Dosierung?"
"Welche Methodik wurde in der Studie verwendet?"
"Du bist so dumm!" (Toxizität)
"Wie stelle ich Sprengstoff her?" (Gefährlicher Inhalt)
"Meine E-Mail ist [email protected]" (PII)
"ChatGPT ist besser" (Konkurrent)
Input: "Kontaktiere mich unter [email protected]"
Output: "Kontaktiere mich unter [EMAIL]"
Variable | Beschreibung | Default |
---|---|---|
LLM_ENDPOINT |
Ollama API Endpoint | http://localhost:11434/v1 |
LLM_API_KEY |
API Key für LLM | ollama |
LLM_MODEL |
Modell für Generation | qwen2.5:latest |
COLPALI_MODEL |
COLPALI Modell | vidore/colqwen2.5-v0.2 |
QDRANT_HOST |
Qdrant Server Host | localhost |
QDRANT_PORT |
Qdrant Server Port | 6333 |
ENABLE_INPUT_GUARDRAILS |
Input-Validierung aktivieren | true |
ENABLE_OUTPUT_GUARDRAILS |
Output-Validierung aktivieren | true |
TOXICITY_THRESHOLD |
Schwellwert für Toxizität | 0.3 |
CONFIDENCE_THRESHOLD |
Mindestvertrauen | 0.7 |
Das System unterstützt alle OpenAI-kompatiblen API-Endpunkte:
qwen2.5:latest
⭐ - Empfohlenes Standardmodell (Allzweck)qwen3:latest
- Neueste Qwen-Versiongranite3.3:8b
- Ausgewogenes Allzweck-Modellgoogle/gemma3:latest
- Google's Gemma-Modell- Alle weiteren Ollama-Modelle - Vollständige Kompatibilität
- OpenAI: GPT-4, GPT-3.5-turbo, GPT-4-turbo
- Anthropic: Claude-3.5-Sonnet, Claude-3-Haiku (via kompatible APIs)
- Groq: Llama-3, Mixtral, Gemma (schnelle Inferenz)
- Together AI: Llama-2/3, Code Llama, Mistral
- Perplexity: Llama-3, Mixtral-8x7B
- OpenRouter: Zugang zu 100+ Modellen
- Azure OpenAI: Enterprise-GPT-Modelle
- AWS Bedrock: Claude, Llama über OpenAI-Proxy
# Lokale Ollama-Installation
LLM_ENDPOINT=http://localhost:11434/v1
LLM_API_KEY=ollama
LLM_MODEL=qwen2.5:latest
# OpenAI
LLM_ENDPOINT=https://api.openai.com/v1
LLM_API_KEY=sk-your-openai-key
LLM_MODEL=gpt-4
# Groq (schnelle Inferenz)
LLM_ENDPOINT=https://api.groq.com/openai/v1
LLM_API_KEY=gsk_your-groq-key
LLM_MODEL=llama-3.1-70b-versatile
# Together AI
LLM_ENDPOINT=https://api.together.xyz/v1
LLM_API_KEY=your-together-key
LLM_MODEL=meta-llama/Llama-3-70b-chat-hf
# OpenRouter (Multi-Provider)
LLM_ENDPOINT=https://openrouter.ai/api/v1
LLM_API_KEY=sk-or-your-openrouter-key
LLM_MODEL=anthropic/claude-3.5-sonnet
# Lokale vLLM-Installation
LLM_ENDPOINT=http://localhost:8000/v1
LLM_API_KEY=token-abc123
LLM_MODEL=microsoft/DialoGPT-medium
Das System funktioniert mit jedem OpenAI-kompatiblen Endpunkt - einfach Endpoint, API-Key und Modellname konfigurieren!
GuardRAG/
├── src/ # 🎯 Kernkomponenten
│ ├── modern_guardrails.py # 🛡️ Hybrid LLM+Regex Guardrails
│ ├── colpali_integration.py # 🔍 COLPALI + Qdrant Integration
│ ├── qdrant_integration.py # 📊 Vektor-Datenbank
│ ├── input_guardrail.py # 🚫 Eingabevalidierung
│ ├── output_guardrail.py # ✅ Ausgabevalidierung
│ └── rag_agent.py # 🤖 Haupt-RAG-Agent
├── mcp_fileconverter/ # 📁 PDF-Konvertierung
│ └── file2pdf.py # 🔄 Datei-zu-PDF-Konverter
├── tests/ # 🧪 Test-Suite (optional)
│ └── (weitere Test-Dateien) # � Ergänzende Tests
├── main.py # 🚀 FastAPI-Anwendung
├── test_hybrid_guardrails.py # �️ Guardrails-Tests
├── test_complete_system.py # 🧪 System-Tests
├── tasks.py # ⚙️ Development Tasks
├── docker-compose.yml # 🐳 Multi-Service Setup
├── pyproject.toml # ⚙️ Projekt-Konfiguration
├── .env.example # 📝 Umgebungsvorlage
└── uploads/ # 📁 Upload-Verzeichnis
GuardRAG nutzt COLPALI (Collaborative Learning for Vision-Language Models) für effizienten visuellen Dokumentenabruf:
- PDF-Verarbeitung: Konvertierung zu hochauflösenden Bildern (200 DPI)
- Embedding-Generierung: COLPALI erstellt Multi-Vector-Embeddings
- Visuelle Suche: Similaritätsberechnung zwischen Query und Dokumentenseiten
- Ranking: Relevanz-Score-basierte Sortierung
- Layout-Bewusstsein: Erkennt Tabellen, Diagramme, Strukturen
- OCR-frei: Keine fehleranfällige Texterkennung nötig
- Multimodal: Text und visuelle Elemente gemeinsam
- Effizienz: Schnelle Suche in großen Dokumentensammlungen
GuardRAG enthält verschiedene Test-Skripte für die Funktionsvalidierung:
# Hybrid Guardrails System testen
python test_hybrid_guardrails.py
# Komplettes System testen
python test_complete_system.py
# Development Tasks ausführen
python tasks.py help
🎯 Test-Funktionen:
- �️ Guardrails-Tests: Hybrid LLM+Regex Validation
- 🔍 System-Tests: Vollständige Integration
- 🧪 Unit-Tests: Einzelkomponenten-Validierung
- 📊 Development Tasks: Code-Qualität und Automatisierung
🎛️ Available Test Commands:
# Hybrid Guardrails testen
python test_hybrid_guardrails.py
# Komplettes System validieren
python test_complete_system.py
# Development Tasks
python tasks.py dev-setup # Entwicklungsumgebung einrichten
python tasks.py test-unit # Unit Tests ausführen
python tasks.py format # Code formatieren
python tasks.py lint # Code-Qualität prüfen
python tasks.py help # Alle verfügbaren Tasks
📋 Test-Ausgabe-Format:
�️ GUARDRAILS TEST RESULTS
==================================================
✅ Input Validation: PASSED/FAILED
🧹 Sanitization: '[EMAIL] entfernt'
� Detection Categories:
• Profanität: 0 found
• PII: 1 detected
• Dangerous Content: 0 found
• Toxicity: 0 found
🎯 Confidence: 0.95
⏱️ Processing Time: 0.12s
# Test-Skripte ausführen
python test_hybrid_guardrails.py # Guardrails-System testen
python test_complete_system.py # Komplette Integration
# Development Tasks
python tasks.py test-unit # Unit Tests
python tasks.py dev-setup # Entwicklungsumgebung
# Direkte Test-Skripte
python test_hybrid_guardrails.py # Guardrails-System testen
python test_complete_system.py # Komplette Integration
📁 Verfügbare Test-Dateien:
test_hybrid_guardrails.py
- Hybrid LLM+Regex Guardrails-Teststest_complete_system.py
- Komplette System-Integration-Teststasks.py
- Entwicklungsaufgaben-Manager und Test-Runner
Die Test-Skripte liefern strukturierte Ausgaben zur Validierung der Guardrails-Funktionalität.
curl -X GET "http://localhost:8000/health"
Logs werden in strukturiertem Format ausgegeben:
2025-01-10 15:30:45 - guardrag.main - INFO - GuardRAG application started successfully
2025-01-10 15:31:02 - guardrag.rag_agent - INFO - Processing query: "Welche Methodik wurde verwendet?"
2025-01-10 15:31:03 - guardrag.input_guardrail - INFO - Input validation passed
2025-01-10 15:31:05 - guardrag.colpali - INFO - Retrieved 5 relevant pages
2025-01-10 15:31:07 - guardrag.output_guardrail - INFO - Output validation approved
# Lokale Qdrant-Instanz
QDRANT_HOST=localhost
QDRANT_PORT=6333
# Qdrant Cloud
QDRANT_URL=https://your-cluster.qdrant.tech
QDRANT_API_KEY=your-api-key
Das System nutzt standardmäßig das vidore/colqwen2.5-v0.2
Modell für visuelle Dokumentenanalyse. Bei Memory-Problemen kann ein kleineres Modell verwendet werden:
# Kleineres COLPALI-Modell bei Memory-Problemen
export COLPALI_MODEL=vidore/colSmol-256M
# Kleineres COLPALI-Modell verwenden
export COLPALI_MODEL=vidore/colSmol-256M
# Docker Memory Limits erhöhen
docker-compose up --scale guardrag=1 --memory=8g
# Ollama-Service prüfen
ollama list
ollama serve
# API-Verfügbarkeit testen
curl http://localhost:11434/api/tags
# Prüfe ob Qdrant läuft
curl http://localhost:6333/collections
# Qdrant in Docker starten
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant:latest
# LibreOffice installieren (für Office-Dateien)
# WeasyPrint installieren (für HTML)
uv pip install weasyprint
# Manuell Model herunterladen
python -c "from colpali_engine.models import ColQwen2; ColQwen2.from_pretrained('vidore/colqwen2.5-v0.2')"
# Prüfe verfügbare Test-Dateien
python test_hybrid_guardrails.py
python test_complete_system.py
# Prüfe moderne_guardrails Module-Import
python -c "from src.modern_guardrails import create_guardrails_validator"
# spaCy deutsche Modelle installieren
python -m spacy download de_core_news_lg
python -m spacy download de_core_news_sm
# Verbose Logging aktivieren
export UVICORN_LOG_LEVEL=debug
python main.py
# Guardrails Learning-Logs überwachen
tail -f guardrails_learning.jsonl
# GPU-Nutzung prüfen
nvidia-smi
# Memory-Usage überwachen
htop
# Qdrant Performance tuning
curl -X PUT "http://localhost:6333/collections/documents/index" \
-H "Content-Type: application/json" \
-d '{"field_name": "vector", "field_schema": "Float"}'
Dieses Projekt steht unter der GNU Affero General Public License v3.0 (AGPL-3.0).
- ✅ Freie Nutzung: Kostenlose Nutzung für alle Zwecke
- ✅ Quellcode-Zugang: Vollständiger Quellcode verfügbar
- ✅ Modifikationen erlaubt: Anpassungen und Erweiterungen möglich
- ✅ Weitergabe erlaubt: Redistribution unter gleicher Lizenz
- 📤 Quellcode-Pflicht: Bei Weitergabe muss Quellcode mitgeliefert werden
- 🌐 Network-Copyleft: Auch bei Online-Services muss Quellcode verfügbar sein
- � Gleiche Lizenz: Abgeleitete Werke müssen unter AGPL-3.0 stehen
Siehe LICENSE.md für vollständige Details.
- COLPALI für das exzellente Vision-Language-Retrieval-Framework
- PydanticAI für die strukturierte LLM-Integration
- FastAPI für das moderne Web-Framework
- Ollama für lokale LLM-Inferenz
- Qdrant für die hochperformante Vektordatenbank
- spaCy für Named Entity Recognition
- OpenAI für die API-Kompatibilität
- API-Dokumentation: http://localhost:8000/docs (Swagger UI)
- Alternative Docs: http://localhost:8000/redoc (ReDoc)
- Health Check: http://localhost:8000/health
- System Status: http://localhost:8000/system-status
🛡️ GuardRAG - Sichere, intelligente und lernfähige Dokumentenanalyse mit modernsten AI-Guardrails!