Paperless-AI：为 Paperless-ngx 提供自动文档分析与 RAG 问答的 AI 扩展
Paperless-AI 是面向 Paperless-ngx 的 AI 文档分析扩展，可通过 OpenAI 兼容 API 或 Ollama 自动分析新文档并分配标题、标签、文档类型和对应人，同时提供基于检索增强生成（RAG）的自然语言文档问答。项目采用 MIT 许可证，支持 Docker 部署；仓库当前已停止维护，作者正在重写代码库。
社区作者 · zZz
它解决什么问题
Paperless-AI 是 Paperless-ngx 的 AI 增强扩展，主要解决文档归档后自动分类、打标签和检索的问题。
【项目定位】 Paperless-AI 使用 OpenAI 兼容 API 与 Ollama，为 Paperless-ngx 带来自动文档分类、智能标签和语义搜索能力，可实现全自动文档工作流、上下文聊天与自定义配置，全部通过直观的 Web 界面完成。
【核心功能】
- 自动化文档处理：自动检测 Paperless-ngx 中的新文档，调用 OpenAI API、Ollama 及其他兼容后端分析内容，并分配标题、标签、文档类型和对应人（correspondent）。
- RAG 智能问答：基于检索增强生成（RAG）在完整档案中进行语义检索与自然语言问答，理解完整文档上下文而非仅关键词匹配，语义记忆基于用户自己的数据。来源给出的示例提问包括：“When did I sign my rental agreement?”“What was the amount of the last electricity bill?”“Which documents mention my health insurance?”。配图 1（RAG_CHAT_DEMO）为项目给出的 RAG 聊天演示图。
- 手动处理：提供 Web 界面进行手动 AI 打标签，适合审查敏感文档时使用，入口路径为 /manual。
- 智能标签与规则：可定义规则限制哪些文档会被处理，可禁用提示词并自动应用标签，可为跟踪分类设置自定义输出标签。
步骤 5 · 界面与部署：提供响应式 Web 界面；
Docker 支持健康监控、自动重启、持久化卷与优雅关闭，最小配置即可开箱使用。配图 2（PPAI_SHOWCASE3）为项目展示截图，来源未附文字说明。
【支持的 AI 后端】 内置支持 Ollama（Mistral、Llama、Phi-3、Gemma-2）、OpenAI、DeepSeek.ai、OpenRouter.ai、Perplexity.ai、Together.ai、LiteLLM、VLLM、Fastchat、Gemini（Google）以及更多兼容服务。
【路线图要点（已完成项）】 多 AI 模型支持、多语言文档分析、标签规则与过滤、集成 RAG 的文档聊天、响应式 Web 界面。
【维护状态】 仓库当前不再维护。作者表示正在以更稳定、更新的架构重写整个代码库，但受限于只能在晚上工作，一边提供支持一边重写并不可行；同时由于 Paperless-ngx 自身即将推出官方 AI 集成，作者也不确定是否会完成重写或继续维护本仓库。
【适用对象】 已在使用 Paperless-ngx 管理扫描件/PDF 文档，希望自动完成分类、标签、对应人识别，并希望用自然语言检索个人文档档案的用户；也适合希望接入本地 Ollama 模型以兼顾隐私的用户。
【许可证】 MIT License，详见仓库 LICENS文档（来源表述为 LICENSE）。
— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。
安装 / 开始使用
以下步骤依据来源正文整理，来源未明确给出的具体镜像名、环境变量与端口等信息标注为待核验。
一、准备工作
- 已部署并可访问的 Paperless-ngx 实例（本扩展是其附加组件）。
- 准备 AI 后端访问凭据：OpenAI 兼容 API 的 API Key，或本地部署的 Ollama 服务（Ollama 支持 Mistral、Llama、Phi-3、Gemma-2）。
步骤 3
Docker 部署方式（推荐）：项目支持 Docker，具备健康监控与自动重启、持久化卷和优雅关闭，最小配置即可开箱使用。镜像名称与完整 docker run / compose 参数来源未给出，待核验，可参考仓库 Installation Wiki。
二、首次安装与初始化（关键顺序）
- 启动容器完成部署。
- 在 Web 界面中完成初始设置，填写 API keys（如 OpenAI / Ollama 等）与 preferences（偏好设置）。
注意：首次安装需要重启容器；后续更新时不需要重启建索引。
- 设置完成后必须重启容器，以构建 RAG 索引。
三、本地开发/测试方式
安装依赖
npm install启动开发/测试模式
npm run test四、使用入口
- 自动化处理：扩展会自动检测 Paperless-ngx 中的新文档并分析内容，自动分配标题、标签、文档类型和对应人。
- 手动处理：访问 /manual 路径，在 Web 界面中手动对文档进行 AI 打标签，适合审查敏感文档。
- RAG 问答：在内置聊天界面用自然语言检索与提问，例如“When did I sign my rental agreement?”。配图 1 为 RAG 聊天演示。
- 规则配置：在设置中定义规则以限制被处理的文档范围，可禁用提示词并自动应用标签，可设置自定义输出标签。
五、贡献代码流程（来源给出的命令顺序）
Fork 并克隆仓库后：
git checkout -b feature/YourFeature修改完成后：
git commit -m " Add YourFeature "git push origin feature/YourFeature然后在 GitHub 上发起 Pull Request。
六、常见问题
- 首次安装后 RAG 索引不可用：需要在完成 API keys 与 preferences 设置后重启容器来构建 RAG 索引；更新时无需此步骤。
- 项目是否仍在维护：来源明确说明该仓库当前不再维护，作者正在重写代码库，且 Paperless-ngx 官方即将内置 AI 集成，因此不保证后续更新与支持。
- 更多安装细节：请参考仓库提供的 Installation Wiki（本页未列出完整 Wiki 内容）。
- 问题反馈渠道：来源给出 Issues 与 Discord 两个社区支持入口。
