# DocSummarizer Deel 2 - Het gebruik van het gereedschap [![GitHub release](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/) [![Versie](https://img.shields.io/badge/version-3.1.0-blue)](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer) Dit is **Deel 2** van de DocSummarizer serie. Zie [Deel 1](/blog/building-a-document-summarizer-with-rag) voor de architectuur en patronen, of [Deel 3](/blog/docsummarizer-advanced-concepts) voor de diepe technische duik in inbeddingen en ophalen. > **Verander documenten of URL's in samenvattingen met bewijsgrond - voor mensen of AI-agenten - zonder iets naar de cloud te sturen.** Elke claim is traceerbaar. Elk feit citeert zijn bron. Zelfstandig binair, draait volledig op uw machine. ```bash # Human-readable summary docsummarizer -f contract.pdf # JSON for agents/pipelines docsummarizer tool -u "https://docs.example.com" ``` **Waar dit artikel over gaat**: Installatie, sleutelmodi (Auto/BertRag/Bert), sjablonen en veelgebruikte cases. **Wat het niet dekt.**: Volledige commando referentie, configuratie opties, probleemoplossing, architectuur details. Voor volledige documentatie, zie de [README](https://github.com/scottgal/mostlylucidweb/blob/main/Mostlylucid.DocSummarizer/README.md). Voor hoe het intern werkt, zie [Deel 3](/blog/docsummarizer-advanced-concepts). [TOC] ## Waarom dit bestaat De meeste samenvattingen geven je tekst. *bewijs*. - **Elke claim omvat `[chunk-N]` aanhalingstekens** terug naar bronmateriaal - **Vertrouwensniveaus** (hoog/medium/laag) op basis van bewijsmateriaal - **Gestructureerde JSON-uitvoer** voor agentintegratie, CI-pijpleidingen of MCP-servers - **Kwaliteitsmetrics** hallucinaties vangen voordat ze ontsnappen Als u *vertrouwen* een samenvatting - of voer het aan een ander systeem - die van belang is. ## Functies - **BertRag Pipeline**: Productie-kwaliteit BERT extractie → Retrieval → LLM synthese - **Auto-modus**: Smart mode selectie op basis van document en query - **Bert-modus**: Pure winningscondensatie - geen LLM nodig, werkt offline (~3-5s) - **Evidence-Grounded Output**: Verwijzingen, betrouwbaarheidsniveaus, traceerbare claims - **Meerdere modi**: Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative - **Gereedschapsmodus**: Clean JSON voor LLM-agenten, MCP-servers, CI-controles - **13 Sjablonen**: standaard, proza, kort, oneliner, kogels, uitvoerende, gedetailleerde, technische, academische, citaten, boekreport, vergadering, strikte - **Grote documenten**: Handles 500+ pagina's met hiërarchische verwerking - **Web ophalen**: Veiligheidsverharding (SSRF-bescherming, HTML-reiniging) - **Playwright-modus**: Hoofdloze browser voor JavaScript-rendered pagina's (SPA's, React apps) - **ONNX-inbeddingen**: Zero-config lokale inbeddingen - modellen automatisch downloaden bij eerste gebruik - **Kwaliteitsanalyse**: Hallucinatiedetectie, entiteit extractie - **Resilient LLM**: Polly-based retry met jitter backoff + stroomonderbreker - **Alleen lokaal**: Niets verlaat je machine ## Gebruiken als LLM-hulpmiddel De `tool` commando is speciaal ontworpen voor integratie met AI agenten, MCP servers en andere geautomatiseerde systemen. Het geeft gestructureerde JSON aan stdout met bewijs gegrond claims - perfect voor het bouwen van RAG pijpleidingen of agent tools. ### Basic Tool Usage ```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' ``` ### Gereedschapsuitvoerstructuur Het gereedschapscommando geeft gestructureerde JSON terug met evidence tracking: ```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" } } ``` ### Gereedschapsopdrachtopties ```bash docsummarizer tool [options] ``` Beschrijving van de optie |--------|-------|-------------| | `--url` | `-u` De URL om op te halen en samen te vatten | `--file` | `-f` Bestand om samen te vatten | `--query` | `-q` Optionele focus query | `--mode` | `-m` Summarization mode (Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative) | `--model` Te gebruiken Ollama model | `--config` | `-c` Configuratiebestandspad ### Belangrijkste ontwerpbeginselen - **Bewijsgrond**: Elke claim omvat `evidence` ID's verwijzen naar bronchunks - **Vertrouwensniveaus**: Vorderingen worden gewaardeerd `high`, `medium`, of `low` gebaseerd op bewijsmateriaal - **Schone uitvoer**: De `executive` samenvatting heeft geen aanhalingstekens voor eenvoudig display - **Metadata**: Processing stats help met debuggen en kwaliteitsbeoordeling - **Fout bij omgaan**: Failures return `success: false` met een `error` bericht ### Integratievoorbeelden **Python script:** ```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']}") ``` **Schelppijplijn:** ```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' ``` ## Snel starten ### Voorgebouwde binaire bestanden downloaden Voorgebouwde native executables zijn beschikbaar vanaf [GitHub releases](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer): Het Platform van de Architectuur Downloaden |----------|--------------|----------| Windows, x64 `docsummarizer-win-x64.zip` | Windows, ARM64 `docsummarizer-win-arm64.zip` | Linux, x64 `docsummarizer-linux-x64.tar.gz` | Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . `docsummarizer-linux-arm64.tar.gz` | MacOS x64 (Intel) `docsummarizer-osx-x64.tar.gz` | MacOS ARM64 (Apple Silicium) `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 "." ``` ### Vereisten #### Bert-modus (geen externe diensten) Voor pure winningscondensatie, **geen externe diensten vereist**: ```bash docsummarizer -f document.md -m Bert ``` ONNX modellen automatisch downloaden van HuggingFace bij eerste gebruik (~23MB). Returns in ~3-5 seconden. #### LLM-modi (Auto, BertRag, MapReduce, enz.) Voor LLM-aangedreven aggregatie is Ollama vereist: ```bash # Install Ollama from https://ollama.ai ollama pull llama3.2:3b # Default model - good balance of speed/quality ollama serve ``` > **Snelheidspunt**: Voor snellere samenvattingen (~3s vs ~15s), gebruik `--model qwen2.5:1.5b` #### Facultatief: Docling (Binaire Formaten) Vereist voor PDF, DOCX, XLSX, PPTX, HTML, afbeeldingen (PNG/JPG/TIFF), CSV, VTT, en AsciiDoc bestanden. **Markdown- en platte tekstbestanden worden direct gelezen - geen Docling vereist.** ```bash docker run -d -p 5001:5001 quay.io/docling-project/docling-serve ``` #### Optioneel: Qdrant (Permanente Vector Opslag) Standaard niet vereist - BertRag gebruikt in-geheugenvectoren. Schakel Qdrant in voor persistente opslag om het opnieuw invoegen van documenten te voorkomen bij volgende bewerkingen: ```bash docker run -d -p 6333:6333 -p 6334:6334 qdrant/qdrant ``` Vervolgens configureren in `docsummarizer.json`: ```json { "bertRag": { "vectorStore": "Qdrant", "collectionName": "docsummarizer", "persistVectors": true } } ``` #### Optioneel: Ollama Inbeddingen Als u Ollama verkiest voor inbeddingen in plaats van ONNX: ```bash ollama pull nomic-embed-text # Or mxbai-embed-large # Then use: --embedding-backend Ollama ``` ### Afhankelijkheden verifiëren ```bash docsummarizer check --verbose ``` Verwachte uitvoer toont een geformatteerde tabel: ``` 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. ``` > **Opmerking**: Docling en Qdrant tonen is prima voor alleen Markdown workflows. ## Gebruik ### Standaardgedrag Uitvoeren `docsummarizer` zonder argumenten: 1. Zoek naar `README.md` in de huidige map 2. Samenvat het met behulp van **Auto-modus** (slimme modusselectie) 3. Print de samenvatting naar console met een mooi paneel UI 4. Automatisch opslaan naar `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 ``` ### Basissamenvatting ```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 ``` ## Samenvattingsmodi Het gereedschap evolueerde van "just MapReduce" naar een volledige pijplijn. Hier is wat elke modus eigenlijk doet: ### Automatisch (standaard) Kies de juiste modus op basis van wat je vraagt. Gebruik dit tenzij je een reden hebt om dat niet te doen. ```bash docsummarizer -f doc.pdf ``` ### BertRag (productie) Dit is wat je wilt voor de productie. 1. **Uitpakken** - Ontleden van het document in segmenten, insluiten met BERT 2. **Ophalen** - Vind de relevante segmenten (semantisch zoeken + salience scoren) 3. **Synthesizer** - LLM schrijft een vloeiend overzicht van deze segmenten ```bash docsummarizer -f doc.pdf -m BertRag docsummarizer -f doc.pdf -m BertRag --focus "payment terms" ``` **Waarom gebruiken:** Elke claim spoort terug naar een bronsegment. Geen hallucinatie. Schaalt naar een documentgrootte. LLM draait alleen aan het einde (goedkoop). ### Bert (Snel, zonder LLM) Pure extractie met behulp van lokale ONNX-modellen. Helemaal geen LLM-oproep. ```bash docsummarizer -f doc.pdf -m Bert ``` **Waarom gebruiken:** Werkt offline. Geeft terug in ~3-5 seconden. Deterministisch (zelfde invoer = dezelfde uitvoer). Goed genoeg voor snelle scans. ### BertHybrid BERT extracten, LLM polijsten. Middengrond tussen Bert en BertRag. ```bash docsummarizer -f doc.pdf -m BertHybrid ``` ### KaartVerminderen / Rag / Iteratief De originele modi. Werkt nog steeds, maar BertRag verving ze voor de meeste use cases. - **Kaartverminderen**: Parallel brokken, goed voor 100% dekking - **Rag**: Vector zoeken, goed voor gerichte vragen (legacy - BertRag doet dit beter) - **Iteratief**: Sequentiële verwerking, alleen voor kleine documenten ```bash docsummarizer -f doc.pdf -m MapReduce # Full coverage docsummarizer -f doc.pdf -m Rag --focus "query" # Legacy focused mode ``` ### Zoekmodus Stel in plaats van een samenvatting vragen over een document: ```bash docsummarizer -f manual.pdf --query "How do I install the software?" ``` ### Web-URL ophalen Samengevat webpagina's direct zonder te downloaden: ```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 ``` **Ondersteunde inhoud**: HTML (geanimeerd), PDF, Markdown, afbeeldingen (OCR), Office documenten. Grote afbeeldingen automatisch verkleind. **Veiligheid**: SSRF bescherming, DNS rebinding bescherming, content-type leging, decompressie bom bescherming, HTML sanitization. **JavaScript-rendered pagina's**Gebruik `--web-mode Playwright` voor SPA's en React-apps (auto-installeert Chroom bij eerste gebruik). ### Gestructureerde modus Uitpakken machineleesbaar JSON in plaats van proza: ```bash docsummarizer -f document.pdf --structured -o Json ``` Extracten: entiteiten, functies, sleutelstromen, feiten (met betrouwbaarheidsniveaus), onzekerheden, quotable passages. ### Samenvattingsjablonen ```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 ``` Sjabloon Words Best For |----------|-------|----------| | `default` Uitgebalanceerde samenvatting met onderwerpen (2 alinea's) | `prose` Schoon multi-paragraf proza - geen metadata | `brief` Quality over Quantity (QoQ) Releases Quantity (QoQ) Releases Vertaling: | `oneliner` 25 samenvatting van één zin | `bullets` Auto Bullet point list (5-7 items) | `executive` . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . | `detailed` Uitgebreid met volledige onderwerpen | `technical` Technische documenten met implementatiedetails | `academic` Quality over Quantity (QoQ) Releases Vertaling: | `citations` Belangrijkste citaten met alleen bronaanhalingstekens | `bookreport` Boekverslag (setting, karakters, plot, thema's) | `meeting` Ontmoetingsnotities (besluiten, acties, vragen) | `strict` Token-efficiënt, 3 kogels max, geen deksel Alle beschikbare sjablonen met beschrijvingen bekijken: ```bash docsummarizer templates ``` ### Modelbenchmarking Vergelijk modellen op hetzelfde document met de `benchmark` subopdracht: ```bash docsummarizer benchmark -f doc.pdf -m "qwen2.5:1.5b,llama3.2:3b,ministral-3:3b" ``` Het benchmark commando ontleedt het document eenmaal en draait vervolgens elk model op dezelfde brokken voor een eerlijke vergelijking. Output toont timing, woordtelling en woorden/seconde voor elk model. ### Batchverwerking Bezig met het verwerken van volledige mappen: ```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 ``` ### Opties voor opdrachtregel Option Short Omschrijving Standaard |--------|-------|-------------|---------| | `--file` | `-f` Pad naar document (DOCX, PDF, MD) | `--directory` | `-d` Pad naar map voor batchverwerking - | `--url` | `-u` Web-URL om op te halen en samen te vatten | `--web-enabled` Inschakelen van web fetching (vereist voor --url) `false` | | `--mode` | `-m` Summarization mode: Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative `Auto` | | `--structured` | `-s` Gebruik gestructureerde JSON extractiemodus `false` | | `--focus` Focus query voor RVS-modus Geen | `--query` | `-q` Zoekmodus in plaats van verduistering Geen | `--model` Te gebruiken Ollama model `llama3.2:3b` | | `--verbose` | `-v` Toon gedetailleerde vooruitgang met live UI `false` | | `--config` | `-c` Pad naar configuratiebestand Auto-ontdekken | `--output-format` | `-o` Uitgangsformaat: Console, Text, Markdown, Json `Console` | | `--output-dir` Uitgangsmap voor bestandsuitvoer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . | `--extensions` | `-e` Bestandsextensies voor batch-modus Alle Docling-formaten | `--recursive` | `-r` Verloop directories recursief `false` | | `--template` | `-t` Samenvatting sjabloon (standaard, kort, kogels, uitvoerend, enz.) `default` | | `--words` | `-w` Aantal targetwoorden (overschrijft sjabloon) Sjabloon standaard | `--embedding-backend` Inbedding backend: Onnx, Ollama `Onnx` | | `--embedding-model` Naam van het ONNX-model (REG-modus) `AllMiniLmL6V2` | | `--web-mode` Web fetch mode: Eenvoudig, Playwright `Simple` | | `--analyze` | `-a` De kwaliteitsanalyse uitvoeren op samenvatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . `false` | ## Samenvattingsmodi ### KaartVerminderen (aanbevolen) Beste voor uitgebreide samenvattingen met volledige documentdekking. ```bash docsummarizer -f document.pdf -m MapReduce -v ``` **Hoe het werkt**: 1. Splits document in structurele stukken (per rubriek) 2. Samenvat elke brok parallel met LLM 3. Vermindert samenvattingen in samenvatting met aanhalingstekens 4. Valideert alle aanhalingen referentie echte brokken **Hiërarchische reductie voor lange documenten**: Voor zeer lange documenten waar de gecombineerde brok samenvattingen het contextvenster van het model overschrijden, maakt MapReduce automatisch gebruik van hiërarchische reductie: 1. **Loting**: Groepen samenvattingen in batches die passen in de context 2. **Tussentijdse verlaging**: Vermindert elke partij tot een gecondenseerde samenvatting 3. **Definitieve verlaging**: Samenvoegt tussentijdse samenvattingen in de uiteindelijke output 4. **Recursief**: Als tussenproducten zijn nog steeds te groot, voegt meer niveaus ``` 100 chunks → 100 summaries → 5 batches → 5 intermediate summaries → final ``` Dit behoudt volledige documentdekking, ongeacht de lengte - elke brok draagt bij aan de definitieve samenvatting. De tool schat tokens (~4 tekens/token) en targets 60% context venster gebruik per reductie pas. **Voordelen**: Snel, volledige dekking, parallelle verwerking, behandelt elke documentlengte **Cons**: Kan doorsnede verbindingen missen, langzamer voor zeer lange documenten ### RAG (Best for Focused Queries) Het beste als je je moet concentreren op specifieke onderwerpen of een gerichte vraag hebt. ```bash docsummarizer -f document.pdf -m Rag --focus "pricing and payment terms" -v ``` **Hoe het werkt**: 1. Indexeert document brokken als vector inbeddingen in Qdrant 2. Uittreksel van sleutelonderwerpen uit de documentrubrieken 3. Ophalen relevante brokken per onderwerp met behulp van semantische zoekopdracht 4. Synthesizers gerichte samenvatting met citaten **Wanneer moet u RAG over MapReduce gebruiken?**: Scenario Best Mode |----------|-----------| "Summarise this whole document" MapVerminderen "Wat zegt dit over beveiliging?" De handleiding van 500 pagina's heeft alles nodig.MapVerminderen (hiërarchisch) De handleiding van 500 pagina's heeft een specifieke sectie nodig. Snel resultaat nodig, Qdrant niet hebben KaartVerminderen RAG is **niet** over het omgaan met lange documenten - MapReduce behandelt dat met hiërarchische reductie. RAG is ongeveer **relevante filtering**: wanneer je 90% van een document wilt negeren en je wilt concentreren op wat belangrijk is voor je specifieke vraag. **Voordelen**: Topic-gericht, semantisch begrip, hergebruik index, sneller voor gerichte queries **Cons**: Kan inhoud missen buiten focusgebied, vereist Qdrant, langzamere initiële indexering ### Iteratief Beste voor narratieve documenten waar context sequentieel stroomt. ```bash docsummarizer -f story.pdf -m Iterative -v ``` **Waarschuwing**: Trager en kan de context verliezen op lange documenten (> 10 brokken). ## Grote documentgids ### De juiste modus kiezen Type document Doel Mode waarom |---------------|------|------|-----| Technische specificaties (50+ pagina's) Volledige samenvatting KaartVerminderen Volledige dekking Nieuw/Narratief Volledige samenvatting van de kaartVerminderen van de tijdscontext Legaal contract Volledige samenvatting KaartVerminderen Kan geen clausules missen Legal contract "Payment terms?" . . . . . Focus op specifieke sectie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . * API docs (200 pagina's) * "Hoe werkt auth?" * * Query specific topic * Onderzoekspapier Volledige samenvatting KaartVerminderen Gestructureerd, alles nodig ### Fictie vs. non-fictie Content Type Best Mode Notes |--------------|-----------|-------| | **Fictie/Narratief** KaartVerminderen Plot vereist sequentiële context | **Technische documenten** MapVerminderen voor overzicht, repareren voor specifieke gegevens | **Juridische zaken/Contracten** KaartVerminderen Elke clausule is van belang | **Handleidingen** Meestal quering voor specifieke gegevens ### Prestaties Documentgrootte KaartVerminderen Notities |---------------|-----------|-----|-------| 10 pagina's 15's 20's beide snel 50 pagina's . 45s . 30s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 pagina's . 3-5 min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500+ pagina's 10-15 min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ## Configuratie ### Standaardconfiguratie aanmaken ```bash docsummarizer config --output myconfig.json ``` ### Configuratiebestand Configuratie wordt automatisch ontdekt van: 1. `--config` optie 2. `docsummarizer.json` in huidige map 3. `.docsummarizer.json` (verborgen bestand) 4. `~/.docsummarizer.json` (gebruiker thuis) Voorbeeld `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 } } ``` ### Verwerkingsopties Option Standaard Beschrijving |--------|---------|-------------| | `maxLlmParallelism` 8 . . . . . . LLM verzoeken (Ollama wachtrijen, dus hogere waarden gewoon wachtrij) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . | `maxHeadingLevel` Gespleten op H1/H2 alleen. Zet op 3 voor fijnere korreligheid | `targetChunkTokens` 0 (auto) Doelblokgrootte. 0 = automatisch berekenen (~25% van het contextvenster) | `minChunkTokens` Minstens 0 (auto) voor de fusie. 0 = 1/8 van het doel ## Uitvoerformaat ### Samenvatting van de structuur ```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-metrics**: Dekking (% secties inbegrepen), Citation rate (citaties/bullet), Chunks verwerkt (RAG kan sommige overslaan). ## Modelaanbevelingen Model Grootte Snelheid Kwaliteit Gebruikscase |-------|------|-------|---------|----------| | `qwen2.5:1.5b` Erg snel (~3s) Goede snelheid geoptimaliseerd | `gemma3:1b` Fast (~10s) Fair (~10s) Alternatief klein model | `llama3.2:3b` 2GB Medium (~15s) Very Good **Standaard** - goed evenwicht | `ministral-3:3b` 2,9GB Medium (~20s) Very Good, Quality-focused | `llama3.1:8b` Quality over Quantity (QoQ) Releases Vertaling: > **Tip**: Voor snellere samenvattingen (~3s vs ~15s), gebruik `--model qwen2.5:1.5b`. Voor kritische documenten waar kwaliteit belangrijker is, gebruik `--model llama3.1:8b`. ## Bouwen van bron ```bash # Clone the repository git clone https://github.com/scottgal/mostlylucidweb.git cd mostlylucidweb/Mostlylucid.DocSummarizer # Build dotnet build # Run dotnet run -- --help ``` ### Zelfingebouwde gebouwen Voor productie-implementatie zonder .NET runtime installatie: ```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 ``` Uitvoer: `bin/Release/net9.0//publish/docsummarizer` ## Problemen oplossen ### "Kan geen verbinding maken met Ollama" - Zorg ervoor dat Ollama draait: `ollama serve` - Check modellen worden getrokken: `ollama list` ### "Docling service niet beschikbaar" - Dit is **alleen nodig voor PDF/DOCX-bestanden** - Voor Markdown-bestanden kunt u deze fout negeren - Te repareren: `docker run -p 5001:5001 quay.io/docling-project/docling-serve` ### "Qdrant-verbinding mislukt" - Dit is **alleen vereist voor de RAG-modus** (`--mode Rag`) - Voor MapReduce-modus (standaard), kunt u deze fout negeren - Te repareren: `docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant` ### "Circuit breaker is open" - Ollama is overbelast of is gecrasht - Wacht 30 seconden voor de stroomonderbreker om te resetten, of herstart Ollama - De tool maakt gebruik van Polly veerkracht beleid en zal auto-retry ### "wsarecv" of verbindingsfouten (Windows) - Dit is een bekend Ollama probleem op Windows (GitHub #13340) - Het gereedschap auto-handelt dit met retry logica en verbinding herstel - Herstart Ollama en probeer het opnieuw. ### "LLM generation timed out" - Verhoog timeout in configuratie - Zeer grote documenten splitsen - Controleer of Ollama niet overbelast is met andere verzoeken ### Repetitieve of lage kwaliteit samenvattingen **Symptomen**: Bullet points echo de prompt ("Return only bullet points," "The rule is...") in plaats van samenvatting van de inhoud. **Oorzaak**: Model worstelt met de prompt of inhoud te lang. **Repareren**: De standaard `qwen2.5:1.5b` behandelt de meeste documenten goed. Voor problematische documenten, probeer `--model llama3.2:3b`. Zie [Modelaanbevelingen](#model-recommendations). ### Samenvatting De inhoud van het document negeren Als de samenvatting generiek lijkt of niet naar specifieke inhoud verwijst: - Het model kan hallucineren - controleren `Citation rate` in trace-uitvoer - RAG-modus proberen (`--mode Rag`) die samenvattingen in opgehaalde stukken rechtvaardigt - Gebruik `--verbose` om te zien welke brokken worden verwerkt ### Verwijzingen ontbreken of zijn ongeldig Indien samenvattingen ontbreken `[chunk-N]` aanhalingstekens: - Kleine modellen prioriteren inhoud boven citaatopmaak - De prompts zijn geoptimaliseerd voor snelheid, niet strikte citaat compliance - Voor strikte aanhalingstekens, gebruik grotere modellen zoals `llama3.2:3b` - Controleren `Citation rate` in spoor - hogere waarden wijzen op een betere traceerbaarheid ## Prestatietips - **Kaartverminderen** voor snelheid (parallelle brokken) - **`qwen2.5:1.5b`** voor snelheid, **`llama3.2:3b`** voor evenwicht, **`llama3.1:8b`** voor kwaliteit - **ONNX-inbeddingen** (standaard) zijn sneller dan Ollama voor RAG-modus - Lager **`maxLlmParallelism`** als er sprake is van time-outs ## Middelen - [Broncode](https://github.com/scottgal/mostlylucidweb/tree/main/Mostlylucid.DocSummarizer) - [GitHub releases](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer) - [Aankoppelen](https://github.com/docling-project/docling) / [Doclingserver](https://github.com/docling-project/docling-serve) - [Qdrant](https://qdrant.tech/) - Lokale vectordatabase - [Ollama](https://ollama.ai/) / [OllamaSharp](https://github.com/awaescher/OllamaSharp) - [Polly](https://github.com/App-vNext/Polly) - .NET veerkracht en transiënt-fout-afhandeling - [Spectre.console](https://spectreconsole.net/) - Mooie terminal UI ## Serienavigatie - **[Deel 1: Het bouwen van een Document Summarizer met RAG](/blog/building-a-document-summarizer-with-rag)** - De architectuur en patronen - **[Deel 2: Gebruik van het gereedschap](/blog/docsummarizer-tool)** (dit artikel) - Snelstartgids - **[Deel 3: Geavanceerde concepten](/blog/docsummarizer-advanced-concepts)** - Diepe duik in BERT, ONNX, inbeddingen, en hybride zoekopdracht ### Gerelateerd - [CSV-analyse met lokale LLM's](/blog/analysing-large-csv-files-with-local-llms) - [Webcontent met LLM's](/blog/fetching-and-analysing-web-content-with-llms)