Ak si nainštaloval Paperless-ngx podľa nášho návodu, môžeš k nemu pridať AI vrstvu. Paperless-AI beží ako samostatná služba a napája sa na Paperless cez API — každých 30 minút prechádza nové dokumenty a automaticky ich taguje a zaraďuje.

Prečo samostatný kontajner, nie compose stack

Paperless-AI v docker-compose stacku spolu s Paperless-ngx nefungoval spoľahlivo — objavoval sa network error pri komunikácii medzi kontajnermi. Riešenie: spustiť Paperless-AI ako samostatný kontajner mimo compose stacku, ale v tej istej Docker sieti.

Čo budeš potrebovať

Bežiaci Paperless-ngx stack (kontajner PaperlessNGX musí byť dostupný)
Claude API kľúč — console.anthropic.com
SSH prístup na NAS alebo server

Krok 1 — Vytvor priečinok a spusti kontajner

Najprv vytvoríme priečinok pre dáta Paperless-AI, potom spustíme kontajner priamo cez Docker (nie cez Portainer Stacks):

mkdir -p /volume1/docker/paperlessngx/paperless-ai

sudo docker run -d \
  --name PaperlessNGX-AI \
  --network paperless_default \
  --restart on-failure:5 \
  -p 8778:3000 \
  -v /volume1/docker/paperlessngx/paperless-ai:/app/data \
  -e PAPERLESS_AI_API_URL=http://paperlessNGX:8000 \
  -e AI_PROVIDER=custom \
  clusterzx/paperless-ai:latest

⚠️ Názov siete

paperless_default je predvolený názov siete Docker Compose stacku s názvom paperless. Ak si stack pomenoval inak, uprav názov siete podľa toho. Zistíš ho cez docker network ls.

Krok 2 — Zisti IP adresu Paperless-ngx kontajnera

Hostname paperlessNGX nemusí fungovať z externého kontajnera. Pre istotu zistíme priamu IP adresu:

sudo docker inspect PaperlessNGX | grep IPAddress

Výstup bude obsahovať niečo ako "IPAddress": "192.168.64.2". Túto IP použiješ namiesto hostname ak UI hlási chybu pripojenia — zmeníš URL v nastaveniach na http://192.168.64.2:8000.

Krok 3 — Získaj API token pre Paperless

Paperless-AI sa pripája k Paperless cez API token. Najrýchlejšie ho nájdeš priamo v Paperless UI: klikni na svoje meno vpravo hore → Môj profil — token je zobrazený tam. Skopíruj ho a zadáš ho neskôr v Paperless-AI Settings.

Alternatívne ho vieš vygenerovať aj cez príkazový riadok:

sudo docker exec PaperlessNGX-AI curl -s -X POST http://192.168.64.2:8000/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username":"TVOJ_USER","password":"TVOJE_HESLO"}'

Krok 4 — Výber AI providera

Paperless-AI podporuje viacero AI providerov — Ollama (lokálne modely), OpenAI, Azure a Custom. Vyber si podľa toho, čo preferuješ.

My sme použili Custom provider s Claude API. Správne premenné prostredia (zistené priamo zo zdrojového kódu kontajnera):

CUSTOM_BASE_URL=https://api.anthropic.com/v1
CUSTOM_API_KEY=sk-ant-...
CUSTOM_MODEL=claude-haiku-4-5-20251001

Ako sme zistili správne názvy premenných

Paperless-AI dokumentácia nie vždy odráža aktuálny stav. Premenné sme overili priamo zo zdrojového kódu kontajnera:

sudo docker exec PaperlessNGX-AI grep -A 10 "custom" /app/services/setupService.js

Krok 5 — Finálna konfigurácia v UI

Otvor Paperless-AI UI na http://IP-NAS:8778 a vyplň v Settings (príklad pre Claude / Custom provider):

Parameter	Hodnota
AI Provider	Custom
Base URL	`https://api.anthropic.com/v1`
API Key	Tvoj Claude API kľúč (`sk-ant-…`)
Model	`claude-haiku-4-5-20251001`
Token Limit	`128000`
Response Tokens	`1000`
Paperless URL	`http://192.168.64.2:8000`
Paperless API Token	Token z kroku 3

⚠️ Model claude-haiku-4-5-20251001

Pre automatické spracovanie dokumentov je Haiku ideálna voľba — rýchla a lacná. Ak chceš presnejšie výsledky, môžeš použiť claude-sonnet-4-6, ale počítaj s vyššími nákladmi na API.

Výsledok

1029+

Dokumentov zindexovaných Paperless-AI po prvom spustení. Automatický scan prebieha každých 30 minút — nové dokumenty sa tagujú a klasifikujú bez akéhokoľvek manuálneho zásahu.

Po uložení nastavení Paperless-AI okamžite začne spracovávať dokumenty. V záložke Dashboard vidíš priebeh — prvý beh môže trvať dlhšie podľa počtu dokumentov.

Troubleshooting

⚠️ Network error pri pripojení na Paperless

Skontroluj, že kontajner beží v správnej sieti (paperless_default). Ak hostname nefunguje, použi priamu IP adresu z kroku 2. Overiš cez: docker inspect PaperlessNGX-AI | grep Networks

⚠️ Authentication failed / 401

Token musí byť vygenerovaný cez API (/api/token/), nie skopírovaný z Paperless UI. Uisti sa, že username a password sú správne a že Paperless beží.

⚠️ AI provider error / model not found

Skontroluj premenné: CUSTOM_BASE_URL musí byť presne https://api.anthropic.com/v1 (bez lomky na konci). Názov modelu musí zodpovedať dostupným modelom Anthropic API.

Paperless-AI — integrácia s Claude API