DocSummarizer Deel 2 - Het gebruik van het gereedschap

Sunday, 21 December 2025

Dit is Deel 2 van de DocSummarizer serie. Zie Deel 1 voor de architectuur en patronen, of Deel 3 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.

# 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. Voor hoe het intern werkt, zie Deel 3.

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

# 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:

{
  "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

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:

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:

# 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:

Het Platform van de Architectuur Downloaden

----------	--------------	----------
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`

# 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:

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:

# 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.

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:

docker run -d -p 6333:6333 -p 6334:6334 qdrant/qdrant

Vervolgens configureren in docsummarizer.json:

{
  "bertRag": {
    "vectorStore": "Qdrant",
    "collectionName": "docsummarizer",
    "persistVectors": true
  }
}

Optioneel: Ollama Inbeddingen

Als u Ollama verkiest voor inbeddingen in plaats van ONNX:

ollama pull nomic-embed-text   # Or mxbai-embed-large
# Then use: --embedding-backend Ollama

Afhankelijkheden verifiëren

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:

Zoek naar README.md in de huidige map
Samenvat het met behulp van Auto-modus (slimme modusselectie)
Print de samenvatting naar console met een mooi paneel UI
Automatisch opslaan naar readme.summary.md

# 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

# 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.

docsummarizer -f doc.pdf

BertRag (productie)

Dit is wat je wilt voor de productie.

Uitpakken - Ontleden van het document in segmenten, insluiten met BERT
Ophalen - Vind de relevante segmenten (semantisch zoeken + salience scoren)
Synthesizer - LLM schrijft een vloeiend overzicht van deze segmenten

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.

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.

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

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:

docsummarizer -f manual.pdf --query "How do I install the software?"

Web-URL ophalen

Samengevat webpagina's direct zonder te downloaden:

# 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'sGebruik --web-mode Playwright voor SPA's en React-apps (auto-installeert Chroom bij eerste gebruik).

Gestructureerde modus

Uitpakken machineleesbaar JSON in plaats van proza:

docsummarizer -f document.pdf --structured -o Json

Extracten: entiteiten, functies, sleutelstromen, feiten (met betrouwbaarheidsniveaus), onzekerheden, quotable passages.

Samenvattingsjablonen

# 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:

docsummarizer templates

Modelbenchmarking

Vergelijk modellen op hetzelfde document met de benchmark subopdracht:

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:

# 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

--web-mode Web fetch mode: Eenvoudig, Playwright Simple

--analyze -a De kwaliteitsanalyse uitvoeren op samenvatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . false

`--embedding-backend` Inbedding backend: Onnx, Ollama `Onnx`
`--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.

docsummarizer -f document.pdf -m MapReduce -v

Hoe het werkt:

Splits document in structurele stukken (per rubriek)
Samenvat elke brok parallel met LLM
Vermindert samenvattingen in samenvatting met aanhalingstekens
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:

Loting: Groepen samenvattingen in batches die passen in de context
Tussentijdse verlaging: Vermindert elke partij tot een gecondenseerde samenvatting
Definitieve verlaging: Samenvoegt tussentijdse samenvattingen in de uiteindelijke output
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.

docsummarizer -f document.pdf -m Rag --focus "pricing and payment terms" -v

Hoe het werkt:

Indexeert document brokken als vector inbeddingen in Qdrant
Uittreksel van sleutelonderwerpen uit de documentrubrieken
Ophalen relevante brokken per onderwerp met behulp van semantische zoekopdracht
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.

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

docsummarizer config --output myconfig.json

Configuratiebestand

Configuratie wordt automatisch ontdekt van:

--config optie
docsummarizer.json in huidige map
.docsummarizer.json (verborgen bestand)
~/.docsummarizer.json (gebruiker thuis)

Voorbeeld docsummarizer.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

## 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

# 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:

# 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/<runtime>/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.

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
GitHub releases
Aankoppelen / Doclingserver
Qdrant - Lokale vectordatabase
Ollama / OllamaSharp
Polly - .NET veerkracht en transiënt-fout-afhandeling
Spectre.console - Mooie terminal UI

Serienavigatie

Deel 1: Het bouwen van een Document Summarizer met RAG - De architectuur en patronen
Deel 2: Gebruik van het gereedschap (dit artikel) - Snelstartgids
Deel 3: Geavanceerde concepten - Diepe duik in BERT, ONNX, inbeddingen, en hybride zoekopdracht

DocSummarizer Deel 2 - Het gebruik van het gereedschap

Waarom dit bestaat

Functies

Gebruiken als LLM-hulpmiddel

Basic Tool Usage

Gereedschapsuitvoerstructuur

Gereedschapsopdrachtopties

Belangrijkste ontwerpbeginselen

Integratievoorbeelden

Snel starten

Voorgebouwde binaire bestanden downloaden

Vereisten

Bert-modus (geen externe diensten)

LLM-modi (Auto, BertRag, MapReduce, enz.)

Facultatief: Docling (Binaire Formaten)

Optioneel: Qdrant (Permanente Vector Opslag)

Optioneel: Ollama Inbeddingen

Afhankelijkheden verifiëren

Gebruik

Standaardgedrag

Basissamenvatting

Samenvattingsmodi

Automatisch (standaard)

BertRag (productie)

Bert (Snel, zonder LLM)

BertHybrid

KaartVerminderen / Rag / Iteratief

Zoekmodus

Web-URL ophalen

Gestructureerde modus

Samenvattingsjablonen

Modelbenchmarking

Batchverwerking

Opties voor opdrachtregel

Samenvattingsmodi

KaartVerminderen (aanbevolen)

RAG (Best for Focused Queries)

Iteratief

Grote documentgids

De juiste modus kiezen

Fictie vs. non-fictie

Prestaties

Configuratie

Standaardconfiguratie aanmaken

Configuratiebestand

Verwerkingsopties

Uitvoerformaat

Samenvatting van de structuur

Modelaanbevelingen

Bouwen van bron

Zelfingebouwde gebouwen

Problemen oplossen

"Kan geen verbinding maken met Ollama"

"Docling service niet beschikbaar"

"Qdrant-verbinding mislukt"

"Circuit breaker is open"

"wsarecv" of verbindingsfouten (Windows)

"LLM generation timed out"

Repetitieve of lage kwaliteit samenvattingen

Samenvatting De inhoud van het document negeren

Verwijzingen ontbreken of zijn ongeldig

Prestatietips

Middelen

Serienavigatie

Gerelateerd