# DocSummarizer Osa 2 - Työkalun käyttö

<!--category-- AI, LLM, RAG, C#, Docling, Ollama, Qdrant, Tools -->
<datetime class="hidden">2025-12-21T11:00</datetime>

[![GitHub-julkaisu](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/)
[![Malli](https://img.shields.io/badge/version-3.1.0-blue)](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer)

Tämä on **2 osa** DocSummarizer -sarjasta. Ks. [Osa 1](/blog/building-a-document-summarizer-with-rag) arkkitehtuurin ja kuvioiden osalta, tai [3 osa](/blog/docsummarizer-advanced-concepts) Syvän teknisen sukelluksen ja haun vuoksi.

> **Muuta dokumentit tai URL-osoitteet todisteisiin pohjautuviksi tiivistelmiksi - ihmisille tai tekoälyagenteille - lähettämättä mitään pilveen.**

Jokainen väite on jäljitettävissä, ja jokainen fakta viittaa sen lähteeseen.

```bash
# Human-readable summary
docsummarizer -f contract.pdf

# JSON for agents/pipelines
docsummarizer tool -u "https://docs.example.com"
```

**Mitä tämä artikkeli kattaa**: Asennus, avaintilat (Auto/BertRag/Bert), mallit ja tavalliset käyttötavat.

**Mitä se ei peitä**: Täyden komennon viitetiedot, asetusasetukset, vianetsintä, arkkitehtuurin yksityiskohdat.

Katso täydelliset asiakirja-aineistot [KIRJEENVAIHTO](https://github.com/scottgal/mostlylucidweb/blob/main/Mostlylucid.DocSummarizer/README.md). Katso, miten se toimii sisäisesti [3 osa](/blog/docsummarizer-advanced-concepts).

[TOC]

## Miksi tämä on olemassa

Suurin osa tiivistelijöistä antaa sinulle tekstiviestejä. *näyttöä*.

- **Jokainen vaatimus sisältää `[chunk-N]` Lainaukset** takaisin lähdeaineistoon
- **Luottamustasot** (korkea/keski-/alhainen) perustuu näyttöön
- **Strukturoitu JSON-lähtö** agenttien integrointiin, CI-putkistoihin tai MCP-palvelimiin
- **Laatumittarit** nappaa hallusinaatioita ennen kuin ne karkaavat

Jos on tarpeen *luottamus* yhteenveto - tai syötä se toiseen järjestelmään - jolla on merkitystä.

## Ominaisuudet

- **BertRag putkijohto**: Tuotantoluokka BERT-louhinta → recovery → LLM-synteesi
- **Automaattinen tila**: Älytilan valinta perustuu asiakirjaan ja kyselyyn
- **Bert-moodi**: Puhdas kaivannaistiivistys - ei LLM tarvitaan, toimii offline (~3-5s)
- **Näyttöjen pyöristämä tuotos**: Lainaukset, luottamusluvut, jäljitettävissä olevat väitteet
- **Useita tiloja**: Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative
- **Työkalutila**: Puhdas JSON LLM-agenteille, MCP-palvelimille, CI-tarkastuksille
- **13 mallit**: oletus, proosa, lyhyt, oneliner, luodit, johtaja, yksityiskohtainen, tekninen, akateeminen, lainaukset, kirjaraportti, kokous, tiukka
- **Suuria asiakirjoja**: Käsittelee 500+ sivua hierarkkisella käsittelyllä
- **Web-haku**: Turvallisuuskarkaistu (SSRF-suojaus, HTML-puhdistus)
- **Näytelmätila**: Headless-selain Javascript-renderoiduille sivuille (SPAs, React apps)
- **ONNX-kytkennät**: Zero-config paikalliset upotukset - mallit lataavat automaattisesti ensimmäisellä käyttökerralla
- **Laatuanalyysi**: Hallusinaatioiden havaitseminen, entiteettien poimiminen
- **Kestävä LLM**: Polly-pohjainen uudelleenryntäys + virtapiirin katkaisin
- **Vain paikallinen**Mikään ei jätä konettasi

## LLM-työkaluna

Erytropoietiini `tool` Komento on suunniteltu erityisesti tekoälyagenteille, MCP-palvelimille ja muille automatisoiduille järjestelmille. Se tuottaa JSON:n strukturoitua todisteisiin perustuvia väitteitä, jotka sopivat erinomaisesti RAG-putkien tai agenttityökalujen rakentamiseen.

### Perustyökalun käyttö

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

### Työkalun ulostulorakenne

Työkalun komento palauttaa JSON:n strukturoidun näytön avulla:

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

### Työkalun komentoasetukset

```bash
docsummarizer tool [options]
```

Vaihtoehto Lyhyt kuvaus
|--------|-------|-------------|
| `--url` | `-u` URL noutaa ja tiivistää
| `--file` | `-f` Yhteenvetona esitettävä tiedosto
| `--query` | `-q` Valinnainen tarkennuskysely
| `--mode` | `-m` Yhteenvetotila (Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative)
| `--model` Ollama-mallia käytetään
| `--config` | `-c` Asetukset- tiedostopolku

### Tärkeimmät suunnitteluperiaatteet

- **Todisteiden pohjana**: Jokainen vaatimus sisältää `evidence` Lähteen osiin viittaavat tunnisteet
- **Luottamustasot**: Saamiset luokitellaan `high`, `medium`, tai `low` perustuen todisteisiin
- **Puhdas tulostus**: `executive` Yhteenvedossa ei ole merkintämerkkejä helppoon näyttöön
- **Metatiedot**: Tilastojen käsittely auttaa vianetsintään ja laadun arviointiin
- **Virheiden käsittely**: Epäonnistumiset palaavat `success: false` jossa on `error` Taloussanomat

### Integrointiesimerkkejä

**Python-skripti:**

```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']}")
```

**Kuormaputki:**

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

## Pikakäynnistys

### Lataa valmiiksi rakennetut binäärit

Esirakennetut natiivit ovat saatavilla osoitteesta [GitHubledget](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer):

Alusta Arkkitehtuuri Lataa
|----------|--------------|----------|
Ikkunat x64 `docsummarizer-win-x64.zip` |
Ikkunat ARM64 `docsummarizer-win-arm64.zip` |
Linux x64 `docsummarizer-linux-x64.tar.gz` |
Linux ARM64 `docsummarizer-linux-arm64.tar.gz` |
X64 (puheenjohtajuus) `docsummarizer-osx-x64.tar.gz` |
ARM64 (Apple Pii) `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 "."
```

### Edeltävät opinnot

#### Bert Mode (ei ulkoisia palveluja)

Puhdasta kaivannaistiivistelmää varten **ulkoisia palveluja ei tarvita**:

```bash
docsummarizer -f document.md -m Bert
```

ONNX-mallit lataavat automaattisesti HuggingFacen ensimmäisellä käyttökerralla (~23MB). Palautuu ~3-5 sekunnissa.

#### LLM-tilat (Auto, BertRag, MapReduce jne.)

LLM-käyttöiseen summarointiin tarvitaan Ollamaa:

```bash
# Install Ollama from https://ollama.ai
ollama pull llama3.2:3b        # Default model - good balance of speed/quality
ollama serve
```

> **Nopeuden kärki**: Nopeampiin tiivistelmiin (~3s vs ~15s) `--model qwen2.5:1.5b`

#### Valinnainen: Docling (Binary Formats)

Vaaditaan PDF-, DOCX-, XLSX-, PPTX-, HTML-, kuvat (PNG/JPG/TIF), CSV-, VTT- ja AsciiDoc-tiedostot. **Markdown ja tavalliset tekstitiedostot luetaan suoraan - Doclingia ei tarvita.**

```bash
docker run -d -p 5001:5001 quay.io/docling-project/docling-serve
```

#### Valinnainen: Qdrant (Persistent Vector Storage)

Ei vaadita oletuksena - BertRag käyttää muistivektoreita. Ota Qdrant käyttöön jatkuvassa tallennuksessa, jotta voit välttää asiakirjojen uudelleen upottamisen seuraavilla kierroksilla:

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

Määrittele sitten `docsummarizer.json`:

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

#### Valinnainen: Ollaman upotukset

Jos suosit Ollamaa ONNX:n sijaan upotuksina:

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

### Varmista riippuvuussuhteet

```bash
docsummarizer check --verbose
```

Odotetussa tuotoksessa on kaavailtu taulukko:

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

> **Huomautus**: Docling ja Qdrant näyttävät vain Markdown-työnkulkuja.

## Käyttö

### Oletuskäyttäytyminen

Suoritetaan `docsummarizer` ilman perusteluja:

1. Etsi `README.md` nykyisessä hakemistossa
2. Tiivistä se **Automaattinen tila** (älykäs tilavalinta)
3. Tulosta yhteenveto konsoliin mukavalla paneelilla UI
4. Automaattitallennus `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
```

### Perustiivistelmä

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

## Yhteenvetotila

Työkalu kehittyi "just MapReducesta" täyteen putkeen. Kukin tila tekee näin:

### Automaattinen (default)

Valitse oikea tila sen perusteella, mitä pyydät. Käytä tätä, ellei sinulla ole syytä olla kysymättä.

```bash
docsummarizer -f doc.pdf
```

### BertRag (Tuotanto)

Tätä te haluatte tuotannolle, kolmivaiheista putkistoa:

1. **Ote** - Jaa asiakirja segmenteiksi, upota ne BERTiin
2. **Hae** - Etsi merkitykselliset segmentit (semanttinen haku + salienssipisteytys)
3. **Synteettikoko** - LLM kirjoittaa sujuvan tiivistelmän näistä segmenteistä

```bash
docsummarizer -f doc.pdf -m BertRag
docsummarizer -f doc.pdf -m BertRag --focus "payment terms"
```

**Miksi käyttää sitä:** Jokainen väite on peräisin lähdesegmentistä. Ei hallusinaatioita. Skaalaa minkä tahansa asiakirjakoon. LLM kulkee vain lopussa (halpa).

### Bert (Fast, No LLM)

Puhdasta poimintaa paikallisten ONNX-mallien avulla. Ei LLM-puhelua lainkaan.

```bash
docsummarizer -f doc.pdf -m Bert
```

**Miksi käyttää sitä:** Toimii offline-tilassa. Palautuu ~3-5 sekunnissa. Deterministinen (sama tulo = sama lähtö). Tarpeeksi hyvä nopeisiin skannauksiin.

### BertHybrid

BERT-uutteita, LLM-kiillokkeita. Bertin ja BertRagin keskikenttä.

```bash
docsummarizer -f doc.pdf -m BertHybrid
```

### MapReduce / Rag / Iterative

Alkuperäiset tilat toimivat yhä, mutta BertRag korvasi ne useimpiin käyttökohteisiin.

- **MapReduce**: Rinnakkainen paloittelu, hyvä 100-prosenttiseen kattavuuteen
- **Rag**: Vektorihaku, hyvä tarkennetuille kyselyille (perintö - BertRag tekee tämän paremmin)
- **Iteratiivinen**: Sekventiaalinen käsittely, vain pienissä dokumenteissa

```bash
docsummarizer -f doc.pdf -m MapReduce  # Full coverage
docsummarizer -f doc.pdf -m Rag --focus "query"  # Legacy focused mode
```

### Kyselytila

Sen sijaan, että tekisit yhteenvedon, esitä kysymyksiä asiakirjasta:

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

### Verkko-osoitteen haku

Tiivistä verkkosivut suoraan lataamatta:

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

**Tuettu sisältö**: HTML (sopeutettu), PDF, Markdown, kuvat (OCR), Office-dokumentit. Suuret kuvat kokoavat automaattisesti.

**Turvallisuus**: SSRF-suojaus, DNS:n uudelleensitomissuojaus, sisällön tyyppisuutin, paineistuksen purkupommisuojaus, HTML-puhdistus.

**Javascript-renderöidyt sivut**: Käyttö `--web-mode Playwright` SPA- ja React-sovelluksiin (auto-asennus Chromiumia ensimmäisen käyttökerran aikana).

### Strukturoitu tila

Ottaa koneella luettava JSON proosan sijaan:

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

Otteita: kokonaisuuksia, toimintoja, avainvirtoja, faktoja (luottamuksellisesti), epävarmuustekijöitä, kiintiöitä.

### Yhteenveto mallit

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

Template Sanat paras
|----------|-------|----------|
| `default` Tasapainoinen yhteenveto aiheittain (2 kappaletta)
| `prose` ~400 Puhdas moniosainen proosa - ei metatietoa
| `brief` ~50 Quick 2-3 lauseen yhteenveto
| `oneliner` "Yhden lauseen yhteenveto"
| `bullets` Auto Bullet Point -lista (5-7 kappaletta)
| `executive` ~150 Johtokunnan tiedotustilaisuus suosituksineen
| `detailed` Kokonaisvaltainen ja kattava aihepiiri
| `technical` ~350 Tekniset dokumentit ja täytäntöönpanotiedot
| `academic` Akateeminen abstrakti muoto
| `citations` Avainlainaukset, joissa on vain lähdeviittauksia
| `bookreport` Kirjan raportti (asetus, hahmot, juoni, teemat)
| `meeting` Kokouksen muistiinpanot (päätökset, toimet, kysymykset)
| `strict` Token-tehokas, enintään 3 luotia, ei suojausta

Katsoaksesi kaikki saatavilla olevat mallit ja kuvaukset:

```bash
docsummarizer templates
```

### Mallin vertailuanalyysi

Vertaa malleja samaan asiakirjaan käyttäen `benchmark` Alakomento:

```bash
docsummarizer benchmark -f doc.pdf -m "qwen2.5:1.5b,llama3.2:3b,ministral-3:3b"
```

Vertailukomento jäsentää asiakirjan kerran ja pyörittää sen jälkeen kutakin mallia samoilla kappaleilla tasapuolista vertailua varten. Tuotos näyttää kunkin mallin ajoituksen, sananlaskun ja sanat/sekunnin.

### Erän käsittely

Käsitellään kokonaiset hakemistot:

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

### Komentolinjan valinnat

Vaihtoehto Lyhyt kuvaus Oletus
|--------|-------|-------------|---------|
| `--file` | `-f` Polku dokumenttiin (DOCX, PDF, MD)
| `--directory` | `-d` Polku hakemistoon eräkäsittelyä varten
| `--url` | `-u` Verkko-osoitteen noutaminen ja tiivistäminen
| `--web-enabled` Ota käyttöön web nouto (tarvitaan --url) `false` |
| `--mode` | `-m` Yhteenvetotila: Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iteratiivinen. `Auto` |
| `--structured` | `-s` Käytä strukturoitua JSON-poistamistilaa `false` |
| `--focus` Focus query for RAG mode None
| `--query` | `-q` Query-tila yhteenvetojen sijaan Ei yhtään
| `--model` Ollama-mallia käytetään `llama3.2:3b` |
| `--verbose` | `-v` Näytä yksityiskohtaiset tiedot live UI:n kanssa `false` |
| `--config` | `-c` Path to configuration file â € Auto-device â €
| `--output-format` | `-o` Tulostusmuoto: Consol, Text, Markdown, Json `Console` |
| `--output-dir` Output-hakemisto tiedostotuloksille Current dir
| `--extensions` | `-e` Tiedoston laajennukset erätilalle Kaikki Docling-formaatit
| `--recursive` | `-r` Prosessihakemistot rekursiivisesti `false` |
| `--template` | `-t` Yhteenvetomalli (oletus, lyhyt kuvaus, luodit, toimeenpanovalta jne.) `default` |
| `--words` | `-w` Kohteen sanaluku (yliviivataan malli) Mallin oletus

| `--embedding-backend` Upotettava taustaosa: Onnx, Ollama `Onnx` |
| `--embedding-model` ONNX-mallin nimi (RAG-tila) `AllMiniLmL6V2` |
| `--web-mode` Web noutotila: yksinkertainen, näytelmäkirjailija `Simple` |
| `--analyze` | `-a` Run laatuanalyysi tiivistelmästä `false` |

## Yhteenvetotila

### MapReduce (suositeltu)

Paras kattava yhteenveto täydellisestä asiakirjakattauksesta.

```bash
docsummarizer -f document.pdf -m MapReduce -v
```

**Miten se toimii?**:

1. Jaa asiakirjan rakenneosiksi (otsikoiden mukaan)
2. Tiivistää jokaisen palan rinnakkain LLM:n avulla
3. Vähentää yhteenvetoja tiivistelmään viitaten
4. Validoidaan kaikki viittaukset referenssikappaleisiin

**Hierarkinen vähennys pitkiin asiakirjoihin**:

MapReduce käyttää automaattisesti hierarkkista vähennystä erittäin pitkissä asiakirjoissa, joissa koostetut koosteet ylittävät mallin kontekstiikkunan:

1. **Leikkaus**: Ryhmien yhteenvedot asiayhteyteen sopiviksi eriksi
2. **Väliaikainen vähennys**: Pienentää jokaisen erän tiivistetyksi tiivistelmäksi
3. **Lopullinen vähennys**: Yhdistää välipäätelmät lopulliseen tuotokseen
4. **Rekursiivinen**: Jos välituotteet ovat vielä liian suuria, lisää tasoja

```
100 chunks → 100 summaries → 5 batches → 5 intermediate summaries → final
```

Tämä säilyttää täydellisen asiakirjasisällön pituudesta riippumatta - jokainen osa on mukana lopullisessa yhteenvedossa. Työkalu arvioi rahakkeet (~4 chars/token) ja tähtää 60 prosentin konteksti-ikkunan käyttöön päästövähennystä kohden.

**Plussat**: Nopea, täydellinen kattavuus, rinnakkaiskäsittely, käsittelee minkä tahansa asiakirjan pituuden
**Miinukset**: Voi jäädä väliin poikkileikkauskytkennät, hitaampi hyvin pitkille dokumenteille

### RAG (Best for Focused Questions)

Paras, kun pitää keskittyä tiettyihin aiheisiin tai esittää kohdennettu kysymys.

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

**Miten se toimii?**:

1. Indeksit asiakirjan palasina vektorin upotuksina Qdrantissa
2. Ottaa avainaiheita asiakirjan otsikoista
3. Haetaan relevantteja kappaleita aiheittain semanttisella haulla
4. Synthesions focused tiivistelmä ja lainaukset

**Milloin voit käyttää RAG:tä MapReducen kautta**:

Parhaan toimintatavan skenaario
|----------|-----------|
"Summaroi koko tämä asiakirja" Kartan vähentäminen
"Mitä tämä kertoo turvallisuudesta?"
500-sivuinen ohjekirja, joka tarvitsee kaiken karttareduktion (hierarkkisen)
500-sivuinen ohjekirja, tarvitsee erityisosan RAG-suuntaviivat
Tarvitaan nopeita tuloksia, ei ole Qdrant karttaa.

LAAJENTUMINEN **ei** pitkien asiakirjojen käsittelystä - MapReduce käsittelee sitä hierarkkisella vähennyksellä. **relevanssisuodatus**: kun haluat jättää huomiotta 90 prosenttia asiakirjasta ja keskittyä siihen, mikä on erityiskysymyksessäsi tärkeää.

**Plussat**: Aihepainotteinen, semanttinen ymmärtäminen, uudelleenkäyttöindeksi, nopeammin tarkennetuissa kyselyissä
**Miinukset**: Saattaa jättää sisällön pois kohderyhmän ulkopuolelta, vaatii Qdrantin, hitaamman alustavan indeksoinnin

### Iteratiivinen

Paras kerronta-asiakirjoille, joissa konteksti virtaa peräkkäin.

```bash
docsummarizer -f story.pdf -m Iterative -v
```

**Varoitus**: Hidasta ja voi menettää asiayhteyden pitkiin asiakirjoihin (> 10 kappaletta).

## Suuri asiakirjaopas

### Oikean tilan valitseminen

Asiakirjan tyyppi Tavoite Mode Miksi?
|---------------|------|------|-----|
Tekniset tiedot (50+ sivua) Koko yhteenveto Kartta Vähennä täydellistä kattavuutta
Uusi/Narratiivinen Yhteenveto Kartta Vähentää tarvetta ajalliseen kontekstiin
Oikeudellinen sopimus Täysi yhteenveto Kartta Vähennetään lausekkeita
Oikeudellinen sopimus "Maksuehdot", "RAG" Keskittykää erityiseen osioon
API-dokumentit (200 sivua) "Miten autth toimii?"
Tutkimuspaperi Koko yhteenveto KarttaRakennettu, tarvitaan kaikki

### Fiktio vs. ei-fiktio

Sisällön tyyppi Paras tila Notes
|--------------|-----------|-------|
| **Fiktio/Luonnollinen** MapReduce Tontti vaatii peräkkäistä kontekstia
| **Tekniset dokumentit** Kartan vähentäminen yleiskatsausta varten, aluetukisuuntaviivojen tarkentaminen
| **Oikeudelliset/Sopimukset** Kartan vähentäminen Jokaisella lausekkeella on merkitystä
| **Manuaalit** LAAG-ALUEET Yleensä kysellään yksityiskohtia

### Suorituskyky

Asiakirjan koko KarttaLyhennä aluekarttaa Huomautukset
|---------------|-----------|-----|-------|
10 sivua 15 sivua 20 sivua molemmat nopeasti
50 sivua 45 sivua 30 sivua
200 sivua 3-5 min 1-2 min Hierarkkinen vähennys
500+ sivua 10-15 min 2-3 min Harkitkaa useita RAG-kyselyitä

## Asetukset

### Luo oletusasetukset

```bash
docsummarizer config --output myconfig.json
```

### Asetukset-tiedosto

Asetukset löytyvät automaattisesti:

1. `--config` vaihtoehto
2. `docsummarizer.json` nykyisessä hakemistossa
3. `.docsummarizer.json` (piilotettu tiedosto)
4. `~/.docsummarizer.json` (käyttäjäkoti)

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

### Käsittelyasetukset

Vaihtoehto Oletus Kuvaus
|--------|---------|-------------|
| `maxLlmParallelism` 8 Yhtäaikaiset LLM-pyynnöt (Ollama jonottaa, joten korkeammat arvot vain jonottavat)
| `maxHeadingLevel` Jakaudu vain H1/H2:een. Aseta kolmeen, jos haluat olla rakeisempi.
| `targetChunkTokens` 0 = automaattinen laskenta (noin 25 % konteksti-ikkunasta)
| `minChunkTokens` 0 (auto) Minimi ennen yhdistämistä. 0 = 1/8 tavoite

## Tuotosmuoto

### Yhteenveto rakenteesta

```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-metriikka**: Kattavuus (% mukaan lukien), lainausprosentti (sitaatiot/pullistumat), Chunks-käsittely (RAG voi jättää osan väliin).

## Mallisuositukset

Malli Koko Nopeus Laatu Käyttö Tapaus
|-------|------|-------|---------|----------|
| `qwen2.5:1.5b` 986MB Erittäin nopea ( ~ 3s) Hyvin nopea optimoitu
| `gemma3:1b` 815MB Nopea ( ~ 10-luku) Reilu ( ~ 10-luku) Vaihtoehtoinen pieni malli
| `llama3.2:3b` 2GB Keskikokoinen ( ~ 15s) Erittäin hyvä **Oletus** - hyvä tasapaino
| `ministral-3:3b` 2.9GB Medium (~20-luku) Erittäin hyvä laatukeskeinen
| `llama3.1:8b` 4,7 GB Hidas ( ~45) Erinomainen Korkealaatuiset tiivistelmät

> **Vinkki**: Nopeampiin tiivistelmiin (~3s vs ~15s) `--model qwen2.5:1.5b`. Kriittisten asiakirjojen kohdalla, joissa laadulla on enemmän merkitystä, käytä `--model llama3.1:8b`.

## Rakentakaa lähteestä

```bash
# Clone the repository
git clone https://github.com/scottgal/mostlylucidweb.git
cd mostlylucidweb/Mostlylucid.DocSummarizer

# Build
dotnet build

# Run
dotnet run -- --help
```

### Omavaraisia rakennelmia

Tuotannon käyttöönottoa varten ilman .NET-käyttöaikaasennusta:

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

Tuloste: `bin/Release/net9.0/<runtime>/publish/docsummarizer`

## Vianetsintä

### "En saanut yhteyttä Ollamaan"

- Varmista, että Ollama on käynnissä: `ollama serve`
- Tarkista mallit: `ollama list`

### "Docling service ei saatavilla"

- Tämä on **vaaditaan vain PDF/DOCX-tiedostoihin**
- Markdown-tiedostoille voit jättää tämän virheen huomiotta
- Korjattava: `docker run -p 5001:5001 quay.io/docling-project/docling-serve`

### "Qdrant-yhteys epäonnistui"

- Tämä on **Vaaditaan vain RAG-tilassa** (`--mode Rag`)
- MapReduce-tilassa (oletus) voit jättää tämän virheen huomiotta
- Korjattava: `docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant`

### "Piirteenkatkaisin on auki"

- Ollama ylikuormittuu tai on syöksynyt maahan
- Odota 30 sekuntia, kunnes virrankatkaisin nollaa tai käynnistä Ollama uudelleen
- Työkalussa käytetään Pollyn sietokykyä koskevia toimintaperiaatteita ja kokeillaan automaattisesti uudelleen

### "wsarecv" tai yhteysvirheet (Windows)

- Tämä on tunnettu Ollama-numero Windowsissa (GitHub #13340)
- Työkalu hoitaa tämän automaattisesti uudelleen logiikan ja yhteyden talteenoton avulla
- Jos olet sinnikäs, käynnistä Ollama uudelleen ja yritä uudelleen

### "LMM-sukupolvi aikakatkaistu"

- Lisää aikakatkaisua kokoonpanossa
- Jaa hyvin suuria asiakirjoja
- Tarkista Ollama ei ole ylikuormittunut muilla pyynnöillä

### Toistuvat tai matalalaatuiset yhteenvedot

**Oireet**: Luodin pistettä kaikuu pikainen ("Palauta vain luotipisteitä", "sääntö on...") sen sijaan, että tiivistettäisiin sisältöä.

**Syy**: Malli kamppailee ripeän tai sisällön kanssa liian pitkään.

**Korjaa**: Oletus `qwen2.5:1.5b` Käsittelee useimpia asiakirjoja hyvin. `--model llama3.2:3b`. Katso [Mallisuositukset](#model-recommendations).

### Yhteenveto jättää asiakirjan sisällön huomiotta

Jos tiivistelmä vaikuttaa yleiseltä tai ei viittaa tiettyyn sisältöön:

- Malli voi olla hallusinaatioita - tarkista `Citation rate` jälkituotoksessa
- Kokeile RAG-tilaa (`--mode Rag`), joka perustelee yhteenvetoja noudetuista kappaleista
- Käyttö `--verbose` nähdäkseen, mitkä palaset jalostetaan

### Lainaukset puuttuvat tai ne ovat virheellisiä

Jos tiivistelmät puuttuvat `[chunk-N]` Lainaukset:

- Pienet mallit priorisoivat sisällön lainausmuotoilun sijaan
- Kannustin on optimoitu nopeuteen, ei tiukkaan sitaattien noudattamiseen
- Tiukkoihin lainauksiin kannattaa käyttää suurempia malleja, kuten `llama3.2:3b`
- Tarkista `Citation rate` jäljettömiin - korkeammat arvot kertovat paremmasta jäljitettävyydestä

## Suoritusvinkkejä

- **MapReduce** nopeudelle (rinnakkaiskolonnit)
- **`qwen2.5:1.5b`** nopeudelle, **`llama3.2:3b`** tasapainoon, **`llama3.1:8b`** laadulle
- **ONNX-kytkennät** (oletus) on nopeampi kuin Ollama RAG-tilassa
- Alempi **`maxLlmParallelism`** jos kokee aikalisän

## Resurssit

- [Lähdekoodi](https://github.com/scottgal/mostlylucidweb/tree/main/Mostlylucid.DocSummarizer)
- [GitHubledget](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer)
- [Dokulaatio](https://github.com/docling-project/docling) / [Valmennuspalvelu](https://github.com/docling-project/docling-serve)
- [Qdrant](https://qdrant.tech/) - Paikallinen vektoritietokanta
- [Ollama](https://ollama.ai/) / [OllamaSharp](https://github.com/awaescher/OllamaSharp)
- [Polly](https://github.com/App-vNext/Polly) - .NET-kestävyys ja tilapäinen vikakäsittely
- [Spectre.Console](https://spectreconsole.net/) - Kaunis pääte UI

## Sarjanavigointi

- **[Osa 1: Asiakirjatiivistelmän laatiminen aluetukialueilla](/blog/building-a-document-summarizer-with-rag)** - Arkkitehtuuri ja kuviot
- **[Osa 2: Työkalun käyttö](/blog/docsummarizer-tool)** (tämä artikkeli) - Pikakäynnistysopas
- **[Osa 3: Kehittyneet käsitteet](/blog/docsummarizer-advanced-concepts)** - Sukella syvälle BERTiin, ONNX:ään, upoksiin ja hybridihakuun

### Aiheeseen liittyvät

- [CSV-analyysi paikallisten LLM:ien kanssa](/blog/analysing-large-csv-files-with-local-llms)
- [Verkkosisältö LLM:ien kanssa](/blog/fetching-and-analysing-web-content-with-llms)