跳到正文
GitHub·· 2 小时前AI 评分58

Paperless-AI 发布 4.1:新增 PaddleOCR 本地 OCR 与提示词向导

clusterzx/paperless-ai

AI 导读

Paperless-AI 发布 4.1,为 Paperless-ngx 文档管理加入基于 PaddleOCR(PP-OCRv5,经 ONNX Runtime)的本地 OCR,模型约 20 MB,可在 AI 分析前自动识别扫描件与乱码文本。

正文

GitHub commit activity Docker Pulls GitHub Stars License

Paperless-AI is an AI extension for Paperless-ngx. It analyzes your documents and fills in title, tags, correspondent, document type, date and custom fields – and lets you ask questions about your whole archive in natural language, with answers that cite their sources.

Works with Paperless-ngx 2.x and 3.x, OpenAI, Anthropic (Claude), Ollama (fully local), Azure OpenAI and every OpenAI-compatible API (DeepSeek, OpenRouter, LiteLLM, vLLM, LM Studio, Gemini, Together, Perplexity, …).

Important

Security notice for 3.x: in all Paperless-AI versions before 4.0, the setup wizard can be used without logging in. Anyone who can reach such an instance can replace its user account and its configuration (Paperless token, AI provider), and this is being exploited. Update to 4.0 – it is not affected. If your 3.x instance was reachable from the internet, read Upgrading from 3.x before you migrate.

💡 Just ask: “When did I sign my rental agreement?” “What was the amount of the last electricity bill?” “Which documents mention my health insurance?”

Dashboard


✨ What's new in 4.1

  • OCR with PaddleOCR – scans, photos and documents with garbled text are read locally (PP-OCRv5 via ONNX Runtime, no extra container, models ~20 MB). Runs automatically before the AI analysis – for documents without text, with poor text or always – or on demand. → OCR
  • OCR page – every document with a text-quality score, filters for missing/poor text, bulk OCR, side-by-side comparison of the Paperless text and the OCR result. Afterwards the AI names and tags the documents again.
  • Better text in Paperless too – the OCR result can replace the document text in Paperless (improves the Paperless full-text search), with undo.
  • GPU image – clusterzx/paperless-ai:latest-cuda runs OCR on NVIDIA GPUs (CUDA 13); latest stays the small CPU image for amd64 and arm64. → Image variants
  • Prompt wizard – a few questions instead of prompt engineering: your own name (never used as correspondent), output language, title style or pattern, tags, short company names, document types and own rules. Live preview and a test on real documents before saving.
  • Privacy – the usage telemetry of ONNX Runtime (OCR and local embeddings) is switched off.

✨ What's new in 4.0 – a complete rewrite

Version 4 is rebuilt from scratch with a focus on reliability, speed and low resource usage.

3.x 4.0
Architecture Node.js + separate Python service (Torch, ChromaDB, NLTK) One Node.js process (TypeScript)
Docker image several GB ~135 MB compressed
RAM in idle 1–2 GB ≈ 80–150 MB (embedding model loaded on demand)
RAG retrieval one embedding of the first ~100 words per document chunked passages, hybrid BM25 + vector search, metadata boosts
RAG answers not streamed, no references streamed, cited sources [1], follow-up questions
Index updates full re-crawl & re-embed incremental (changed/deleted documents only)
Settings written to .env, container restart required validated, applied instantly – no restart
Paperless-ngx 2.x 2.x and 3.x (API version negotiated automatically, verified against 2.14, 2.20 and 3.2)
Undo only “forget processing state” real undo – restores the original values in Paperless
Interface server-rendered pages new design: single-page app, command menu, light/dark + accent colours

Upgrading from 3.x is automatic: your data/.env, user account, processing state, history and token statistics are migrated on first start (the old files are kept untouched) – see Upgrading from 3.x.

🚀 Features

Automatic processing

  • Detects new documents (schedule and/or instantly via a Paperless workflow webhook)
  • Title, tags, correspondent, document type, document date and custom fields (text, long text, number, monetary, date, boolean, URL, select)
  • AI providers: OpenAI, Anthropic (Claude), Ollama, any OpenAI-compatible API (DeepSeek, OpenRouter, LiteLLM, vLLM, LM Studio, Gemini …) and Azure OpenAI – reasoning/thinking models included
  • Structured JSON output (JSON schema) with automatic fallback for providers without support
  • Process all documents or only documents with trigger tags (optionally removed afterwards), mark processed documents with a tag
  • Restrict the AI to existing tags / correspondents / document types, or to a fixed tag list
  • Optional context from an external API (e.g. your customer list) with an optional JavaScript transformation (runs in a separate worker thread with a time limit)
  • Parallel processing, retries with back-off, failed/skipped documents visible on the dashboard; rate limits of the AI provider pause the queue instead of failing documents
  • Existing correspondents are kept unless you allow the AI to overwrite them; created tags/correspondents/types are visible to all Paperless users (configurable)

OCR with PaddleOCR (optional)

  • Reads scans and photos locally with PaddleOCR (PP-OCRv5) via ONNX Runtime – no extra container, no cloud service; models (~20 MB) are downloaded on first use
  • Runs before the AI analysis, so titles, tags and correspondents come from good text: automatically for documents without text, with poor text (heuristic text-quality score) or always – or only on demand
  • OCR page lists all documents with their text quality, finds the garbled ones and reads them in bulk; afterwards the AI names and tags them again
  • The text replaces the content in Paperless (better Paperless full-text search) only when it reads better than the existing text – with a side-by-side comparison and undo
  • Detects pages scanned sideways or upside down, 30+ Latin-script languages plus Cyrillic, Greek, Arabic, Chinese/Japanese, Korean, …
  • CPU (all platforms) or NVIDIA GPU with the :latest-cuda image

Prompt wizard

  • A few questions instead of prompt engineering: your name (never used as correspondent), output language, title style or pattern, how many and what kind of tags, short company names, document types, own rules
  • Live preview of the generated prompt, test on real documents before saving – the answers are kept, so the wizard can be opened again later

Ask your archive (RAG)

  • Hybrid search: SQLite FTS5 (BM25) + compact in-memory vector index (int8)
  • Embeddings: built-in multilingual model (offline, CPU), Ollama, OpenAI, Azure, any OpenAI-compatible API – or keyword-only
  • Understands follow-up questions, filters (date range, correspondent, document type), “latest …” questions and mentioned years/correspondents
  • “How many …?” questions are answered with exact numbers from Paperless – not by counting the excerpts the AI sees
  • Answers stream in, cite their sources and link to the documents in Paperless; conversations are kept in your browser
  • Pure semantic search mode without AI costs

Ask your archive

Interactive tools

  • Document chat – ask questions about a single document (long documents are handled automatically)
  • Manual review – let the AI suggest metadata and decide yourself what to save
  • Prompt playground – test prompts on real documents side by side with the current values, rate and keep prompts
  • History with undo, filters and search
  • Dashboard with live processing status, coverage, activity, token usage
  • Logs & diagnostics – live log stream, connection checks, Paperless API explorer
  • Modern interface: light/dark theme with five accent colours, ⌘K / Ctrl+K command menu (jump to pages, open documents by number, ask a question), works on mobile
Manual review History with undo
Manual review History
Settings Sign-in
Settings Sign-in

🐳 Installation

# docker-compose.yml
services:
  paperless-ai:
    image: clusterzx/paperless-ai:latest
    container_name: paperless-ai
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - paperless-ai_data:/app/data
    extra_hosts:
      - "host.docker.internal:host-gateway" # to reach Ollama on the Docker host

volumes:
  paperless-ai_data:
docker compose up -d

Open http://<your-server>:3000 – the setup wizard guides you through account, Paperless connection, AI provider and processing options. No restart is needed afterwards.

Image variants:

Tag For
latest (= latest-cpu), 4.x.y default – amd64 and arm64, OCR and local embeddings on the CPU
latest-cuda, 4.x.y-cuda NVIDIA GPU for OCR (amd64, CUDA 13 + cuDNN 9). Needs the NVIDIA Container Toolkit and a driver ≥ 580; falls back to the CPU when no GPU is found
    image: clusterzx/paperless-ai:latest-cuda
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Paperless API user: create a dedicated user in Paperless-ngx with permission to view and change documents, tags, correspondents, document types and custom fields, and use its API token (Profile → API Auth Token). Only documents this user may change are processed.

Upgrading from 3.x

Keep your data volume and switch the image – everything else happens on the first start.

  1. Back up the data volume (docker volume ls shows its exact name, often with the project name in front):
    docker compose stop paperless-ai
    docker run --rm -v paperless-ai_data:/data -v "$PWD":/backup alpine \
      tar czf /backup/paperless-ai-3x-backup.tgz -C /data .
  2. Update docker-compose.yml: use image: clusterzx/paperless-ai:latest (or a fixed version such as 4.1.1), keep the volume …:/app/data and the port. Remove the 3.x lines RAG_SERVICE_URL, PUID and PGID (no longer used) and RAG_SERVICE_ENABLED (it would lock the setting in the UI).
  3. Start: docker compose pull && docker compose up -d. The log (docker compose logs -f paperless-ai) shows Migrated legacy data/.env configuration to data/config.json and Imported data from legacy documents.db with the number of migrated users, documents and history entries.
  4. Sign in with your previous username and password and review the settings – everything is prefilled; values set by environment variables are shown locked.

What is migrated: settings from data/.env, the user account, which documents were already processed (nothing is analysed again, no extra AI costs), the history including the original values (undo works for old changes too) and the token statistics. The search index for Ask your archive is rebuilt in the background; the first time, the built-in embedding model (~120 MB) is downloaded. The 3.x files (.env, documents.db) are left untouched, so you can switch back to the 3.x image – it just won't know about anything done in 4.0.

Warning

If your 3.x instance was reachable from the internet (without an additional login such as a VPN or an authenticating reverse proxy in front of it), it may have been taken over through the setup wizard – see the security notice above. 3.x only has one account, so the clearest sign is that your previous username and password no longer work, or that the settings contain a Paperless URL or AI endpoint you did not set. In that case:

  • do not migrate the old data – start 4.0 with a new, empty data volume and run the setup again;
  • create a new Paperless API token for Paperless-AI and delete the old one, and replace the API keys of your AI provider;
  • check the Paperless-ngx logs for document access with the old token.

In any case, don't expose a fresh installation to the internet before the setup is completed: until the first account exists, the setup wizard is open to everyone who can reach it.

Instant processing with a Paperless workflow

  1. Paperless-ngx → Workflows → Add workflow, trigger Document Added
  2. Action Webhook: URL http://paperless-ai:3000/api/webhook/document, body parameter url = {doc_url}
  3. Header x-api-key: <API key from Settings → API & webhooks>

⚙️ Configuration

Everything can be configured in the web interface. Settings are stored in data/config.json. Environment variables override stored settings (the UI shows them as locked) – handy for Docker deployments. The variable names of 3.x are still supported.

Variable Setting
PAPERLESS_AI_PORT HTTP port (default 3000)
PAPERLESS_AI_DATA_DIR data directory (default ./data, /app/data in Docker)
PAPERLESS_API_URL (or PAPERLESS_URL), PAPERLESS_API_TOKEN Paperless-ngx URL (with or without /api) and token – PAPERLESS_API_URL wins when both are set
PAPERLESS_PUBLIC_URL URL for links opened in the browser (optional)
AI_PROVIDER openai, anthropic, ollama, custom, azure
OPENAI_API_KEY, OPENAI_MODEL OpenAI
ANTHROPIC_API_KEY, ANTHROPIC_MODEL, ANTHROPIC_BASE_URL Anthropic (Claude); the base URL only for a gateway/proxy
OLLAMA_API_URL, OLLAMA_MODEL, OLLAMA_KEEP_ALIVE Ollama
OLLAMA_NUM_CTX (or OLLAMA_CONTEXT_SIZE), OLLAMA_THINK, OLLAMA_UNLOAD_WHEN_IDLE Ollama context size (0 = per document), thinking (auto, off, on, low, medium, high), unload when the queue is empty
CUSTOM_BASE_URL, CUSTOM_API_KEY, CUSTOM_MODEL, CUSTOM_EXTRA_BODY OpenAI-compatible provider; extra request parameters as JSON
AZURE_ENDPOINT, AZURE_API_KEY, AZURE_DEPLOYMENT_NAME, AZURE_API_VERSION Azure OpenAI
TOKEN_LIMIT, RESPONSE_TOKENS, AI_TEMPERATURE, AI_TIMEOUT_SECONDS model limits
SCAN_INTERVAL, DISABLE_AUTOMATIC_PROCESSING, PROCESSING_CONCURRENCY scheduling
PROCESS_PREDEFINED_DOCUMENTS, TAGS, REMOVE_TRIGGER_TAGS only process tagged documents
ADD_AI_PROCESSED_TAG, AI_PROCESSED_TAG_NAME mark processed documents
USE_PROMPT_TAGS, PROMPT_TAGS, USE_EXISTING_DATA, SYSTEM_PROMPT prompt
OVERWRITE_CORRESPONDENT, SHARE_CREATED_OBJECTS replace existing correspondents (default off); create tags/correspondents/types without owner (default on)
ACTIVATE_TAGGING, ACTIVATE_CORRESPONDENTS, ACTIVATE_DOCUMENT_TYPE, ACTIVATE_TITLE, ACTIVATE_CUSTOM_FIELDS, ACTIVATE_DOCUMENT_DATE enabled functions
RESTRICT_TO_EXISTING_TAGS, RESTRICT_TO_EXISTING_CORRESPONDENTS, RESTRICT_TO_EXISTING_DOCUMENT_TYPES restrictions
CUSTOM_FIELDS custom fields (JSON, format of 3.x)
EXTERNAL_API_ENABLED, EXTERNAL_API_URL, EXTERNAL_API_METHOD, EXTERNAL_API_HEADERS, EXTERNAL_API_BODY, EXTERNAL_API_TIMEOUT, EXTERNAL_API_TRANSFORM external data
RAG_ENABLED (or RAG_SERVICE_ENABLED), RAG_EMBEDDING_PROVIDER, RAG_EMBEDDING_MODEL, RAG_QUERY_EXPANSION ask your archive
OCR_ENABLED, OCR_MODE (manual, missing, poor, always), OCR_WRITE_BACK OCR on/off, when it runs automatically, replace the text in Paperless (default on)
OCR_LANGUAGE (latin, en, multi, cyrillic, eslav, greek, arabic, devanagari, korean, thai, tamil, telugu), OCR_QUALITY (fast, balanced, accurate) OCR model
OCR_DEVICE (auto, cpu, cuda), OCR_THREADS, OCR_MAX_PAGES OCR hardware and limits (0 threads = automatic, 0 pages = all)
API_KEY, JWT_SECRET secrets (generated automatically when unset; use at least 32 random characters for JWT_SECRET)
LOG_LEVEL, LOG_FORMAT=json operations
TRUST_PROXY behind a reverse proxy: number of proxy hops (usually 1) or the proxy addresses – needed for correct client IPs (login rate limit) and secure cookies; off by default

Empty variables (e.g. OPENAI_API_KEY= left in a compose file) are ignored, so they never replace what you configured in the web interface.

OCR

Settings → OCR turns OCR on. The modes:

  • No text or poor text (recommended): before the AI analysis, documents without text or with garbled text (text-quality score below 50) are read with OCR.
  • Only documents without text: for archives where Paperless' own OCR is fine.
  • Every document: best text for every document, costs time per document.
  • Manual: only from the OCR page or the API (POST /api/ocr/run). The documents are analyzed by the AI afterwards.

The OCR text replaces the text in Paperless only when its text-quality score is higher than that of the existing text – a clean text layer of a digital PDF or well-read print is never replaced by a weaker OCR result (e.g. of handwriting); the AI then analyses the existing text, too. On the OCR page you can compare both texts and save the OCR text anyway.

On a 4-core CPU an A4 page takes about 1–2 s (Balanced). Accurate uses a larger detection model and 300 dpi – noticeably better for small print, but slow without a GPU. Models are stored in the data directory (models/paddleocr), so they are downloaded only once; behind a proxy or offline, set HF_ENDPOINT to a Hugging Face mirror or copy the folder from another installation.

ONNX Runtime's own usage telemetry is switched off (ORT_DISABLE_TELEMETRY=1) – nothing about your documents leaves your server.

Local models (Ollama)

  • Context size: Paperless-AI sends a fixed num_ctx (default 16,384 tokens). Ollama reloads the model whenever num_ctx changes, so a fixed size keeps it loaded between documents. Longer documents are shortened to fit; raise the size if your GPU has room, or set 0 to size it per document.
  • Thinking: thinking models (qwen3, gpt-oss, deepseek-r1 …) can be switched off in Settings → AI provider, which is much faster for metadata extraction. gpt-oss also accepts low/medium/high.
  • Free the GPU: Unload the model when the queue is empty releases the memory right after the last document; alternatively use Keep model loaded (keep_alive).
  • Other local servers (vLLM, llama.cpp, LM Studio) run as OpenAI-compatible provider; parameters such as {"chat_template_kwargs": {"enable_thinking": false}} go into Extra request parameters.

Self-signed certificates

If Paperless-ngx or your AI server uses a certificate from your own CA, mount the CA certificate and point Node.js to it:

    environment:
      - NODE_EXTRA_CA_CERTS=/certs/my-ca.pem
    volumes:
      - ./my-ca.pem:/certs/my-ca.pem:ro

As a last resort, NODE_TLS_REJECT_UNAUTHORIZED=0 turns certificate checks off completely. ⚠️ This applies to every connection of Paperless-AI – including the one carrying your OpenAI/Anthropic API key – so anybody in the network path could read and change the traffic. Only use it for testing in a trusted network.

Choosing embeddings for “Ask your archive”

Option Notes
Local (default) Xenova/multilingual-e5-small (~120 MB, downloaded once to data/models), 100+ languages incl. cross-lingual search, runs on the CPU in a worker thread (≈ 0.5 GB RAM while indexing, released after 5 minutes idle)
Ollama e.g. nomic-embed-text, bge-m3, mxbai-embed-large (ollama pull …)
OpenAI / OpenAI-compatible / Azure e.g. text-embedding-3-small
None keyword search only (BM25) – smallest footprint

Changing the embedding model re-embeds the passages automatically; the keyword search keeps working meanwhile.

Memory: the vector index keeps one byte per dimension and passage in RAM (a document has about one passage per 1,000 characters) – e.g. 100,000 passages need ≈ 40 MB with the local model (384 dimensions) and ≈ 155 MB with text-embedding-3-small (1,536 dimensions).

Smart search terms (on by default, RAG_QUERY_EXPANSION=false to disable): before searching, the AI adds a few search terms to the question – synonyms, names and translations into the language of your archive. This costs one short extra AI call per question and noticeably improves the hit rate, especially when you ask in a different language than your documents are written in.

Retrieval quality, measured with npx tsx e2e/rag-eval/run.ts (49 German/English documents, 27 questions in both languages; “hit@k” = the right document is among the first k sources the AI sees):

Retrieval hit@1 hit@3 hit@5
3.x (emulated) 52 % 56 % 63 %
4.0 keyword only 56 % 70 % 70 %
4.0 hybrid, local model 81 % 89 % 93 %
4.0 hybrid, local model + smart search terms (qwen2.5:3b via Ollama) 85 % 100 % 100 %

🔌 API

The REST API is documented at /api-docs (OpenAPI). Authenticate with the header x-api-key. The endpoints used by the Paperless-AI browser extension and by scripts written for 3.x (/chat/init/:id, /chat/message, /api/scan/now, /api/webhook/document, /api/rag/ask, …) are still available.

🧑‍💻 Development

Requirements: Node.js ≥ 22.12.

npm install
npm run dev          # backend (tsx watch, port 3000) + web UI (Vite, port 5173)
npm run demo         # demo with a fake Paperless-ngx and a fake LLM: http://127.0.0.1:3456 (admin / demo1234)
npm run check        # typecheck + lint + unit/integration tests
npm run test:e2e     # Playwright end-to-end tests (uses the demo server)
# compatibility check against a real (disposable!) Paperless-ngx instance:
PAPERLESS_URL=http://localhost:8000 PAPERLESS_TOKEN=… npx tsx e2e/real-paperless-check.ts
npm run build && npm start

Architecture overview: docs/ARCHITECTURE.md.

🤝 Contributing

Pull requests are welcome! Please run npm run check before submitting.

🆘 Support & Community

📄 License

MIT – see LICENSE.

AI-assisted development Paperless-AI is a hobby project, and large parts of the new v4 code are written with the help of AI coding tools. The code is covered by automated tests, but AI-assisted code can still contain bugs or security issues that are easy to miss. Please report security problems privately as described in SECURITY.md.

No warranty This software is provided "as is", without warranty of any kind (see LICENSE). Keep it in your local network and don't expose it to the internet without additional protection, such as a VPN or an authenticating reverse proxy.

🙏 Support Development

Patreon PayPal BuyMeACoffee Ko-Fi

来源:GitHub · github.com