paperless-gpt

paperless-gpt 与 paperless-ngx 配合生成 AI 驱动的文档标题和标签,为自托管而构建,并保持免费和开源。

核验日期2026-11-01

核心信息

以下信息由程序从官方接口读取，不经模型改写。

仓库地址: https://github.com/icereed/paperless-gpt
许可证: MIT
语言: Go
维护方: icereed
核验日期: 2026-11-01

它是什么

paperless-gpt 与 paperless-ngx 配合,生成 AI 驱动的文档标题和标签。paperless-gpt 为自托管而构建,并保持免费和开源。paperless-gpt 完全可自托管,并以 MIT 许可证免费提供。本项目与 paperless-ngx 没有官方隶属关系。

主要能力

配合 paperless-ngx 3.0,可搜索 PDF 能作为同一文档的新版本添加,从而保留其 ID、标签、自定义字段和备注,原件作为上一版本继续可用。
AI 工作流是放在提示词旁边的普通文件。
手动审核功能可以批准或调整 AI 的建议。
临时文档分析功能可以使用自定义提示词,对选定的一组文档进行分析。

怎么上手

自托管需要已安装 Docker。
paperless-gpt 需要一个运行中的 paperless-ngx 实例,该实例已针对 2.20.x 版本系列和 3.0.0 beta 测试。
使用 OpenAI 时,需要带有 gpt-4o 或 gpt-3.5-turbo 等模型的 API 密钥。
使用 Ollama 时,需要一个运行中的 Ollama 服务器,并带有 qwen3:8b 等模型。

摘自 README · yaml

services:
  paperless-ngx:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    # ... (your existing paperless-ngx config)

  paperless-gpt:
    # Use one of these image sources:
    image: icereed/paperless-gpt:latest # Docker Hub (upstream)
    # image: ghcr.io/icereed/paperless-gpt:latest  # GitHub Container Registry (upstream)
    # image: ghcr.io/hensing/paperless-gpt:latest  # This fork's GHCR image
    environment:
      PAPERLESS_BASE_URL: "http://paperless-ngx:8000"
      PAPERLESS_API_TOKEN: "your_paperless_api_token"
      PAPERLESS_PUBLIC_URL: "http://paperless.mydomain.com" # Optional
      MANUAL_TAG: "paperless-gpt" # Optional, default: paperless-gpt
      AUTO_TAG: "paperless-gpt-auto" # Optional, default: paperless-gpt-auto
      FAIL_TAG: "paperless-gpt-failed" # Optional, default: paperless-gpt-failed. Applied to documents whose update is rejected by paperless-ngx or whose OCR keeps failing (see OCR_MAX_RETRIES), so they don't get re-processed in a loop. Auto-created at startup.
      # LLM Configuration - Choose one:

      # Option 1: Standard OpenAI
      LLM_PROVIDER: "openai"
      LLM_MODEL: "gpt-4o"
      OPENAI_API_KEY: "your_openai_api_key"

      # Option 2: Mistral
      # LLM_PROVIDER: "mistral"
      # LLM_MODEL: "mistral-large-latest"
      # MISTRAL_API_KEY: "your_mistral_api_key"

      # Option 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"

      # Option 4: Ollama (Local)
      # LLM_PROVIDER: "ollama"
      # LLM_MODEL: "qwen3:8b"
      # OLLAMA_HOST: "http://host.docker.internal:11434"
      # OLLAMA_CONTEXT_LENGTH: "8192" # Sets Ollama NumCtx (context window)
      # LLM_MAX_TOKENS: "256" # Sets Ollama num_predict (output-token budget)
      # OLLAMA_KEEP_ALIVE: "10m" # Keeps the model loaded between metadata requests
      # OLLAMA_THINK: "false" # true/false, or low/medium/high for supported models
      # OLLAMA_HEADERS: "Authorization=Bearer mytoken" # Optional headers for reverse-proxy auth
      # TOKEN_LIMIT: 1000 # Recommended for smaller models

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

      # Optional LLM Settings
      # LLM_LANGUAGE: "English" # Optional, default: English

      # OCR Configuration - Choose one:
      # Option 1: LLM-based OCR
      OCR_PROVIDER: "llm" # Default OCR provider
      VISION_LLM_PROVIDER: "ollama" # openai, ollama, mistral, or anthropic
      VISION_LLM_MODEL: "minicpm-v" # minicpm-v (ollama) or gpt-4o (openai) or claude-sonnet-4-5 (anthropic/claude)
      OLLAMA_HOST: "http://host.docker.internal:11434" # If using Ollama

      # OCR Processing Mode
      OCR_PROCESS_MODE: "image" # Optional, default: image, other options: pdf, whole_pdf
      PDF_SKIP_EXISTING_OCR: "false" # Optional, skip OCR for PDFs with existing OCR

      # Option 2: Google Document AI
      # OCR_PROVIDER: 'google_docai'       # Use Google Document AI
      # GOOGLE_PROJECT_ID: 'your-project'  # Your GCP project ID
      # GOOGLE_LOCATION: 'us'              # Document AI region
      # GOOGLE_PROCESSOR_ID: 'processor-id' # Your processor ID
      # GOOGLE_APPLICATION_CREDENTIALS: '/app/credentials.json' # Path to service account key

      # Option 3: Azure Document Intelligence
      # OCR_PROVIDER: 'azure'              # Use Azure Document Intelligence
      # AZURE_DOCAI_ENDPOINT: 'your-endpoint' # Your Azure endpoint URL
      # AZURE_DOCAI_KEY: 'your-key'        # Your Azure API key
      # AZURE_DOCAI_MODEL_ID: 'prebuilt-read' # Optional, defaults to prebuilt-read
      # AZURE_DOCAI_TIMEOUT_SECONDS: '120'  # Optional, defaults to 120 seconds
      # AZURE_DOCAI_OUTPUT_CONTENT_FORMAT: 'text' # Optional, defaults to 'text', other valid option is 'markdown'
      # 'markdown' requires the 'prebuilt-layout' model

      # Enhanced OCR Features
      CREATE_LOCAL_HOCR: "false" # Optional, save hOCR files locally
      LOCAL_HOCR_PATH: "/app/hocr" # Optional, path for hOCR files
      CREATE_LOCAL_PDF: "false" # Optional, save enhanced PDFs locally
      LOCAL_PDF_PATH: "/app/pdf" # Optional, path for PDF files
      PDF_UPLOAD: "false" # Optional, upload enhanced PDFs to paperless-ngx
      PDF_UPLOAD_MODE: "new" # Optional: "new" (new document) or "version" (new version of the same document, paperless-ngx 3.0+, recommended)
      PDF_REPLACE: "false" # Optional and DANGEROUS, delete original after upload ("new" mode only)
      PDF_COPY_METADATA: "true" # Optional, copy metadata from original document
      PDF_OCR_TAGGING: "true" # Optional, add tag to processed documents
      PDF_OCR_COMPLETE_TAG: "paperless-gpt-ocr-complete" # Optional, tag name

      # Option 4: Docling Server
      # OCR_PROVIDER: 'docling'              # Use a Docling server
      # DOCLING_URL: 'http://your-docling-server:port' # URL of your Docling instance
      # DOCLING_IMAGE_EXPORT_MODE: "placeholder" # Optional, defaults to "embedded"
      # DOCLING_OCR_PIPELINE: "standard" # Optional, defaults to "vlm"
      # DOCLING_OCR_ENGINE: "easyocr" # Optional, defaults to "easyocr" (only used when `DOCLING_OCR_PIPELINE is set to 'standard')
      # DOCLING_OUTPUT_FORMAT: "md" # Optional, defaults to "md", other option: "text"

      AUTO_OCR_TAG: "paperless-gpt-ocr-auto" # Optional, default: paperless-gpt-ocr-auto
      OCR_LIMIT_PAGES: "5" # Optional, default: 5. Set to 0 for no limit.
      OCR_MAX_RETRIES: "3" # Optional, default: 3. Failed OCR attempts per document before it is fail-tagged and removed from the queue. Set to 0 to retry forever.
      LOG_LEVEL: "info" # Optional: debug, warn, error
    volumes:
      - ./prompts:/app/prompts # Mount the prompts directory
      - ./config:/app/config # Mount the config directory (settings made in the UI)
      - ./db:/app/db # Mount the db directory (history for undo, OCR run log)
      # For Google Document AI:
      - ${HOME}/.config/gcloud/application_default_credentials.json:/app/credentials.json
      # For local hOCR and PDF saving:
      - ./hocr:/app/hocr # Only if CREATE_LOCAL_HOCR is true
      - ./pdf:/app/pdf # Only if CREATE_LOCAL_PDF is true
    ports:
      - "8080:8080"
    deploy:
      resources:
        reservations:
          cpus: '0.01'
          memory: 20M
    depends_on:
      - paperless-ngx

摘自 README · bash

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

摘自 README · bash

   mkdir prompts

摘自 README · bash

   docker build -t paperless-gpt .

摘自 README · bash

   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 \
     -v $(pwd)/config:/app/config \
     -v $(pwd)/db:/app/db \
     -p 8080:8080 \
     paperless-gpt

适合谁

paperless-gpt 没有内置身份验证。不要将 paperless-gpt 直接暴露到互联网或不受信任的网络。应将 paperless-gpt 置于添加了身份验证的反向代理之后。

默认情况下,Docker 容器以非 root 用户运行。paperless-gpt 会在启动时验证配置,并阻止不受支持的模式与提供方组合。LLM OCR 使用 OpenAI 或 Ollama 从图像中提取文本。

Azure Document Intelligence 是 Microsoft 的企业级 OCR 解决方案。Docling Server 是自托管的 OCR 和文档转换服务。图像模式在处理前将 PDF 页面转换为图像。

整份 PDF 模式在一次操作中处理整个 PDF 文档。自动自定义字段生成必须在设置中启用,并且必须至少选择一个自定义字段才能工作。自定义字段的更新模式会添加新字段,并用新建议覆盖已有字段。

自定义字段的替换模式会删除文档上所有已有的自定义字段,并完全替换为建议的字段。PDF 处理可配置如何处理经 OCR 增强的 PDF,可选择保存到本地或上传到 paperless-ngx。OCR 完成标记功能可以给已完全经过 OCR 处理的文档自动打上特殊标签,以防重复处理。

在文档上添加 paperless-gpt 标签,用于手动处理。添加 paperless-gpt-auto 标签,用于自动处理。点击 Generate Suggestions 可查看 AI 提出的标题、标签和通讯方。

点击 Apply 可将更改保存到 paperless-ngx。

来源

本页内容整理自以下官方来源，点击可核对原文。

GitHub READMEhttps://github.com/icereed/paperless-gpt抓取于 2026-10-31

核验日期 · 2026-11-01

本页由 AI 依据上述官方来源整理，并经自动核对，未经本站实测。发现错误？告诉我们。

核心信息

它是什么

主要能力

怎么上手

适合谁

相关工具

图改改

多维视界

Winston AI

Cherry Studio

Ollama

来源