wiki/Catalogue-Self-Hosted/apps/app-paperless-ai.md

---
title: Paperless AI
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, artificial-intelligence, paperless, document-management, rag, llm, ocr, javascript, agpl]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=artificial-intelligence, https://github.com/clusterzx/paperless-ai]
---

# Paperless AI 📄
> **L'extension IA pour [[app-paperless-ngx|Paperless-ngx]]** — analyse, tag, classe et **permet de discuter avec vos documents** via RAG, compatible OpenAI / Ollama / DeepSeek / Azure / Gemini, sans rien envoyer dans le cloud si vous utilisez un LLM local.

| Métadonnée | Valeur |
| :--- | :--- |
| **Site web** | (GitHub) |
| **GitHub** | https://github.com/clusterzx/paperless-ai |
| **License** | AGPL-3.0 |
| **Langage** | JavaScript (54 %), EJS (30 %), Python (10 %) |
| **Étoiles** | 309 |
| **Dernière MAJ** | 2025-11-04 (v3.0.9) |
| **Catégorie** | [[cat-artificial-intelligence]] |

## 📝 Description

**Paperless-AI** est une **extension officielle-tierce** pour [Paperless-ngx](https://github.com/paperless-ngx/paperless-ngx) qui ajoute deux super-pouvoirs manquants à votre GED : (1) **l'analyse automatique** de chaque nouveau document pour proposer un **titre, des tags, un type et un correspondant** sans intervention manuelle, et (2) **un chat RAG** (Retrieval-Augmented Generation) qui permet de poser des questions en langage naturel sur l'ensemble de votre archive. Plus jamais besoin d'ouvrir 200 PDF pour retrouver votre contrat de bail : vous demandez *« Quand ai-je signé mon bail et pour quel loyer ? »* et l'IA répond en citant le document.

Côté backend, Paperless-AI est un **monolith Node.js/Express + EJS** qui tourne **à côté** de votre instance Paperless-ngx, écoute l'API REST de celle-ci pour récupérer les nouveaux documents, les envoie à un **LLM compatible OpenAI** (Ollama en local, OpenAI, DeepSeek, OpenRouter, Perplexity, Together.ai, LiteLLM, VLLM, Fastchat, Gemini, Azure, etc.), puis **PATCH les métadonnées** via l'API. L'index RAG est reconstruit dans un **ChromaDB** embarqué (mode `Dockerfile.rag`) ou via un store externe. Une **UI web** (`/manual`) permet de rejouer l'analyse sur un document, de corriger les tags proposés et d'interroger le chat.

Le projet compte **5 700 ⭐**, 311 forks, 413 commits, 58 releases — c'est la référence self-hostée pour Paperless+IA. ⚠️ **Note importante** : l'auteur a annoncé que le repo est **actuellement en pause de maintenance** (réécriture en cours) et que **Paperless-ngx intégrera bientôt sa propre AI native**. À surveiller avant d'investir dessus, mais pour les déploiements existants en v3.0.9 l'app reste fonctionnelle et stable.

## 🚀 Installation

### Option 1 : Docker Compose (recommandé)

```yaml
# docker-compose.yml
services:
  paperless-ai:
    image: clusterzx/paperless-ai:latest    # ou ghcr.io/clusterzx/paperless-ai-rag:latest pour le RAG
    container_name: paperless-ai
    restart: unless-stopped
    depends_on:
      - paperless-webserver  # référence externe à votre stack Paperless-ngx
    ports:
      - "8085:8085"
    environment:
      - PAPERLESS_URL=http://paperless-webserver:8000
      - PAPERLESS_API_TOKEN=change...ci
      - AI_PROVIDER=ollama             # ollama / openai / deepseek / openrouter / gemini
      - OLLAMA_URL=http://host.docker.internal:11434
      - OLLAMA_MODEL=llama3.1:8b
      - OPENAI_API_KEY=                 # remplir si AI_PROVIDER=openai
      - AI_TITLE_PROMPT_ENABLED=true
      - AI_TAGS_PROMPT_ENABLED=true
      - AI_CORRESPONDENT_PROMPT_ENABLED=true
      - AI_DOCUMENT_TYPE_PROMPT_ENABLED=true
      - TZ=Europe/Paris
    volumes:
      - paperless-ai-data:/app/data
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8085/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3

  # (optionnel) Ollama local pour LLM 100 % privé
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ollama-models:/root/./.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  paperless-ai-data:
  ollama-models:
```

⚠️ **Premier démarrage** : configurez vos clés LLM et providers dans l'UI, **puis redémarrez le conteneur** pour que l'index RAG soit initialisé. Cette étape n'est **pas** nécessaire pour les mises à jour ultérieures.

### Option 2 : Installation manuelle

Prérequis : **Node.js 20+**, **Python 3.11+** (pour les modules RAG), **Paperless-ngx** déjà installé. `git clone`, `npm install` (ou `pnpm`), créer un `.env` à partir de `.env.example`, `npm run build` (frontend), `npm start` (backend sur `:8085`). Le `npm run test` lance le mode dev. Voir le [wiki d'install](https://github.com/clusterzx/paperless-ai/wiki/2.-Installation) pour les détails npm vs Docker.

## ⚙️ Configuration

Paperless-AI se configure via **variables d'environnement** ET une **UI web** accessible sur `http://localhost:8085` :

- `PAPERLESS_URL` + `PAPERLESS_API_TOKEN` : connexion à votre instance Paperless-ngx (créez un token dédié dans l'admin Paperless).
- `AI_PROVIDER` : choisir le backend (`ollama` recommandé pour le local-first).
- `AI_*_PROMPT_ENABLED` : activer/désactiver individuellement le titre, les tags, le type, le correspondant.
- **Manual mode** : depuis l'UI `/manual`, lancez l'analyse sur n'importe quel document sans toucher à la base.
- **Règles de filtrage** : exclure certains types de documents (ex. tickets de caisse) de l'auto-analyse pour économiser des tokens.

## 🔄 Alternatives

### Open Source
- **Paperless-ngx AI native** (en cours de dev) — l'AI officielle arrivera probablement en v2.x et pourrait rendre ce projet obsolète. À suivre.
- **TagStudio** — gestionnaire de tags fichiers, pas un plugin Paperless.
- **Teable**, **NocoDB** — bases de données avec AI, mais pas de RAG sur documents scannés.
- **Quivr** — RAG open source « second brain », pas spécifique Paperless.
- [[app-paperless-ngx]] — la GED de base (à installer avant Paperless-AI).
- [[app-ollama]] — backend LLM local parfait pour Paperless-AI.
- [[app-open-webui]] — UI chat qui peut aussi indexer des documents.

### Propriétaires (ce que Paperless-AI remplace)
- **Adobe Acrobat AI** — chat sur PDF cloud, abonnement, pas de self-hosting.
- **ChatPDF** ($0-$20/mois) — upload un PDF à la fois, pas d'archive centralisée.
- **Humata** ($0-$15/mois) — équivalent ChatPDF.
- **Notion AI Q&A** — fonctionne sur Notion, pas sur une GED auto-hébergée.
- **Evernote AI**, **OneNote Copilot** — verrouillés dans leurs écosystèmes.

## 🔐 Sécurité

- **PAPERLESS_API_TOKEN** : ce token donne accès à **tous** vos documents Paperless. Créez un token dédié à Paperless-AI (admin > API Tokens), **ne réutilisez pas** votre token admin personnel.
- **Choix du provider LLM** : si vous utilisez Ollama en local, **aucune donnée ne quitte votre réseau**. Avec OpenAI, GPT-4 reçoit le texte OCR de **chaque document** (factures, contrats, données médicales potentielles). Lisez les CGU et chiffrez les volumes.
- **URLs internes** : `http://paperless-webserver:8000` doit être sur un réseau Docker **interne**, jamais exposé publiquement.
- **Pas d'auth par défaut sur l'UI** : protégez `/8085` derrière un reverse-proxy authentifié (Authelia, oauth2-proxy, Authentik) ou un VPN (Tailscale/WireGuard). Cf. [[securisation-home-lab]].
- **Backups** : le volume `paperless-ai-data` stocke l'index ChromaDB — sauvegardez-le avec [[app-restic]] ou [[app-borg]] en même temps que votre base Paperless.
- **Désactivation RAG** : si vous n'utilisez que l'auto-tagging, désactivez l'image RAG (`paperless-ai-rag`) pour économiser 1 Go de RAM.

## 📚 Ressources

- [GitHub clusterzx/paperless-ai](https://github.com/clusterzx/paperless-ai)
- [Wiki d'installation](https://github.com/clusterzx/paperless-ai/wiki/2.-Installation)
- [Paperless-ngx](https://github.com/paperless-ngx/paperless-ngx)
- [Ollama](https://ollama.com/)
- [Démo vidéo Paperless-ngx + Local AI](https://www.youtube.com/watch?v=NMAwHjleqHg)

## Pages Liées
- [[cat-artificial-intelligence]] — Catégorie AI
- [[app-paperless-ngx]] — GED de base (prérequis)
- [[app-ollama]] — Backend LLM local
- [[app-restic]] — Backup des volumes
- [[recettes-docker-compose]] — Templates Docker
- [[securisation-home-lab]] — Reverse proxy, tokens