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ť

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 \
  clusterzx/paperless-ai:latest
⚠️ Nezadávaj env premenné pri docker run

Environment premenné nastavené pri docker run majú vyššiu prioritu ako nastavenia z UI. Ak ich nastavíš tu, UI ich nebude vedieť prepísať a konfigurácia sa môže zaseknúť. Všetko nastav výhradne cez Paperless-AI UI.

⚠️ 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. Nájdeš ho v Paperless UI: klikni na svoje meno vpravo hore → Môj profil — token je zobrazený tam. Skopíruj ho, zadáš ho neskôr v Paperless-AI Settings.

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

ParameterHodnota
AI ProviderCustom
Base URLhttps://api.anthropic.com/v1
API KeyTvoj Claude API kľúč (sk-ant-…)
Modelclaude-haiku-4-5-20251001
Token Limit128000
Response Tokens1000
Paperless URLhttp://192.168.64.2:8000
Paperless API TokenToken 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

⚠️ AI nespracováva dokumenty napriek nastaveniu v UI

Environment premenné nastavené pri docker run majú vyššiu prioritu ako .env súbor generovaný cez UI. Skontroluj:

sudo docker exec PaperlessNGX-AI env | grep PROCESS

Ak vidíš PROCESS_PREDEFINED_DOCUMENTS=yes, treba kontajner zmazať a spustiť znovu bez env premenných (pozri Krok 1):

sudo docker stop PaperlessNGX-AI
sudo docker rm PaperlessNGX-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 \
  clusterzx/paperless-ai:latest
⚠️ 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ť skopírovaný z Paperless UI (Môj profil). Uisti sa, že Paperless beží a token je celý bez medzier.

⚠️ 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.