From 2c58ac73cb97c66158ab3afacc3e6b1a2577ac48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Fr=C3=B6hlich?= Date: Wed, 29 Apr 2026 10:19:18 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20README=20aktualisiert=20=E2=80=93=20ing?= =?UTF-8?q?est=5FV2,=20extractor,=20normalizer=20dokumentiert?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 196 ++++++++++++++++++++++++++---------------------------- 1 file changed, 93 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 2a9b67d..52469a0 100644 --- a/README.md +++ b/README.md @@ -1,183 +1,173 @@ # RAG Ingestion Tools Lokale Python-Tools zum Importieren von Dokumenten in pgvector-Datenbanken. -Drei eigenständige Tools für unterschiedliche Zieldatenbanken und Anwendungsfälle. +Drei eigenständige Ingestion-Scripts für unterschiedliche Zieldatenbanken und +Anwendungsfälle, plus zwei gemeinsame Module für Extraktion und KI-Normalisierung. + +--- + +## Dateistruktur + +\`\`\` +rag-ingestion/ +├── ingest_V2.py Vollpipeline v2: OCR + KI-Normalisierung (→ Hetzner) +├── ingest_anythingllm.py Einfaches Script v1: nur MD/TXT/PDF (→ Hetzner) +├── ingest_job_matching.py Job-Matching Script: direkt auf NAS (→ NAS Port 5433) +│ +├── extractor.py Modul: Text-Extraktion + OCR (wird von ingest_V2 genutzt) +├── normalizer.py Modul: KI-Normalisierung via Claude (wird von ingest_V2 genutzt) +│ +├── templates/ +│ ├── *_TEMPLATE.md Ziel-Strukturvorlagen (leer) +│ └── ausgefuellt/ Ausgefüllte Referenzbeispiele (Few-Shot für KI, nicht in Git) +│ +├── .env.ingest Secrets für ingest_V2.py (nicht in Git) +├── .env.job_matching Secrets für ingest_job_matching.py (nicht in Git) +└── .env.example Vorlage für .env.ingest +\`\`\` --- ## Übersicht -| Tool | Zieldatenbank | Verbindung | Besonderheit | -|---|---|---|---| -| `ingest.py` | Hetzner (anythingllm) | SSH-Tunnel | OCR + KI-Normalisierung | -| `ingest_anythingllm.py` | Hetzner (anythingllm) | SSH-Tunnel | Einfach, nur MD/TXT/PDF | -| `ingest_job_matching.py` | NAS 192.168.178.128 | Direkt (Port 5433) | Job-Matching-Datenbank | +| Tool | Zieldatenbank | Verbindung | .env-Datei | Besonderheit | +|---|---|---|---|---| +| \`ingest_V2.py\` | Hetzner (anythingllm) | SSH-Tunnel | \`.env.ingest\` | OCR + KI-Normalisierung | +| \`ingest_anythingllm.py\` | Hetzner (anythingllm) | SSH-Tunnel | \`.env.ingest\` | Einfach, nur MD/TXT/PDF | +| \`ingest_job_matching.py\` | NAS 192.168.178.128 | Direkt (Port 5433) | \`.env.job_matching\` | Job-Matching-Datenbank | --- -## Tool 1: `ingest.py` — Vollpipeline mit OCR + KI-Normalisierung +## Tool 1: \`ingest_V2.py\` — Vollpipeline mit OCR + KI-Normalisierung Das Haupt-Tool der neuen Generation. Verarbeitet beliebige Dokumente (inkl. Scans und Bilder) und normalisiert sie via Claude KI in die einheitliche Template-Struktur. -**Abhängigkeiten:** `extractor.py`, `normalizer.py` (müssen im gleichen Verzeichnis liegen) +**Benötigt:** \`extractor.py\` und \`normalizer.py\` im gleichen Verzeichnis. ### Unterstützte Formate -`.md` `.txt` `.pdf` `.docx` `.png` `.jpg` `.jpeg` `.tif` `.tiff` `.bmp` `.webp` +\`.md\` \`.txt\` \`.pdf\` \`.docx\` \`.png\` \`.jpg\` \`.jpeg\` \`.tif\` \`.tiff\` \`.bmp\` \`.webp\` ### Voraussetzungen -```bash -# Tesseract (OCR, einmalig) -brew install tesseract tesseract-lang +\`\`\`bash +# System-Tools (einmalig) +brew install tesseract tesseract-lang poppler # Python-Pakete pip install -r requirements.txt -# .env konfigurieren -cp .env.example .env -# ANTHROPIC_API_KEY eintragen -``` +# .env.ingest konfigurieren +cp .env.example .env.ingest +nano .env.ingest # ANTHROPIC_API_KEY eintragen +\`\`\` ### Verwendung -```bash -# Einzelne Datei (mit KI-Normalisierung) -python ingest.py file ~/Downloads/fremdes_cv.pdf - -# Erst testen ohne DB-Speicherung -python ingest.py file ~/Desktop/scan.png --dry-run - -# Ohne KI-Normalisierung (z.B. eigene fertige Templates) -python ingest.py file ~/templates/ausgefuellt/mein_cv.md --no-normalize - -# Ganzes Verzeichnis -python ingest.py dir ~/Dokumente/bewerbungsunterlagen/ --force - -# Ordner live beobachten (neue Dateien automatisch verarbeiten) -python ingest.py watch ~/Desktop/scan-eingang/ - -# DB-Inhalt anzeigen -python ingest.py list - -# Dokument löschen -python ingest.py delete "fremdes_cv.pdf" -``` +\`\`\`bash +python ingest_V2.py file ~/Downloads/fremdes_cv.pdf +python ingest_V2.py file ~/Desktop/scan.png --dry-run +python ingest_V2.py file ~/templates/ausgefuellt/mein_cv.md --no-normalize +python ingest_V2.py dir ~/Dokumente/bewerbungsunterlagen/ --force +python ingest_V2.py watch ~/Desktop/scan-eingang/ +python ingest_V2.py list +python ingest_V2.py delete "fremdes_cv.pdf" +\`\`\` ### Flags | Flag | Beschreibung | |---|---| -| `--force` | Bestehende Chunks überschreiben | -| `--no-normalize` | KI-Normalisierung überspringen | -| `--dry-run` | Nur extrahieren + normalisieren, nicht speichern | -| `--quality-min 0.5` | Mindest-Qualitäts-Score (0.0–1.0) | +| \`--force\` | Bestehende Chunks überschreiben | +| \`--no-normalize\` | KI-Normalisierung überspringen | +| \`--dry-run\` | Nur extrahieren + normalisieren, nicht in DB speichern | +| \`--quality-min 0.5\` | Mindest-Qualitäts-Score (0.0–1.0, Standard: 0.0) | -### KI-Normalisierung +### KI-Normalisierung (\`normalizer.py\`) -Erkennt den Dokumenttyp automatisch und transformiert den Inhalt in die passende -Template-Struktur aus `templates/`. Nutzt die ausgefüllten Beispiele aus -`templates/ausgefuellt/` als Few-Shot-Referenz. +- **Typ-Erkennung:** Claude Haiku (günstig + schnell) +- **Transformation:** Claude Sonnet +- **Fehlende Felder** werden mit \`[FEHLT]\` markiert, nie halluziniert +- **Qualitäts-Score:** 0.0–1.0 (Anteil befüllter Pflichtfelder) -- Typ-Erkennung: Claude Haiku (günstig + schnell) -- Transformation: Claude Sonnet -- Fehlende Felder werden mit `[FEHLT]` markiert, nicht halluziniert +Erkannte Typen: \`arbeitszeugnis\`, \`cv\`, \`lebenslauf\`, \`anschreiben\`, +\`projektbeschreibung\`, \`karriereziele\`, \`technologie\`, \`zertifikate\`, +\`referenzen\`, \`elevatorpitch\`, \`rahmenbedingungen\`, \`zielstellen\` + +### OCR-Pipeline (\`extractor.py\`) + +1. \`pypdf\` versucht Text zu extrahieren +2. Weniger als 150 Zeichen → OCR-Fallback via Tesseract (300 DPI) +3. Bilder (PNG, JPG etc.) → direkt OCR --- -## Tool 2: `ingest_anythingllm.py` — Einfaches Ingestion-Script +## Tool 2: \`ingest_anythingllm.py\` — Einfaches Ingestion-Script (v1) -Schlankes Tool ohne OCR und ohne KI-Normalisierung. Direkte Übernahme von -MD/TXT/PDF-Dateien in die anythingllm-Datenbank auf dem Hetzner-Server. - -Geeignet für: eigene, bereits fertig strukturierte Dokumente. +Schlankes Tool ohne OCR und ohne KI-Normalisierung. Geeignet für eigene, +bereits fertig strukturierte Dokumente (z.B. ausgefüllte Templates). ### Unterstützte Formate -`.md` `.txt` `.pdf` - -### Voraussetzungen - -```bash -pip install openai psycopg2-binary pgvector sshtunnel python-dotenv pypdf tiktoken sentence-transformers -cp .env.example .env -# OPENAI_API_KEY eintragen (wird nur für Client-Init benötigt, Embeddings laufen lokal) -``` +\`.md\` \`.txt\` \`.pdf\` ### Verwendung -```bash -# Einzelne Datei +\`\`\`bash python ingest_anythingllm.py file ~/Dokumente/Lebenslauf.md - -# Mit --force (bestehende Chunks überschreiben) python ingest_anythingllm.py file ~/Dokumente/Lebenslauf.md --force - -# Ganzes Verzeichnis python ingest_anythingllm.py dir ~/Dokumente/bewerbung/ - -# DB-Inhalt anzeigen python ingest_anythingllm.py list -``` +\`\`\` --- -## Tool 3: `ingest_job_matching.py` — Job-Matching-Datenbank (NAS) +## Tool 3: \`ingest_job_matching.py\` — Job-Matching-Datenbank (NAS) -Importiert Dokumente direkt in die `job_matching`-Datenbank auf dem lokalen NAS +Importiert Dokumente direkt in die \`job_matching\`-Datenbank auf dem lokalen NAS (192.168.178.128, Port 5433). Kein SSH-Tunnel erforderlich. -### Voraussetzungen - -```bash -pip install -r requirements.txt -cp .env.job_matching .env.job_matching.local -# Werte in .env.job_matching.local anpassen -``` +Embeddings via OpenAI \`text-embedding-3-small\` (kostenpflichtig). ### Verwendung -```bash +\`\`\`bash python ingest_job_matching.py file ~/Dokumente/stellenanzeige.pdf python ingest_job_matching.py dir ~/Dokumente/stellen/ python ingest_job_matching.py list -``` +python ingest_job_matching.py clear "stellenanzeige.pdf" +\`\`\` --- ## Gemeinsame Infrastruktur -### Embedding-Modell +### Embedding-Modelle -Alle Tools verwenden `intfloat/multilingual-e5-small` (384 Dimensionen) lokal. -Wird beim ersten Aufruf automatisch heruntergeladen (~120 MB). - -### Templates - -``` -templates/ -├── *_TEMPLATE.md Ziel-Strukturvorlagen (leer) -└── ausgefuellt/ Ausgefüllte Referenzbeispiele (für KI-Few-Shot) -``` +| Tool | Modell | Dimensionen | Kosten | +|---|---|---|---| +| \`ingest_V2.py\` | multilingual-e5-small (lokal) | 384 | kostenlos | +| \`ingest_anythingllm.py\` | multilingual-e5-small (lokal) | 384 | kostenlos | +| \`ingest_job_matching.py\` | OpenAI text-embedding-3-small | 1536 | kostenpflichtig | ### Umgebungsvariablen -| Datei | Verwendet von | -|---|---| -| `.env` | `ingest.py`, `ingest_anythingllm.py` | -| `.env.job_matching` | `ingest_job_matching.py` | +| Datei | Verwendet von | Inhalt | +|---|---|---| +| \`.env.ingest\` | \`ingest_V2.py\`, \`ingest_anythingllm.py\` | ANTHROPIC_API_KEY, SSH, DB | +| \`.env.job_matching\` | \`ingest_job_matching.py\` | OPENAI_API_KEY, NAS-DB | --- ## Setup (komplett, einmalig) -```bash +\`\`\`bash cd ~/Projekte/rag-ingestion python3 -m venv venv source venv/bin/activate pip install -r requirements.txt -brew install tesseract tesseract-lang # nur für ingest.py (OCR) -cp .env.example .env -nano .env # API-Keys + DB-Zugangsdaten eintragen -``` +brew install tesseract tesseract-lang poppler # nur für ingest_V2.py +cp .env.example .env.ingest +nano .env.ingest # ANTHROPIC_API_KEY + SSH + DB-Zugangsdaten eintragen +\`\`\`