paperless-gpt

_{💡 由Icereed维护。自豪地得到BubbleTax.de的支持——为德国Interactive Brokers交易员提供自动化、符合BMF标准的税务报告。}

paperless-gpt 可与 paperless-ngx 无缝配合，生成 AI驱动的文档标题 和 标签，从而为您节省数小时的手动分类时间。虽然其他工具也可能提供AI聊天功能，但 paperless-gpt 的独特之处在于它通过 LLM增强OCR技术 来确保高精度，即使面对复杂的扫描件也能游刃有余。如果您渴望更高级的文本提取和轻松的文档管理，那么这就是您的解决方案。

https://github.com/user-attachments/assets/bd5d38b9-9309-40b9-93ca-918dfa4f3fd4

❤️ 支持这个项目
如果 paperless-gpt 正在帮助您整理文档并节省时间，请考虑 赞助其开发。您的支持将有助于持续改进和维护！

核心亮点

1. LLM增强型OCR
   利用大型语言模型（OpenAI或Ollama）实现 优于传统OCR 的效果——将杂乱或低质量的扫描件转化为具有上下文理解能力的高质量文本。

2. 使用专业的AI OCR服务

   • LLM OCR: 使用OpenAI或Ollama从图像中提取文本。
   • Google Document AI: 利用Google强大的Document AI进行OCR任务。
   • Azure Document Intelligence: 使用微软的企业级OCR解决方案。
   • Docling Server: 自托管的OCR和文档转换服务

3. 自动标题、标签及创建日期生成
   不再需要猜测。让AI完成命名和分类工作。您可以轻松查看建议，并在必要时进行调整。

4. 支持Ollama中的推理模型
   通过使用像qwen3:8b这样的推理模型，可以显著提高准确性。这是隐私与性能之间的完美平衡！当然，如果您有足够的GPU或NPU，更大的模型将进一步提升体验。

5. 自动对应方生成
   自动识别并从您的文档中生成对应方信息，使跟踪和组织通信更加便捷。

6. 自动自定义字段生成
   从您的文档中提取并填充自定义字段。您可以配置要提取哪些字段以及如何填写它们。此功能必须在设置中启用，并且至少选择一个自定义字段才能生效。提供三种写入模式：

   • 追加：这是最安全的选项：仅添加文档上尚不存在的新字段。绝不会覆盖现有字段，即使该字段为空。
   • 更新：添加新字段，并用新建议覆盖现有字段。文档上没有新建议的字段将保持不变。
   • 替换：删除文档上所有现有的自定义字段，并完全用建议的字段替换。

7. 可搜索且可选中的PDF
   生成带有透明文本层的PDF，这些文本层精确地位于每个单词之上，使您的文档既可搜索又可选中，同时保留原始外观。

8. 广泛的自定义功能

   • 通过Web界面自定义提示词：您可以在“设置”菜单下的Web界面中直接调整和管理用于标题、标签、对应方等的所有AI提示词。应用程序采用安全的default_prompts和prompts目录结构，确保您的自定义持久化。
   • 标记方式：您可以决定文档是手动标记、自动标记，还是通过基于OCR的工作流来标记。
   • PDF处理：配置如何处理经过OCR增强的PDF文件，可以选择本地保存或上传到paperless-ngx。

9. 简单的Docker部署
   只需几个环境变量，即可快速启动！与paperless-ngx一起使用Compose文件部署，操作简单快捷。

10. 统一的Web界面

    • 手动审核：批准或调整AI的建议。
    • 自动处理：您只需关注边缘情况，其余工作将由系统自动完成。

11. 临时文档分析 使用自定义提示词对选定的文档进行临时分析。快速获取洞察、摘要，或一次性从多份文档中提取特定信息。

目录

• paperless-gpt
  • 关键亮点
  • 目录
  • 开始使用
    • 先决条件
    • 安装
      • Docker Compose
      • 手动设置
  • OCR 提供商
    • 1. 基于 LLM 的 OCR（默认）
    • 2. Azure Document Intelligence
    • 3. Google Document AI
    • 4. Docling Server
  • OCR 处理模式
    • 图像模式（默认）
    • PDF 模式
    • 整 PDF 模式
    • 提供商兼容性
    • 现有 OCR 检测
  • 增强的 OCR 功能
    • PDF 文本层生成
    • 本地文件保存
    • PDF 上传到 paperless-ngx
    • 元数据复制限制
    • 安全特性
    • 使用建议
  • 配置
    • 环境变量
    • 自定义提示模板
      • 模板变量
  • 基于 LLM 的 OCR：亲自比较
    • 示例 1
    • 示例 2
    • 工作原理
  • 使用方法
  • 故障排除
    • 使用本地 LLM
      • 令牌管理
    • PDF 处理问题
    • 自定义字段生成问题
  • 贡献
  • 支持该项目
  • 许可证
  • 星标历史
  • 免责声明

开始使用

先决条件

• 已安装 Docker。
• 运行中的 paperless-ngx 实例。
• 可访问 LLM 提供商：
  • OpenAI：具有 gpt-4o 或 gpt-3.5-turbo 等模型的 API 密钥。
  • Ollama：运行中的 Ollama 服务器，配备如 qwen3:8b 等模型。

安装

Docker Compose

以下是一个 docker-compose.yml 示例，用于将 paperless-gpt 与 paperless-ngx 一起启动：

services:
  paperless-ngx:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    # ... (您现有的 paperless-ngx 配置)

  paperless-gpt:
    # 使用以下任一镜像源：
    image: icereed/paperless-gpt:latest # Docker Hub
    # image: ghcr.io/icereed/paperless-gpt:latest  # GitHub Container Registry
    environment:
      PAPERLESS_BASE_URL: "http://paperless-ngx:8000"
      PAPERLESS_API_TOKEN: "your_paperless_api_token"
      PAPERLESS_PUBLIC_URL: "http://paperless.mydomain.com" # 可选
      MANUAL_TAG: "paperless-gpt" # 可选，默认值：paperless-gpt
      AUTO_TAG: "paperless-gpt-auto" # 可选，默认值：paperless-gpt-auto
      # LLM 配置 - 选择其中一种：

      # 选项 1：标准 OpenAI
      LLM_PROVIDER: "openai"
      LLM_MODEL: "gpt-4o"
      OPENAI_API_KEY: "your_openai_api_key"

      # 选项 2：Mistral
      # LLM_PROVIDER: "mistral"
      # LLM_MODEL: "mistral-large-latest"
      # MISTRAL_API_KEY: "your_mistral_api_key"

      # 选项 3：Azure OpenAI
      # LLM_PROVIDER: "openai"
      # LLM_MODEL: "your-deployment-name"
      # OPENAI_API_KEY: "your_azure_api_key"
      # OPENAI_API_TYPE: "azure"
      # OPENAI_BASE_URL: "https://your-resource.openai.azure.com"

      # 选项 4：Ollama（本地）
      # LLM_PROVIDER: "ollama"
      # LLM_MODEL: "qwen3:8b"
      # OLLAMA_HOST: "http://host.docker.internal:11434"
      # OLLAMA_CONTEXT_LENGTH: "8192" # 设置 Ollama 的 NumCtx（上下文窗口）
      # TOKEN_LIMIT: 1000 # 建议用于较小的模型

      # 选项 5：Anthropic/Claude
      # LLM_PROVIDER: "anthropic"
      # LLM_MODEL: "claude-sonnet-4-5"
      # ANTHROPIC_API_KEY: "your_anthropic_api_key"

      # 可选 LLM 设置
      # LLM_LANGUAGE: "English" # 可选，默认为英语

      # OCR 配置 - 选择其中一种：
      # 选项 1：基于 LLM 的 OCR
      OCR_PROVIDER: "llm" # 默认 OCR 提供者
      VISION_LLM_PROVIDER: "ollama" # openai、ollama、mistral 或 anthropic
      VISION_LLM_MODEL: "minicpm-v" # minicpm-v（ollama）或 gpt-4o（openai）或 claude-sonnet-4-5（anthropic/claude）
      OLLAMA_HOST: "http://host.docker.internal:11434" # 如果使用 Ollama

      # OCR 处理模式
      OCR_PROCESS_MODE: "image" # 可选，默认为 image，其他选项：pdf、whole_pdf
      PDF_SKIP_EXISTING_OCR: "false" # 可选，跳过已存在 OCR 的 PDF 文件

      # 选项 2：Google Document AI
      # OCR_PROVIDER: 'google_docai'       # 使用 Google Document AI
      # GOOGLE_PROJECT_ID: 'your-project'  # 您的 GCP 项目 ID
      # GOOGLE_LOCATION: 'us'              # Document AI 区域
      # GOOGLE_PROCESSOR_ID: 'processor-id' # 您的处理器 ID
      # GOOGLE_APPLICATION_CREDENTIALS: '/app/credentials.json' # 服务账号密钥路径

      # 选项 3：Azure Document Intelligence
      # OCR_PROVIDER: 'azure'              # 使用 Azure Document Intelligence
      # AZURE_DOCAI_ENDPOINT: 'your-endpoint' # 您的 Azure 端点 URL
      # AZURE_DOCAI_KEY: 'your-key'        # 您的 Azure API 密钥
      # AZURE_DOCAI_MODEL_ID: 'prebuilt-read' # 可选，默认为 prebuilt-read
      # AZURE_DOCAI_TIMEOUT_SECONDS: '120'  # 可选，默认为 120 秒
      # AZURE_DOCAI_OUTPUT_CONTENT_FORMAT: 'text' # 可选，默认为 'text'，另一个有效选项是 'markdown'
      # 'markdown' 需要使用 'prebuilt-layout' 模型

      # 增强 OCR 功能
      CREATE_LOCAL_HOCR: "false" # 可选，保存 hOCR 文件到本地
      LOCAL_HOCR_PATH: "/app/hocr" # 可选，hOCR 文件的保存路径
      CREATE_LOCAL_PDF: "false" # 可选，保存增强后的 PDF 到本地
      LOCAL_PDF_PATH: "/app/pdf" # 可选，PDF 文件的保存路径
      PDF_UPLOAD: "false" # 可选，将增强后的 PDF 上传到 paperless-ngx
      PDF_REPLACE: "false" # 可选且危险，上传后会删除原始文件
      PDF_COPY_METADATA: "true" # 可选，复制原始文档的元数据
      PDF_OCR_TAGGING: "true" # 可选，为处理过的文档添加标签
      PDF_OCR_COMPLETE_TAG: "paperless-gpt-ocr-complete" # 可选，标签名称

      # 选项 4：Docling Server
      # OCR_PROVIDER: 'docling'              # 使用 Docling 服务器
      # DOCLING_URL: 'http://your-docling-server:port' # 您的 Docling 实例的 URL
      # DOCLING_IMAGE_EXPORT_MODE: "placeholder" # 可选，默认为 "embedded"
      # DOCLING_OCR_PIPELINE: "standard" # 可选，默认为 "vlm"
      # DOCLING_OCR_ENGINE: "easyocr" # 可选，默认为 "easyocr"（仅在 `DOCLING_OCR_PIPELINE` 设置为 'standard' 时使用）


      AUTO_OCR_TAG: "paperless-gpt-ocr-auto" # 可选，默认为 paperless-gpt-ocr-auto
      OCR_LIMIT_PAGES: "5" # 可选，默认为 5。设置为 0 表示无限制。
      LOG_LEVEL: "info" # 可选：debug、warn、error
    volumes:
      - ./prompts:/app/prompts # 挂载 prompts 目录
      # 对于 Google Document AI：
      - ${HOME}/.config/gcloud/application_default_credentials.json:/app/credentials.json
      # 对于本地 hOCR 和 PDF 保存：
      - ./hocr:/app/hocr # 仅当 CREATE_LOCAL_HOCR 为 true 时
      - ./pdf:/app/pdf # 仅当 CREATE_LOCAL_PDF 为 true 时
    ports:
      - "8080:8080"
    depends_on:
      - paperless-ngx

实用提示：请将占位符替换为实际值，如果出现异常情况，请查看日志。

手动安装

1. 克隆仓库

   git clone https://github.com/icereed/paperless-gpt.git
   cd paperless-gpt
   

2. 创建 prompts 目录

   mkdir prompts
   

3. 构建 Docker 镜像

   docker build -t paperless-gpt .
   

4. 运行容器

   docker run -d \
     -e PAPERLESS_BASE_URL='http://your_paperless_ngx_url' \
     -e PAPERLESS_API_TOKEN='your_paperless_api_token' \
     -e LLM_PROVIDER='openai' \
     -e LLM_MODEL='gpt-4o' \
     -e OPENAI_API_KEY='your_openai_api_key' \
     -e LLM_LANGUAGE='English' \
     -e VISION_LLM_PROVIDER='ollama' \
     -e VISION_LLM_MODEL='minicpm-v' \
     -e LOG_LEVEL='info' \
     -v $(pwd)/prompts:/app/prompts \
     -p 8080:8080 \
     paperless-gpt
   

OCR 提供商

有关各提供商的详细文档：

• Mistral AI 集成

paperless-gpt 支持四种不同的 OCR 提供商，每种都有其独特的优势和功能：

1. 基于 LLM 的 OCR（默认）

• 主要特点：
  • 使用具备视觉能力的 LLM，如 gpt-4o 或 MiniCPM-V
  • 对复杂布局和困难扫描具有高精度
  • 上下文感知的文本识别
  • 具备自我纠正 OCR 错误的能力
• 适用场景：
  • 复杂或不寻常的文档布局
  • 质量较差的扫描件
  • 包含多种语言的文档
• 配置：

  OCR_PROVIDER: "llm"
  VISION_LLM_PROVIDER: "openai" # 或 "ollama"
  VISION_LLM_MODEL: "gpt-4o" # 或 "minicpm-v"
  

2. Azure Document Intelligence

• 核心功能：
  • 企业级 OCR 解决方案
  • 针对常见文档类型的预构建模型
  • 保留版面布局和表格检测
  • 处理速度快
• 最适合场景：
  • 商务文档和表单
  • 大量文档处理
  • 需要版面分析的文档
• 配置示例：

  OCR_PROVIDER: "azure"
  AZURE_DOCAI_ENDPOINT: "https://your-endpoint.cognitiveservices.azure.com/"
  AZURE_DOCAI_KEY: "your-key"
  AZURE_DOCAI_MODEL_ID: "prebuilt-read" # 可选
  AZURE_DOCAI_TIMEOUT_SECONDS: "120" # 可选
  AZURE_DOCAI_OUTPUT_CONTENT_FORMAT:
    "text" # 可选，默认为文本，另一个有效选项是 'markdown'
    # 'markdown' 需要使用 'prebuilt-layout' 模型
  

3. Google Document AI

• 核心功能：
  • 企业级 OCR/HTR 解决方案
  • 专用文档处理器
  • 强大的表单字段检测能力
  • 多语言支持
  • 对结构化文档具有高精度
  • 独家 hOCR 生成，用于创建带有文本层的可搜索 PDF
  • 唯一支持增强 PDF 生成功能的提供商
• 最适合场景：
  • 表单和结构化文档
  • 包含表格的文档
  • 多语言文档
  • 手写文本（HTR）
• 配置示例：

  OCR_PROVIDER: "google_docai"
  GOOGLE_PROJECT_ID: "your-project"
  GOOGLE_LOCATION: "us"
  GOOGLE_PROCESSOR_ID: "processor-id"
  CREATE_LOCAL_HOCR: "true" # 可选，用于生成 hOCR 文件
  LOCAL_HOCR_PATH: "/app/hocr" # 可选，默认路径
  CREATE_LOCAL_PDF: "true" # 可选，用于将 OCR 应用到 PDF
  LOCAL_PDF_PATH: "/app/pdf" # 可选，默认路径
  

4. Docling Server

• 核心功能：
  • 自托管的 OCR 和文档转换服务
  • 支持多种输入和输出格式（包括文本）
  • 利用多个 OCR 引擎（EasyOCR、Tesseract 等）
  • 可在本地或私有网络中运行
• 最适合场景：
  • 偏好自托管解决方案的用户
  • 数据隐私至关重要的环境
  • 处理各种类型的文档
• 配置示例：

  OCR_PROVIDER: "docling"
  DOCLING_URL: "http://your-docling-server:port"
  DOCLING_IMAGE_EXPORT_MODE: "placeholder" # 可选，默认为 "embedded"
  DOCLING_OCR_PIPELINE: "standard" # 可选，默认为 "vlm"
  DOCLING_OCR_ENGINE: "macocr" # 可选，默认为 "easyocr"（仅当 `DOCLING_OCR_PIPELINE 设置为 'standard' 时使用）
  

OCR 处理模式

paperless-gpt 提供了不同的文档处理方式，可根据您的需求和 OCR 提供商的能力灵活选择：

图像模式（默认）

• 工作原理：在处理前将 PDF 页面转换为图像
• 最适合场景：与所有 OCR 提供商兼容。
• 配置示例：OCR_PROCESS_MODE: "image"

PDF 模式

• 工作原理：直接处理 PDF 页面，无需转换为图像
• 最适合场景：保留 PDF 特性，某些提供商可能处理速度更快且准确性更高
• 配置示例：OCR_PROCESS_MODE: "pdf"

整个 PDF 模式

• 工作原理：一次性处理整个 PDF 文档
• 最适合场景：适合能够高效处理多页文档的提供商，减少 API 调用次数
• 配置示例：OCR_PROCESS_MODE: "whole_pdf"
• 注意：处理大型 PDF 文件可能会达到 OCR 提供商的 API 使用上限。如果遇到大型文档问题，建议切换到“pdf”模式，该模式会逐页处理。

各提供商支持的处理模式

不同 OCR 提供商支持的处理模式有所不同：

重要提示：paperless-gpt 会在启动时验证您的配置，并阻止不支持的模式与提供商组合。如果您为特定提供商指定了不支持的模式，应用程序将无法启动，并显示明确的错误信息。

现有 OCR 检测

在使用 PDF 或整个 PDF 模式时，您可以启用现有 OCR 的自动检测功能：

environment:
  OCR_PROCESS_MODE: "pdf" # 或 "whole_pdf"
  PDF_SKIP_EXISTING_OCR: "true" # 如果 PDF 中已存在 OCR，则跳过处理

注意：并非所有 OCR 提供商都支持所有处理模式。有些提供商在某些模式下表现更好。根据提供商的不同，以 PDF 模式处理可能比以图像模式处理消耗更多的或更少的 API 调用次数。处理结果会因文档复杂度和提供商能力而异。建议尝试不同的模式，以找到最适合您特定文档和 OCR 提供商的方式。

增强的 OCR 功能

paperless-gpt 包含强大的 OCR 增强功能，超越了基本的文本提取：

重要提示：PDF 文本层生成和 hOCR 功能目前仅支持 Google Document AI 作为 OCR 提供商。这些功能在使用基于 LLM 的 OCR 或 Azure Document Intelligence 时不可用。

PDF 文本层生成

• 可搜索且可选中的 PDF：创建带有透明文本叠加层的 PDF，精确地覆盖文档中的每个单词
• hOCR 集成：利用 hOCR 格式（基于 HTML 的 OCR 表示形式）来保持精确的文本位置
• 提升文档质量：使文档既可搜索又可选择，同时保留原始外观
• 需要 Google Document AI：这些功能依赖于 Google Document AI 生成包含准确单词位置的 hOCR 数据的能力。

本地文件保存

paperless-gpt 可以将 hOCR 文件和增强后的 PDF 本地保存：

environment:
  # 启用本地文件保存
  CREATE_LOCAL_HOCR: "true" # 将 hOCR 文件本地保存
  CREATE_LOCAL_PDF: "true" # 将生成的 PDF 文件本地保存
  LOCAL_HOCR_PATH: "/app/hocr" # 保存 hOCR 文件的路径
  LOCAL_PDF_PATH: "/app/pdf" # 保存 PDF 文件的路径
volumes:
  # 挂载卷以便从主机访问文件
  - ./hocr_files:/app/hocr
  - ./pdf_files:/app/pdf

注意：您必须在 Docker 配置中将这些目录挂载为卷，才能从主机系统访问生成的文件。

将 PDF 上传至 paperless-ngx

由于 paperless-ngx 的 API 存在限制，无法直接用 OCR 增强后的版本更新现有文档。作为 workaround，paperless-gpt 可以：

1. 将增强后的 PDF 作为新文档上传
2. 将元数据从原文档复制到新文档
3. 可选地删除原文档

environment:
  # PDF 上传配置
  PDF_UPLOAD: "true" # 将处理后的 PDF 上传至 paperless-ngx
  PDF_COPY_METADATA: "true" # 从原文档复制元数据到新文档
  PDF_REPLACE: "false" # 是否删除原文档（请谨慎使用！）
  PDF_OCR_TAGGING: "true" # 添加标签以标记已进行 OCR 处理的文档
  PDF_OCR_COMPLETE_TAG: "paperless-gpt-ocr-complete" # 用于标记已 OCR 处理文档的标签

⚠️ 警告 ⚠️
将 PDF_REPLACE: "true" 设置后，在上传增强版本之后会删除原文档。此操作不可撤销，若上传或元数据复制过程中出现任何问题，可能导致数据丢失。请务必谨慎使用！

元数据复制的限制

在将元数据从原文档复制到新文档时，paperless-gpt 会尝试复制以下内容：

• 文档标题
• 标签（包括添加 OCR 完成标签）
• 收件人信息
• 创建日期

然而，由于 paperless-ngx 的 API 限制，部分元数据无法被复制：

• 文档 ID（新文档始终会获得一个新的 ID）
• 添加日期（将反映当前的上传日期）
• 修改日期
• 其他 paperless-ngx 插件可能添加的自定义字段
• 备注和注释

安全特性

为防止意外生成不完整文档，paperless-gpt 提供了多项安全措施：

1. 页数检查：如果使用 OCR_LIMIT_PAGES 参数仅处理部分页面（出于速度或资源考虑），而实际处理的页数少于原文档的总页数，则会完全跳过 PDF 生成步骤。

environment:
  OCR_LIMIT_PAGES: "5" # 限制 OCR 只处理前 5 页，设置为 0 表示无限制

2. OCR 完成标记：已完成 OCR 处理的文档可自动打上特殊标签，从而避免重复处理。

3. 跳过处理：若文档已带有 OCR 完成标签，则会自动跳过处理流程。

使用建议

为获得最佳的 OCR 增强效果：

1. 初次测试：请先将 PDF_REPLACE: "false"，待确认流程对您的文档运行良好后再启用替换功能。

2. 定期备份：在启用文档替换功能之前，请确保已对 paperless-ngx 数据库及文档进行备份。

3. 流程管理：对于大型文档，建议将 OCR_LIMIT_PAGES: "0"，以确保所有页面都被处理，尽管这会花费更多时间。

4. 本地副本：启用本地文件保存功能（CREATE_LOCAL_HOCR 和 CREATE_LOCAL_PDF），以便额外保留增强文件的副本。

5. 标签策略：使用 OCR 完成标签（PDF_OCR_COMPLETE_TAG）来跟踪哪些文档已经完成处理。

配置

环境变量

注意：使用 Ollama 时，请确保 Ollama 服务器正在运行，并且 paperless-gpt 容器可以访问该服务器。

自定义提示模板

paperless-gpt 的灵活 提示模板 允许您定义 AI 的响应方式。尽管您仍然可以手动管理文件，但推荐的自定义提示方法是通过 Web UI 中的 设置 页面进行。

该应用使用两个目录来管理模板：

• default_prompts/：包含内置的默认模板。这些模板不应被修改。
• prompts/：您的工作目录。首次运行时，默认模板会被复制到这里。所有在 UI 中进行的编辑都会保存到此目录下的文件中。

为确保您的自定义提示在容器重启后仍然保留，您必须在 docker-compose.yml 文件中将 prompts 目录挂载为卷：

volumes:
  # 这对于保存您的自定义提示至关重要！
  - ./prompts:/app/prompts

应用程序会在您通过 UI 保存模板后以及启动时立即重新加载模板，因此无需重启即可使更改生效。

模板变量

每个模板都可以访问特定的变量：

title_prompt.tmpl:

• {{.Language}} - 目标语言（例如，“英语”）
• {{.Content}} - 文档内容文本
• {{.Title}} - 原始文档标题

tag_prompt.tmpl:

• {{.Language}} - 目标语言
• {{.AvailableTags}} - paperless-ngx 中现有的标签列表
• {{.OriginalTags}} - 文档当前的标签
• {{.Title}} - 文档标题
• {{.Content}} - 文档内容文本

ocr_prompt.tmpl:

• {{.Language}} - 目标语言

correspondent_prompt.tmpl:

• {{.Language}} - 目标语言
• {{.AvailableCorrespondents}} - 现有的通信方列表
• {{.BlackList}} - 被列入黑名单的通信方名称列表
• {{.Title}} - 文档标题
• {{.Content}} - 文档内容文本

created_date_prompt.tmpl:

• {{.Language}} - 目标语言
• {{.Content}} - 文档内容文本

custom_field_prompt.tmpl:

• {{.DocumentType}} - 文档在 paperless-ngx 中的类型名称。
• {{.CustomFieldsXML}} - 一个 XML 字符串，列出了在设置中选择用于处理的自定义字段。
• {{.Title}} - 文档标题
• {{.CreatedDate}} - 文档的创建日期
• {{.Content}} - 文档内容文本

模板使用 Go 的 text/template 语法。paperless-gpt 会在 UI 保存后以及启动时自动重新加载模板更改。

基于 LLM 的 OCR：亲自比较

La Grande Recre

Gentre Gommercial 1'Esplanade
1349 LOLNAIN LA NEWWE
TA BERBOGAAL Tel =. 010 45,96 12
Ticket 1440112 03/11/2006 a 13597:
4007176614518. DINOS. TYRAMNESA
TOTAET.T.LES
ReslE par Lask-Euron
Rencu en Cash Euro
V.14.6 -Hotgese = VALERTE
TICKET A-GONGERVER PORR TONT. EEHANGE
HERET ET A BIENTOT

La Grande Récré
Centre Commercial l'Esplanade
1348 LOUVAIN LA NEUVE
TVA 860826401 Tel : 010 45 95 12
Ticket 14421 le 03/11/2006 à 15:27:18
4007176614518 DINOS TYRANNOSA 14.90
TOTAL T.T.C. 14.90
Réglé par Cash Euro 50.00
Rendu en Cash Euro 35.10
V.14.6 Hôtesse : VALERIE
TICKET A CONSERVER POUR TOUT ECHANGE
MERCI ET A BIENTOT

Invoice Number: 1-996-84199

Fed: Invoica Date: Sep01, 2014
Accaunt Number: 1334-8037-4
Page: 1012

Fod£x Tax ID 71.0427007

IRISINC
SHARON ANDERSON
4731 W ATLANTIC AVE STE BI
DELRAY BEACH FL 33445-3897 ’ a
Invoice Questions?

Bing, ‚Account Shipping Address: Contact FedEx Reı

ISINC
4731 W ATLANTIC AVE Phone: (800) 622-1147 M-F 7-6 (CST)
DELRAY BEACH FL 33445-3897 US Fax: (800) 548-3020

Internet: www.fedex.com

Invoice Summary Sep 01, 2014

FodEx Ground Services
Other Charges 11.00
Total Charges 11.00 Da £
>
polo) Fz// /G
TOTAL THIS INVOICE .... usps 11.00 P 2/1 f

‘The only charges accrued for this period is the Weekly Service Charge.

The Fedix Ground aceounts teferencedin his involce have been transteired and assigned 10, are owned by,andare payable to FedEx Express:

To onsurs propor credit, plasa raturn this portion wirh your payment 10 FodEx
‚Please do not staple or fold. Ploase make your chack payablı to FedEx.

[TI For change ol address, hc har and camphat lrm or never ide

Remittance Advice
Your payment is due by Sep 16, 2004

Number Number Dus

1334803719968 41993200000110071

AT 01 0391292 468448196 A**aDGT

IRISINC Illallun elalalssollallansdHilalellund
SHARON ANDERSON

4731 W ATLANTIC AVE STEBI FedEx

DELRAY BEACH FL 334453897 PO. Box 94516

PALATINE IL 60094-4515

FedEx.                                                                                      Invoice Number: 1-996-84199
                                                                                           Invoice Date: Sep 01, 2014
                                                                                           Account Number: 1334-8037-4
                                                                                           Page: 1 of 2
                                                                                           FedEx Tax ID: 71-0427007

I R I S INC
SHARON ANDERSON
4731 W ATLANTIC AVE STE B1
DELRAY BEACH FL 33445-3897
                                                                                           Invoice Questions?
Billing Account Shipping Address:                                                          Contact FedEx Revenue Services
I R I S INC                                                                                Phone: (800) 622-1147 M-F 7-6 (CST)
4731 W ATLANTIC AVE                                                                        Fax: (800) 548-3020
DELRAY BEACH FL 33445-3897 US                                                              Internet: www.fedex.com

Invoice Summary Sep 01, 2014

FedEx Ground Services
Other Charges                                                                 11.00

Total Charges .......................................................... USD $          11.00

TOTAL THIS INVOICE .............................................. USD $                 11.00

The only charges accrued for this period is the Weekly Service Charge.

                                                                                           RECEIVED
                                                                                           SEP _ 8 REC'D
                                                                                           BY: _

                                                                                           posted 9/21/14

The FedEx Ground accounts referenced in this invoice have been transferred and assigned to, are owned by, and are payable to FedEx Express.

To ensure proper credit, please return this portion with your payment to FedEx.
Please do not staple or fold. Please make your check payable to FedEx.

❑ For change of address, check here and complete form on reverse side.

Remittance Advice
Your payment is due by Sep 16, 2004

Invoice
Number
1-996-84199

Account
Number
1334-8037-4

Amount
Due
USD $ 11.00

133480371996841993200000110071

AT 01 031292 468448196 A**3DGT

I R I S INC
SHARON ANDERSON
4731 W ATLANTIC AVE STE B1
DELRAY BEACH FL 33445-3897

FedEx
P.O. Box 94515

Why Does It Matter?

• Traditional OCR often jumbles text from complex or low-quality scans.
• Large Language Models interpret context and correct likely errors, producing results that are more precise and readable.
• You can integrate these cleaned-up texts into your paperless-ngx pipeline for better tagging, searching, and archiving.

How It Works

• Vanilla OCR typically uses classical methods or Tesseract-like engines to extract text, which can result in garbled outputs for complex fonts or poor-quality scans.
• LLM-Powered OCR uses your chosen AI backend—OpenAI or Ollama—to interpret the image's text in a more context-aware manner. This leads to fewer errors and more coherent text.
• Google Document AI and Azure Document Intelligence provide high-accuracy OCR with advanced layout analysis.
• Enhanced PDF Generation combines OCR results with the original document to create searchable PDFs with properly positioned text layers.

Usage

1. Tag Documents

   • Add paperless-gpt tag to documents for manual processing
   • Add paperless-gpt-auto for automatic processing
   • Add paperless-gpt-ocr-auto for automatic OCR processing

2. Visit Web UI

   • Go to http://localhost:8080 (or your host) in your browser
   • Review documents tagged for processing

3. Generate & Apply Suggestions

   • Click "Generate Suggestions" to see AI-proposed titles/tags/correspondents
   • Review and approve or edit suggestions
   • Click "Apply" to save changes to paperless-ngx

4. OCR Processing

   • Tag documents with appropriate OCR tag to process them
   • If enhanced PDF features are enabled, documents will be processed accordingly:
     • For local file saving, check the configured directories for output files
     • For PDF uploads, new documents will appear in paperless-ngx with copied metadata
   • Monitor progress in the Web UI
   • Review results and apply changes

Troubleshooting

使用本地大模型

在使用本地大模型（例如通过 Ollama 提供的模型）时，可能需要调整某些设置以优化性能：

令牌管理

• 使用 TOKEN_LIMIT 环境变量来控制发送到大模型的最大令牌数。
• 对于 Ollama，设置 OLLAMA_CONTEXT_LENGTH 来控制模型的上下文窗口大小（NumCtx）。这与 TOKEN_LIMIT 是独立的，用于配置服务器端的 KV 缓存大小。如果未设置或设为 0，则使用模型默认值。请根据模型支持的窗口范围选择一个合适的值（例如 8192）。
• 如果给小型模型输入过多文本，可能会导致内容被意外截断。
• 建议从一个保守的限制值开始（如 1000 个令牌），然后根据模型的能力逐步调整。
• 将其设置为 0 可以禁用限制（请谨慎使用）。

针对小型模型的示例配置：

environment:
  TOKEN_LIMIT: "2000" # 根据你的模型上下文窗口调整
  OLLAMA_CONTEXT_LENGTH: "4096" # 控制 Ollama 的 NumCtx（上下文窗口）；未设置时将使用模型默认值
  LLM_PROVIDER: "ollama"
  LLM_MODEL: "qwen3:8b" # 或其他本地模型

常见问题及解决方法：

• 如果看到响应被截断或不完整，请尝试降低 TOKEN_LIMIT。
• 在 Ollama 中，如果出现“上下文长度超出”或内存问题，可以减少 OLLAMA_CONTEXT_LENGTH，或者选择更小的模型和上下文窗口。
• 如果处理能力受限，可以在监控性能的同时逐步提高限制。
• 对于具有更大上下文窗口的模型，可以适当增加限制，甚至完全禁用限制。

PDF 处理问题

• 如果 PDF 文件未能生成，请检查 OCR_LIMIT_PAGES 是否设置得太低，与文档的实际页数相比。
• 如果使用 CREATE_LOCAL_PDF 或 CREATE_LOCAL_HOCR 功能，请确保卷已正确挂载。
• 当使用 PDF_REPLACE: "true" 时，务必确认你已备份了最新的 paperless-ngx 数据。

自定义字段生成问题

• 功能未生效：如果自定义字段建议未生成，即使该功能已启用，也请确保在设置中至少选择了一个自定义字段。该功能需要至少选择一个字段才能知道要处理的内容。

贡献

欢迎提交 Pull 请求 和 问题报告！

1. 克隆仓库并创建分支（feature/my-awesome-update）
2. 提交更改（git commit -m "改进 X"）
3. 打开 PR

更多详情请参阅我们的 贡献指南。

支持本项目

如果 paperless-gpt 正在帮助您节省时间并简化文档管理工作，欢迎您支持其持续开发：

• GitHub Sponsors：资助项目的持续开发与维护。
• 分享您的成功案例和使用场景。
• 在 GitHub 上为本项目点赞。
• 参与代码、文档或错误报告的贡献。

您的支持将有助于确保 paperless-gpt 得到积极维护，并不断改进！

维护者注释

本项目完全开源，且将继续免费使用。
由 Icereed 维护，同时部分支持来自我的另一个项目：
👉 BubbleTax.de — 为德国 IBKR 交易员提供自动化的税务报表。
如果您是一名开发者兼交易者，不妨试试这个工具。如果不是也没关系 😊

许可证

paperless-gpt 采用 MIT 许可证 开源，您可以自由地修改和分享！

星标历史

免责声明

本项目与 paperless-ngx 官方并无关联。请自行承担使用风险。

paperless-gpt：您文档管理一直期待的基于大语言模型的助手。轻松实现智能文档标题、标签以及更高层次的 OCR 处理。

paperless-gpt 快速上手指南

paperless-gpt 是一款专为 paperless-ngx 设计的 AI 增强工具。它利用大语言模型（LLM）和多模态视觉模型，自动为文档生成精准的标题、标签、对应方及自定义字段，并提供超越传统 OCR 的文本提取能力，大幅减少人工整理文档的时间。

环境准备

在部署前，请确保满足以下前置条件：

• 运行环境：已安装并配置好 Docker 和 Docker Compose。
• 核心依赖：拥有一个正在运行的 paperless-ngx 实例。
• AI 模型服务（任选其一）：
  • OpenAI / Azure OpenAI / Anthropic / Mistral：拥有有效的 API Key。
  • Ollama（推荐本地部署）：已安装并运行 Ollama 服务，且拉取了相关模型（如 qwen3:8b 用于文本推理，minicpm-v 用于视觉 OCR）。
    • 国内用户提示：若使用 Ollama，建议通过国内镜像源加速模型下载，或自行部署本地 Ollama 服务以保障隐私和速度。

安装步骤

推荐使用 Docker Compose 将 paperless-gpt 与现有的 paperless-ngx 编排在一起。

1. 获取 paperless-ngx 的 API Token 登录你的 paperless-ngx 后台，进入设置生成一个 API Token。

2. 创建 docker-compose.yml 在你的 docker-compose 文件中添加 paperless-gpt 服务。以下是一个基于 Ollama (本地模型) 的最小化配置示例：

services:
  paperless-ngx:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    # ... (保留你原有的 paperless-ngx 配置)

  paperless-gpt:
    image: icereed/paperless-gpt:latest
    # 或者使用 GitHub 镜像: ghcr.io/icereed/paperless-gpt:latest
    environment:
      # 基础连接配置
      PAPERLESS_BASE_URL: "http://paperless-ngx:8000"
      PAPERLESS_API_TOKEN: "your_paperless_api_token_here"
      
      # LLM 配置 (用于生成标题、标签等)
      LLM_PROVIDER: "ollama"
      LLM_MODEL: "qwen3:8b"
      OLLAMA_HOST: "http://host.docker.internal:11434"
      
      # OCR 配置 (用于高精度文字识别)
      OCR_PROVIDER: "llm"
      VISION_LLM_PROVIDER: "ollama"
      VISION_LLM_MODEL: "minicpm-v"
      
      # 可选：限制 Token 数量以适应小显存
      TOKEN_LIMIT: "1000"
    depends_on:
      - paperless-ngx
    restart: unless-stopped

注意：如果你在使用 Linux 宿主机运行 Docker，host.docker.internal 可能需要替换为宿主机的实际 IP 地址，或者在 Docker 启动参数中添加 --add-host host.docker.internal:host-gateway。

3. 启动服务 在包含 docker-compose.yml 的目录下执行：

docker compose up -d

基本使用

部署完成后，无需复杂的命令行操作，主要通过 paperless-ngx 的界面进行交互。

1. 自动处理流程

默认情况下，工具会监听带有特定标签的文档。

• 手动触发：在 paperless-ngx 中给文档打上标签 paperless-gpt（可通过环境变量 MANUAL_TAG 修改），系统会自动分析该文档，生成标题、标签和建议内容。
• 自动处理：给文档打上标签 paperless-gpt-auto（可通过环境变量 AUTO_TAG 修改），系统将直接应用 AI 生成的结果而无需人工确认。

2. 审查与确认

1. 登录 paperless-ngx Web 界面。
2. 找到被标记的文档，你会看到 AI 生成的建议标题和标签。
3. 点击文档进入详情页，检查 AI 提取的内容。
4. 如果满意，点击保存/接受；如果不满意，可手动修改后保存。

3. 高级功能：自定义提示词

你可以在 paperless-gpt 自带的 Web UI 中调整 AI 的行为：

1. 访问 http://<你的服务器 IP>:8080 (默认端口，具体视容器映射而定，部分版本集成在 paperless-ngx 菜单中，请参考容器日志输出的实际地址)。
2. 进入 Settings 菜单。
3. 修改 Prompts（提示词），自定义标题生成规则、标签分类逻辑或对应方识别规则。

4. 临时分析 (Ad-hoc Analysis)

选中多个文档，通过工具提供的接口或界面功能，使用自定义 Prompt 进行批量摘要或信息提取，快速获取文档集的关键洞察。