# DocSummarizer Teil 2 - Mit dem Tool [![GitHub-Freigabe](https://img.shields.io/github/v/release/scottgal/mostlylucidweb?filter=docsummarizer*&label=docsummarizer)](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer) [![.NET](https://img.shields.io/badge/.NET-9.0-512BD4)](https://dotnet.microsoft.com/) [![Fassung](https://img.shields.io/badge/version-3.1.0-blue)](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer) Das ist **Teil 2** der DocSummarizer-Serie. Siehe [Teil 1](/blog/building-a-document-summarizer-with-rag) für Architektur und Muster oder [Teil 3](/blog/docsummarizer-advanced-concepts) für den tiefen technischen Sprung in Einbettungen und Retrieval. > **Verwandeln Sie Dokumente oder URLs in beweisgestützte Zusammenfassungen - für Menschen oder KI-Agenten - ohne etwas in die Cloud zu schicken.** Jeder Anspruch ist rückverfolgbar. Jede Tatsache zitiert seine Quelle. Selbstintegrierte binäre, läuft vollständig auf Ihrer Maschine. ```bash # Human-readable summary docsummarizer -f contract.pdf # JSON for agents/pipelines docsummarizer tool -u "https://docs.example.com" ``` **Was dieser Artikel behandelt**: Installation, Schlüsselmodi (Auto/BertRag/Bert), Vorlagen und häufige Anwendungsfälle. **Was es nicht deckt**: Vollständige Befehlsreferenz, Konfigurationsoptionen, Fehlerbehebung, Architekturdetails. Die vollständige Dokumentation finden Sie im [README](https://github.com/scottgal/mostlylucidweb/blob/main/Mostlylucid.DocSummarizer/README.md). Wie es intern funktioniert, siehe [Teil 3](/blog/docsummarizer-advanced-concepts). [TOC] ## Warum dies existiert Die meisten Zusammenfassungen geben Ihnen Text. Dies gibt Ihnen *Nachweise*. - **Jeder Anspruch beinhaltet `[chunk-N]` Zitate** zurück zum Ausgangsmaterial - **Vertrauensniveau** (hoch/mittel/niedrig) auf der Grundlage von Belegen - **Strukturierte JSON-Ausgabe** für Agentenintegration, CI-Pipelines oder MCP-Server - **Qualitätskennzahlen** Halluzinationen fangen, bevor sie entkommen Wenn Sie *Vertrauen* eine Zusammenfassung - oder füttere sie an ein anderes System - das zählt. ## Merkmale - **BERTRAG-Pipeline**: Produktionsqualität BERT-Extraktion → Retrieval → LLM-Synthese - **Auto-Modus**: Smart-Modus-Auswahl basierend auf Dokument und Abfrage - **BETRIEBSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHRSVERKEHR**: Reine extraktive Zusammenfassung - keine LLM benötigt, funktioniert offline (~3-5s) - **Evidenzgerundete Ausgabe**: Zitate, Konfidenzniveau, rückverfolgbare Behauptungen - **Mehrere Betriebsarten**: Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative - **Werkzeugmodus**: Saubere JSON für LLM-Agenten, MCP-Server, CI-Kontrollen - **13 Vorlagen**: default, prosa, kurz, oneliner, kugeln, executive, detailliert, technisch, akademisch, Zitate, bookreport, meeting, streng - **Große Dokumente**: Griffe 500+ Seiten mit hierarchischer Bearbeitung - **Web-Fetching**: Sicherheitsgehärtet (SSRF-Schutz, HTML-Sanitisierung) - **Wiedergabemodus**: Headless-Browser für JavaScript-gerenderte Seiten (SPAs, React-Apps) - **ONNX-Einbetten**: Zero-config lokale Einbettungen - Modelle Auto-Download bei erster Verwendung - **Qualitätsanalyse**: Halluzinationserkennung, Entitätsextraktion - **Resiliente LLM**: Polly-basierte Retry mit Jitter Backoff + Leistungsschalter - **Nur lokal**: Nichts verlässt Ihre Maschine ## Als LLM-Werkzeug verwenden Das `tool` command wurde speziell für die Integration mit KI-Agenten, MCP-Servern und anderen automatisierten Systemen entwickelt. Es gibt strukturierte JSON auf stdout mit evidenzbasierten Claims aus - perfekt für den Aufbau von RAG-Pipelines oder Agenten-Tools. ### Verwendung des Basiswerkzeugs ```bash # Summarize a URL and get JSON output docsummarizer tool --url "https://example.com/docs.html" # Summarize a local file docsummarizer tool -f document.pdf # With a focus query docsummarizer tool -f contract.pdf -q "payment terms and conditions" # Pipe to jq for processing docsummarizer tool -f doc.pdf | jq '.summary.keyFacts' ``` ### Werkzeug-Ausgabe-Struktur Der Tool-Befehl gibt strukturiertes JSON mit Evidenz-Tracking zurück: ```json { "success": true, "source": "https://example.com/docs.html", "contentType": "text/html", "summary": { "executive": "Brief summary of the document.", "keyFacts": [ { "claim": "The system supports 10,000 TPS.", "confidence": "high", "evidence": ["chunk-3", "chunk-7"], "type": "fact" } ], "topics": [ { "name": "Architecture", "summary": "The system uses microservices...", "evidence": ["chunk-1", "chunk-2"] } ], "entities": { "people": ["John Smith"], "organizations": ["Acme Corp"], "concepts": ["OAuth 2.0", "REST API"] }, "openQuestions": ["What is the disaster recovery plan?"] }, "metadata": { "processingSeconds": 12.5, "chunksProcessed": 15, "model": "qwen2.5:1.5b", "mode": "MapReduce", "coverageScore": 0.95, "citationRate": 1.2, "fetchedAt": "2025-01-15T10:30:00Z" } } ``` ### Befehlsoptionen für Werkzeug ```bash docsummarizer tool [options] ``` Kurzbeschreibung |--------|-------|-------------| | `--url` | `-u` URL zum Abrufen und Zusammenfassen | `--file` | `-f` Datei zum Zusammenfassen | `--query` | `-q` Optionale Fokusabfrage | `--mode` | `-m` Zusammenfassungsmodus (Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative) | `--model` Ollama Modell zu verwenden | `--config` | `-c` Konfigurationsdatei-Pfad ### Die wichtigsten Grundsätze für die Gestaltung - **Beweise für die Erdung**: Jeder Anspruch beinhaltet `evidence` IDs, die sich auf Quellstücke beziehen - **Vertrauensniveaus**: Forderungen werden bewertet `high`, `medium`, oder `low` auf der Grundlage von Belegen - **Saubere Ausgabe**: Das `executive` Zusammenfassung hat keine Zitiermarker für eine einfache Anzeige - **Metadaten**: Verarbeitung von Statistiken Hilfe bei Debugging und Qualitätsbewertung - **Fehlerbehebung**: Fehler bei der Rückkehr `success: false` mit einem `error` Nachricht ### Integrationsbeispiele **Python-Skript:** ```python import subprocess import json result = subprocess.run( ["docsummarizer", "tool", "-u", "https://example.com/api-docs"], capture_output=True, text=True ) data = json.loads(result.stdout) if data["success"]: for fact in data["summary"]["keyFacts"]: if fact["confidence"] == "high": print(f"- {fact['claim']}") ``` **Shell-Pipeline:** ```bash # Extract high-confidence facts only docsummarizer tool -f doc.pdf | jq '[.summary.keyFacts[] | select(.confidence == "high")]' # Get just the executive summary docsummarizer tool -u "https://example.com" | jq -r '.summary.executive' ``` ## Schnellstart ### Vorgefertigte Binaries herunterladen Vorgefertigte native ausführbare Dateien sind verfügbar unter [GitHub veröffentlicht](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer): Plattform , Architektur , Download , |----------|--------------|----------| Fenster x64 `docsummarizer-win-x64.zip` | Fenster ARM64 `docsummarizer-win-arm64.zip` | Linux, x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-x64-xx64-x64-xx64-x64-x64-x64-x64-xx64-x64-x64-x64-xx64-x64-x64-x64-x64-x64-x64-x64-x64-xx64-xx64-xx64-xx64-xx64-xxx64-xxx-x64-xx64-x64-x64-x64-x64-x64-xxx64-xx64-x64-x64-xxxx64-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx `docsummarizer-linux-x64.tar.gz` | Linux , ARM64 , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , `docsummarizer-linux-arm64.tar.gz` | MacOS, x64 (Intel) `docsummarizer-osx-x64.tar.gz` | „ macOS" ARM64 (Apfelsilizium) `docsummarizer-osx-arm64.tar.gz` | ```bash # Download and extract (Linux/macOS) curl -L -o docsummarizer.tar.gz https://github.com/scottgal/mostlylucidweb/releases/download/docsummarizer-v3.1.0/docsummarizer-linux-x64.tar.gz tar -xzf docsummarizer.tar.gz chmod +x docsummarizer # Download and extract (Windows PowerShell) Invoke-WebRequest -Uri "https://github.com/scottgal/mostlylucidweb/releases/download/docsummarizer-v3.1.0/docsummarizer-win-x64.zip" -OutFile "docsummarizer.zip" Expand-Archive -Path "docsummarizer.zip" -DestinationPath "." ``` ### Voraussetzungen #### Bert-Modus (keine externen Dienste) Zur reinen extraktiven Zusammenfassung, **keine externen Dienstleistungen erforderlich**: ```bash docsummarizer -f document.md -m Bert ``` ONNX modelliert Auto-Download von HuggingFace beim ersten Einsatz (~23MB). Gibt in ~3-5 Sekunden zurück. #### LLM-Modus (Auto, BertRag, MapReduce usw.) Für die LLM-gestützte Zusammenfassung ist Ollama erforderlich: ```bash # Install Ollama from https://ollama.ai ollama pull llama3.2:3b # Default model - good balance of speed/quality ollama serve ``` > **Geschwindigkeitsspitze**: Für schnellere Zusammenfassungen (~3s vs ~15s), verwenden Sie `--model qwen2.5:1.5b` #### Optional: Docling (Binäre Formate) Erforderlich für PDF-, DOCX-, XLSX-, PPTX-, HTML-, Images (PNG/JPG/TIFF), CSV-, VTT- und AsciiDoc-Dateien. **Markdown und einfache Textdateien werden direkt gelesen - keine Docling erforderlich.** ```bash docker run -d -p 5001:5001 quay.io/docling-project/docling-serve ``` #### Optional: Qdrant (Persistent Vector Storage) Standardmäßig nicht erforderlich - BertRag verwendet In-Memory-Vektoren. Aktivieren Sie Qdrant für persistente Speicherung, um eine erneute Einbettung von Dokumenten bei folgenden Ausläufen zu vermeiden: ```bash docker run -d -p 6333:6333 -p 6334:6334 qdrant/qdrant ``` Konfigurieren Sie dann in `docsummarizer.json`: ```json { "bertRag": { "vectorStore": "Qdrant", "collectionName": "docsummarizer", "persistVectors": true } } ``` #### Optional: Ollama-Embeddings Wenn Sie Ollama für Einbettungen anstelle von ONNX bevorzugen: ```bash ollama pull nomic-embed-text # Or mxbai-embed-large # Then use: --embedding-backend Ollama ``` ### Abhängigkeiten überprüfen ```bash docsummarizer check --verbose ``` Erwartete Ausgabe zeigt eine formatierte Tabelle: ``` Dependency Status ╭─────────┬────────┬────────────────────────╮ │ Service │ Status │ Endpoint │ ├─────────┼────────┼────────────────────────┤ │ Ollama │ OK │ http://localhost:11434 │ │ Docling │ Optional │ http://localhost:5001 │ │ Qdrant │ Optional │ localhost:6333 │ ╰─────────┴────────┴────────────────────────╯ Default Model Info ╭────────────────┬────────────────╮ │ Property │ Value │ ├────────────────┼────────────────┤ │ Name │ llama3.2:3b │ │ Family │ llama │ │ Parameters │ 3.2B │ │ Context Window │ 128,000 tokens │ ╰────────────────┴────────────────╯ Ready to summarize! Ollama is available. ``` > **Anmerkung**: Docling und Qdrant zeigen, ist in Ordnung für Markdown-only-Workflows. ## Verwendung ### Standardverhalten Laufen `docsummarizer` ohne Argumente wird: 1. Suchen Sie nach `README.md` im aktuellen Verzeichnis 2. Zusammenfassen mit **Automatischer Modus** (Smart-Modus-Auswahl) 3. Drucken Sie die Zusammenfassung auf Konsole mit einem schönen Panel UI 4. Automatisch speichern `readme.summary.md` ```bash # Summarize README.md in current directory docsummarizer # Shows a formatted panel with: # - Document info table (file, mode, model) # - Progress indicators during processing # - Summary panel with the result # - Topics tree if available # - Saved: readme.summary.md ``` ### Grundlegende Zusammenfassung ```bash # Just run it - Auto mode picks the best approach docsummarizer -f document.pdf # Fast mode - no LLM, pure extraction (~3-5s) docsummarizer -f document.pdf -m Bert # Production mode - best quality with validated citations docsummarizer -f document.pdf -m BertRag # Focused on specific topic docsummarizer -f manual.pdf -m BertRag --focus "installation steps" # Verbose progress docsummarizer -f document.pdf -v ``` ## Zusammenfassungsmodi Das Tool entwickelte sich von "nur MapReduce" zu einer vollständigen Pipeline. Hier ist, was jeder Modus tatsächlich tut: ### Automatisch (Standard) Wählen Sie den richtigen Modus basierend auf dem, was Sie verlangen. Verwenden Sie dies, es sei denn, Sie haben einen Grund, nicht zu. ```bash docsummarizer -f doc.pdf ``` ### BertRag (Produktion) Das ist, was Sie für die Produktion wollen. Drei-Phasen-Pipeline: 1. **Auszug** - Parsen Sie das Dokument in Segmente, betten Sie sie mit BERT ein 2. **Abrufen** - Finden Sie die relevanten Segmente (semantische Suche + Salience Scoring) 3. **Synthesize** - LLM schreibt eine fließende Zusammenfassung aus diesen Segmenten ```bash docsummarizer -f doc.pdf -m BertRag docsummarizer -f doc.pdf -m BertRag --focus "payment terms" ``` **Warum verwenden Sie es:** Jeder Anspruch geht auf ein Quellsegment zurück. Keine Halluzination. Skaliert auf jede Dokumentgröße. LLM läuft nur am Ende (billig). ### Bert (Fast, Nr. LLM) Reine Extraktion mit lokalen ONNX-Modellen. Kein LLM-Aufruf. ```bash docsummarizer -f doc.pdf -m Bert ``` **Warum verwenden Sie es:** Funktioniert offline. Gibt in ~3-5 Sekunden zurück. Deterministisch (gleicher Eingang = gleicher Ausgang). Gut genug für schnelle Scans. ### BertHybrid BERT-Extrakte, LLM-Polierungen. Mittlerer Boden zwischen Bert und BertRag. ```bash docsummarizer -f doc.pdf -m BertHybrid ``` ### KarteReduce / Rag / iterative Die ursprünglichen Modi. Noch funktionieren, aber BertRag ersetzte sie für die meisten Anwendungsfälle. - **KarteReduce**: Paralleles Lochen, gut für 100% Deckung - **Wanzen**: Vektorsuche, gut für fokussierte Abfragen (Vermächtnis - BertRag macht das besser) - **Iterativ**: Sequenzielle Verarbeitung, nur für winzige Docs ```bash docsummarizer -f doc.pdf -m MapReduce # Full coverage docsummarizer -f doc.pdf -m Rag --focus "query" # Legacy focused mode ``` ### Abfragemodus Stellen Sie statt zu summieren Fragen über ein Dokument: ```bash docsummarizer -f manual.pdf --query "How do I install the software?" ``` ### Web-URL-Fetching Zusammenfassen von Webseiten direkt ohne Download: ```bash # Summarize a web article docsummarizer --url "https://example.com/article.html" --web-enabled # Summarize a remote PDF docsummarizer --url "https://example.com/document.pdf" --web-enabled # With structured JSON extraction docsummarizer --url "https://example.com/api-docs.html" --web-enabled --structured ``` **Unterstützte Inhalte**: HTML (sanitisiert), PDF, Markdown, Images (OCR), Office-Dokumente. Große Bilder werden automatisch verkleinert. **Sicherheit**: SSRF-Schutz, DNS-Rebinding-Schutz, Content-Gating, Dekompression-Bombenschutz, HTML-Sanitisierung. **JavaScript-gestrichene Seiten**: Verwendung `--web-mode Playwright` für SPAs und React-Apps (auto-installiert Chromium beim ersten Einsatz). ### Strukturierter Modus Extrahieren Sie maschinenlesbare JSON anstelle von Prosa: ```bash docsummarizer -f document.pdf --structured -o Json ``` Auszüge: Entitäten, Funktionen, Schlüsselflüsse, Fakten (mit Vertrauensniveau), Ungewissheiten, kontingentierbare Passagen. ### Zusammenfassungsvorlagen ```bash # Use a template docsummarizer -f doc.pdf --template executive docsummarizer -f doc.pdf -t bullets # Specify custom word count with template:wordcount syntax docsummarizer -f doc.pdf -t bookreport:500 docsummarizer -f doc.pdf -t executive:100 # Or use --words to override any template's default docsummarizer -f doc.pdf -t detailed --words 300 ``` Vordrucke, Wörter, die am besten für sie geeignet sind |----------|-------|----------| | `default` Ausgewogene Zusammenfassung mit Themen (2 Absätze) | `prose` ~400. Saubere Mehr-Absatz-Prosa - keine Metadaten | `brief` Schnell 2-3 Satz Zusammenfassung | `oneliner` Zusammenfassung eines einzigen Satzes | `bullets` Liste der Bulletpunkte (5-7 Punkte) | `executive` Exekutives Briefing mit Empfehlungen | `detailed` Umfassend mit vollen Themen | `technical` Technical docs with implementation details | `academic` Akademisches abstraktes Format | `citations` Schlüssel-Zitate nur mit Quellenzitierungen | `bookreport` ~500. Buchbericht (Einstellen, Zeichen, Handlung, Themen) | `meeting` ~200. Sitzungsnotizen (Entscheidungen, Handlungen, Fragen) | `strict` ~60. Token-effizient, 3 Kugeln max, kein Hedging Um alle verfügbaren Vorlagen mit Beschreibungen zu sehen: ```bash docsummarizer templates ``` ### Modell-Benchmarking Vergleichen Sie Modelle auf dem gleichen Dokument mit dem `benchmark` Unterbefehl: ```bash docsummarizer benchmark -f doc.pdf -m "qwen2.5:1.5b,llama3.2:3b,ministral-3:3b" ``` Der Benchmark-Befehl parsiert das Dokument einmal und führt dann jedes Modell auf den gleichen Stücken für einen fairen Vergleich aus. Ausgabe zeigt Timing, Wortanzahl und Wörter/Sekunde für jedes Modell an. ### Batch-Verarbeitung Ganze Verzeichnisse bearbeiten: ```bash # Use BertRag for quality docsummarizer -d ./documents -m BertRag -v # Fast offline batch (no LLM needed) docsummarizer -d ./documents -m Bert -o Json --output-dir ./summaries # Process only PDFs recursively docsummarizer -d ./documents -e .pdf --recursive -v ``` ### Befehlszeilenoptionen Optionen Kurzbeschreibung Standard |--------|-------|-------------|---------| | `--file` | `-f` Pfad zum Dokument (DOCX, PDF, MD) --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | `--directory` | `-d` Pfad zum Verzeichnis für die Batch-Verarbeitung------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | `--url` | `-u` Web-URL zum Abrufen und Zusammenfassungen | `--web-enabled` Aktivieren Sie Web-Hotching (erforderlich für --url) `false` | | `--mode` | `-m` Zusammenfassungsmodus: Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative `Auto` | | `--structured` | `-s` Verwendung des strukturierten JSON-Extraktionsmodus `false` | | `--focus` Fokus-Abfrage für den RAG-Modus Keine | `--query` | `-q` Abfragemodus statt Zusammenfassungen | `--model` Ollama Modell zu verwenden `llama3.2:3b` | | `--verbose` | `-v` Ausführlichen Fortschritt mit Live-UI-Anzeigen anzeigen `false` | | `--config` | `-c` Pfad zur Konfigurationsdatei-Erkennen Sie automatisch | `--output-format` | `-o` Ausgabeformat: Konsole, Text, Markdown, Json `Console` | | `--output-dir` Ausgabe-Verzeichnis für Datei-Ausgaben Aktueller Ordner | `--extensions` | `-e` Dateierweiterungen für Batch-ModusAlle Docling-Formate | `--recursive` | `-r` Ordner rekursiv verarbeiten `false` | | `--template` | `-t` Zusammenfassung Vorlage (Standard, kurze, Kugeln, Exekutive, etc.) `default` | | `--words` | `-w` Zielwortzahl (überschriebene Vorlage)Vorlage voreingestellt | `--embedding-backend` Einbetten Backend: Onnx, Ollama `Onnx` | | `--embedding-model` ONNX-Modellname (RAG-Modus) `AllMiniLmL6V2` | | `--web-mode` Web-Hotch-Modus: Einfach, Playwright `Simple` | | `--analyze` | `-a` Ausführen der Qualitätsanalyse auf Zusammenfassung `false` | ## Zusammenfassungsmodi ### KarteReduce (empfohlen) Am besten für umfassende Zusammenfassungen mit vollständiger Dokumentenabdeckung. ```bash docsummarizer -f document.pdf -m MapReduce -v ``` **Wie es funktioniert**: 1. Teilt Dokument in Strukturstücke auf (nach Rubriken) 2. Zusammenfasst jeden Block parallel mit LLM 3. Reduziert Zusammenfassungen in Zusammenfassungen mit Zitaten 4. Validiert alle Zitate Referenz reale Stücke **Hierarchische Reduktion für lange Dokumente**: Für sehr lange Dokumente, bei denen die kombinierten Brockenzusammenfassungen das Kontextfenster des Modells überschreiten, verwendet MapReduce automatisch hierarchische Reduktion: 1. **Batching**: Gruppenzusammenfassungen in Chargen, die in den Kontext passen 2. **Halbzeitkürzung**: Reduziert jede Charge auf eine kondensierte Zusammenfassung 3. **Endgültige Kürzung**: Zusammenführen von Zwischenzusammenfassungen in die Endproduktion 4. **Rekursiv**: Wenn Zwischenprodukte noch zu groß sind, fügt mehr Ebenen hinzu ``` 100 chunks → 100 summaries → 5 batches → 5 intermediate summaries → final ``` Dadurch bleibt die volle Dokumentabdeckung unabhängig von der Länge erhalten - jeder Brocken trägt zur abschließenden Zusammenfassung bei. Das Tool schätzt Token (~4 Zeichen/Token) und zielt auf 60% Kontextfensterauslastung pro Reduktionspass. **Vorsätzliche**: Schnelle, vollständige Abdeckung, parallele Verarbeitung, behandelt jede Dokumentlänge **Nachteile**: Kann Querschnittsverbindungen vermissen, langsamer für sehr lange Dokumente ### RAG (am besten für fokussierte Abfragen) Am besten, wenn Sie sich auf bestimmte Themen konzentrieren oder eine gezielte Frage haben müssen. ```bash docsummarizer -f document.pdf -m Rag --focus "pricing and payment terms" -v ``` **Wie es funktioniert**: 1. Indexe dokumentieren Brocken als Vektoreinbettungen in Qdrant 2. Extrahiert die wichtigsten Themen aus Dokumentenüberschriften 3. Ruft relevante Brocken pro Thema mit semantischer Suche ab 4. Synthesizes fokussierte Zusammenfassung mit Zitaten **Wann RAG über MapReduce verwendet werden soll**: Szenarium - Bester Modus |----------|-----------| "Zusammenfassen dieses ganze Dokument" - MapReduce "Was sagt das über Sicherheit?" 500-Seiten-Handbuch, brauchen alles, Karte Reduce (hierarchisch) 500-seitiges Handbuch, spezifischer Abschnitt benötigen Benötigen Sie schnelle Ergebnisse, haben Sie nicht Qdrant-KarteReduce- RAG ist **nicht** über den Umgang mit langen Dokumenten - MapReduce behandelt, dass mit hierarchischen Reduktion. RAG ist über **Relevanzfilterung**: wenn Sie 90% eines Dokuments ignorieren und sich darauf konzentrieren wollen, was für Ihre spezifische Frage von Bedeutung ist. **Vorsätzliche**: Themaorientiertes, semantisches Verständnis, Wiederverwendungsindex, schneller für fokussierte Abfragen **Nachteile**: Kann Inhalte außerhalb des Fokusbereichs vermissen, erfordert Qdrant, langsamere anfängliche Indexierung ### Iterativ Am besten für narrative Dokumente, in denen Kontext sequenziell fließt. ```bash docsummarizer -f story.pdf -m Iterative -v ``` **Warnung**: Langsamer und kann den Kontext auf langen Dokumenten (> 10 Brocken) verlieren. ## Große Dokument-Leitfaden ### Den richtigen Modus wählen Dokumenttyp: Zielmodus: Warum? |---------------|------|------|-----| Technische Daten (50+ Seiten) Neu/Narrativer Inhalt Vollständige Zusammenfassung KarteReduce Benötigt zeitlichen Kontext Rechtlicher Vertrag Vollständige Zusammenfassungen KarteReduce , kann Klauseln nicht verpassen , Rechtlicher Vertrag "Zahlungskonditionen?" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . API-Dokumente (200 Seiten) "Wie funktioniert Auth?" Forschungspapier Vollständige Zusammenfassung KarteReduce, strukturiert, brauchen alles ### Fiction vs. Sachbuch Anmerkungen zum besten Modus |--------------|-----------|-------| | **Fiction/Narrative** Der MapReduce-Plot erfordert einen sequentiellen Kontext. | **Technische Dokumentation** Beides, MapReduce für die Übersicht, RAG für Spezifika | **Rechtsvorschriften/Verträge** Jede Klausel ist wichtig | **Handbücher** Gewöhnliches Abfragen nach Spezifika ### Leistung Dokumentengröße KarteReduce-RAG-Anmerkungen |---------------|-----------|-----|-------| 10 Seiten 15s 20s Beide schnell 50 Seiten, 45s, 30s, RAG schneller, wenn fokussiert 200 Seiten 3-5 Minuten 1-2 Minuten Hierarchische Reduktion > 500 Seiten > 10-15 min > 2-3 min > Betrachten Sie mehrere RAG-Abfragen > ## Einrichtung ### Standardkonfiguration generieren ```bash docsummarizer config --output myconfig.json ``` ### Konfigurationsdatei Die Konfiguration wird automatisch von: 1. `--config` Option 2. `docsummarizer.json` im aktuellen Verzeichnis 3. `.docsummarizer.json` (versteckte Datei) 4. `~/.docsummarizer.json` (Zuhause) Beispiel `docsummarizer.json`: ```json { "embeddingBackend": "Onnx", "onnx": { "embeddingModel": "AllMiniLmL6V2" }, "ollama": { "model": "llama3.2:3b", "embedModel": "mxbai-embed-large", "baseUrl": "http://localhost:11434", "temperature": 0.3, "timeoutSeconds": 1200 }, "docling": { "baseUrl": "http://localhost:5001", "timeoutSeconds": 1200, "pdfBackend": "pypdfium2", "pagesPerChunk": 10, "maxConcurrentChunks": 4, "enableSplitProcessing": true }, "qdrant": { "host": "localhost", "port": 6333, "collectionName": "documents" }, "processing": { "maxHeadingLevel": 2, "targetChunkTokens": 1500, "minChunkTokens": 200, "maxLlmParallelism": 2 }, "output": { "format": "Console", "verbose": false, "includeTrace": false }, "webFetch": { "enabled": false, "mode": "Simple", "timeoutSeconds": 30, "userAgent": "Mozilla/5.0 DocSummarizer/1.0" }, "batch": { "fileExtensions": [".pdf", ".docx", ".md", ".txt", ".html"], "recursive": false, "continueOnError": true } } ``` ### Verarbeitungsoptionen Voreinstellung Beschreibung |--------|---------|-------------| | `maxLlmParallelism` 8) Gleichzeitige LLM-Anfragen (Ollama-Warteschlangen, also höhere Werte nur Warteschlange) | `maxHeadingLevel` Nur auf H1/H2 teilen. Auf 3 für feinere Granularität einstellen | `targetChunkTokens` 0 = automatische Berechnung (~25% des Kontextfensters) | `minChunkTokens` 0 = 1/8 des Ziels ## Ausgabeformat ### Übersichtsstruktur ```C:\Blog\mostlylucidweb\Mostlylucid\Markdown\docsummarizer-tool.md ## Executive Summary - Key finding 1 with specific details [chunk-0] - Important point 2 with numbers and dates [chunk-3] - Critical requirement 3 [chunk-5] ## Section Highlights - Introduction: Overview of the system architecture [chunk-0] - Requirements: Technical specifications detailed [chunk-3] ... ## Open Questions - What is the timeline for Phase 2? - How does the fallback mechanism work? ### Trace - Document: document.pdf - Chunks: 12 total, 12 processed - Topics: 5 - Time: 21.4s - Coverage: 100% - Citation rate: 1.20 ``` **Trace-Metriken**: Erfassung (% Abschnitte enthalten), Zitationsrate (Zitate/Bülle), verarbeitete Chunks (RAG kann einige überspringen). ## Modellempfehlungen Modell Größe Geschwindigkeit Qualität Fall verwenden |-------|------|-------|---------|----------| | `qwen2.5:1.5b` Sehr schnell (~3s) Gute Geschwindigkeit optimiert | `gemma3:1b` Schnell (~10s)Alternatives kleines Modell | `llama3.2:3b` Mittel (~15s) Sehr gut **Vorgabe** - gute Ausgewogenheit | `ministral-3:3b` Mittel (~20er Jahre) | `llama3.1:8b` Langsam (~45s)Ausgezeichnet Hochqualitative Zusammenfassungen > **Tipp**: Für schnellere Zusammenfassungen (~3s vs ~15s), verwenden Sie `--model qwen2.5:1.5b`. Für kritische Dokumente, bei denen Qualität mehr zählt, verwenden Sie `--model llama3.1:8b`. ## Bauen aus Quelle ```bash # Clone the repository git clone https://github.com/scottgal/mostlylucidweb.git cd mostlylucidweb/Mostlylucid.DocSummarizer # Build dotnet build # Run dotnet run -- --help ``` ### Selbstverwaltete Gebäude Für den Produktionseinsatz ohne .NET-Laufzeitinstallation: ```bash # Build self-contained executable (Windows x64) dotnet publish -c Release -r win-x64 --self-contained # Build for Linux dotnet publish -c Release -r linux-x64 --self-contained # Build for macOS dotnet publish -c Release -r osx-x64 --self-contained ``` Ausgabe: `bin/Release/net9.0//publish/docsummarizer` ## Fehlerbehebung ### "Könnte sich nicht mit Ollama verbinden" - Stellen Sie sicher, dass Ollama läuft: `ollama serve` - Prüfmodelle werden gezogen: `ollama list` ### "Docling-Service nicht verfügbar" - Das ist **nur für PDF/DOCX-Dateien erforderlich** - Für Markdown-Dateien können Sie diesen Fehler ignorieren - Um Folgendes zu beheben: `docker run -p 5001:5001 quay.io/docling-project/docling-serve` ### "Qdrant-Verbindung fehlgeschlagen" - Das ist **nur für den RAG-Modus erforderlich** (`--mode Rag`) - Für den MapReduce-Modus (Standard) können Sie diesen Fehler ignorieren. - Um Folgendes zu beheben: `docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant` ### "Circuit Breaker ist offen" - Ollama ist überlastet oder abgestürzt - Warten Sie 30 Sekunden, bis der Leistungsschalter zurückgesetzt wird, oder starten Sie Ollama neu - Das Tool verwendet Polly Resilienz-Richtlinien und wird automatisch retry ### "wsarecv" oder Verbindungsfehler (Windows) - Dies ist ein bekanntes Ollama-Problem unter Windows (GitHub #13340) - Das Tool auto-handles dies mit retry Logik und Verbindung Wiederherstellung - Wenn Sie persistent sind, starten Sie Ollama neu und versuchen Sie es erneut. ### "LLM generation timed out" - Timeout in der Konfiguration erhöhen - Sehr große Dokumente teilen - Check Ollama ist nicht mit anderen Anfragen überlastet ### Wiederholungs- oder minderwertige Zusammenfassungen **Symptome**: Bullet points echo the prompt ("Return only bullet points", "The rule is..."), anstatt den Inhalt zusammenzufassen. **Ursache**: Modell, das mit der Eingabeaufforderung oder dem Inhalt zu lange kämpft. **Fixieren**: Der Standardwert `qwen2.5:1.5b` behandelt die meisten Dokumente gut. Für problematische Dokumente, versuchen `--model llama3.2:3b`. Siehe [Modellempfehlungen](#model-recommendations). ### Zusammenfassung Ignoriert Dokumentinhalt Wenn die Zusammenfassung generisch erscheint oder nicht auf bestimmte Inhalte verweist: - Das Modell kann halluzinieren - überprüfen `Citation rate` in der Trace-Ausgabe - Testen Sie den RAG-Modus (`--mode Rag`) die Zusammenfassungen in abgerufenen Brocken begründen - Verwendung `--verbose` zu sehen, welche Stücke verarbeitet werden ### Zitate fehlen oder sind ungültig Wenn Zusammenfassungen fehlen `[chunk-N]` Zitate: - Kleine Modelle priorisieren Inhalte über die Formatierung von Zitaten - Die Eingabeaufforderung ist auf Geschwindigkeit optimiert, nicht auf strikte Zitieren-Compliance - Für strenge Zitate, verwenden Sie größere Modelle wie `llama3.2:3b` - Kontrolle `Citation rate` in trace - höhere Werte deuten auf eine bessere Rückverfolgbarkeit hin ## Leistungstipps - **KarteReduce** für Geschwindigkeit (Parallelstücke) - **`qwen2.5:1.5b`** für Geschwindigkeit, **`llama3.2:3b`** für den Restbetrag, **`llama3.1:8b`** für Qualität - **Einbettungen von ONNX** (Standard) sind schneller als Ollama für RAG-Modus - Untere **`maxLlmParallelism`** wenn Timeouts auftreten ## Aufkommen - [Quellencode](https://github.com/scottgal/mostlylucidweb/tree/main/Mostlylucid.DocSummarizer) - [GitHub veröffentlicht](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer) - [Doktoranden](https://github.com/docling-project/docling) / [Docling Servieren](https://github.com/docling-project/docling-serve) - [Qdrant](https://qdrant.tech/) - Lokale Vektordatenbank - [Ollama](https://ollama.ai/) / [OllamaSharp](https://github.com/awaescher/OllamaSharp) - [Polly. - (EN) Nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein, nein.](https://github.com/App-vNext/Polly) - .NET-Belastbarkeit und transiente Fehlerbehandlung - [Spectre.Console](https://spectreconsole.net/) - Schöne Terminal UI ## Reihennavigation - **[Teil 1: Aufbau eines Dokument-Zusammenfassung mit RAG](/blog/building-a-document-summarizer-with-rag)** - Architektur und Muster - **[Teil 2: Verwendung des Werkzeugs](/blog/docsummarizer-tool)** (dieser Artikel) - Kurzanleitung - **[Teil 3: Fortgeschrittene Konzepte](/blog/docsummarizer-advanced-concepts)** - Tief tauchen in BERT, ONNX, Einbettungen und hybride Suche ### Verbunden - [CSV-Analyse mit lokalen LLMs](/blog/analysing-large-csv-files-with-local-llms) - [Web-Inhalte mit LLMs](/blog/fetching-and-analysing-web-content-with-llms)