paperless-gpt 评测：用 LLM 给 paperless-ngx 文档自动起名、打标签，还能重做 OCR
Use LLMs and LLM Vision (OCR) to handle paperless-ngx - Document Digitalization powered by AI
秒懂
- 它是什么？
- paperless-gpt 是一个 Go 写的开源服务，专门配合 paperless-ngx 使用。它用 LLM 做 OCR、生成标题和标签，并提供一个 Web UI 让人工审核。本文基于 README 和仓库信息，分析它的机制、部署方式和适用边界。
- 适合谁用？
- 如果你已经在用 paperless-ngx，并且每天要处理大量扫描件、发票或信件，paperless-gpt 的 LLM OCR 和自动标题生成确实能省下不少手工整理时间。它适合愿意接受 AI 出错、并且有精力在 Web UI 里审核建议的用户。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 1 天前。
- 用什么语言写的？
- 主要是 Go（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是 paperless-ngx 的整理痛点
paperless-ngx 本身是一个文档管理系统，擅长存储和检索，但它的 OCR 和元数据生成依赖传统工具，对低质量扫描件效果有限。paperless-gpt 瞄准的是这个缝隙：用 LLM 和视觉模型来识别文字、生成标题、打标签、判断发件人，甚至填充自定义字段。它不是一个通用 AI 聊天工具，而是专门为 paperless-ngx 用户设计的辅助服务。目标用户很明确：家里或小办公室用 paperless-ngx 归档大量纸张文档的人，尤其是那些扫描件模糊、倾斜、或带有手写内容的情况。
从扫描件到可搜索 PDF 的完整链路
根据 README，paperless-gpt 的核心流程是：先从 paperless-ngx 获取文档，然后调用 OCR 提供方提取文本，再用 LLM 生成标题、标签、发件人和自定义字段，最后把结果写回 paperless-ngx。OCR 提供方有四种：默认的 LLM OCR（OpenAI 或 Ollama）、Google Document AI、Azure Document Intelligence、Docling Server。处理模式分三种：Image Mode 处理单张图片，PDF Mode 逐页处理，Whole PDF Mode 把整个 PDF 交给模型。README 强调 LLM OCR 对低质量扫描件的准确率高于传统 OCR，还提供了对比示例。PDF 文本层生成功能会把识别出的文字以透明层覆盖在原图上，使 PDF 可搜索、可选中，同时保留原始外观。
部署：Docker Compose 是主要入口
README 推荐用 Docker Compose 部署，只需设置几个环境变量。它没有给出完整的 compose 文件内容，但明确说可以跟 paperless-ngx 一起编排。手动安装方式也存在，但细节同样需要看仓库文档。关键配置项包括：选择 OCR 提供方（如 OPENAI_API_KEY 或 OLLAMA_BASE_URL）、设置 paperless-ngx 的 API 地址和认证令牌。自定义提示词模板存放在一个安全的目录结构里，包含 default_prompts 和 prompts 两层，用户可以通过 Web UI 的 Settings 菜单修改，修改会持久化。环境变量的具体名称和取值，README 没有全部列出，需要查阅仓库的配置文档。
自定义字段写入模式：三种策略的风险差异
paperless-gpt 支持自动填充自定义字段，但必须先在设置里启用并至少选定一个字段。它提供三种写入模式：Append 只添加不存在的字段，绝不覆盖已有值，即使已有值为空；Update 会覆盖已有字段，但不会删除文档上未被建议的字段；Replace 则删除所有现有自定义字段，用建议结果整体替换。这三种模式的风险等级差异很大。Append 最安全，适合首次部署试运行。Replace 风险最高，一旦 AI 输出有误，原有字段会全部丢失。README 明确建议用 Append 作为默认，这个提醒值得认真对待，因为 LLM 的输出并非百分百可靠。
本地保存与上传的取舍
OCR 处理后的 PDF 有两种去向：保存到本地，或上传回 paperless-ngx。README 提到一个已知限制：元数据复制不完整。也就是说，当生成新 PDF 时，原始文档的某些元数据可能无法保留。这会影响依赖元数据（如自定义字段、标签）的工作流。因此 README 建议用户在使用上传功能前，先测试自己的文档类型。另一个安全特性是：默认情况下，paperless-gpt 不会自动覆盖 paperless-ngx 中的原始文档，而是生成新版本或新文件。这个设计降低了误操作风险，但也意味着存储空间会增长，需要用户定期清理。
模型选择：本地 Ollama 与云端 API 的隐私权衡
paperless-gpt 支持 OpenAI 和 Ollama 两种 LLM 后端。Ollama 可以本地运行，比如 README 中提到的 qwen3:8b 这类推理模型。作者声称推理模型能显著提升准确率，同时兼顾隐私。但这个说法需要用户自己验证，因为实际效果取决于文档语言、清晰度和模型大小。如果你处理的是敏感文件（如税单、医疗记录），本地 Ollama 是更稳妥的选择，但需要足够的 GPU 或 NPU。云端 API（OpenAI、Azure、Google）则更方便，但文档内容会离开你的网络。README 没有提供任何关于数据保留政策的说明，用户需要自行查阅各提供方的条款。
维护成本与许可证现实
项目采用 MIT 许可证，使用上限制很少，可以自由修改和商用。维护方面，仓库最近一次推送是 2026 年 9 月，v0.27.0 发布于 2026 年 7 月，说明项目仍在活跃迭代。但从 v0.26.0 到 v0.27.0 的版本跨度中，release notes 标题带有“Resilience Expansion”和“Clarity Expansion”这类措辞，暗示可能有破坏性变更或配置迁移。升级前必须阅读对应版本的 release notes。另外，项目依赖外部 OCR 服务和 LLM API，这些服务的价格和可用性会变化，不是项目本身能控制的。如果你使用 Docling Server 这类自托管方案，还需要额外维护一个服务实例。
编辑结论
如果你已经在用 paperless-ngx，并且每天要处理大量扫描件、发票或信件，paperless-gpt 的 LLM OCR 和自动标题生成确实能省下不少手工整理时间。它适合愿意接受 AI 出错、并且有精力在 Web UI 里审核建议的用户。不适合对数据隐私极度敏感、或者完全不想碰 Docker 和 API 密钥的人。在采用前，先确认你的 paperless-ngx 版本兼容性，检查 paperless-gpt 的 release notes 中是否有针对该版本的破坏性变更，并测试至少一个低质量扫描样本，用你自己的文档比较传统 OCR 和 LLM OCR 的输出差异。
社区笔记