Paperless-AI 发布 4.1:新增 PaddleOCR 本地 OCR 与提示词向导
clusterzx/paperless-ai
Paperless-AI 发布 4.1,为 Paperless-ngx 文档管理加入基于 PaddleOCR(PP-OCRv5,经 ONNX Runtime)的本地 OCR,模型约 20 MB,可在 AI 分析前自动识别扫描件与乱码文本。
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?”
✨ 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-cudaruns OCR on NVIDIA GPUs (CUDA 13);lateststays 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-cudaimage
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
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 |
|---|---|
![]() |
![]() |
| 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.
- Back up the data volume (
docker volume lsshows 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 .
- Update
docker-compose.yml: useimage: clusterzx/paperless-ai:latest(or a fixed version such as4.1.1), keep the volume…:/app/dataand the port. Remove the 3.x linesRAG_SERVICE_URL,PUIDandPGID(no longer used) andRAG_SERVICE_ENABLED(it would lock the setting in the UI). - Start:
docker compose pull && docker compose up -d. The log (docker compose logs -f paperless-ai) showsMigrated legacy data/.env configuration to data/config.jsonandImported data from legacy documents.dbwith the number of migrated users, documents and history entries. - 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
- Paperless-ngx → Workflows → Add workflow, trigger Document Added
- Action Webhook: URL
http://paperless-ai:3000/api/webhook/document, body parameterurl={doc_url} - 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 whenevernum_ctxchanges, so a fixed size keeps it loaded between documents. Longer documents are shortened to fit; raise the size if your GPU has room, or set0to 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
来源:GitHub · github.com





