[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-icereed--paperless-gpt":3,"tool-icereed--paperless-gpt":62},[4,18,26,36,46,54],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",160784,2,"2026-04-19T11:32:54",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":42,"last_commit_at":43,"category_tags":44,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,45],"插件",{"id":47,"name":48,"github_repo":49,"description_zh":50,"stars":51,"difficulty_score":32,"last_commit_at":52,"category_tags":53,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,"2026-04-18T11:18:24",[14,15,13],{"id":55,"name":56,"github_repo":57,"description_zh":58,"stars":59,"difficulty_score":32,"last_commit_at":60,"category_tags":61,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[45,13,15,14],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":68,"readme_en":69,"readme_zh":70,"quickstart_zh":71,"use_case_zh":72,"hero_image_url":73,"owner_login":74,"owner_name":75,"owner_avatar_url":76,"owner_bio":77,"owner_company":78,"owner_location":79,"owner_email":80,"owner_twitter":80,"owner_website":80,"owner_url":81,"languages":82,"stars":113,"forks":114,"last_commit_at":115,"license":116,"difficulty_score":10,"env_os":117,"env_gpu":118,"env_ram":119,"env_deps":120,"category_tags":126,"github_topics":127,"view_count":32,"oss_zip_url":80,"oss_zip_packed_at":80,"status":17,"created_at":136,"updated_at":137,"faqs":138,"releases":169},9789,"icereed\u002Fpaperless-gpt","paperless-gpt","Use LLMs and LLM Vision (OCR) to handle paperless-ngx - Document Digitalization powered by AI","paperless-gpt 是一款专为 paperless-ngx 文档管理系统设计的 AI 增强工具，旨在利用大语言模型（LLM）和视觉识别技术，彻底改变传统文档数字化的处理方式。它主要解决了用户在整理大量扫描文件时面临的痛点：传统 OCR 对模糊或复杂版面识别率低，以及手动命名、分类和提取信息耗时费力的问题。\n\n无论是希望搭建私有知识库的个人用户，还是需要高效管理档案的小型企业团队，只要正在使用 paperless-ngx，都能从该工具中获益。其核心亮点在于\"LLM 增强型 OCR\"，不仅能比传统技术更精准地提取低质量扫描件中的文字，还能智能理解文档语境。在此基础上，paperless-gpt 能自动生成准确的文档标题、标签、发文日期及联系人信息，甚至支持按配置自动填充自定义字段。\n\n技术上，它展现了极高的灵活性，既支持调用 OpenAI 等云端服务，也完美兼容 Ollama 本地部署的大模型（包括具备推理能力的模型），在保障数据隐私的同时提供企业级的识别效果。此外，它还集成了 Google Document AI、Azure Document Intelligence 等多种专业","paperless-gpt 是一款专为 paperless-ngx 文档管理系统设计的 AI 增强工具，旨在利用大语言模型（LLM）和视觉识别技术，彻底改变传统文档数字化的处理方式。它主要解决了用户在整理大量扫描文件时面临的痛点：传统 OCR 对模糊或复杂版面识别率低，以及手动命名、分类和提取信息耗时费力的问题。\n\n无论是希望搭建私有知识库的个人用户，还是需要高效管理档案的小型企业团队，只要正在使用 paperless-ngx，都能从该工具中获益。其核心亮点在于\"LLM 增强型 OCR\"，不仅能比传统技术更精准地提取低质量扫描件中的文字，还能智能理解文档语境。在此基础上，paperless-gpt 能自动生成准确的文档标题、标签、发文日期及联系人信息，甚至支持按配置自动填充自定义字段。\n\n技术上，它展现了极高的灵活性，既支持调用 OpenAI 等云端服务，也完美兼容 Ollama 本地部署的大模型（包括具备推理能力的模型），在保障数据隐私的同时提供企业级的识别效果。此外，它还集成了 Google Document AI、Azure Document Intelligence 等多种专业 OCR 方案供用户选择。通过自动化处理繁琐的元数据生成工作，paperless-gpt 让用户能将精力集中在文档内容本身，真正实现轻松高效的无纸化办公。","# paperless-gpt\n\n[![License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Ficereed\u002Fpaperless-gpt)](LICENSE)\n[![Discord Banner](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FJoin%20us%20on-Discord-blue?logo=discord)](https:\u002F\u002Fdiscord.gg\u002FfJQppDH2J7)\n[![Docker Pulls](https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fpulls\u002Ficereed\u002Fpaperless-gpt)](https:\u002F\u002Fhub.docker.com\u002Fr\u002Ficereed\u002Fpaperless-gpt)\n[![GitHub Container Registry](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGHCR-Package-181717?logo=github)](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpkgs\u002Fcontainer\u002Fpaperless-gpt)\n[![Contributor Covenant](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FContributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)\n[![GitHub Sponsors](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSponsor-icereed-ea4aaa?logo=github-sponsors)](https:\u002F\u002Fgithub.com\u002Fsponsors\u002Ficereed)\n\n\n\u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F12701\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_readme_bbada6ddd5d3.png\" alt=\"icereed%2Fpaperless-gpt | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\n![Screenshot](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_readme_fb7a485fb2b5.png)\n\n\u003Csub>💡 Maintained by [Icereed](https:\u002F\u002Fgithub.com\u002Ficereed). Proudly supported by [BubbleTax.de](https:\u002F\u002Fbubbletax.de\u002F?utm_source=github&utm_medium=readme&utm_campaign=paperless) – automated, BMF-compliant tax reports for Interactive Brokers traders in Germany.\u003C\u002Fsub>\n\n---\n**paperless-gpt** seamlessly pairs with [paperless-ngx][paperless-ngx] to generate **AI-powered document titles** and **tags**, saving you hours of manual sorting. While other tools may offer AI chat features, **paperless-gpt** stands out by **supercharging OCR with LLMs**-ensuring high accuracy, even with tricky scans. If you're craving next-level text extraction and effortless document organization, this is your solution.\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fbd5d38b9-9309-40b9-93ca-918dfa4f3fd4\n\n> **❤️ Support This Project** \n> If paperless-gpt is helping you organize your documents and saving you time, please consider [sponsoring its development](https:\u002F\u002Fgithub.com\u002Fsponsors\u002Ficereed). Your support helps ensure continued improvements and maintenance!\n\n---\n\n## Key Highlights\n\n1. **LLM-Enhanced OCR** \n Harness Large Language Models (OpenAI or Ollama) for **better-than-traditional** OCR—turn messy or low-quality scans into context-aware, high-fidelity text.\n\n2. **Use specialized AI OCR services**\n\n - **LLM OCR**: Use OpenAI or Ollama to extract text from images.\n - **Google Document AI**: Leverage Google's powerful Document AI for OCR tasks.\n - **Azure Document Intelligence**: Use Microsoft's enterprise OCR solution.\n - **Docling Server**: Self-hosted OCR and document conversion service\n\n3. **Automatic Title, Tag & Created Date Generation** \n No more guesswork. Let the AI do the naming and categorizing. You can easily review suggestions and refine them if needed.\n\n4. **Supports reasoning models in Ollama** \n Greatly enhance accuracy by using a reasoning model like `qwen3:8b`. The perfect tradeoff between privacy and performance! Of course, if you got enough GPUs or NPUs, a bigger model will enhance the experience.\n\n5. **Automatic Correspondent Generation** \n Automatically identify and generate correspondents from your documents, making it easier to track and organize your communications.\n\n6. **Automatic Custom Field Generation** \n Extract and populate custom fields from your documents. Configure which fields to target and how they should be filled. This feature must be enabled in the settings, and you must select at least one custom field for it to function. Three write modes are available:\n - **Append**: This is the safest option: It only adds new fields that do not already exist on the document. It will never overwrite an existing field, even if it's empty.\n - **Update**: Adds new fields and overwrites existing fields with new suggestions. Fields on the document that don't have a new suggestion are left untouched.\n - **Replace**: Deletes all existing custom fields on the document and replaces them entirely with the suggested fields.\n\n7. **Searchable & Selectable PDFs** \n Generate PDFs with transparent text layers positioned accurately over each word, making your documents both searchable and selectable while preserving the original appearance.\n\n7. **Extensive Customization**\n\n - **Customizable Prompts via Web UI**: Tweak and manage all AI prompts for titles, tags, correspondents, and more directly within the web interface under the \"Settings\" menu. The application uses a safe `default_prompts` and `prompts` directory structure, ensuring your customizations are persistent.\n - **Tagging**: Decide how documents get tagged—manually, automatically, or via OCR-based flows.\n - **PDF Processing**: Configure how OCR-enhanced PDFs are handled, with options to save locally or upload to paperless-ngx.\n\n8. **Simple Docker Deployment** \n A few environment variables, and you're off! Compose it alongside paperless-ngx with minimal fuss.\n\n9. **Unified Web UI**\n\n - **Manual Review**: Approve or tweak AI's suggestions.\n - **Auto Processing**: Focus only on edge cases while the rest is sorted for you.\n\n9. **Ad-hoc Document Analysis**\n Perform ad-hoc analysis on a selection of documents using a custom prompt. Gain quick insights, summaries, or extract specific information from multiple documents at once.\n\n---\n\n## Table of Contents\n\n- [paperless-gpt](#paperless-gpt)\n - [Key Highlights](#key-highlights)\n - [Table of Contents](#table-of-contents)\n - [Getting Started](#getting-started)\n - [Prerequisites](#prerequisites)\n - [Installation](#installation)\n - [Docker Compose](#docker-compose)\n - [Manual Setup](#manual-setup)\n - [OCR Providers](#ocr-providers)\n - [1. LLM-based OCR (Default)](#1-llm-based-ocr-default)\n - [2. Azure Document Intelligence](#2-azure-document-intelligence)\n - [3. Google Document AI](#3-google-document-ai)\n - [4. Docling Server](#4-docling-server)\n - [OCR Processing Modes](#ocr-processing-modes)\n - [Image Mode (Default)](#image-mode-default)\n - [PDF Mode](#pdf-mode)\n - [Whole PDF Mode](#whole-pdf-mode)\n - [Provider Compatibility](#provider-compatibility)\n - [Existing OCR Detection](#existing-ocr-detection)\n - [Enhanced OCR Features](#enhanced-ocr-features)\n - [PDF Text Layer Generation](#pdf-text-layer-generation)\n - [Local File Saving](#local-file-saving)\n - [PDF Upload to paperless-ngx](#pdf-upload-to-paperless-ngx)\n - [Metadata Copying Limitations](#metadata-copying-limitations)\n - [Safety Features](#safety-features)\n - [Usage Recommendations](#usage-recommendations)\n - [Configuration](#configuration)\n - [Environment Variables](#environment-variables)\n - [Custom Prompt Templates](#custom-prompt-templates)\n - [Template Variables](#template-variables)\n - [LLM-Based OCR: Compare for Yourself](#llm-based-ocr-compare-for-yourself)\n - [Example 1](#example-1)\n - [Example 2](#example-2)\n - [How It Works](#how-it-works)\n - [Usage](#usage)\n - [Troubleshooting](#troubleshooting)\n - [Working with Local LLMs](#working-with-local-llms)\n - [Token Management](#token-management)\n - [PDF Processing Issues](#pdf-processing-issues)\n - [Custom Field Generation Issues](#custom-field-generation-issues)\n - [Contributing](#contributing)\n - [Support the Project](#support-the-project)\n - [License](#license)\n - [Star History](#star-history)\n - [Disclaimer](#disclaimer)\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- [Docker][docker-install] installed.\n- A running instance of [paperless-ngx][paperless-ngx].\n- Access to an LLM provider:\n - **OpenAI**: An API key with models like `gpt-4o` or `gpt-3.5-turbo`.\n - **Ollama**: A running Ollama server with models like `qwen3:8b`.\n\n### Installation\n\n#### Docker Compose\n\nHere's an example `docker-compose.yml` to spin up **paperless-gpt** alongside paperless-ngx:\n\n```yaml\nservices:\n paperless-ngx:\n image: ghcr.io\u002Fpaperless-ngx\u002Fpaperless-ngx:latest\n # ... (your existing paperless-ngx config)\n\n paperless-gpt:\n # Use one of these image sources:\n image: icereed\u002Fpaperless-gpt:latest # Docker Hub\n # image: ghcr.io\u002Ficereed\u002Fpaperless-gpt:latest # GitHub Container Registry\n environment:\n PAPERLESS_BASE_URL: \"http:\u002F\u002Fpaperless-ngx:8000\"\n PAPERLESS_API_TOKEN: \"your_paperless_api_token\"\n PAPERLESS_PUBLIC_URL: \"http:\u002F\u002Fpaperless.mydomain.com\" # Optional\n MANUAL_TAG: \"paperless-gpt\" # Optional, default: paperless-gpt\n AUTO_TAG: \"paperless-gpt-auto\" # Optional, default: paperless-gpt-auto\n # LLM Configuration - Choose one:\n\n # Option 1: Standard OpenAI\n LLM_PROVIDER: \"openai\"\n LLM_MODEL: \"gpt-4o\"\n OPENAI_API_KEY: \"your_openai_api_key\"\n\n # Option 2: Mistral\n # LLM_PROVIDER: \"mistral\"\n # LLM_MODEL: \"mistral-large-latest\"\n # MISTRAL_API_KEY: \"your_mistral_api_key\"\n\n # Option 3: Azure OpenAI\n # LLM_PROVIDER: \"openai\"\n # LLM_MODEL: \"your-deployment-name\"\n # OPENAI_API_KEY: \"your_azure_api_key\"\n # OPENAI_API_TYPE: \"azure\"\n # OPENAI_BASE_URL: \"https:\u002F\u002Fyour-resource.openai.azure.com\"\n\n # Option 4: Ollama (Local)\n # LLM_PROVIDER: \"ollama\"\n # LLM_MODEL: \"qwen3:8b\"\n # OLLAMA_HOST: \"http:\u002F\u002Fhost.docker.internal:11434\"\n # OLLAMA_CONTEXT_LENGTH: \"8192\" # Sets Ollama NumCtx (context window)\n # TOKEN_LIMIT: 1000 # Recommended for smaller models\n\n # Option 5: Anthropic\u002FClaude\n # LLM_PROVIDER: \"anthropic\"\n # LLM_MODEL: \"claude-sonnet-4-5\"\n # ANTHROPIC_API_KEY: \"your_anthropic_api_key\"\n\n # Optional LLM Settings\n # LLM_LANGUAGE: \"English\" # Optional, default: English\n\n # OCR Configuration - Choose one:\n # Option 1: LLM-based OCR\n OCR_PROVIDER: \"llm\" # Default OCR provider\n VISION_LLM_PROVIDER: \"ollama\" # openai, ollama, mistral, or anthropic\n VISION_LLM_MODEL: \"minicpm-v\" # minicpm-v (ollama) or gpt-4o (openai) or claude-sonnet-4-5 (anthropic\u002Fclaude)\n OLLAMA_HOST: \"http:\u002F\u002Fhost.docker.internal:11434\" # If using Ollama\n\n # OCR Processing Mode\n OCR_PROCESS_MODE: \"image\" # Optional, default: image, other options: pdf, whole_pdf\n PDF_SKIP_EXISTING_OCR: \"false\" # Optional, skip OCR for PDFs with existing OCR\n\n # Option 2: Google Document AI\n # OCR_PROVIDER: 'google_docai' # Use Google Document AI\n # GOOGLE_PROJECT_ID: 'your-project' # Your GCP project ID\n # GOOGLE_LOCATION: 'us' # Document AI region\n # GOOGLE_PROCESSOR_ID: 'processor-id' # Your processor ID\n # GOOGLE_APPLICATION_CREDENTIALS: '\u002Fapp\u002Fcredentials.json' # Path to service account key\n\n # Option 3: Azure Document Intelligence\n # OCR_PROVIDER: 'azure' # Use Azure Document Intelligence\n # AZURE_DOCAI_ENDPOINT: 'your-endpoint' # Your Azure endpoint URL\n # AZURE_DOCAI_KEY: 'your-key' # Your Azure API key\n # AZURE_DOCAI_MODEL_ID: 'prebuilt-read' # Optional, defaults to prebuilt-read\n # AZURE_DOCAI_TIMEOUT_SECONDS: '120' # Optional, defaults to 120 seconds\n # AZURE_DOCAI_OUTPUT_CONTENT_FORMAT: 'text' # Optional, defaults to 'text', other valid option is 'markdown'\n # 'markdown' requires the 'prebuilt-layout' model\n\n # Enhanced OCR Features\n CREATE_LOCAL_HOCR: \"false\" # Optional, save hOCR files locally\n LOCAL_HOCR_PATH: \"\u002Fapp\u002Fhocr\" # Optional, path for hOCR files\n CREATE_LOCAL_PDF: \"false\" # Optional, save enhanced PDFs locally\n LOCAL_PDF_PATH: \"\u002Fapp\u002Fpdf\" # Optional, path for PDF files\n PDF_UPLOAD: \"false\" # Optional, upload enhanced PDFs to paperless-ngx\n PDF_REPLACE: \"false\" # Optional and DANGEROUS, delete original after upload\n PDF_COPY_METADATA: \"true\" # Optional, copy metadata from original document\n PDF_OCR_TAGGING: \"true\" # Optional, add tag to processed documents\n PDF_OCR_COMPLETE_TAG: \"paperless-gpt-ocr-complete\" # Optional, tag name\n\n # Option 4: Docling Server\n # OCR_PROVIDER: 'docling' # Use a Docling server\n # DOCLING_URL: 'http:\u002F\u002Fyour-docling-server:port' # URL of your Docling instance\n # DOCLING_IMAGE_EXPORT_MODE: \"placeholder\" # Optional, defaults to \"embedded\"\n # DOCLING_OCR_PIPELINE: \"standard\" # Optional, defaults to \"vlm\"\n # DOCLING_OCR_ENGINE: \"easyocr\" # Optional, defaults to \"easyocr\" (only used when `DOCLING_OCR_PIPELINE is set to 'standard')\n\n\n AUTO_OCR_TAG: \"paperless-gpt-ocr-auto\" # Optional, default: paperless-gpt-ocr-auto\n OCR_LIMIT_PAGES: \"5\" # Optional, default: 5. Set to 0 for no limit.\n LOG_LEVEL: \"info\" # Optional: debug, warn, error\n volumes:\n - .\u002Fprompts:\u002Fapp\u002Fprompts # Mount the prompts directory\n # For Google Document AI:\n - ${HOME}\u002F.config\u002Fgcloud\u002Fapplication_default_credentials.json:\u002Fapp\u002Fcredentials.json\n # For local hOCR and PDF saving:\n - .\u002Fhocr:\u002Fapp\u002Fhocr # Only if CREATE_LOCAL_HOCR is true\n - .\u002Fpdf:\u002Fapp\u002Fpdf # Only if CREATE_LOCAL_PDF is true\n ports:\n - \"8080:8080\"\n depends_on:\n - paperless-ngx\n```\n\n**Pro Tip**: Replace placeholders with real values and read the logs if something looks off.\n\n#### Manual Setup\n\n1. **Clone the Repository**\n ```bash\n git clone https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt.git\n cd paperless-gpt\n ```\n2. **Create a `prompts` Directory**\n ```bash\n mkdir prompts\n ```\n3. **Build the Docker Image**\n ```bash\n docker build -t paperless-gpt .\n ```\n4. **Run the Container**\n ```bash\n docker run -d \\\n -e PAPERLESS_BASE_URL='http:\u002F\u002Fyour_paperless_ngx_url' \\\n -e PAPERLESS_API_TOKEN='your_paperless_api_token' \\\n -e LLM_PROVIDER='openai' \\\n -e LLM_MODEL='gpt-4o' \\\n -e OPENAI_API_KEY='your_openai_api_key' \\\n -e LLM_LANGUAGE='English' \\\n -e VISION_LLM_PROVIDER='ollama' \\\n -e VISION_LLM_MODEL='minicpm-v' \\\n -e LOG_LEVEL='info' \\\n -v $(pwd)\u002Fprompts:\u002Fapp\u002Fprompts \\\n -p 8080:8080 \\\n paperless-gpt\n ```\n\n---\n\n## OCR Providers\n\nFor detailed provider-specific documentation:\n\n- [Mistral AI Integration](docs\u002Fmistral_llm.md)\n\npaperless-gpt supports four different OCR providers, each with unique strengths and capabilities:\n\n### 1. LLM-based OCR (Default)\n\n- **Key Features**:\n - Uses vision-capable LLMs like gpt-4o or MiniCPM-V\n - High accuracy with complex layouts and difficult scans\n - Context-aware text recognition\n - Self-correcting capabilities for OCR errors\n- **Best For**:\n - Complex or unusual document layouts\n - Poor quality scans\n - Documents with mixed languages\n- **Configuration**:\n ```yaml\n OCR_PROVIDER: \"llm\"\n VISION_LLM_PROVIDER: \"openai\" # or \"ollama\"\n VISION_LLM_MODEL: \"gpt-4o\" # or \"minicpm-v\"\n ```\n\n### 2. Azure Document Intelligence\n\n- **Key Features**:\n - Enterprise-grade OCR solution\n - Prebuilt models for common document types\n - Layout preservation and table detection\n - Fast processing speeds\n- **Best For**:\n - Business documents and forms\n - High-volume processing\n - Documents requiring layout analysis\n- **Configuration**:\n ```yaml\n OCR_PROVIDER: \"azure\"\n AZURE_DOCAI_ENDPOINT: \"https:\u002F\u002Fyour-endpoint.cognitiveservices.azure.com\u002F\"\n AZURE_DOCAI_KEY: \"your-key\"\n AZURE_DOCAI_MODEL_ID: \"prebuilt-read\" # optional\n AZURE_DOCAI_TIMEOUT_SECONDS: \"120\" # optional\n AZURE_DOCAI_OUTPUT_CONTENT_FORMAT:\n \"text\" # optional, defaults to text, other valid option is 'markdown'\n # 'markdown' requires the 'prebuilt-layout' model\n ```\n\n### 3. Google Document AI\n\n- **Key Features**:\n - Enterprise-grade OCR\u002FHTR solution\n - Specialized document processors\n - Strong form field detection\n - Multi-language support\n - High accuracy on structured documents\n - **Exclusive hOCR generation** for creating searchable PDFs with text layers\n - **Only provider that supports** enhanced PDF generation features\n- **Best For**:\n - Forms and structured documents\n - Documents with tables\n - Multi-language documents\n - Handwritten text (HTR)\n- **Configuration**:\n ```yaml\n OCR_PROVIDER: \"google_docai\"\n GOOGLE_PROJECT_ID: \"your-project\"\n GOOGLE_LOCATION: \"us\"\n GOOGLE_PROCESSOR_ID: \"processor-id\"\n CREATE_LOCAL_HOCR: \"true\" # Optional, for hOCR generation\n LOCAL_HOCR_PATH: \"\u002Fapp\u002Fhocr\" # Optional, default path\n CREATE_LOCAL_PDF: \"true\" # Optional, for applying OCR to PDF\n LOCAL_PDF_PATH: \"\u002Fapp\u002Fpdf\" # Optional, default path\n ```\n\n### 4. Docling Server\n\n- **Key Features**:\n - Self-hosted OCR and document conversion service\n - Supports various input and output formats (including text)\n - Utilizes multiple OCR engines (EasyOCR, Tesseract, etc.)\n - Can be run locally or in a private network\n- **Best For**:\n - Users who prefer a self-hosted solution\n - Environments where data privacy is paramount\n - Processing a wide variety of document types\n- **Configuration**:\n ```yaml\n OCR_PROVIDER: \"docling\"\n DOCLING_URL: \"http:\u002F\u002Fyour-docling-server:port\"\n DOCLING_IMAGE_EXPORT_MODE: \"placeholder\" # Optional, defaults to \"embedded\"\n DOCLING_OCR_PIPELINE: \"standard\" # Optional, defaults to \"vlm\"\n DOCLING_OCR_ENGINE: \"macocr\" # Optional, defaults to \"easyocr\" (only used when `DOCLING_OCR_PIPELINE is set to 'standard')\n ```\n\n## OCR Processing Modes\n\npaperless-gpt offers different methods for processing documents, giving you flexibility based on your needs and OCR provider capabilities:\n\n### Image Mode (Default)\n\n- **How it works**: Converts PDF pages to images before processing\n- **Best for**: Compatibility with all OCR providers.\n- **Configuration**: `OCR_PROCESS_MODE: \"image\"`\n\n### PDF Mode\n\n- **How it works**: Processes PDF pages directly without image conversion\n- **Best for**: Preserving PDF features, potentially faster processing and improved accuracy with some providers\n- **Configuration**: `OCR_PROCESS_MODE: \"pdf\"`\n\n### Whole PDF Mode\n\n- **How it works**: Processes the entire PDF document in a single operation\n- **Best for**: Providers that handle multi-page documents efficiently, reduced API calls\n- **Configuration**: `OCR_PROCESS_MODE: \"whole_pdf\"`\n- **Note**: Processing large PDFs may cause you to hit the API limit of your OCR provider. If you encounter problems with large documents, consider switching to `pdf` mode, which processes pages individually.\n\n### Provider Compatibility\n\nDifferent OCR providers support different processing modes:\n\n| Provider | Image Mode | PDF Mode | Whole PDF Mode |\n|----------|------------|----------|----------------|\n| **LLM-based OCR** (OpenAI\u002FOllama) | ✅ | ❌ | ❌ |\n| **Azure Document Intelligence** | ✅ | ❌ | ❌ |\n| **Google Document AI** | ✅ | ✅ | ✅ |\n| **Mistral OCR** | ✅ | ✅ | ✅ |\n| **Docling Server** | ✅ | ✅ | ✅ |\n\n> **Important**: paperless-gpt will validate your configuration at startup and prevent unsupported mode\u002Fprovider combinations. If you specify an unsupported mode for your provider, the application will fail to start with a clear error message.\n\n### Existing OCR Detection\n\nWhen using PDF or whole PDF modes, you can enable automatic detection of existing OCR:\n\n```yaml\nenvironment:\n OCR_PROCESS_MODE: \"pdf\" # or \"whole_pdf\"\n PDF_SKIP_EXISTING_OCR: \"true\" # Skip processing if existing OCR is detected in the PDF\n```\n\n> **Note**: Not all OCR providers support all processing modes. Some may work better with certain modes than others. Processing as PDF might use more or fewer API tokens than processing as images, depending on the provider. Results may vary based on document complexity and provider capabilities. It's recommended to experiment with different modes to find what works best for your specific documents and OCR provider.\n\n## Enhanced OCR Features\n\npaperless-gpt includes powerful OCR enhancements that go beyond basic text extraction:\n\n> **Important Note**: The PDF text layer generation and hOCR features are currently **only supported with Google Document AI** as the OCR provider. These features are not available when using LLM-based OCR or Azure Document Intelligence.\n\n### PDF Text Layer Generation\n\n- **Searchable & Selectable PDFs**: Creates PDFs with transparent text overlays accurately positioned over each word in the document\n- **hOCR Integration**: Utilizes hOCR format (HTML-based OCR representation) to maintain precise text positioning\n- **Document Quality Improvement**: Makes documents both searchable and selectable while preserving the original appearance\n- **Google Document AI Required**: These features rely on Google Document AI's ability to generate hOCR data with accurate word positions\n\n### Local File Saving\n\npaperless-gpt can save both the hOCR files and enhanced PDFs locally:\n\n```yaml\nenvironment:\n # Enable local file saving\n CREATE_LOCAL_HOCR: \"true\" # Save hOCR files locally\n CREATE_LOCAL_PDF: \"true\" # Save generated PDFs locally\n LOCAL_HOCR_PATH: \"\u002Fapp\u002Fhocr\" # Path to save hOCR files\n LOCAL_PDF_PATH: \"\u002Fapp\u002Fpdf\" # Path to save PDF files\nvolumes:\n # Mount volumes to access the files from your host\n - .\u002Fhocr_files:\u002Fapp\u002Fhocr\n - .\u002Fpdf_files:\u002Fapp\u002Fpdf\n```\n\n> **Note**: You must mount these directories as volumes in your Docker configuration to access the generated files from your host system.\n\n### PDF Upload to paperless-ngx\n\nDue to limitations in paperless-ngx's API, it's not possible to directly update existing documents with their OCR-enhanced versions. As a workaround, paperless-gpt can:\n\n1. Upload the enhanced PDF as a new document\n2. Copy metadata from the original document to the new one\n3. Optionally delete the original document\n\n```yaml\nenvironment:\n # PDF upload configuration\n PDF_UPLOAD: \"true\" # Upload processed PDFs to paperless-ngx\n PDF_COPY_METADATA: \"true\" # Copy metadata from original to new document\n PDF_REPLACE: \"false\" # Whether to delete the original document (use with caution!)\n PDF_OCR_TAGGING: \"true\" # Add a tag to mark documents as OCR-processed\n PDF_OCR_COMPLETE_TAG: \"paperless-gpt-ocr-complete\" # Tag used to mark OCR-processed documents\n```\n\n> **⚠️ WARNING ⚠️** \n> Setting `PDF_REPLACE: \"true\"` will delete the original document after uploading the enhanced version. This process cannot be undone and may result in data loss if something goes wrong during the upload or metadata copying process. Use with extreme caution!\n\n### Metadata Copying Limitations\n\nWhen copying metadata from the original document to the new one, paperless-gpt attempts to copy:\n\n- Document title\n- Tags (including adding the OCR complete tag)\n- Correspondent information\n- Created date\n\nHowever, some metadata **cannot** be copied due to paperless-ngx API limitations:\n\n- Document ID (new document always gets a new ID)\n- Added date (will reflect the current upload date)\n- Modified date\n- Custom fields that might be added by other paperless-ngx plugins\n- Notes and annotations\n\n### Safety Features\n\nTo prevent accidental creation of incomplete documents, paperless-gpt includes several safety features:\n\n1. **Page Count Check**: If using `OCR_LIMIT_PAGES` to process only a subset of pages (for speed or resource reasons), PDF generation will be skipped entirely if fewer pages would be processed than exist in the original document.\n\n```yaml\nenvironment:\n OCR_LIMIT_PAGES: \"5\" # Limit OCR to first 5 pages, set to 0 for no limit\n```\n\n2. **OCR Complete Tagging**: Documents that have been fully processed with OCR can be automatically tagged with a special tag, preventing duplicate processing.\n\n3. **Processing Skip**: If a document already has the OCR complete tag, processing will be skipped automatically.\n\n### Usage Recommendations\n\nFor best results with the enhanced OCR features:\n\n1. **Initial Testing**: Start with `PDF_REPLACE: \"false\"` until you've confirmed the process works well with your documents.\n\n2. **Regular Backups**: Ensure you have backups of your paperless-ngx database and documents before enabling document replacement.\n\n3. **Process Management**: For large documents, consider using `OCR_LIMIT_PAGES: \"0\"` to ensure all pages are processed, even though this will take longer.\n\n4. **Local Copies**: Enable local file saving (`CREATE_LOCAL_HOCR` and `CREATE_LOCAL_PDF`) to keep copies of the enhanced files as an extra precaution.\n\n5. **Tagging Strategy**: Use the OCR complete tag (`PDF_OCR_COMPLETE_TAG`) to track which documents have already been processed.\n\n## Configuration\n\n### Environment Variables\n\n> **Note:** When using Ollama, ensure that the Ollama server is running and accessible from the paperless-gpt container.\n\n| Variable | Description | Required | Default |\n| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------- |\n| `PAPERLESS_BASE_URL` | URL of your paperless-ngx instance (e.g. `http:\u002F\u002Fpaperless-ngx:8000`). | Yes | |\n| `PAPERLESS_API_TOKEN` | API token for paperless-ngx. Generate one in paperless-ngx admin. | Yes | |\n| `PAPERLESS_PUBLIC_URL` | Public URL for Paperless (if different from `PAPERLESS_BASE_URL`). | No | |\n| `MANUAL_TAG` | Tag for manual processing. | No | paperless-gpt |\n| `AUTO_TAG` | Tag for auto processing. | No | paperless-gpt-auto |\n| `LLM_PROVIDER` | AI backend (`openai`, `ollama`, `googleai`, `mistral`, or `anthropic`). | Yes | |\n| `LLM_MODEL` | AI model name (e.g., `gpt-4o`, `mistral-large-latest`, `qwen3:8b`, `claude-sonnet-4-5`). | Yes | |\n| `OPENAI_API_KEY` | OpenAI API key (required if using OpenAI). | Cond. | |\n| `MISTRAL_API_KEY` | Mistral API key (required if using Mistral). | Cond. | |\n| `ANTHROPIC_API_KEY` | Anthropic API key (required if using Anthropic\u002FClaude). | Cond. | |\n| `OPENAI_API_TYPE` | Set to `azure` to use Azure OpenAI Service. | No | |\n| `OPENAI_BASE_URL` | Base URL for OpenAI API. For Azure OpenAI, set to your deployment URL (e.g., `https:\u002F\u002Fyour-resource.openai.azure.com`). | No | |\n| `LLM_LANGUAGE` | Likely language for documents (e.g. `English`). Appears in the prompt to help the LLM. | No | English |\n| `GOOGLEAI_API_KEY` | Google Gemini API key (required if using `LLM_PROVIDER=googleai`). | Cond. | |\n| `GOOGLEAI_THINKING_BUDGET` | (Optional, googleai only) Integer. Controls Gemini \"thinking\" budget. If unset, model default is used (thinking enabled if supported). Set to `0` to disable thinking (if model supports it). | No | |\n| `OLLAMA_HOST` | Ollama server URL (e.g. `http:\u002F\u002Fhost.docker.internal:11434`). | No | |\n| `LLM_REQUESTS_PER_MINUTE` | Maximum requests per minute for the main LLM. Useful for managing API costs or local LLM load. | No | 120 |\n| `LLM_MAX_RETRIES` | Maximum retry attempts for failed main LLM requests. | No | 3 |\n| `LLM_BACKOFF_MAX_WAIT` | Maximum wait time between retries for the main LLM (e.g., `30s`). | No | 30s |\n| `OCR_PROVIDER` | OCR provider to use (`llm`, `azure`, or `google_docai`). | No | llm |\n| `OCR_PROCESS_MODE` | Method for processing documents: `image` (convert to images first), `pdf` (process PDF pages directly), or `whole_pdf` (entire PDF at once). | No | image |\n| `VISION_LLM_PROVIDER` | AI backend for LLM OCR (`openai`, `ollama`, `mistral`, or `anthropic`). Required if OCR_PROVIDER is `llm`. | Cond. | |\n| `VISION_LLM_MODEL` | Model name for LLM OCR (e.g. `minicpm-v`). Required if OCR_PROVIDER is `llm`. | Cond. | |\n| `VISION_LLM_REQUESTS_PER_MINUTE` | Maximum requests per minute for the Vision LLM. Useful for managing API costs or local LLM load. | No | 120 |\n| `VISION_LLM_MAX_RETRIES` | Maximum retry attempts for failed Vision LLM requests. | No | 3 |\n| `VISION_LLM_BACKOFF_MAX_WAIT` | Maximum wait time between retries for the Vision LLM (e.g., `30s`). | No | 30s |\n| `VISION_LLM_MAX_TOKENS` | Maximum tokens for Vision LLM OCR output. | No | |\n| `VISION_LLM_TEMPERATURE` | Sampling temperature for Vision OCR generation. Lower is more deterministic. Important: For OpenAI GPT-5 it must be explicitly set to `1.0`. | No | |\n| `OLLAMA_CONTEXT_LENGTH` | (Ollama only) Integer. Sets NumCtx (context window) for the Ollama runner. If unset or 0, the model default is used. | No | |\n| `OLLAMA_OCR_TOP_K` | (Ollama only) Top-k token sampling for Vision OCR. Lower favors more likely tokens; higher increases diversity. | No | |\n| `AZURE_DOCAI_ENDPOINT` | Azure Document Intelligence endpoint. Required if OCR_PROVIDER is `azure`. | Cond. | |\n| `AZURE_DOCAI_KEY` | Azure Document Intelligence API key. Required if OCR_PROVIDER is `azure`. | Cond. | |\n| `AZURE_DOCAI_MODEL_ID` | Azure Document Intelligence model ID. Optional if using `azure` provider. | No | prebuilt-read |\n| `AZURE_DOCAI_TIMEOUT_SECONDS` | Azure Document Intelligence timeout in seconds. | No | 120 |\n| `AZURE_DOCAI_OUTPUT_CONTENT_FORMAT` | Azure Document Intelligence output content format. Optional if using `azure` provider. Defaults to `text`. 'markdown' is the other option and it requires the 'prebuild-layout' model ID. | No | text |\n| `GOOGLE_PROJECT_ID` | Google Cloud project ID. Required if OCR_PROVIDER is `google_docai`. | Cond. | |\n| `GOOGLE_LOCATION` | Google Cloud region (e.g. `us`, `eu`). Required if OCR_PROVIDER is `google_docai`. | Cond. | |\n| `GOOGLE_PROCESSOR_ID` | Document AI processor ID. Required if OCR_PROVIDER is `google_docai`. | Cond. | |\n| `GOOGLE_APPLICATION_CREDENTIALS` | Path to the mounted Google service account key. Required if OCR_PROVIDER is `google_docai`. | Cond. | |\n| `DOCLING_URL` | URL of the Docling server instance. Required if OCR_PROVIDER is `docling`. | Cond. | |\n| `DOCLING_IMAGE_EXPORT_MODE` | Mode for image export. Optional; defaults to `embedded` if unset. | No | embedded |\n| `DOCLING_OCR_PIPELINE` | Sets the pipeline type. Optional; defaults to `vlm` if unset. | No | vlm |\n| `DOCLING_OCR_ENGINE` | Sets the ocr engine, if `DOCLING_OCR_PIPELINE` is set to `standard`. Optional; defaults to `easyocr` | No | easyocr |\n| `CREATE_LOCAL_HOCR` | Whether to save hOCR files locally. | No | false |\n| `LOCAL_HOCR_PATH` | Path where hOCR files will be saved when hOCR generation is enabled. | No | \u002Fapp\u002Fhocr |\n| `CREATE_LOCAL_PDF` | Whether to save enhanced PDFs locally. | No | false |\n| `LOCAL_PDF_PATH` | Path where PDF files will be saved when PDF generation is enabled. | No | \u002Fapp\u002Fpdf |\n| `PDF_UPLOAD` | Whether to upload enhanced PDFs to paperless-ngx. | No | false |\n| `PDF_REPLACE` | Whether to delete the original document after uploading the enhanced version (DANGEROUS). | No | false |\n| `PDF_COPY_METADATA` | Whether to copy metadata from the original document to the uploaded PDF. Only applicable when using PDF_UPLOAD. | No | true |\n| `PDF_OCR_TAGGING` | Whether to add a tag to mark documents as OCR-processed. | No | true |\n| `PDF_OCR_COMPLETE_TAG` | Tag used to mark documents as OCR-processed. | No | paperless-gpt-ocr-complete |\n| `PDF_SKIP_EXISTING_OCR` | Whether to skip OCR processing for PDFs that already have OCR. Works with `pdf` and `whole_pdf` processing modes (`OCR_PROCESS_MODE`). | No | false |\n| `AUTO_OCR_TAG` | Tag for automatically processing docs with OCR. | No | paperless-gpt-ocr-auto |\n| `OCR_LIMIT_PAGES` | Limit the number of pages for OCR. Set to `0` for no limit. | No | 5 |\n| `LOG_LEVEL` | Application log level (`info`, `debug`, `warn`, `error`). | No | info |\n| `LISTEN_INTERFACE` | Network interface to listen on. | No | 8080 |\n| `AUTO_GENERATE_TITLE` | Generate titles automatically if `paperless-gpt-auto` is used. | No | true |\n| `AUTO_GENERATE_TAGS` | Generate tags automatically if `paperless-gpt-auto` is used. | No | true |\n| `CREATE_NEW_TAGS` | Allow the LLM to suggest new tags that don't exist in paperless-ngx yet. When enabled, new tags will be created automatically in paperless-ngx. | No | false |\n| `AUTO_GENERATE_CORRESPONDENTS` | Generate correspondents automatically if `paperless-gpt-auto` is used. | No | true |\n| `AUTO_GENERATE_DOCUMENT_TYPE` | Generate document types automatically if `paperless-gpt-auto` is used. Only existing document types from paperless-ngx will be used. | No | true |\n| `AUTO_GENERATE_CREATED_DATE` | Generate the created dates automatically if `paperless-gpt-auto` is used. | No | true |\n| `TOKEN_LIMIT` | Maximum tokens allowed for prompts\u002Fcontent. Set to `0` to disable limit. Useful for smaller LLMs. | No | |\n| `IMAGE_MAX_PIXEL_DIMENSION` | Maximum pixels along any side when rendering document pages to images. | No | 10000 |\n| `IMAGE_MAX_TOTAL_PIXELS` | Maximum total pixel count (width × height) when rendering document pages to images. | No | 40000000 |\n| `IMAGE_MAX_RENDER_DPI` | Maximum DPI used when rendering document pages to images. | No | 600 |\n| `IMAGE_MAX_FILE_BYTES` | Maximum JPEG file size in bytes for rendered page images. Images exceeding this are compressed or resized. | No | 10485760 |\n| `CORRESPONDENT_BLACK_LIST` | A comma-separated list of names to exclude from the correspondents suggestions. Example: `John Doe, Jane Smith`. | No | |\n\n### Custom Prompt Templates\n\npaperless-gpt's flexible **prompt templates** let you shape how AI responds. While you can still manually manage files, the recommended way to customize prompts is through the **Settings** page in the web UI.\n\nThe application uses two directories for management:\n- **`default_prompts\u002F`**: Contains the built-in, default templates. These should not be modified.\n- **`prompts\u002F`**: Your working directory. On first run, the default templates are copied here. All edits made in the UI are saved to the files in this directory.\n\nTo ensure your custom prompts persist across container restarts, you must mount the `prompts` directory as a volume in your `docker-compose.yml`:\n\n```yaml\nvolumes:\n # This is crucial to save your custom prompts!\n - .\u002Fprompts:\u002Fapp\u002Fprompts\n```\n\nThe application reloads the templates instantly after you save them in the UI and also on startup, so no restart is needed to apply changes.\n\n#### Template Variables\n\nEach template has access to specific variables:\n\n**title_prompt.tmpl**:\n\n- `{{.Language}}` - Target language (e.g., \"English\")\n- `{{.Content}}` - Document content text\n- `{{.Title}}` - Original document title\n\n**tag_prompt.tmpl**:\n\n- `{{.Language}}` - Target language\n- `{{.AvailableTags}}` - List of existing tags in paperless-ngx\n- `{{.OriginalTags}}` - Document's current tags\n- `{{.Title}}` - Document title\n- `{{.Content}}` - Document content text\n\n**ocr_prompt.tmpl**:\n\n- `{{.Language}}` - Target language\n\n**correspondent_prompt.tmpl**:\n\n- `{{.Language}}` - Target language\n- `{{.AvailableCorrespondents}}` - List of existing correspondents\n- `{{.BlackList}}` - List of blacklisted correspondent names\n- `{{.Title}}` - Document title\n- `{{.Content}}` - Document content text\n\n**created_date_prompt.tmpl**:\n\n- `{{.Language}}` - Target language\n- `{{.Content}}` - Document content text\n\n**custom_field_prompt.tmpl**:\n\n- `{{.DocumentType}}` - The name of the document's type in paperless-ngx.\n- `{{.CustomFieldsXML}}` - An XML string listing the custom fields selected in the settings for processing.\n- `{{.Title}}` - Document title\n- `{{.CreatedDate}}` - Document's created date\n- `{{.Content}}` - Document content text\n\nThe templates use Go's text\u002Ftemplate syntax. paperless-gpt automatically reloads template changes after UI saves and on startup.\n\n---\n\n## LLM-Based OCR: Compare for Yourself\n\n\u003Cdetails>\n\u003Csummary>Click to expand the vanilla OCR vs. AI-powered OCR comparison\u003C\u002Fsummary>\n\n### Example 1\n\n**Image**:\n\n![Image](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_readme_b7f38db62490.jpg)\n\n**Vanilla Paperless-ngx OCR**:\n\n```\nLa Grande Recre\n\nGentre Gommercial 1'Esplanade\n1349 LOLNAIN LA NEWWE\nTA BERBOGAAL Tel =. 010 45,96 12\nTicket 1440112 03\u002F11\u002F2006 a 13597:\n4007176614518. DINOS. TYRAMNESA\nTOTAET.T.LES\nReslE par Lask-Euron\nRencu en Cash Euro\nV.14.6 -Hotgese = VALERTE\nTICKET A-GONGERVER PORR TONT. EEHANGE\nHERET ET A BIENTOT\n```\n\n**LLM-Powered OCR (OpenAI gpt-4o)**:\n\n```\nLa Grande Récré\nCentre Commercial l'Esplanade\n1348 LOUVAIN LA NEUVE\nTVA 860826401 Tel : 010 45 95 12\nTicket 14421 le 03\u002F11\u002F2006 à 15:27:18\n4007176614518 DINOS TYRANNOSA 14.90\nTOTAL T.T.C. 14.90\nRéglé par Cash Euro 50.00\nRendu en Cash Euro 35.10\nV.14.6 Hôtesse : VALERIE\nTICKET A CONSERVER POUR TOUT ECHANGE\nMERCI ET A BIENTOT\n```\n\n---\n\n### Example 2\n\n**Image**:\n\n![Image](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_readme_ba0fdb1cf694.jpg)\n\n**Vanilla Paperless-ngx OCR**:\n\n```\nInvoice Number: 1-996-84199\n\nFed: Invoica Date: Sep01, 2014\nAccaunt Number: 1334-8037-4\nPage: 1012\n\nFod£x Tax ID 71.0427007\n\nIRISINC\nSHARON ANDERSON\n4731 W ATLANTIC AVE STE BI\nDELRAY BEACH FL 33445-3897 ’ a\nInvoice Questions?\n\nBing, ‚Account Shipping Address: Contact FedEx Reı\n\nISINC\n4731 W ATLANTIC AVE Phone: (800) 622-1147 M-F 7-6 (CST)\nDELRAY BEACH FL 33445-3897 US Fax: (800) 548-3020\n\nInternet: www.fedex.com\n\nInvoice Summary Sep 01, 2014\n\nFodEx Ground Services\nOther Charges 11.00\nTotal Charges 11.00 Da £\n>\npolo) Fz\u002F\u002F \u002FG\nTOTAL THIS INVOICE .... usps 11.00 P 2\u002F1 f\n\n‘The only charges accrued for this period is the Weekly Service Charge.\n\nThe Fedix Ground aceounts teferencedin his involce have been transteired and assigned 10, are owned by,andare payable to FedEx Express:\n\nTo onsurs propor credit, plasa raturn this portion wirh your payment 10 FodEx\n‚Please do not staple or fold. Ploase make your chack payablı to FedEx.\n\n[TI For change ol address, hc har and camphat lrm or never ide\n\nRemittance Advice\nYour payment is due by Sep 16, 2004\n\nNumber Number Dus\n\n1334803719968 41993200000110071\n\nAT 01 0391292 468448196 A**aDGT\n\nIRISINC Illallun elalalssollallansdHilalellund\nSHARON ANDERSON\n\n4731 W ATLANTIC AVE STEBI FedEx\n\nDELRAY BEACH FL 334453897 PO. Box 94516\n\nPALATINE IL 60094-4515\n```\n\n**LLM-Powered OCR (OpenAI gpt-4o)**:\n\n```\nFedEx. Invoice Number: 1-996-84199\n Invoice Date: Sep 01, 2014\n Account Number: 1334-8037-4\n Page: 1 of 2\n FedEx Tax ID: 71-0427007\n\nI R I S INC\nSHARON ANDERSON\n4731 W ATLANTIC AVE STE B1\nDELRAY BEACH FL 33445-3897\n Invoice Questions?\nBilling Account Shipping Address: Contact FedEx Revenue Services\nI R I S INC Phone: (800) 622-1147 M-F 7-6 (CST)\n4731 W ATLANTIC AVE Fax: (800) 548-3020\nDELRAY BEACH FL 33445-3897 US Internet: www.fedex.com\n\nInvoice Summary Sep 01, 2014\n\nFedEx Ground Services\nOther Charges 11.00\n\nTotal Charges .......................................................... USD $ 11.00\n\nTOTAL THIS INVOICE .............................................. USD $ 11.00\n\nThe only charges accrued for this period is the Weekly Service Charge.\n\n RECEIVED\n SEP _ 8 REC'D\n BY: _\n\n posted 9\u002F21\u002F14\n\nThe FedEx Ground accounts referenced in this invoice have been transferred and assigned to, are owned by, and are payable to FedEx Express.\n\nTo ensure proper credit, please return this portion with your payment to FedEx.\nPlease do not staple or fold. Please make your check payable to FedEx.\n\n❑ For change of address, check here and complete form on reverse side.\n\nRemittance Advice\nYour payment is due by Sep 16, 2004\n\nInvoice\nNumber\n1-996-84199\n\nAccount\nNumber\n1334-8037-4\n\nAmount\nDue\nUSD $ 11.00\n\n133480371996841993200000110071\n\nAT 01 031292 468448196 A**3DGT\n\nI R I S INC\nSHARON ANDERSON\n4731 W ATLANTIC AVE STE B1\nDELRAY BEACH FL 33445-3897\n\nFedEx\nP.O. Box 94515\n```\n\n---\n\n\u003C\u002Fdetails>\n\n**Why Does It Matter?**\n\n- Traditional OCR often jumbles text from complex or low-quality scans.\n- Large Language Models interpret context and correct likely errors, producing results that are more precise and readable.\n- You can integrate these cleaned-up texts into your **paperless-ngx** pipeline for better tagging, searching, and archiving.\n\n### How It Works\n\n- **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.\n- **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.\n- **Google Document AI and Azure Document Intelligence** provide high-accuracy OCR with advanced layout analysis.\n- **Enhanced PDF Generation** combines OCR results with the original document to create searchable PDFs with properly positioned text layers.\n\n---\n\n## Usage\n\n1. **Tag Documents**\n\n - Add `paperless-gpt` tag to documents for manual processing\n - Add `paperless-gpt-auto` for automatic processing\n - Add `paperless-gpt-ocr-auto` for automatic OCR processing\n\n2. **Visit Web UI**\n\n - Go to `http:\u002F\u002Flocalhost:8080` (or your host) in your browser\n - Review documents tagged for processing\n\n3. **Generate & Apply Suggestions**\n\n - Click \"Generate Suggestions\" to see AI-proposed titles\u002Ftags\u002Fcorrespondents\n - Review and approve or edit suggestions\n - Click \"Apply\" to save changes to paperless-ngx\n\n4. **OCR Processing**\n - Tag documents with appropriate OCR tag to process them\n - If enhanced PDF features are enabled, documents will be processed accordingly:\n - For local file saving, check the configured directories for output files\n - For PDF uploads, new documents will appear in paperless-ngx with copied metadata\n - Monitor progress in the Web UI\n - Review results and apply changes\n\n## Troubleshooting\n\n### Working with Local LLMs\n\nWhen using local LLMs (like those through Ollama), you might need to adjust certain settings to optimize performance:\n\n#### Token Management\n\n- Use `TOKEN_LIMIT` environment variable to control the maximum number of tokens sent to the LLM\n- For Ollama, set `OLLAMA_CONTEXT_LENGTH` to control the model's context window (NumCtx). This is independent of `TOKEN_LIMIT` and configures the server-side KV cache size. If unset or 0, the model default is used. Choose a value within the model's supported window (e.g., 8192).\n- Smaller models might truncate content unexpectedly if given too much text\n- Start with a conservative limit (e.g., 1000 tokens) and adjust based on your model's capabilities\n- Set to `0` to disable the limit (use with caution)\n\nExample configuration for smaller models:\n\n```yaml\nenvironment:\n TOKEN_LIMIT: \"2000\" # Adjust based on your model's context window\n OLLAMA_CONTEXT_LENGTH: \"4096\" # Controls Ollama NumCtx (context window); if unset, model default is used\n LLM_PROVIDER: \"ollama\"\n LLM_MODEL: \"qwen3:8b\" # Or other local model\n```\n\nCommon issues and solutions:\n\n- If you see truncated or incomplete responses, try lowering the `TOKEN_LIMIT`\n- On Ollama, if you hit \"context length exceeded\" or memory issues, reduce `OLLAMA_CONTEXT_LENGTH` or choose a smaller model\u002Fcontext size.\n- If processing is too limited, gradually increase the limit while monitoring performance\n- For models with larger context windows, you can increase the limit or disable it entirely\n\n### PDF Processing Issues\n\n- If PDFs aren't being generated, check that `OCR_LIMIT_PAGES` isn't set too low compared to your document page count\n- Ensure volumes are properly mounted if using `CREATE_LOCAL_PDF` or `CREATE_LOCAL_HOCR`\n- When using `PDF_REPLACE: \"true\"`, verify you have recent backups of your paperless-ngx data\n\n### Custom Field Generation Issues\n\n- **Feature Not Working**: If custom field suggestions are not being generated even though the feature is enabled, ensure you have selected at least one custom field in the settings. The feature requires at least one field to be selected to know what to process.\n\n---\n\n## Contributing\n\n**Pull requests** and **issues** are welcome!\n\n1. Fork the repo\n2. Create a branch (`feature\u002Fmy-awesome-update`)\n3. Commit changes (`git commit -m \"Improve X\"`)\n4. Open a PR\n\nCheck out our [contributing guidelines](CONTRIBUTING.md) for details.\n\n---\n\n## Support the Project\n\nIf paperless-gpt is saving you time and making your document management easier, please consider supporting its continued development:\n\n- **[GitHub Sponsors](https:\u002F\u002Fgithub.com\u002Fsponsors\u002Ficereed)**: Help fund ongoing development and maintenance\n- **Share** your success stories and use cases\n- **Star** the project on GitHub\n- **Contribute** code, documentation, or bug reports\n\nYour support helps ensure paperless-gpt remains actively maintained and continues to improve!\n\n---\n\n## Maintainer Note\n\nThis project is fully open-source and will remain free to use. \nIt's maintained by [Icereed](https:\u002F\u002Fgithub.com\u002Ficereed), with partial support from my other project: \n👉 [BubbleTax.de](https:\u002F\u002Fbubbletax.de\u002F?utm_source=github&utm_medium=footer&utm_campaign=paperless) — automated tax reports for IBKR traders in Germany. \nIf you're a developer who also trades, check it out. If not – no worries 😊\n\n---\n\n## License\n\npaperless-gpt is licensed under the [MIT License](LICENSE). Feel free to adapt and share!\n\n---\n\n## Star History\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_readme_dac589a4d459.png)](https:\u002F\u002Fwww.star-history.com\u002F#icereed\u002Fpaperless-gpt&Date)\n\n---\n\n## Disclaimer\n\nThis project is **not** officially affiliated with [paperless-ngx][paperless-ngx]. Use at your own risk.\n\n---\n\n**paperless-gpt**: The **LLM-based** companion your doc management has been waiting for. Enjoy effortless, intelligent document titles, tags, and next-level OCR.\n\n[paperless-ngx]: https:\u002F\u002Fgithub.com\u002Fpaperless-ngx\u002Fpaperless-ngx\n[docker-install]: https:\u002F\u002Fdocs.docker.com\u002Fget-docker\u002F\n","# paperless-gpt\n\n[![许可证](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Ficereed\u002Fpaperless-gpt)](LICENSE)\n[![Discord横幅](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F加入我们%20在-Discord-蓝色?logo=discord)](https:\u002F\u002Fdiscord.gg\u002FfJQppDH2J7)\n[![Docker拉取次数](https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fpulls\u002Ficereed\u002Fpaperless-gpt)](https:\u002F\u002Fhub.docker.com\u002Fr\u002Ficereed\u002Fpaperless-gpt)\n[![GitHub容器注册表](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGHCR-Package-181717?logo=github)](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpkgs\u002Fcontainer\u002Fpaperless-gpt)\n[![贡献者公约](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F贡献者%20公约-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)\n[![GitHub赞助者](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F赞助-icereed-ea4aaa?logo=github-sponsors)](https:\u002F\u002Fgithub.com\u002Fsponsors\u002Ficereed)\n\n\n\u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F12701\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_readme_bbada6ddd5d3.png\" alt=\"icereed%2Fpaperless-gpt | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\n![截图](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_readme_fb7a485fb2b5.png)\n\n\u003Csub>💡 由[Icereed](https:\u002F\u002Fgithub.com\u002Ficereed)维护。自豪地得到[BubbleTax.de](https:\u002F\u002Fbubbletax.de\u002F?utm_source=github&utm_medium=readme&utm_campaign=paperless)的支持——为德国Interactive Brokers交易员提供自动化、符合BMF标准的税务报告。\u003C\u002Fsub>\n\n---\n**paperless-gpt** 可与 [paperless-ngx][paperless-ngx] 无缝配合，生成 **AI驱动的文档标题** 和 **标签**，从而为您节省数小时的手动分类时间。虽然其他工具也可能提供AI聊天功能，但 **paperless-gpt** 的独特之处在于它通过 **LLM增强OCR技术** 来确保高精度，即使面对复杂的扫描件也能游刃有余。如果您渴望更高级的文本提取和轻松的文档管理，那么这就是您的解决方案。\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fbd5d38b9-9309-40b9-93ca-918dfa4f3fd4\n\n> **❤️ 支持这个项目** \n> 如果 paperless-gpt 正在帮助您整理文档并节省时间，请考虑 [赞助其开发](https:\u002F\u002Fgithub.com\u002Fsponsors\u002Ficereed)。您的支持将有助于持续改进和维护！\n\n---\n\n## 核心亮点\n\n1. **LLM增强型OCR** \n 利用大型语言模型（OpenAI或Ollama）实现 **优于传统OCR** 的效果——将杂乱或低质量的扫描件转化为具有上下文理解能力的高质量文本。\n\n2. **使用专业的AI OCR服务**\n\n - **LLM OCR**: 使用OpenAI或Ollama从图像中提取文本。\n - **Google Document AI**: 利用Google强大的Document AI进行OCR任务。\n - **Azure Document Intelligence**: 使用微软的企业级OCR解决方案。\n - **Docling Server**: 自托管的OCR和文档转换服务\n\n3. **自动标题、标签及创建日期生成** \n 不再需要猜测。让AI完成命名和分类工作。您可以轻松查看建议，并在必要时进行调整。\n\n4. **支持Ollama中的推理模型** \n 通过使用像`qwen3:8b`这样的推理模型，可以显著提高准确性。这是隐私与性能之间的完美平衡！当然，如果您有足够的GPU或NPU，更大的模型将进一步提升体验。\n\n5. **自动对应方生成** \n 自动识别并从您的文档中生成对应方信息，使跟踪和组织通信更加便捷。\n\n6. **自动自定义字段生成** \n 从您的文档中提取并填充自定义字段。您可以配置要提取哪些字段以及如何填写它们。此功能必须在设置中启用，并且至少选择一个自定义字段才能生效。提供三种写入模式：\n - **追加**：这是最安全的选项：仅添加文档上尚不存在的新字段。绝不会覆盖现有字段，即使该字段为空。\n - **更新**：添加新字段，并用新建议覆盖现有字段。文档上没有新建议的字段将保持不变。\n - **替换**：删除文档上所有现有的自定义字段，并完全用建议的字段替换。\n\n7. **可搜索且可选中的PDF** \n 生成带有透明文本层的PDF，这些文本层精确地位于每个单词之上，使您的文档既可搜索又可选中，同时保留原始外观。\n\n7. **广泛的自定义功能**\n\n - **通过Web界面自定义提示词**：您可以在“设置”菜单下的Web界面中直接调整和管理用于标题、标签、对应方等的所有AI提示词。应用程序采用安全的`default_prompts`和`prompts`目录结构，确保您的自定义持久化。\n - **标记方式**：您可以决定文档是手动标记、自动标记，还是通过基于OCR的工作流来标记。\n - **PDF处理**：配置如何处理经过OCR增强的PDF文件，可以选择本地保存或上传到paperless-ngx。\n\n8. **简单的Docker部署** \n 只需几个环境变量，即可快速启动！与paperless-ngx一起使用Compose文件部署，操作简单快捷。\n\n9. **统一的Web界面**\n\n - **手动审核**：批准或调整AI的建议。\n - **自动处理**：您只需关注边缘情况，其余工作将由系统自动完成。\n\n9. **临时文档分析**\n 使用自定义提示词对选定的文档进行临时分析。快速获取洞察、摘要，或一次性从多份文档中提取特定信息。\n\n---\n\n## 目录\n\n- [paperless-gpt](#paperless-gpt)\n - [关键亮点](#key-highlights)\n - [目录](#table-of-contents)\n - [开始使用](#getting-started)\n - [先决条件](#prerequisites)\n - [安装](#installation)\n - [Docker Compose](#docker-compose)\n - [手动设置](#manual-setup)\n - [OCR 提供商](#ocr-providers)\n - [1. 基于 LLM 的 OCR（默认）](#1-llm-based-ocr-default)\n - [2. Azure Document Intelligence](#2-azure-document-intelligence)\n - [3. Google Document AI](#3-google-document-ai)\n - [4. Docling Server](#4-docling-server)\n - [OCR 处理模式](#ocr-processing-modes)\n - [图像模式（默认）](#image-mode-default)\n - [PDF 模式](#pdf-mode)\n - [整 PDF 模式](#whole-pdf-mode)\n - [提供商兼容性](#provider-compatibility)\n - [现有 OCR 检测](#existing-ocr-detection)\n - [增强的 OCR 功能](#enhanced-ocr-features)\n - [PDF 文本层生成](#pdf-text-layer-generation)\n - [本地文件保存](#local-file-saving)\n - [PDF 上传到 paperless-ngx](#pdf-upload-to-paperless-ngx)\n - [元数据复制限制](#metadata-copying-limitations)\n - [安全特性](#safety-features)\n - [使用建议](#usage-recommendations)\n - [配置](#configuration)\n - [环境变量](#environment-variables)\n - [自定义提示模板](#custom-prompt-templates)\n - [模板变量](#template-variables)\n - [基于 LLM 的 OCR：亲自比较](#llm-based-ocr-compare-for-yourself)\n - [示例 1](#example-1)\n - [示例 2](#example-2)\n - [工作原理](#how-it-works)\n - [使用方法](#usage)\n - [故障排除](#troubleshooting)\n - [使用本地 LLM](#working-with-local-llms)\n - [令牌管理](#token-management)\n - [PDF 处理问题](#pdf-processing-issues)\n - [自定义字段生成问题](#custom-field-generation-issues)\n - [贡献](#contributing)\n - [支持该项目](#support-the-project)\n - [许可证](#license)\n - [星标历史](#star-history)\n - [免责声明](#disclaimer)\n\n---\n\n## 开始使用\n\n### 先决条件\n\n- 已安装 [Docker][docker-install]。\n- 运行中的 [paperless-ngx][paperless-ngx] 实例。\n- 可访问 LLM 提供商：\n - **OpenAI**：具有 `gpt-4o` 或 `gpt-3.5-turbo` 等模型的 API 密钥。\n - **Ollama**：运行中的 Ollama 服务器，配备如 `qwen3:8b` 等模型。\n\n### 安装\n\n#### Docker Compose\n\n以下是一个 `docker-compose.yml` 示例，用于将 **paperless-gpt** 与 paperless-ngx 一起启动：\n\n```yaml\nservices:\n paperless-ngx:\n image: ghcr.io\u002Fpaperless-ngx\u002Fpaperless-ngx:latest\n # ... (您现有的 paperless-ngx 配置)\n\n paperless-gpt:\n # 使用以下任一镜像源：\n image: icereed\u002Fpaperless-gpt:latest # Docker Hub\n # image: ghcr.io\u002Ficereed\u002Fpaperless-gpt:latest # GitHub Container Registry\n environment:\n PAPERLESS_BASE_URL: \"http:\u002F\u002Fpaperless-ngx:8000\"\n PAPERLESS_API_TOKEN: \"your_paperless_api_token\"\n PAPERLESS_PUBLIC_URL: \"http:\u002F\u002Fpaperless.mydomain.com\" # 可选\n MANUAL_TAG: \"paperless-gpt\" # 可选，默认值：paperless-gpt\n AUTO_TAG: \"paperless-gpt-auto\" # 可选，默认值：paperless-gpt-auto\n # LLM 配置 - 选择其中一种：\n\n # 选项 1：标准 OpenAI\n LLM_PROVIDER: \"openai\"\n LLM_MODEL: \"gpt-4o\"\n OPENAI_API_KEY: \"your_openai_api_key\"\n\n # 选项 2：Mistral\n # LLM_PROVIDER: \"mistral\"\n # LLM_MODEL: \"mistral-large-latest\"\n # MISTRAL_API_KEY: \"your_mistral_api_key\"\n\n # 选项 3：Azure OpenAI\n # LLM_PROVIDER: \"openai\"\n # LLM_MODEL: \"your-deployment-name\"\n # OPENAI_API_KEY: \"your_azure_api_key\"\n # OPENAI_API_TYPE: \"azure\"\n # OPENAI_BASE_URL: \"https:\u002F\u002Fyour-resource.openai.azure.com\"\n\n # 选项 4：Ollama（本地）\n # LLM_PROVIDER: \"ollama\"\n # LLM_MODEL: \"qwen3:8b\"\n # OLLAMA_HOST: \"http:\u002F\u002Fhost.docker.internal:11434\"\n # OLLAMA_CONTEXT_LENGTH: \"8192\" # 设置 Ollama 的 NumCtx（上下文窗口）\n # TOKEN_LIMIT: 1000 # 建议用于较小的模型\n\n # 选项 5：Anthropic\u002FClaude\n # LLM_PROVIDER: \"anthropic\"\n # LLM_MODEL: \"claude-sonnet-4-5\"\n # ANTHROPIC_API_KEY: \"your_anthropic_api_key\"\n\n # 可选 LLM 设置\n # LLM_LANGUAGE: \"English\" # 可选，默认为英语\n\n # OCR 配置 - 选择其中一种：\n # 选项 1：基于 LLM 的 OCR\n OCR_PROVIDER: \"llm\" # 默认 OCR 提供者\n VISION_LLM_PROVIDER: \"ollama\" # openai、ollama、mistral 或 anthropic\n VISION_LLM_MODEL: \"minicpm-v\" # minicpm-v（ollama）或 gpt-4o（openai）或 claude-sonnet-4-5（anthropic\u002Fclaude）\n OLLAMA_HOST: \"http:\u002F\u002Fhost.docker.internal:11434\" # 如果使用 Ollama\n\n # OCR 处理模式\n OCR_PROCESS_MODE: \"image\" # 可选，默认为 image，其他选项：pdf、whole_pdf\n PDF_SKIP_EXISTING_OCR: \"false\" # 可选，跳过已存在 OCR 的 PDF 文件\n\n # 选项 2：Google Document AI\n # OCR_PROVIDER: 'google_docai' # 使用 Google Document AI\n # GOOGLE_PROJECT_ID: 'your-project' # 您的 GCP 项目 ID\n # GOOGLE_LOCATION: 'us' # Document AI 区域\n # GOOGLE_PROCESSOR_ID: 'processor-id' # 您的处理器 ID\n # GOOGLE_APPLICATION_CREDENTIALS: '\u002Fapp\u002Fcredentials.json' # 服务账号密钥路径\n\n # 选项 3：Azure Document Intelligence\n # OCR_PROVIDER: 'azure' # 使用 Azure Document Intelligence\n # AZURE_DOCAI_ENDPOINT: 'your-endpoint' # 您的 Azure 端点 URL\n # AZURE_DOCAI_KEY: 'your-key' # 您的 Azure API 密钥\n # AZURE_DOCAI_MODEL_ID: 'prebuilt-read' # 可选，默认为 prebuilt-read\n # AZURE_DOCAI_TIMEOUT_SECONDS: '120' # 可选，默认为 120 秒\n # AZURE_DOCAI_OUTPUT_CONTENT_FORMAT: 'text' # 可选，默认为 'text'，另一个有效选项是 'markdown'\n # 'markdown' 需要使用 'prebuilt-layout' 模型\n\n # 增强 OCR 功能\n CREATE_LOCAL_HOCR: \"false\" # 可选，保存 hOCR 文件到本地\n LOCAL_HOCR_PATH: \"\u002Fapp\u002Fhocr\" # 可选，hOCR 文件的保存路径\n CREATE_LOCAL_PDF: \"false\" # 可选，保存增强后的 PDF 到本地\n LOCAL_PDF_PATH: \"\u002Fapp\u002Fpdf\" # 可选，PDF 文件的保存路径\n PDF_UPLOAD: \"false\" # 可选，将增强后的 PDF 上传到 paperless-ngx\n PDF_REPLACE: \"false\" # 可选且危险，上传后会删除原始文件\n PDF_COPY_METADATA: \"true\" # 可选，复制原始文档的元数据\n PDF_OCR_TAGGING: \"true\" # 可选，为处理过的文档添加标签\n PDF_OCR_COMPLETE_TAG: \"paperless-gpt-ocr-complete\" # 可选，标签名称\n\n # 选项 4：Docling Server\n # OCR_PROVIDER: 'docling' # 使用 Docling 服务器\n # DOCLING_URL: 'http:\u002F\u002Fyour-docling-server:port' # 您的 Docling 实例的 URL\n # DOCLING_IMAGE_EXPORT_MODE: \"placeholder\" # 可选，默认为 \"embedded\"\n # DOCLING_OCR_PIPELINE: \"standard\" # 可选，默认为 \"vlm\"\n # DOCLING_OCR_ENGINE: \"easyocr\" # 可选，默认为 \"easyocr\"（仅在 `DOCLING_OCR_PIPELINE` 设置为 'standard' 时使用）\n\n\n AUTO_OCR_TAG: \"paperless-gpt-ocr-auto\" # 可选，默认为 paperless-gpt-ocr-auto\n OCR_LIMIT_PAGES: \"5\" # 可选，默认为 5。设置为 0 表示无限制。\n LOG_LEVEL: \"info\" # 可选：debug、warn、error\n volumes:\n - .\u002Fprompts:\u002Fapp\u002Fprompts # 挂载 prompts 目录\n # 对于 Google Document AI：\n - ${HOME}\u002F.config\u002Fgcloud\u002Fapplication_default_credentials.json:\u002Fapp\u002Fcredentials.json\n # 对于本地 hOCR 和 PDF 保存：\n - .\u002Fhocr:\u002Fapp\u002Fhocr # 仅当 CREATE_LOCAL_HOCR 为 true 时\n - .\u002Fpdf:\u002Fapp\u002Fpdf # 仅当 CREATE_LOCAL_PDF 为 true 时\n ports:\n - \"8080:8080\"\n depends_on:\n - paperless-ngx\n```\n\n**实用提示**：请将占位符替换为实际值，如果出现异常情况，请查看日志。\n\n#### 手动安装\n\n1. **克隆仓库**\n ```bash\n git clone https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt.git\n cd paperless-gpt\n ```\n2. **创建 `prompts` 目录**\n ```bash\n mkdir prompts\n ```\n3. **构建 Docker 镜像**\n ```bash\n docker build -t paperless-gpt .\n ```\n4. **运行容器**\n ```bash\n docker run -d \\\n -e PAPERLESS_BASE_URL='http:\u002F\u002Fyour_paperless_ngx_url' \\\n -e PAPERLESS_API_TOKEN='your_paperless_api_token' \\\n -e LLM_PROVIDER='openai' \\\n -e LLM_MODEL='gpt-4o' \\\n -e OPENAI_API_KEY='your_openai_api_key' \\\n -e LLM_LANGUAGE='English' \\\n -e VISION_LLM_PROVIDER='ollama' \\\n -e VISION_LLM_MODEL='minicpm-v' \\\n -e LOG_LEVEL='info' \\\n -v $(pwd)\u002Fprompts:\u002Fapp\u002Fprompts \\\n -p 8080:8080 \\\n paperless-gpt\n ```\n\n---\n\n## OCR 提供商\n\n有关各提供商的详细文档：\n\n- [Mistral AI 集成](docs\u002Fmistral_llm.md)\n\npaperless-gpt 支持四种不同的 OCR 提供商，每种都有其独特的优势和功能：\n\n### 1. 基于 LLM 的 OCR（默认）\n\n- **主要特点**：\n - 使用具备视觉能力的 LLM，如 gpt-4o 或 MiniCPM-V\n - 对复杂布局和困难扫描具有高精度\n - 上下文感知的文本识别\n - 具备自我纠正 OCR 错误的能力\n- **适用场景**：\n - 复杂或不寻常的文档布局\n - 质量较差的扫描件\n - 包含多种语言的文档\n- **配置**：\n ```yaml\n OCR_PROVIDER: \"llm\"\n VISION_LLM_PROVIDER: \"openai\" # 或 \"ollama\"\n VISION_LLM_MODEL: \"gpt-4o\" # 或 \"minicpm-v\"\n ```\n\n### 2. Azure Document Intelligence\n\n- **核心功能**：\n - 企业级 OCR 解决方案\n - 针对常见文档类型的预构建模型\n - 保留版面布局和表格检测\n - 处理速度快\n- **最适合场景**：\n - 商务文档和表单\n - 大量文档处理\n - 需要版面分析的文档\n- **配置示例**：\n ```yaml\n OCR_PROVIDER: \"azure\"\n AZURE_DOCAI_ENDPOINT: \"https:\u002F\u002Fyour-endpoint.cognitiveservices.azure.com\u002F\"\n AZURE_DOCAI_KEY: \"your-key\"\n AZURE_DOCAI_MODEL_ID: \"prebuilt-read\" # 可选\n AZURE_DOCAI_TIMEOUT_SECONDS: \"120\" # 可选\n AZURE_DOCAI_OUTPUT_CONTENT_FORMAT:\n \"text\" # 可选，默认为文本，另一个有效选项是 'markdown'\n # 'markdown' 需要使用 'prebuilt-layout' 模型\n ```\n\n### 3. Google Document AI\n\n- **核心功能**：\n - 企业级 OCR\u002FHTR 解决方案\n - 专用文档处理器\n - 强大的表单字段检测能力\n - 多语言支持\n - 对结构化文档具有高精度\n - **独家 hOCR 生成**，用于创建带有文本层的可搜索 PDF\n - **唯一支持**增强 PDF 生成功能的提供商\n- **最适合场景**：\n - 表单和结构化文档\n - 包含表格的文档\n - 多语言文档\n - 手写文本（HTR）\n- **配置示例**：\n ```yaml\n OCR_PROVIDER: \"google_docai\"\n GOOGLE_PROJECT_ID: \"your-project\"\n GOOGLE_LOCATION: \"us\"\n GOOGLE_PROCESSOR_ID: \"processor-id\"\n CREATE_LOCAL_HOCR: \"true\" # 可选，用于生成 hOCR 文件\n LOCAL_HOCR_PATH: \"\u002Fapp\u002Fhocr\" # 可选，默认路径\n CREATE_LOCAL_PDF: \"true\" # 可选，用于将 OCR 应用到 PDF\n LOCAL_PDF_PATH: \"\u002Fapp\u002Fpdf\" # 可选，默认路径\n ```\n\n### 4. Docling Server\n\n- **核心功能**：\n - 自托管的 OCR 和文档转换服务\n - 支持多种输入和输出格式（包括文本）\n - 利用多个 OCR 引擎（EasyOCR、Tesseract 等）\n - 可在本地或私有网络中运行\n- **最适合场景**：\n - 偏好自托管解决方案的用户\n - 数据隐私至关重要的环境\n - 处理各种类型的文档\n- **配置示例**：\n ```yaml\n OCR_PROVIDER: \"docling\"\n DOCLING_URL: \"http:\u002F\u002Fyour-docling-server:port\"\n DOCLING_IMAGE_EXPORT_MODE: \"placeholder\" # 可选，默认为 \"embedded\"\n DOCLING_OCR_PIPELINE: \"standard\" # 可选，默认为 \"vlm\"\n DOCLING_OCR_ENGINE: \"macocr\" # 可选，默认为 \"easyocr\"（仅当 `DOCLING_OCR_PIPELINE 设置为 'standard' 时使用）\n ```\n\n## OCR 处理模式\n\npaperless-gpt 提供了不同的文档处理方式，可根据您的需求和 OCR 提供商的能力灵活选择：\n\n### 图像模式（默认）\n\n- **工作原理**：在处理前将 PDF 页面转换为图像\n- **最适合场景**：与所有 OCR 提供商兼容。\n- **配置示例**：`OCR_PROCESS_MODE: \"image\"`\n\n### PDF 模式\n\n- **工作原理**：直接处理 PDF 页面，无需转换为图像\n- **最适合场景**：保留 PDF 特性，某些提供商可能处理速度更快且准确性更高\n- **配置示例**：`OCR_PROCESS_MODE: \"pdf\"`\n\n### 整个 PDF 模式\n\n- **工作原理**：一次性处理整个 PDF 文档\n- **最适合场景**：适合能够高效处理多页文档的提供商，减少 API 调用次数\n- **配置示例**：`OCR_PROCESS_MODE: \"whole_pdf\"`\n- **注意**：处理大型 PDF 文件可能会达到 OCR 提供商的 API 使用上限。如果遇到大型文档问题，建议切换到“pdf”模式，该模式会逐页处理。\n\n### 各提供商支持的处理模式\n\n不同 OCR 提供商支持的处理模式有所不同：\n\n| 提供商 | 图像模式 | PDF 模式 | 整个 PDF 模式 |\n|----------|------------|----------|----------------|\n| **基于 LLM 的 OCR**（OpenAI\u002FOllama） | ✅ | ❌ | ❌ |\n| **Azure Document Intelligence** | ✅ | ❌ | ❌ |\n| **Google Document AI** | ✅ | ✅ | ✅ |\n| **Mistral OCR** | ✅ | ✅ | ✅ |\n| **Docling Server** | ✅ | ✅ | ✅ |\n\n> **重要提示**：paperless-gpt 会在启动时验证您的配置，并阻止不支持的模式与提供商组合。如果您为特定提供商指定了不支持的模式，应用程序将无法启动，并显示明确的错误信息。\n\n### 现有 OCR 检测\n\n在使用 PDF 或整个 PDF 模式时，您可以启用现有 OCR 的自动检测功能：\n\n```yaml\nenvironment:\n OCR_PROCESS_MODE: \"pdf\" # 或 \"whole_pdf\"\n PDF_SKIP_EXISTING_OCR: \"true\" # 如果 PDF 中已存在 OCR，则跳过处理\n```\n\n> **注意**：并非所有 OCR 提供商都支持所有处理模式。有些提供商在某些模式下表现更好。根据提供商的不同，以 PDF 模式处理可能比以图像模式处理消耗更多的或更少的 API 调用次数。处理结果会因文档复杂度和提供商能力而异。建议尝试不同的模式，以找到最适合您特定文档和 OCR 提供商的方式。\n\n## 增强的 OCR 功能\n\npaperless-gpt 包含强大的 OCR 增强功能，超越了基本的文本提取：\n\n> **重要提示**：PDF 文本层生成和 hOCR 功能目前**仅支持 Google Document AI** 作为 OCR 提供商。这些功能在使用基于 LLM 的 OCR 或 Azure Document Intelligence 时不可用。\n\n### PDF 文本层生成\n\n- **可搜索且可选中的 PDF**：创建带有透明文本叠加层的 PDF，精确地覆盖文档中的每个单词\n- **hOCR 集成**：利用 hOCR 格式（基于 HTML 的 OCR 表示形式）来保持精确的文本位置\n- **提升文档质量**：使文档既可搜索又可选择，同时保留原始外观\n- **需要 Google Document AI**：这些功能依赖于 Google Document AI 生成包含准确单词位置的 hOCR 数据的能力。\n\n### 本地文件保存\n\npaperless-gpt 可以将 hOCR 文件和增强后的 PDF 本地保存：\n\n```yaml\nenvironment:\n # 启用本地文件保存\n CREATE_LOCAL_HOCR: \"true\" # 将 hOCR 文件本地保存\n CREATE_LOCAL_PDF: \"true\" # 将生成的 PDF 文件本地保存\n LOCAL_HOCR_PATH: \"\u002Fapp\u002Fhocr\" # 保存 hOCR 文件的路径\n LOCAL_PDF_PATH: \"\u002Fapp\u002Fpdf\" # 保存 PDF 文件的路径\nvolumes:\n # 挂载卷以便从主机访问文件\n - .\u002Fhocr_files:\u002Fapp\u002Fhocr\n - .\u002Fpdf_files:\u002Fapp\u002Fpdf\n```\n\n> **注意**：您必须在 Docker 配置中将这些目录挂载为卷，才能从主机系统访问生成的文件。\n\n### 将 PDF 上传至 paperless-ngx\n\n由于 paperless-ngx 的 API 存在限制，无法直接用 OCR 增强后的版本更新现有文档。作为 workaround，paperless-gpt 可以：\n\n1. 将增强后的 PDF 作为新文档上传\n2. 将元数据从原文档复制到新文档\n3. 可选地删除原文档\n\n```yaml\nenvironment:\n # PDF 上传配置\n PDF_UPLOAD: \"true\" # 将处理后的 PDF 上传至 paperless-ngx\n PDF_COPY_METADATA: \"true\" # 从原文档复制元数据到新文档\n PDF_REPLACE: \"false\" # 是否删除原文档（请谨慎使用！）\n PDF_OCR_TAGGING: \"true\" # 添加标签以标记已进行 OCR 处理的文档\n PDF_OCR_COMPLETE_TAG: \"paperless-gpt-ocr-complete\" # 用于标记已 OCR 处理文档的标签\n```\n\n> **⚠️ 警告 ⚠️** \n> 将 `PDF_REPLACE: \"true\"` 设置后，在上传增强版本之后会删除原文档。此操作不可撤销，若上传或元数据复制过程中出现任何问题，可能导致数据丢失。请务必谨慎使用！\n\n### 元数据复制的限制\n\n在将元数据从原文档复制到新文档时，paperless-gpt 会尝试复制以下内容：\n\n- 文档标题\n- 标签（包括添加 OCR 完成标签）\n- 收件人信息\n- 创建日期\n\n然而，由于 paperless-ngx 的 API 限制，部分元数据无法被复制：\n\n- 文档 ID（新文档始终会获得一个新的 ID）\n- 添加日期（将反映当前的上传日期）\n- 修改日期\n- 其他 paperless-ngx 插件可能添加的自定义字段\n- 备注和注释\n\n### 安全特性\n\n为防止意外生成不完整文档，paperless-gpt 提供了多项安全措施：\n\n1. **页数检查**：如果使用 `OCR_LIMIT_PAGES` 参数仅处理部分页面（出于速度或资源考虑），而实际处理的页数少于原文档的总页数，则会完全跳过 PDF 生成步骤。\n\n```yaml\nenvironment:\n OCR_LIMIT_PAGES: \"5\" # 限制 OCR 只处理前 5 页，设置为 0 表示无限制\n```\n\n2. **OCR 完成标记**：已完成 OCR 处理的文档可自动打上特殊标签，从而避免重复处理。\n\n3. **跳过处理**：若文档已带有 OCR 完成标签，则会自动跳过处理流程。\n\n### 使用建议\n\n为获得最佳的 OCR 增强效果：\n\n1. **初次测试**：请先将 `PDF_REPLACE: \"false\"`，待确认流程对您的文档运行良好后再启用替换功能。\n\n2. **定期备份**：在启用文档替换功能之前，请确保已对 paperless-ngx 数据库及文档进行备份。\n\n3. **流程管理**：对于大型文档，建议将 `OCR_LIMIT_PAGES: \"0\"`，以确保所有页面都被处理，尽管这会花费更多时间。\n\n4. **本地副本**：启用本地文件保存功能（`CREATE_LOCAL_HOCR` 和 `CREATE_LOCAL_PDF`），以便额外保留增强文件的副本。\n\n5. **标签策略**：使用 OCR 完成标签（`PDF_OCR_COMPLETE_TAG`）来跟踪哪些文档已经完成处理。\n\n## 配置\n\n### 环境变量\n\n> **注意**：使用 Ollama 时，请确保 Ollama 服务器正在运行，并且 paperless-gpt 容器可以访问该服务器。\n\n| 变量 | 描述 | 必填 | 默认值 |\n| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------- |\n| `PAPERLESS_BASE_URL` | 您的 paperless-ngx 实例的 URL（例如 `http:\u002F\u002Fpaperless-ngx:8000`）。 | 是 | |\n| `PAPERLESS_API_TOKEN` | paperless-ngx 的 API 令牌。请在 paperless-ngx 管理员界面生成一个。 | 是 | |\n| `PAPERLESS_PUBLIC_URL` | Paperless 的公网 URL（如果与 `PAPERLESS_BASE_URL` 不同）。 | 否 | |\n| `MANUAL_TAG` | 手动处理的标签。 | 否 | paperless-gpt |\n| `AUTO_TAG` | 自动处理的标签。 | 否 | paperless-gpt-auto |\n| `LLM_PROVIDER` | AI 后端（`openai`、`ollama`、`googleai`、`mistral` 或 `anthropic`）。 | 是 | |\n| `LLM_MODEL` | AI 模型名称（例如 `gpt-4o`、`mistral-large-latest`、`qwen3:8b`、`claude-sonnet-4-5`）。 | 是 | |\n| `OPENAI_API_KEY` | OpenAI API 密钥（如果使用 OpenAI，则必需）。 | 条件 | |\n| `MISTRAL_API_KEY` | Mistral API 密钥（如果使用 Mistral，则必需）。 | 条件 | |\n| `ANTHROPIC_API_KEY` | Anthropic API 密钥（如果使用 Anthropic\u002FClaude，则必需）。 | 条件 | |\n| `OPENAI_API_TYPE` | 设置为 `azure` 以使用 Azure OpenAI 服务。 | 否 | |\n| `OPENAI_BASE_URL` | OpenAI API 的基础 URL。对于 Azure OpenAI，设置为您部署的 URL（例如 `https:\u002F\u002Fyour-resource.openai.azure.com`）。 | 否 | |\n| `LLM_LANGUAGE` | 文档可能的语言（例如 `English`）。会出现在提示中，以帮助 LLM。 | 否 | English |\n| `GOOGLEAI_API_KEY` | Google Gemini API 密钥（如果使用 `LLM_PROVIDER=googleai`，则必需）。 | 条件 | |\n| `GOOGLEAI_THINKING_BUDGET` | （可选，仅适用于 googleai）整数。控制 Gemini 的“思考”预算。如果未设置，则使用模型默认值（如果支持则启用思考）。设置为 `0` 可禁用思考（如果模型支持）。 | 否 | |\n| `OLLAMA_HOST` | Ollama 服务器 URL（例如 `http:\u002F\u002Fhost.docker.internal:11434`）。 | 否 | |\n| `LLM_REQUESTS_PER_MINUTE` | 主 LLM 每分钟的最大请求数。有助于管理 API 成本或本地 LLM 的负载。 | 否 | 120 |\n| `LLM_MAX_RETRIES` | 主 LLM 请求失败时的最大重试次数。 | 否 | 3 |\n| `LLM_BACKOFF_MAX_WAIT` | 主 LLM 重试之间的最大等待时间（例如 `30s`）。 | 否 | 30s |\n| `OCR_PROVIDER` | 要使用的 OCR 提供商（`llm`、`azure` 或 `google_docai`）。 | 否 | llm |\n| `OCR_PROCESS_MODE` | 处理文档的方式：`image`（先转换为图像）、`pdf`（直接处理 PDF 页面）或 `whole_pdf`（一次性处理整个 PDF）。 | 否 | image |\n| `VISION_LLM_PROVIDER` | 用于 LLM OCR 的 AI 后端（`openai`、`ollama`、`mistral` 或 `anthropic`）。如果 OCR_PROVIDER 是 `llm`，则必需。 | 条件 | |\n| `VISION_LLM_MODEL` | LLM OCR 的模型名称（例如 `minicpm-v`）。如果 OCR_PROVIDER 是 `llm`，则必需。 | 条件 | |\n| `VISION_LLM_REQUESTS_PER_MINUTE` | 视觉 LLM 每分钟的最大请求数。有助于管理 API 成本或本地 LLM 的负载。 | 否 | 120 |\n| `VISION_LLM_MAX_RETRIES` | 视觉 LLM 请求失败时的最大重试次数。 | 否 | 3 |\n| `VISION_LLM_BACKOFF_MAX_WAIT` | 视觉 LLM 重试之间的最大等待时间（例如 `30s`）。 | 否 | 30s |\n| `VISION_LLM_MAX_TOKENS` | 视觉 LLM OCR 输出的最大 token 数。 | 否 | |\n| `VISION_LLM_TEMPERATURE` | 视觉 OCR 生成的采样温度。数值越低，结果越确定性。重要提示：对于 OpenAI GPT-5，必须显式设置为 `1.0`。 | 否 | |\n| `OLLAMA_CONTEXT_LENGTH` | （仅适用于 Ollama）整数。设置 Ollama 运行器的 NumCtx（上下文窗口）。如果未设置或为 0，则使用模型默认值。 | 否 | |\n| `OLLAMA_OCR_TOP_K` | （仅适用于 Ollama）视觉 OCR 的 top-k 采样。数值越低，越倾向于更可能的 token；数值越高，则增加多样性。 | 否 | |\n| `AZURE_DOCAI_ENDPOINT` | Azure Document Intelligence 端点。如果 OCR_PROVIDER 是 `azure`，则必需。 | 条件 | |\n| `AZURE_DOCAI_KEY` | Azure Document Intelligence API 密钥。如果 OCR_PROVIDER 是 `azure`，则必需。 | 条件 | |\n| `AZURE_DOCAI_MODEL_ID` | Azure Document Intelligence 模型 ID。如果使用 `azure` 提供商，可以不设置。 | 否 | prebuilt-read |\n| `AZURE_DOCAI_TIMEOUT_SECONDS` | Azure Document Intelligence 的超时时间，单位为秒。 | 否 | 120 |\n| `AZURE_DOCAI_OUTPUT_CONTENT_FORMAT` | Azure Document Intelligence 输出内容格式。如果使用 `azure` 提供商，可以不设置。默认为 `text`。另一个选项是 `markdown`，但需要使用 `prebuild-layout` 模型 ID。 | 否 | text |\n| `GOOGLE_PROJECT_ID` | Google Cloud 项目 ID。如果 OCR_PROVIDER 是 `google_docai`，则必需。 | 条件 | |\n| `GOOGLE_LOCATION` | Google Cloud 地区（例如 `us`、`eu`）。如果 OCR_PROVIDER 是 `google_docai`，则必需。 | 条件 | |\n| `GOOGLE_PROCESSOR_ID` | Document AI 处理器 ID。如果 OCR_PROVIDER 是 `google_docai`，则必需。 | 条件 | |\n| `GOOGLE_APPLICATION_CREDENTIALS` | 挂载的 Google 服务账号密钥路径。如果 OCR_PROVIDER 是 `google_docai`，则必需。 | 条件 | |\n| `DOCLING_URL` | Docling 服务器实例的 URL。如果 OCR_PROVIDER 是 `docling`，则必需。 | 条件 | |\n| `DOCLING_IMAGE_EXPORT_MODE` | 图像导出模式。可选；未设置时默认为 `embedded`。 | 否 | embedded |\n| `DOCLING_OCR_PIPELINE` | 设置管道类型。可选；未设置时默认为 `vlm`。 | 否 | vlm |\n| `DOCLING_OCR_ENGINE` | 设置 OCR 引擎，如果 `DOCLING_OCR_PIPELINE` 设置为 `standard`。可选；默认为 `easyocr` | 否 | easyocr |\n| `CREATE_LOCAL_HOCR` | 是否将 hOCR 文件本地保存。 | 否 | false |\n| `LOCAL_HOCR_PATH` | 当启用 hOCR 生成时，hOCR 文件将保存的路径。 | 否 | \u002Fapp\u002Fhocr |\n| `CREATE_LOCAL_PDF` | 是否将增强后的 PDF 文件本地保存。 | 否 | false |\n| `LOCAL_PDF_PATH` | 当启用 PDF 生成时，PDF 文件将保存的路径。 | 否 | \u002Fapp\u002Fpdf |\n| `PDF_UPLOAD` | 是否将增强后的 PDF 上传到 paperless-ngx。 | 否 | false |\n| `PDF_REPLACE` | 是否在上传增强版本后删除原始文档（危险操作）。 | 否 | false |\n| `PDF_COPY_METADATA` | 是否将元数据从原始文档复制到上传的 PDF 中。仅在使用 PDF_UPLOAD 时适用。 | 否 | true |\n| `PDF_OCR_TAGGING` | 是否添加标签以标记已进行 OCR 处理的文档。 | 否 | true |\n| `PDF_OCR_COMPLETE_TAG` | 用于标记已进行 OCR 处理的文档的标签。 | 否 | paperless-gpt-ocr-complete |\n| `PDF_SKIP_EXISTING_OCR` | 是否跳过已包含 OCR 的 PDF 的 OCR 处理。适用于 `pdf` 和 `whole_pdf` 处理模式（`OCR_PROCESS_MODE`）。 | 否 | false |\n| `AUTO_OCR_TAG` | 自动使用 OCR 处理文档的标签。 | 否 | paperless-gpt-ocr-auto |\n| `OCR_LIMIT_PAGES` | 限制 OCR 处理的页数。设置为 `0` 表示无限制。 | 否 | 5 |\n| `LOG_LEVEL` | 应用程序日志级别（`info`、`debug`、`warn`、`error`）。 | 否 | info |\n| `LISTEN_INTERFACE` | 监听的网络接口。 | 否 | 8080 |\n| `AUTO_GENERATE_TITLE` | 如果使用 `paperless-gpt-auto`，是否自动生标题。 | 否 | true |\n| `AUTO_GENERATE_TAGS` | 如果使用 `paperless-gpt-auto`，是否自动生标签。 | 否 | true |\n| `CREATE_NEW_TAGS` | 允许 LLM 建议尚未存在于 paperless-ngx 中的新标签。启用后，新标签将自动在 paperless-ngx 中创建。 | 否 | false |\n| `AUTO_GENERATE_CORRESPONDENTS` | 如果使用 `paperless-gpt-auto`，是否自动生通信对象。 | 否 | true |\n| `AUTO_GENERATE_DOCUMENT_TYPE` | 如果使用 `paperless-gpt-auto`，是否自动生文档类型。仅会使用 paperless-ngx 中已有的文档类型。 | 否 | true |\n| `AUTO_GENERATE_CREATED_DATE` | 如果使用 `paperless-gpt-auto`，是否自动生创建日期。 | 否 | true |\n| `TOKEN_LIMIT` | 提示\u002F内容允许的最大 token 数。设置为 `0` 可禁用限制。对小型 LLM 有用。 | 否 | |\n| `IMAGE_MAX_PIXEL_DIMENSION` | 渲染文档页面为图像时，任意一边的最大像素数。 | 否 | 10000 |\n| `IMAGE_MAX_TOTAL_PIXELS` | 渲染文档页面为图像时，总像素数（宽度 × 高度）的最大值。 | 否 | 40000000 |\n| `IMAGE_MAX_RENDER_DPI` | 渲染文档页面为图像时使用的最大 DPI。 | 否 | 600 |\n| `IMAGE_MAX_FILE_BYTES` | 渲染后的页面图像的最大 JPEG 文件大小（以字节为单位）。超过此限制的图像会被压缩或调整尺寸。 | 否 | 10485760 |\n| `CORRESPONDENT_BLACK_LIST` | 以逗号分隔的姓名列表，用于排除在通信对象建议之外。例如：`John Doe, Jane Smith`。 | 否 | |\n\n### 自定义提示模板\n\npaperless-gpt 的灵活 **提示模板** 允许您定义 AI 的响应方式。尽管您仍然可以手动管理文件，但推荐的自定义提示方法是通过 Web UI 中的 **设置** 页面进行。\n\n该应用使用两个目录来管理模板：\n- **`default_prompts\u002F`**：包含内置的默认模板。这些模板不应被修改。\n- **`prompts\u002F`**：您的工作目录。首次运行时，默认模板会被复制到这里。所有在 UI 中进行的编辑都会保存到此目录下的文件中。\n\n为确保您的自定义提示在容器重启后仍然保留，您必须在 `docker-compose.yml` 文件中将 `prompts` 目录挂载为卷：\n\n```yaml\nvolumes:\n # 这对于保存您的自定义提示至关重要！\n - .\u002Fprompts:\u002Fapp\u002Fprompts\n```\n\n应用程序会在您通过 UI 保存模板后以及启动时立即重新加载模板，因此无需重启即可使更改生效。\n\n#### 模板变量\n\n每个模板都可以访问特定的变量：\n\n**title_prompt.tmpl**:\n\n- `{{.Language}}` - 目标语言（例如，“英语”）\n- `{{.Content}}` - 文档内容文本\n- `{{.Title}}` - 原始文档标题\n\n**tag_prompt.tmpl**:\n\n- `{{.Language}}` - 目标语言\n- `{{.AvailableTags}}` - paperless-ngx 中现有的标签列表\n- `{{.OriginalTags}}` - 文档当前的标签\n- `{{.Title}}` - 文档标题\n- `{{.Content}}` - 文档内容文本\n\n**ocr_prompt.tmpl**:\n\n- `{{.Language}}` - 目标语言\n\n**correspondent_prompt.tmpl**:\n\n- `{{.Language}}` - 目标语言\n- `{{.AvailableCorrespondents}}` - 现有的通信方列表\n- `{{.BlackList}}` - 被列入黑名单的通信方名称列表\n- `{{.Title}}` - 文档标题\n- `{{.Content}}` - 文档内容文本\n\n**created_date_prompt.tmpl**:\n\n- `{{.Language}}` - 目标语言\n- `{{.Content}}` - 文档内容文本\n\n**custom_field_prompt.tmpl**:\n\n- `{{.DocumentType}}` - 文档在 paperless-ngx 中的类型名称。\n- `{{.CustomFieldsXML}}` - 一个 XML 字符串，列出了在设置中选择用于处理的自定义字段。\n- `{{.Title}}` - 文档标题\n- `{{.CreatedDate}}` - 文档的创建日期\n- `{{.Content}}` - 文档内容文本\n\n模板使用 Go 的 text\u002Ftemplate 语法。paperless-gpt 会在 UI 保存后以及启动时自动重新加载模板更改。\n\n---\n\n## 基于 LLM 的 OCR：亲自比较\n\n\u003Cdetails>\n\u003Csummary>点击展开原生 OCR 与 AI 驱动的 OCR 对比\u003C\u002Fsummary>\n\n### 示例 1\n\n**图片**：\n\n![图片](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_readme_b7f38db62490.jpg)\n\n**原生 Paperless-ngx OCR**：\n\n```\nLa Grande Recre\n\nGentre Gommercial 1'Esplanade\n1349 LOLNAIN LA NEWWE\nTA BERBOGAAL Tel =. 010 45,96 12\nTicket 1440112 03\u002F11\u002F2006 a 13597:\n4007176614518. DINOS. TYRAMNESA\nTOTAET.T.LES\nReslE par Lask-Euron\nRencu en Cash Euro\nV.14.6 -Hotgese = VALERTE\nTICKET A-GONGERVER PORR TONT. EEHANGE\nHERET ET A BIENTOT\n```\n\n**LLM 驱动的 OCR（OpenAI gpt-4o）**：\n\n```\nLa Grande Récré\nCentre Commercial l'Esplanade\n1348 LOUVAIN LA NEUVE\nTVA 860826401 Tel : 010 45 95 12\nTicket 14421 le 03\u002F11\u002F2006 à 15:27:18\n4007176614518 DINOS TYRANNOSA 14.90\nTOTAL T.T.C. 14.90\nRéglé par Cash Euro 50.00\nRendu en Cash Euro 35.10\nV.14.6 Hôtesse : VALERIE\nTICKET A CONSERVER POUR TOUT ECHANGE\nMERCI ET A BIENTOT\n```\n\n---\n\n### Example 2\n\n**Image**:\n\n![Image](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_readme_ba0fdb1cf694.jpg)\n\n**Vanilla Paperless-ngx OCR**:\n\n```\nInvoice Number: 1-996-84199\n\nFed: Invoica Date: Sep01, 2014\nAccaunt Number: 1334-8037-4\nPage: 1012\n\nFod£x Tax ID 71.0427007\n\nIRISINC\nSHARON ANDERSON\n4731 W ATLANTIC AVE STE BI\nDELRAY BEACH FL 33445-3897 ’ a\nInvoice Questions?\n\nBing, ‚Account Shipping Address: Contact FedEx Reı\n\nISINC\n4731 W ATLANTIC AVE Phone: (800) 622-1147 M-F 7-6 (CST)\nDELRAY BEACH FL 33445-3897 US Fax: (800) 548-3020\n\nInternet: www.fedex.com\n\nInvoice Summary Sep 01, 2014\n\nFodEx Ground Services\nOther Charges 11.00\nTotal Charges 11.00 Da £\n>\npolo) Fz\u002F\u002F \u002FG\nTOTAL THIS INVOICE .... usps 11.00 P 2\u002F1 f\n\n‘The only charges accrued for this period is the Weekly Service Charge.\n\nThe Fedix Ground aceounts teferencedin his involce have been transteired and assigned 10, are owned by,andare payable to FedEx Express:\n\nTo onsurs propor credit, plasa raturn this portion wirh your payment 10 FodEx\n‚Please do not staple or fold. Ploase make your chack payablı to FedEx.\n\n[TI For change ol address, hc har and camphat lrm or never ide\n\nRemittance Advice\nYour payment is due by Sep 16, 2004\n\nNumber Number Dus\n\n1334803719968 41993200000110071\n\nAT 01 0391292 468448196 A**aDGT\n\nIRISINC Illallun elalalssollallansdHilalellund\nSHARON ANDERSON\n\n4731 W ATLANTIC AVE STEBI FedEx\n\nDELRAY BEACH FL 334453897 PO. Box 94516\n\nPALATINE IL 60094-4515\n```\n\n**LLM-Powered OCR (OpenAI gpt-4o)**:\n\n```\nFedEx. Invoice Number: 1-996-84199\n Invoice Date: Sep 01, 2014\n Account Number: 1334-8037-4\n Page: 1 of 2\n FedEx Tax ID: 71-0427007\n\nI R I S INC\nSHARON ANDERSON\n4731 W ATLANTIC AVE STE B1\nDELRAY BEACH FL 33445-3897\n Invoice Questions?\nBilling Account Shipping Address: Contact FedEx Revenue Services\nI R I S INC Phone: (800) 622-1147 M-F 7-6 (CST)\n4731 W ATLANTIC AVE Fax: (800) 548-3020\nDELRAY BEACH FL 33445-3897 US Internet: www.fedex.com\n\nInvoice Summary Sep 01, 2014\n\nFedEx Ground Services\nOther Charges 11.00\n\nTotal Charges .......................................................... USD $ 11.00\n\nTOTAL THIS INVOICE .............................................. USD $ 11.00\n\nThe only charges accrued for this period is the Weekly Service Charge.\n\n RECEIVED\n SEP _ 8 REC'D\n BY: _\n\n posted 9\u002F21\u002F14\n\nThe FedEx Ground accounts referenced in this invoice have been transferred and assigned to, are owned by, and are payable to FedEx Express.\n\nTo ensure proper credit, please return this portion with your payment to FedEx.\nPlease do not staple or fold. Please make your check payable to FedEx.\n\n❑ For change of address, check here and complete form on reverse side.\n\nRemittance Advice\nYour payment is due by Sep 16, 2004\n\nInvoice\nNumber\n1-996-84199\n\nAccount\nNumber\n1334-8037-4\n\nAmount\nDue\nUSD $ 11.00\n\n133480371996841993200000110071\n\nAT 01 031292 468448196 A**3DGT\n\nI R I S INC\nSHARON ANDERSON\n4731 W ATLANTIC AVE STE B1\nDELRAY BEACH FL 33445-3897\n\nFedEx\nP.O. Box 94515\n```\n\n---\n\n\u003C\u002Fdetails>\n\n**Why Does It Matter?**\n\n- Traditional OCR often jumbles text from complex or low-quality scans.\n- Large Language Models interpret context and correct likely errors, producing results that are more precise and readable.\n- You can integrate these cleaned-up texts into your **paperless-ngx** pipeline for better tagging, searching, and archiving.\n\n### How It Works\n\n- **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.\n- **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.\n- **Google Document AI and Azure Document Intelligence** provide high-accuracy OCR with advanced layout analysis.\n- **Enhanced PDF Generation** combines OCR results with the original document to create searchable PDFs with properly positioned text layers.\n\n---\n\n## Usage\n\n1. **Tag Documents**\n\n - Add `paperless-gpt` tag to documents for manual processing\n - Add `paperless-gpt-auto` for automatic processing\n - Add `paperless-gpt-ocr-auto` for automatic OCR processing\n\n2. **Visit Web UI**\n\n - Go to `http:\u002F\u002Flocalhost:8080` (or your host) in your browser\n - Review documents tagged for processing\n\n3. **Generate & Apply Suggestions**\n\n - Click \"Generate Suggestions\" to see AI-proposed titles\u002Ftags\u002Fcorrespondents\n - Review and approve or edit suggestions\n - Click \"Apply\" to save changes to paperless-ngx\n\n4. **OCR Processing**\n - Tag documents with appropriate OCR tag to process them\n - If enhanced PDF features are enabled, documents will be processed accordingly:\n - For local file saving, check the configured directories for output files\n - For PDF uploads, new documents will appear in paperless-ngx with copied metadata\n - Monitor progress in the Web UI\n - Review results and apply changes\n\n## Troubleshooting\n\n### 使用本地大模型\n\n在使用本地大模型（例如通过 Ollama 提供的模型）时，可能需要调整某些设置以优化性能：\n\n#### 令牌管理\n\n- 使用 `TOKEN_LIMIT` 环境变量来控制发送到大模型的最大令牌数。\n- 对于 Ollama，设置 `OLLAMA_CONTEXT_LENGTH` 来控制模型的上下文窗口大小（NumCtx）。这与 `TOKEN_LIMIT` 是独立的，用于配置服务器端的 KV 缓存大小。如果未设置或设为 0，则使用模型默认值。请根据模型支持的窗口范围选择一个合适的值（例如 8192）。\n- 如果给小型模型输入过多文本，可能会导致内容被意外截断。\n- 建议从一个保守的限制值开始（如 1000 个令牌），然后根据模型的能力逐步调整。\n- 将其设置为 `0` 可以禁用限制（请谨慎使用）。\n\n针对小型模型的示例配置：\n\n```yaml\nenvironment:\n TOKEN_LIMIT: \"2000\" # 根据你的模型上下文窗口调整\n OLLAMA_CONTEXT_LENGTH: \"4096\" # 控制 Ollama 的 NumCtx（上下文窗口）；未设置时将使用模型默认值\n LLM_PROVIDER: \"ollama\"\n LLM_MODEL: \"qwen3:8b\" # 或其他本地模型\n```\n\n常见问题及解决方法：\n\n- 如果看到响应被截断或不完整，请尝试降低 `TOKEN_LIMIT`。\n- 在 Ollama 中，如果出现“上下文长度超出”或内存问题，可以减少 `OLLAMA_CONTEXT_LENGTH`，或者选择更小的模型和上下文窗口。\n- 如果处理能力受限，可以在监控性能的同时逐步提高限制。\n- 对于具有更大上下文窗口的模型，可以适当增加限制，甚至完全禁用限制。\n\n### PDF 处理问题\n\n- 如果 PDF 文件未能生成，请检查 `OCR_LIMIT_PAGES` 是否设置得太低，与文档的实际页数相比。\n- 如果使用 `CREATE_LOCAL_PDF` 或 `CREATE_LOCAL_HOCR` 功能，请确保卷已正确挂载。\n- 当使用 `PDF_REPLACE: \"true\"` 时，务必确认你已备份了最新的 paperless-ngx 数据。\n\n### 自定义字段生成问题\n\n- **功能未生效**：如果自定义字段建议未生成，即使该功能已启用，也请确保在设置中至少选择了一个自定义字段。该功能需要至少选择一个字段才能知道要处理的内容。\n\n---\n\n## 贡献\n\n欢迎提交 **Pull 请求** 和 **问题报告**！\n\n1. 克隆仓库并创建分支（`feature\u002Fmy-awesome-update`）\n2. 提交更改（`git commit -m \"改进 X\"`）\n3. 打开 PR\n\n更多详情请参阅我们的 [贡献指南](CONTRIBUTING.md)。\n\n---\n\n## 支持本项目\n\n如果 paperless-gpt 正在帮助您节省时间并简化文档管理工作，欢迎您支持其持续开发：\n\n- **[GitHub Sponsors](https:\u002F\u002Fgithub.com\u002Fsponsors\u002Ficereed)**：资助项目的持续开发与维护。\n- 分享您的成功案例和使用场景。\n- 在 GitHub 上为本项目点赞。\n- 参与代码、文档或错误报告的贡献。\n\n您的支持将有助于确保 paperless-gpt 得到积极维护，并不断改进！\n\n---\n\n## 维护者注释\n\n本项目完全开源，且将继续免费使用。 \n由 [Icereed](https:\u002F\u002Fgithub.com\u002Ficereed) 维护，同时部分支持来自我的另一个项目： \n👉 [BubbleTax.de](https:\u002F\u002Fbubbletax.de\u002F?utm_source=github&utm_medium=footer&utm_campaign=paperless) — 为德国 IBKR 交易员提供自动化的税务报表。 \n如果您是一名开发者兼交易者，不妨试试这个工具。如果不是也没关系 😊\n\n---\n\n## 许可证\n\npaperless-gpt 采用 [MIT 许可证](LICENSE) 开源，您可以自由地修改和分享！\n\n---\n\n## 星标历史\n\n[![星标历史图表](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_readme_dac589a4d459.png)](https:\u002F\u002Fwww.star-history.com\u002F#icereed\u002Fpaperless-gpt&Date)\n\n---\n\n## 免责声明\n\n本项目与 [paperless-ngx][paperless-ngx] 官方并无关联。请自行承担使用风险。\n\n---\n\n**paperless-gpt**：您文档管理一直期待的基于大语言模型的助手。轻松实现智能文档标题、标签以及更高层次的 OCR 处理。\n\n[paperless-ngx]: https:\u002F\u002Fgithub.com\u002Fpaperless-ngx\u002Fpaperless-ngx\n[docker-install]: https:\u002F\u002Fdocs.docker.com\u002Fget-docker\u002F","# paperless-gpt 快速上手指南\n\n`paperless-gpt` 是一款专为 [paperless-ngx](https:\u002F\u002Fgithub.com\u002Fpaperless-ngx\u002Fpaperless-ngx) 设计的 AI 增强工具。它利用大语言模型（LLM）和多模态视觉模型，自动为文档生成精准的标题、标签、对应方及自定义字段，并提供超越传统 OCR 的文本提取能力，大幅减少人工整理文档的时间。\n\n## 环境准备\n\n在部署前，请确保满足以下前置条件：\n\n* **运行环境**：已安装并配置好 **Docker** 和 **Docker Compose**。\n* **核心依赖**：拥有一个正在运行的 **paperless-ngx** 实例。\n* **AI 模型服务**（任选其一）：\n * **OpenAI \u002F Azure OpenAI \u002F Anthropic \u002F Mistral**：拥有有效的 API Key。\n * **Ollama**（推荐本地部署）：已安装并运行 Ollama 服务，且拉取了相关模型（如 `qwen3:8b` 用于文本推理，`minicpm-v` 用于视觉 OCR）。\n * *国内用户提示*：若使用 Ollama，建议通过国内镜像源加速模型下载，或自行部署本地 Ollama 服务以保障隐私和速度。\n\n## 安装步骤\n\n推荐使用 Docker Compose 将 `paperless-gpt` 与现有的 paperless-ngx 编排在一起。\n\n1. **获取 paperless-ngx 的 API Token**\n 登录你的 paperless-ngx 后台，进入设置生成一个 API Token。\n\n2. **创建 `docker-compose.yml`**\n 在你的 docker-compose 文件中添加 `paperless-gpt` 服务。以下是一个基于 **Ollama (本地模型)** 的最小化配置示例：\n\n```yaml\nservices:\n paperless-ngx:\n image: ghcr.io\u002Fpaperless-ngx\u002Fpaperless-ngx:latest\n # ... (保留你原有的 paperless-ngx 配置)\n\n paperless-gpt:\n image: icereed\u002Fpaperless-gpt:latest\n # 或者使用 GitHub 镜像: ghcr.io\u002Ficereed\u002Fpaperless-gpt:latest\n environment:\n # 基础连接配置\n PAPERLESS_BASE_URL: \"http:\u002F\u002Fpaperless-ngx:8000\"\n PAPERLESS_API_TOKEN: \"your_paperless_api_token_here\"\n \n # LLM 配置 (用于生成标题、标签等)\n LLM_PROVIDER: \"ollama\"\n LLM_MODEL: \"qwen3:8b\"\n OLLAMA_HOST: \"http:\u002F\u002Fhost.docker.internal:11434\"\n \n # OCR 配置 (用于高精度文字识别)\n OCR_PROVIDER: \"llm\"\n VISION_LLM_PROVIDER: \"ollama\"\n VISION_LLM_MODEL: \"minicpm-v\"\n \n # 可选：限制 Token 数量以适应小显存\n TOKEN_LIMIT: \"1000\"\n depends_on:\n - paperless-ngx\n restart: unless-stopped\n```\n\n> **注意**：如果你在使用 Linux 宿主机运行 Docker，`host.docker.internal` 可能需要替换为宿主机的实际 IP 地址，或者在 Docker 启动参数中添加 `--add-host host.docker.internal:host-gateway`。\n\n3. **启动服务**\n 在包含 `docker-compose.yml` 的目录下执行：\n\n```bash\ndocker compose up -d\n```\n\n## 基本使用\n\n部署完成后，无需复杂的命令行操作，主要通过 paperless-ngx 的界面进行交互。\n\n### 1. 自动处理流程\n默认情况下，工具会监听带有特定标签的文档。\n* **手动触发**：在 paperless-ngx 中给文档打上标签 `paperless-gpt`（可通过环境变量 `MANUAL_TAG` 修改），系统会自动分析该文档，生成标题、标签和建议内容。\n* **自动处理**：给文档打上标签 `paperless-gpt-auto`（可通过环境变量 `AUTO_TAG` 修改），系统将直接应用 AI 生成的结果而无需人工确认。\n\n### 2. 审查与确认\n1. 登录 paperless-ngx Web 界面。\n2. 找到被标记的文档，你会看到 AI 生成的建议标题和标签。\n3. 点击文档进入详情页，检查 AI 提取的内容。\n4. 如果满意，点击保存\u002F接受；如果不满意，可手动修改后保存。\n\n### 3. 高级功能：自定义提示词\n你可以在 paperless-gpt 自带的 Web UI 中调整 AI 的行为：\n1. 访问 `http:\u002F\u002F\u003C你的服务器 IP>:8080` (默认端口，具体视容器映射而定，部分版本集成在 paperless-ngx 菜单中，请参考容器日志输出的实际地址)。\n2. 进入 **Settings** 菜单。\n3. 修改 **Prompts**（提示词），自定义标题生成规则、标签分类逻辑或对应方识别规则。\n\n### 4. 临时分析 (Ad-hoc Analysis)\n选中多个文档，通过工具提供的接口或界面功能，使用自定义 Prompt 进行批量摘要或信息提取，快速获取文档集的关键洞察。","某小型会计师事务所的助理每天需处理大量客户寄来的手写发票、模糊传真件及多语言合同，并将其录入 paperless-ngx 系统进行归档。\n\n### 没有 paperless-gpt 时\n- **OCR 识别率低**：传统 OCR 无法准确提取手写笔记或低质量扫描件中的文字，导致大量关键信息丢失或乱码。\n- **人工命名耗时**：助理必须逐个打开文档，阅读内容后手动重命名为\"2023 年 XX 公司服务费发票”等规范格式，效率极低。\n- **分类依赖经验**：标签（如“税务”、“合同”）和往来单位完全靠人工判断，新员工容易标错，导致后期检索困难。\n- **日期提取繁琐**：文档创建日期往往需要人工查看文件内容后手动修改，容易因疏忽导致时间线混乱。\n- **自定义字段空白**：发票号、金额等关键结构化数据无法自动提取，后续统计仍需二次人工录入。\n\n### 使用 paperless-gpt 后\n- **智能增强识别**：paperless-gpt 调用 LLM 视觉模型，即使面对潦草手写或模糊传真，也能结合上下文精准还原文字内容。\n- **自动生成标题**：系统自动分析文档语义，瞬间生成如\"2023 年 10 月 - 某某科技 - 咨询服务费发票”的清晰标题，无需人工干预。\n- **精准自动打标**：AI 自动识别文档类型并打上“增值税发票”、“租赁协议”等标签，同时准确提取往来单位名称，分类一致性大幅提升。\n- **智能提取日期**：自动从文档正文中识别签署日期或开票日期并更新元数据，确保档案时间轴准确无误。\n- **结构化数据填充**：配置后自动提取发票号码、税额等填入自定义字段，直接支持后续财务报表生成，彻底消除二次录入。\n\npaperless-gpt 通过将大语言模型的推理能力融入文档数字化流程，将原本数小时的人工整理工作压缩至分钟级，让非结构化文档真正变为可即时检索的智能资产。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ficereed_paperless-gpt_fb7a485f.png","icereed","Icereed","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Ficereed_3c750fa0.jpg","Building bubbletax.de and paperless-gpt.","@bubbletax ","Munich, Germany",null,"https:\u002F\u002Fgithub.com\u002Ficereed",[83,87,91,94,98,102,106,110],{"name":84,"color":85,"percentage":86},"Go","#00ADD8",70.8,{"name":88,"color":89,"percentage":90},"TypeScript","#3178c6",26.5,{"name":92,"color":85,"percentage":93},"Go Template",1.5,{"name":95,"color":96,"percentage":97},"Dockerfile","#384d54",0.5,{"name":99,"color":100,"percentage":101},"CSS","#663399",0.4,{"name":103,"color":104,"percentage":105},"JavaScript","#f1e05a",0.2,{"name":107,"color":108,"percentage":109},"HTML","#e34c26",0.1,{"name":111,"color":112,"percentage":109},"Shell","#89e051",2272,147,"2026-04-19T13:40:57","MIT","Linux, macOS, Windows","非必需。若使用本地大模型（Ollama），建议配备 NVIDIA GPU 或 NPU 以提升性能；具体型号和显存取决于所选模型（如 qwen3:8b），README 未指定具体 CUDA 版本。","未说明（取决于所选 LLM 模型大小，本地运行大模型通常建议 16GB+）",{"notes":121,"python":122,"dependencies":123},"该工具主要通过 Docker 部署，需配合正在运行的 paperless-ngx 实例。支持多种 LLM 提供商（OpenAI, Ollama, Mistral, Azure, Anthropic）。若选择本地部署 Ollama 进行 OCR 或推理，需自行安装并运行 Ollama 服务器，且硬件需求完全取决于所选用的具体模型（例如运行 8B 参数模型需要相应显存）。无需手动配置 Python 环境或安装特定 Python 库。","未说明（通过 Docker 部署，环境已封装）",[124,125],"Docker","paperless-ngx (外部依赖)",[13,15,35,14],[128,129,130,131,132,133,134,135],"ai","chatgpt","llm","ollama","paperless","paperless-ngx","mistral","ocr","2026-03-27T02:49:30.150509","2026-04-20T07:17:58.210895",[139,144,149,154,159,164],{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},43958,"如何为远程运行的 Ollama 配置 API 密钥认证？","可以通过环境变量以类似 OpenAI 密钥的方式指定 Ollama 的 API 密钥。在 .env 文件或 docker-compose 的环境变量中，使用 `Authorization: Bearer YOUR_KEY` 格式进行配置。用户反馈确认该方式有效，无需额外代码修改即可支持远程受保护的 Ollama 实例。","https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fissues\u002F3",{"id":145,"question_zh":146,"answer_zh":147,"source_url":148},43959,"加载文档时耗时过长且提示\"Failed to reload documents\"或\"i\u002Fo timeout\"错误，如何解决？","这通常是因为使用了旧版本的 paperless-gpt，其 API 查询参数格式已过时。解决方法是将 Docker 镜像版本固定为 `icereed\u002Fpaperless-gpt:v0.5.1` 或更高版本。新版将 API 查询从 `?query=tag:\u003Ctag>` 更改为 `?tags__name__iexact=\u003Ctag>`。操作步骤：\n1. 在 docker-compose.yml 中将 image 改为 `icereed\u002Fpaperless-gpt:v0.5.1`。\n2. 运行 `docker compose pull` 拉取最新镜像。\n3. 重启容器。\n若问题依旧，可添加 `LOG_LEVEL: 'debug'` 环境变量以获取更详细的连接诊断日志。","https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fissues\u002F43",{"id":150,"question_zh":151,"answer_zh":152,"source_url":153},43960,"GLM-OCR 模型输出异常（如重复字符、无法生成 Markdown 表格）怎么办？","GLM-OCR 在某些情况下会出现字符或整行重复循环直到达到 token 限制的问题，且对 Markdown 格式支持有限（通常只支持 HTML 格式的表格）。如果遇到此类问题，建议尝试切换到 Ollama 提供的其他视觉模型，或者调整提示词（prompt）。社区反馈表明 GLM 虽然速度快，但在格式化输出上不如其他模型稳定；若必须使用 GLM，需接受其仅输出 HTML 表格而非 Markdown 的现状。","https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fissues\u002F880",{"id":155,"question_zh":156,"answer_zh":157,"source_url":158},43961,"是否支持自动应用生成的标题和标签，而无需人工确认？","项目正在开发基于“工作流（workflows）”的概念来实现此功能。用户可以通过自定义手动和自动工作流，精确控制文档处理流程（包括自动应用标题和标签）。该功能灵感来源于 Paperless-ngx 的设计理念，旨在让用户根据偏好选择是否跳过人工检查步骤。目前相关前端代码已在 `feature\u002Fcustom-tags` 分支中完成，后端正在开发中，未来将通过设置选项开放给用户。","https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fissues\u002F19",{"id":160,"question_zh":161,"answer_zh":162,"source_url":163},43962,"如何使用视觉大模型（Vision LLM）改进或替代传统的 OCR 功能？","项目已引入自动 OCR 模式，支持使用视觉大模型（如通过 Ollama 运行的模型）来生成 OCR 内容。这使得系统不仅能处理标准打印文本，还能更好地识别手写内容、医疗报告或非标准文档。用户可以在配置中指定 `VISION_LLM_PROVIDER`（如 'ollama'）和 `VISION_LLM_MODEL`（如 'minicpm-v' 或 'llama3.2-vision'）来启用此功能。对于手写签名等特殊情况，可能需要调整提示词以强制模型进行转录。","https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fissues\u002F20",{"id":165,"question_zh":166,"answer_zh":167,"source_url":168},43963,"是否集成了 Google Document AI？如何处理包含手写字迹的复杂文档？","Google Document AI 的集成已被视为完成状态。该服务在处理手写字迹以及提取键值对（如表格记录）方面表现优异。集成后，系统能够从 Google Document AI 的输出中提取 hOCR 层并应用到 PDF 文件中。对于需要高精度识别手写体或复杂表单的用户，这是一个推荐的解决方案。","https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fissues\u002F169",[170,175,180,185,190,195,200,205,210,215,220,225,230,235,240,245,250,255,260,265],{"id":171,"version":172,"summary_zh":173,"released_at":174},351445,"v0.16.0","## 🌟 New Features\r\n\r\n### Enhanced PDF Processing (PR #353)\r\n- **Smart Text Layer Integration**\r\n - Creates searchable PDFs by embedding OCR text layers\r\n - Maintains original document appearance while adding invisible text layer\r\n - Preserves accurate text positioning using hOCR data\r\n - Works with Google Document AI's hOCR output\r\n\r\n- **Paperless-ngx Integration**\r\n - Automatic metadata preservation (tags, correspondent, created date)\r\n - Smart document replacement workflow\r\n - Processing status tracking via document tagging\r\n - Skip mechanism for already processed documents\r\n\r\n- **Safety Features**\r\n - Page count validation to prevent incomplete processing\r\n - Optional local file backup for verification\r\n - Configurable document replacement\r\n - Comprehensive error handling and logging\r\n\r\n### Cloud Provider Integrations\r\n\r\n#### Azure OpenAI Support\r\n- Added native support for Azure OpenAI Service\r\n- New configuration options: `OPENAI_API_TYPE` and `OPENAI_BASE_URL` \r\n- Improved validation for Azure-specific environment variables\r\n\r\n#### Docling Server Integration\r\n- Added Docling Server as a new OCR provider\r\n- Self-hosted OCR capabilities for enhanced privacy\r\n- Support for multiple OCR engines\r\n\r\n### Container Registry Support\r\n- Added GitHub Container Registry (GHCR) as an alternative image source\r\n- Multi-architecture support for both Docker Hub and GHCR\r\n\r\n## 🔧 Configuration\r\n\r\nNew PDF Processing Variables:\r\n```\r\nCREATE_LOCAL_HOCR: Save hOCR files locally\r\nLOCAL_HOCR_PATH: Directory for hOCR files\r\nCREATE_LOCAL_PDF: Save PDFs locally\r\nLOCAL_PDF_PATH: Directory for PDFs\r\nPDF_UPLOAD: Enable paperless-ngx uploads\r\nPDF_REPLACE: Control document replacement\r\nPDF_COPY_METADATA: Enable metadata copying\r\nPDF_OCR_TAGGING: Enable process tracking\r\nPDF_OCR_COMPLETE_TAG: Tag for processed documents\r\n```\r\n\r\nAzure OpenAI Variables:\r\n```\r\nOPENAI_API_TYPE=azure\r\nOPENAI_BASE_URL=https:\u002F\u002F\u003Cyour-azure-openai-endpoint>.openai.azure.com\u002F\r\n```\r\n\r\nFor detailed setup instructions, please refer to the updated documentation.\r\n\r\n# Contributors\r\n\r\nA big shoutout to @signorecello for the docling integration and @gardar for the advanced hOCR support.","2025-04-25T12:44:34",{"id":176,"version":177,"summary_zh":178,"released_at":179},351446,"v0.15.0","## Azure DocAI Markdown Output\r\n\r\nThis adds a new environment variable for the Azure DocAI provider that adds the markdown output format query parameter to the processing request. It has no effect unless the new variable is added to the .env config and the model ID is also changed to prebuilt-layout, as described in the updated readme. Having the content in markdown adds additional context for the original document, which is useful when LLM tools are reading the content.\r\n\r\n## What else Changed\r\n* chore(deps): update dependency typescript to v5.8.3 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F335\r\n* fix(deps): update dependency @headlessui\u002Freact to v2.2.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F331\r\n* chore(deps): update dependency vite to v6.2.6 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F341\r\n* chore(deps): update react monorepo to v19.1.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F339\r\n* Feature\u002FAzure DocAI markdown output option by @cbrown350 in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F346\r\n\r\n## New Contributors\r\n* @cbrown350 made their first contribution in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F346\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.14.4...v0.15.0","2025-04-16T03:58:02",{"id":181,"version":182,"summary_zh":183,"released_at":184},351447,"v0.14.4","## What's Changed\r\n* chore(deps): update golang docker tag to v1.24.2 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F325\r\n* chore(deps): update dependency testcontainers to v10.23.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F316\r\n* chore(deps): update dependency go to v1.24.2 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F324\r\n* fix(deps): update react monorepo to v19.1.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F318\r\n* chore(deps): update dependency vite to v6.2.5 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F326\r\n* fix(deps): update dependency react-router-dom to v7.4.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F315\r\n* chore(deps): update dependency testcontainers to v10.24.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F328\r\n* fix(deps): update module google.golang.org\u002Fapi to v0.228.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F317\r\n* chore(deps): update dependency typescript-eslint to v8.29.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F262\r\n* chore(deps): update dependency @types\u002Fnode to v22.14.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F258\r\n* chore(deps): update dependency typescript to v5.8.2 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F329\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.14.3...v0.14.4","2025-04-04T14:18:53",{"id":186,"version":187,"summary_zh":188,"released_at":189},351448,"v0.14.3","## What's Changed\r\n* chore(deps): update dependency vite to v6.2.4 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F320\r\n* Refactor - Move background logic to background.go (and background_test.go) by @thiscantbeserious in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F321\r\n* fix(ocr): Fix custom OCR prompt by @icereed in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F323\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.14.2...v0.14.3","2025-04-01T19:53:18",{"id":191,"version":192,"summary_zh":193,"released_at":194},351449,"v0.14.2","## What's Changed\r\n* HOTFIX - make auto-process not silently fail on document update failure (=endless loop) by @thiscantbeserious in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F319\r\n\r\n## New Contributors\r\n* @thiscantbeserious made their first contribution in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F319\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.14.1...v0.14.2","2025-03-30T19:50:38",{"id":196,"version":197,"summary_zh":198,"released_at":199},351450,"v0.14.1","## What's Changed\r\n* fix(deps): update dependency axios to v1.8.4 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F300\r\n* chore(deps): update dependency @vitejs\u002Fplugin-react-swc to v3.8.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F299\r\n* chore(deps): update dependency @types\u002Freact to v19.0.12 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F298\r\n* chore(deps): update dependency @playwright\u002Ftest to v1.51.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F296\r\n* fix(deps): update dependency react-router-dom to v7.4.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F307\r\n* chore(deps): update eslint monorepo to v9.23.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F306\r\n* chore(deps): update dependency testcontainers to v10.21.0 - autoclosed by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F292\r\n* chore(deps): update dependency vite to v6.2.2 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F289\r\n* fix(deps): update module google.golang.org\u002Fapi to v0.227.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F286\r\n* chore(deps): update dependency vite to v6.2.3 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F308\r\n* fix(deps): update module cloud.google.com\u002Fgo\u002Fdocumentai to v1.36.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F309\r\n* chore(deps): update dependency testcontainers to v10.22.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F310\r\n* [fix for #311] CreatedDatePrompt to derive date when no day or month were p… by @hensing in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F312\r\n\r\n## New Contributors\r\n* @hensing made their first contribution in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F312\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.14.0...v0.14.1","2025-03-25T10:09:14",{"id":201,"version":202,"summary_zh":203,"released_at":204},351451,"v0.14.0","# New Feature: Automatic creation date generation\r\n\r\nWeird creation dates in paperless-ngx? Have no fear, the LLM comes to rescue 💯 🚀 \r\nIntroduced automatic creation date generation for documents with new UI controls and suggestion handling. (by @AxcellF in #303)\r\n\r\n## What's Changed\r\n* chore(deps): update dependency autoprefixer to v10.4.21 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F278\r\n* fix(deps): update module google.golang.org\u002Fapi to v0.224.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F276\r\n* fix(deps): update dependency axios to v1.8.2 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F275\r\n* chore(deps): update eslint monorepo to v9.22.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F277\r\n* fix(deps): update dependency react-router-dom to v7.3.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F273\r\n* fix(deps): update dependency axios to v1.8.3 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F285\r\n* fix(deps): update module google.golang.org\u002Fapi to v0.225.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F284\r\n* chore(deps): update dependency testcontainers to v10.19.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F283\r\n* chore(deps): update dependency node to v22 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F282\r\n* fix(deps): update module cloud.google.com\u002Fgo\u002Fdocumentai to v1.35.3 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F288\r\n* chore(deps): update react monorepo by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F266\r\n* Generate created date (#303) by @icereed in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F304\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.13.0...v0.14.0","2025-03-24T07:03:24",{"id":206,"version":207,"summary_zh":208,"released_at":209},351452,"v0.13.0","## New Features\r\n\r\n* Introduced Azure Document Intelligence as a new OCR provider, enhancing document processing capabilities.\r\n* Improved configuration with dedicated environment variables for Azure integration and robust error handling.\r\n\r\n## What's Changed\r\n* fix(deps): update module github.com\u002Ftmc\u002Flangchaingo to v0.1.13 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F243\r\n* chore(deps): update react monorepo to v19.0.10 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F242\r\n* chore(deps): update alpine docker tag to v3.21.3 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F240\r\n* chore(deps): update dependency go to v1.24.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F225\r\n* chore(deps): update dependency @types\u002Fnode to v22.13.4 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F238\r\n* chore(deps): update dependency postcss to v8.5.2 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F220\r\n* Potential fix for code scanning alert no. 3: Clear-text logging of sensitive information by @icereed in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F247\r\n* chore(deps): update dependency typescript-eslint to v8.24.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F249\r\n* fix(deps): update dependency react-router-dom to v7.2.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F250\r\n* chore(deps): update dependency vite to v6.1.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F253\r\n* fix(deps): update dependency react-icons to v5.5.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F251\r\n* chore(deps): update dependency globals to v16 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F257\r\n* fix(deps): update module google.golang.org\u002Fapi to v0.222.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F256\r\n* chore(deps): update dependency postcss to v8.5.3 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F255\r\n* chore(deps): update dependency vite to v6.2.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F263\r\n* chore(deps): update eslint monorepo to v9.21.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F259\r\n* fix(deps): update dependency axios to v1.8.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F265\r\n* fix(deps): update module google.golang.org\u002Fapi to v0.223.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F264\r\n* chore(deps): update dependency @playwright\u002Ftest to v1.51.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F272\r\n* chore(deps): update dependency vite to v6.2.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F271\r\n* fix(deps): update module golang.org\u002Fx\u002Fsync to v0.12.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F274\r\n* chore(deps): update golang docker tag to v1.24.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F270\r\n* chore(deps): update dependency go to v1.24.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F269\r\n* feat(ocr): enhance OCR processing with structured results and hOCR su… by @icereed in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F212\r\n* feat(ocr): add support for Azure Document Intelligence provider by @icereed in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F279\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.12.2...v0.13.0","2025-03-10T10:03:12",{"id":211,"version":212,"summary_zh":213,"released_at":214},351453,"v0.12.2","## What's Changed\r\n* chore(deps): update dependency typescript-eslint to v8.24.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F215\r\n* Set Fixed Alpine Version by @kaindlnetwork in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F217\r\n* Enhance Readme Variables Table by @kaindlnetwork in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F221\r\n* refactor: Improve auto-tagging process to skip OCR-tagged documents by @mkrinke in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F227\r\n* chore(deps): update dependency eslint to v9.20.1 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F228\r\n* feat: Add TLS configuration support for HTTPS connections in Paperless client by @mkrinke in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F230\r\n* chore(deps): update dependency globals to v15.15.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F232\r\n* fix(deps): update module cloud.google.com\u002Fgo\u002Fdocumentai to v1.35.2 - autoclosed by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F233\r\n* chore(deps): update golang docker tag to v1.24.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F234\r\n* chore(deps): update dependency @types\u002Fnode to v22.13.2 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F236\r\n* fix(deps): update module google.golang.org\u002Fapi to v0.221.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F235\r\n* chore(deps): update dependency alpine_3_21\u002Fmusl-dev to v1.2.5-r9 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F246\r\n* feat: add custom HTTP transport with headers for OpenAI client by @icereed in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F245\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.12.1...v0.12.2","2025-02-17T10:40:24",{"id":216,"version":217,"summary_zh":218,"released_at":219},351454,"v0.12.1","## What's Changed\r\n* fix(deps): update module github.com\u002Fgabriel-vasile\u002Fmimetype to v1.4.8 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F209\r\n* fix(deps): update module google.golang.org\u002Fapi to v0.220.0 by @renovate in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F210\r\n* fix(ocr): fix the auto-tag trigger for OCR by @icereed in https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F216\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.12.0...v0.12.1","2025-02-10T20:27:11",{"id":221,"version":222,"summary_zh":223,"released_at":224},351435,"v0.25.1","# 🛠️ v0.25.1 – 补丁版本\n\n### 概述\n\n此补丁版本修复了 v0.25.0 中引入的一个回归问题，该问题会导致用户界面陷入重新加载循环，并且在使用手动队列标签（例如包含表情符号或空格的标签，如 `🤖 AI-Queue`）时无法从 Paperless 获取文档。\n\n### 修复内容\n\n- 🟢 **Unicode\u002F表情符号标签过滤现已正常工作：** 修复了 `tags__name__iexact` 中非 ASCII 字符或空格标签的查询编码问题。现在，使用表情符号或带空格的标签进行查询可以按预期工作。\n- 当类似 `🤖 AI-Queue` 的标签被用作 `MANUAL_TAG` 时，用户界面不再进入重新加载循环。\n- 其他功能和设置无需任何更改。\n\n### 升级方法\n\n1. 将您的 paperless-gpt Docker 镜像\u002F标签更新至 `v0.25.1`。\n2. 无需执行迁移步骤或修改配置。\n\n### 感谢\n\n感谢所有报告并协助调试此回归问题的用户！\n- [#898](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fissues\u002F898)：“通过 `tags__name__iexact` 使用表情符号标签查询文档时，paperless-gpt 返回 400 错误” – @icereed\n\n### 变更内容\n* 更新 README.md，由 @nettnikl 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F895 中完成\n* 修复包含特殊字符的标签查询的 URL 编码问题，由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F901 中完成\n\n### 新贡献者\n* @nettnikl 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F895 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.25.0...v0.25.1","2026-02-26T14:50:11",{"id":226,"version":227,"summary_zh":228,"released_at":229},351436,"v0.25.0","# 🚀 paperless-gpt v0.25.0 - “视觉扩展”\n\n*Gemini 加入视觉 OCR 阵营，轮询机制更智能，图像处理也全面可调！*\n\n## 🌟 重大新特性\n\n### 👁️ **Google Gemini 作为视觉（OCR）提供商**\n现在可以直接将 Google Gemini 用作 OCR 的视觉 LLM 提供者！凭借原生的 PDF 处理能力，Gemini 开箱即用地支持 `image`、`pdf` 和 `whole_pdf` 三种处理模式，为文档处理提供更多灵活性。\n- 设置 `VISION_LLM_PROVIDER: \"googleai\"` 和 `VISION_LLM_MODEL: \"gemini-2.5-flash\"` 即可开始使用\n- 可通过 `GOOGLEAI_THINKING_BUDGET` 为推理模型提供可选的思考预算支持\n*感谢 @its-a-unixsystem 的精彩贡献！*\n\n### 🎛️ **可配置的图像处理限制**\n图像处理的限制不再硬编码！现在可以通过环境变量微调最大像素尺寸、总像素数、渲染 DPI 和最大文件大小。这对于像 `minicpm-v` 这样的小型视觉模型尤其有用，因为它们在适当大小的图像上表现更好。\n- `IMAGE_MAX_PIXEL_DIMENSION`、`IMAGE_MAX_TOTAL_PIXELS`、`IMAGE_MAX_RENDER_DPI`、`IMAGE_MAX_FILE_BYTES`\n- 保留合理的默认值以确保向后兼容\n*非常棒的补充，来自 @cfilipov！*\n\n## ⚡ 性能提升\n\n### 🔄 **更智能的 Paperless 轮询**\n现在轮询新文档的速度显著加快，资源占用也更低。paperless-gpt 不再查询完整的文档 API，而是使用基于标签的文档计数来快速判断是否有待处理的文档——从而将响应时间从大型实例上的 500–1000 毫秒缩短到 10–50 毫秒。\n- 修复了由于激进轮询导致 paperless-ngx CPU 使用率过高的问题\n- 用单标签检索替代多标签查询\n- 当没有待处理的文档时，API 调用会提前中止\n*感谢 @apoapoapo 在性能优化方面的贡献！*\n\n## 🔧 CI\u002FCD 改进\n\n### 🛡️ **安全的 Fork PR 端到端测试**\n现在可以通过基于标签的审批流程，安全地运行 Fork 拉取请求的端到端测试。维护者在代码审查后添加 `safe-to-test` 标签，即可触发带有密钥访问的本地 Docker 构建端到端测试——无需注册表凭据。\n*由 @Copilot 贡献！*\n\n---\n\n## ⚙️ 配置亮点\n\n### 新增环境变量\n\n```yaml\n# Gemini 视觉 OCR\nVISION_LLM_PROVIDER: \"googleai\"\nVISION_LLM_MODEL: \"gemini-2.5-flash\"\nGOOGLEAI_API_KEY: \"your-api-key\"\nGOOGLEAI_THINKING_BUDGET: \"16384\" # 可选\nOCR_PROCESS_MODE: \"whole_pdf\" # image、pdf 或 whole_pdf\n\n# 图像处理限制\nIMAGE_MAX_PIXEL_DIMENSION: \"10000\"\nIMAGE_MAX_TOTAL_PIXELS: \"40000000\"\nIMAGE_MAX_RENDER_DPI: \"300\"\nIMAGE_MAX_FILE_BYTES: \"10485760\"\n```\n\n### 无破坏性变更\n现有配置仍可正常工作。所有新功能均为可选！\n\n---\n\n## 📋 变更内容\n* 添加了基于标签审批的安全 Fork PR 端到端测试，由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F857 中实现\n* 改进了 Paperless 轮询","2026-02-16T08:31:48",{"id":231,"version":232,"summary_zh":233,"released_at":234},351437,"v0.24.0","# 🚀 paperless-gpt v0.24.0 - “智能扩展”\n\n*您的 AI 驱动文档处理功能现已更智能，新增 Claude 支持、自动文档类型识别等功能！*\n\n## 🌟 重大新特性\n\n### 🧠 **Anthropic Claude API 支持**\nClaude 加入啦！现在您可以将 Anthropic 强大的 Claude 模型用作 LLM 提供商。非常适合偏好 Claude 理性推理能力的用户，或希望尝试 OpenAI\u002FOllama 之外选项的用户。\n- 设置 `LLM_PROVIDER: \"anthropic\"` 并配置您的 `ANTHROPIC_API_KEY` 即可开始使用。\n*感谢 @kamcnally 的精彩贡献！*\n\n### 📁 **自动文档类型分配**\npaperless-gpt 现在能够智能地为您的文档建议并分配类型！让 AI 自动分类发票、合同、收据等各类文档，无需您动手。\n- **UI 切换开关**用于启用或禁用文档类型生成\n- **查看和编辑**每份文档的建议文档类型\n- 设置 `AUTO_GENERATE_DOCUMENT_TYPE: \"true\"` 即可开始使用。\n*来自 @niklasfink 的出色贡献！*\n\n### 🎨 **OCR 界面与 LLM 选项增强**\nOCR 界面进行了重大升级，提供了更多微调 LLM 交互的选项，让您对文档处理方式拥有更强的控制力。\n*由 @dawidkulpa 改进！*\n\n## 🔧 改进与修复\n\n### 🔗 **子路径托管支持**\n现在可以在反向代理的子路径下（例如 `\u002Fai\u002F`）托管 paperless-gpt，一切运行顺畅！所有前端 API 调用都已适配子路径，确保设置菜单及其他 UI 功能正常加载。\n*感谢 @tldev-de！*\n\n### 🐛 **OCR 标签循环修复**\n修复了一个关键 bug：当 OCR 自动标签是最后一个剩余标签时，它永远不会被清除，从而导致无限循环处理。\n*由 @haigcd 修复 — 关闭了 #817！*\n\n### 🏷️ **标签移除修复**\n修复了自动\u002F手动标签移除的处理逻辑，避免发送空数组，从而防止与 paperless-ngx 产生问题。\n*由 @itkevin 修复 — 关闭了 #659！*\n\n### 🤖 **推理模型清理**\nOCR 输出现在会自动从 DeepSeek-R1 等模型中剥离 `\u003Cthink>` 推理标签，为您提供更干净的提取文本。\n*由 @Copilot 贡献！*\n\n### 📄 **Docling 提供商增强**\n- Docling 服务器 API 更新至 v1\n- 新增 PDF 处理模式支持（`pdf` 和 `whole_pdf`）\n- 添加了用于额外配置的新环境变量\n*感谢 @T-Eberle 和 @Schweinhitti！*\n\n## 📦 内部更新\n\n本次发布包含 Go 后端和 TypeScript 前端的 **100 多项依赖更新**，确保系统安全且保持最新状态：\n\n| 组件 | 版本 |\n|--------------|------------|\n| React | 19.2.3 |\n| Go | 1.25.5 |\n| Vite | 7.3.0 |\n| Node.js | 24 |\n| PostgreSQL | 18 |\n| Alpine | 3.23.0 |\n| Gin | 1.11.0 |\n| GORM | 1.31.1 |\n| LangChainGo | 0.1.14 |\n| Google GenAI | 1.39.0 |\n\n### CI\u002FCD 改进\n- 更新至 actions\u002Fcheckout v6、actions\u002Fsetup-node v6、actions\u002Fsetup-go v6\n- GitHub 工件操作已更新至最新版本。","2026-01-14T21:28:09",{"id":236,"version":237,"summary_zh":238,"released_at":239},351438,"v0.23.0","# 🚀 paperless-gpt v0.23.0 - “高级用户版”\n\n*借助自定义字段、外部提示以及更强大的开发者体验，将 AI 驱动的文档处理提升至全新高度！*\n\n## 🌟 重大新特性\n\n### 📝 **外部提示与 UI 编辑器** \n彻底革新您自定义 AI 行为的方式！现在您可以将提示语管理在外部，并通过精美的网页界面进行编辑。无需再深入配置文件——轻松打造完美的文档处理提示，得心应手！\n\n*感谢 @hensing 带来的这一颠覆性功能！*\n\n### 🎯 **自动检测自定义字段** \npaperless-gpt 现在能够智能地从您的文档中自动检测并提取自定义字段。让 AI 发现纸质文档中的数据模式，并为您推荐那些您甚至未曾想到过的自定义字段。\n\n*再次感谢 @hensing 的精彩贡献！*\n\n### ⏱️ **文档处理运行时日志记录** \n是否曾好奇每份文档需要多长时间才能完成处理？现在您将一目了然！所有文档处理操作都会被计时并记录下来，为您提供性能洞察，帮助您优化 AI 工作流。\n\n*衷心感谢 @matgoebl 的这一实用新增功能！*\n\n### 🛠️ **开发者体验增强** \n我们新增了详尽的 GitHub Copilot 指南，让参与 paperless-gpt 的贡献变得轻而易举。无论是修复 bug 还是添加新功能，开发流程如今都比以往更加顺畅。\n\n*由 @Copilot 对该项目的首次贡献所驱动！*\n\n## 🔧 基础设施改进\n\n- **可选 Docker Hub 推送**：更灵活的 CI\u002FCD 流水线管理\n- **日期验证**：更好地处理无效的文档日期\n- **依赖堡垒**：大规模更新依赖包，确保一切安全且最新\n\n## 📦 内部揭秘\n\n本次发布包含了 Go 后端和 TypeScript 前端共计 **50 多项依赖更新**，确保您始终使用最新、最优秀的软件包。从 React 19.1.1 到 Go 1.25.0，我们为您全面保驾护航。\n\n## 🎉 欢迎新贡献者！\n\n特别鸣谢 @Copilot 加入我们的贡献者大家庭！🤖\n\n---\n\n**准备好为您的文档处理赋能了吗？**\n\n📥 **下载**：[v0.23.0 版本](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Freleases\u002Ftag\u002Fv0.23.0) \n📚 **文档**：查看更新后的文档，了解新特性 \n🐛 **问题反馈**：发现任何问题？我们非常欢迎您的反馈！\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.22.0...v0.23.0","2025-09-17T10:15:51",{"id":241,"version":242,"summary_zh":243,"released_at":244},351439,"v0.22.0","# 支持反向代理的相对 URL\n\n使用相对 URL，以便从反向代理转发子路径时能够正常工作。感谢 @matgoebl。\n\n## 变更内容\n* doc：由 @thiswillbeyourgithub 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F472 中澄清 LLM_LANGUAGE\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F465 中更新依赖 go 到 v1.24.4\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F462 中更新依赖 @types\u002Freact 到 v19.1.8\n* fix(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F444 中更新模块 google.golang.org\u002Fapi 到 v0.239.0\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F443 中更新依赖 postcss 到 v8.5.6\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F481 中更新 docker.io\u002Fgolang 的镜像标签到 v1.24.4\n* fix(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F482 中更新依赖 react-router-dom 到 v7.6.3\n* fix(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F483 中更新模块 github.com\u002Fgen2brain\u002Fgo-fitz 到 v1.24.15\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F430 中更新依赖 @types\u002Fnode 到 v22.15.34\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F431 中更新依赖 typescript-eslint 到 v8.35.0\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F447 中更新 docker.io\u002Falpine 的镜像标签到 v3.22.0\n* fix(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F484 中更新模块 github.com\u002Fhashicorp\u002Fgo-retryablehttp 到 v0.7.8\n* fix(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F426 中更新模块 gorm.io\u002Fgorm 到 v1.30.0\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F485 中更新依赖 @playwright\u002Ftest 到 v1.53.1\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F486 中更新依赖 dotenv 到 v16.6.1\n* chore(config)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F487 中迁移 renovate 配置\n* fix(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F489 中更新依赖 axios 到 v1.10.0\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F488 中更新 eslint 单体仓库到 v9.30.0\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F494 中更新依赖 dotenv 到 v17\n* fix(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F492 中更新模块 google.golang.org\u002Fgenai 到 v1.13.0\n* fix(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F490 中更新依赖 react-tooltip 到 v5.29.1\n* chore(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F495 中更新依赖 vite 到 v7\n* fix(deps)：由 @renovate[bot] 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F495 中更新模块 gorm.io\u002Fdriver\u002Fsqlite to","2025-07-17T06:35:43",{"id":246,"version":247,"summary_zh":248,"released_at":249},351440,"v0.21.0","## 发布亮点 🚀\n\n### 新功能\n\n#### 🔮 Mistral OCR 与高级 PDF 处理集成\n- **扩展的 PDF 处理支持** - Mistral OCR 现在与 Google Document AI 一起支持所有处理模式：`image`、`pdf` 和 `whole_pdf`\n- **经济高效的 OCR** - 专为文档处理打造的 OCR 端点，定价具有竞争力\n- **Markdown 格式输出** - 返回结构良好的 Markdown 文本，保留文档格式和布局\n- **大文件支持** - 能够高效处理大小达 50MB、最多 1,000 页的文件\n- 设置 `OCR_PROVIDER: \"mistral_ocr\"` 并配置您的 Mistral API 密钥即可开始使用\n\n#### 🏷️ 增强的上下文标题生成\n- **原始标题上下文** - 标题生成现在会将现有文档标题作为上下文信息纳入考虑\n- **提升相关性** - 语言模型可以利用原始标题生成更准确、更符合上下文的建议\n- **更好的连续性** - 在提升标题质量的同时，保持文档命名的一致性\n- **智能回退机制** - 能够妥善处理原始标题缺失或不完整的情况\n\n### 改进与优化\n\n#### 🛡️ 配置验证\n- **OCR 提供商兼容性检查** - 防止 OCR 提供商与处理模式之间的无效组合\n- **清晰的错误信息** - 当检测到不支持的模式组合时，提供详细的反馈\n- **启动时验证** - 在处理开始前尽早发现配置问题\n- **提供商特定指导** - 友好的错误信息会说明每个提供商支持哪些模式\n\n#### 📄 优化的 PDF 处理架构\n- **混合文件命名** - 改进了 PDF 分割功能，采用标准化命名规范，同时保持向后兼容性\n- **更多提供商选择** - 用户现在可以在 Google Document AI 和 Mistral OCR 之间选择适合的方案进行高级 PDF 处理\n- **一致的行为** - 两种高级提供商均支持 `pdf` 和 `whole_pdf` 模式，且性能表现相似\n\n#### 🧪 全面的端到端测试\n- **Mistral OCR 测试套件** - 对 Mistral OCR 与真实 PDF 文档的集成进行全面的端到端测试\n- **处理模式验证** - 测试验证了 `whole_pdf` 模式在多页文档上的正确性\n- **性能指标** - 测试输出包括原始与增强 OCR 内容的详细对比\n- **跨提供商兼容性** - 测试确保不同 OCR 提供商之间行为的一致性\n\n### 文档更新\n\n#### 📚 OCR 提供商对比\n- **更新的提供商文档** - 清晰说明哪些提供商支持哪些处理模式\n- **模式兼容性矩阵** - 方便用户参考，选择合适的提供商和模式组合\n- **Mistral 特定指南** - 提供 Mistral OCR 的详细设置说明和最佳实践\n- **配置示例** - 包含所有支持配置的完整 docker-compose 示例\n\n## 技术详情","2025-06-19T11:54:59",{"id":251,"version":252,"summary_zh":253,"released_at":254},351441,"v0.20.0","## 发布亮点 🚀\n\n### 新功能\n\n#### 🧠 Google Gemini AI 集成\n- **新增 Google Gemini AI 支持** - Paperless-GPT 现在支持 Google 的 Gemini AI 模型，作为新的 LLM 提供商选项\n- **思考预算支持** - 利用 Gemini 的新思考能力，提升文档处理效果\n- **增强的错误处理** - 改进了对 Google AI 服务的 API 响应验证和错误管理\n- 设置 `LLM_PROVIDER: \"googleai\"` 并配置您的 Google AI API 凭证即可开始使用\n\n### 改进与优化\n\n#### 🔧 LLM 提示优化\n- **增强提示结构** - 在 LLM 提示中添加了类似 XML 的分隔符，以提高解析的准确性和一致性\n- **更好的数据组织** - 输入数据现在被封装在结构化标签中，使 LLM 更清晰地理解\n- **可靠性提升** - 不同文档类型和 LLM 提供商之间的结果更加一致\n\n#### 📄 PDF 处理修复\n- **修复了拆分 PDF 的逻辑** - 更新了文件命名模式，使其与 `pdfcpu` 的输出格式一致（移除了零填充）\n- **统一命名** - 拆分后的文件现在采用简化命名：`original_1.pdf`、`original_2.pdf` 等\n- **更好的工作流集成** - 提高了与现有 PDF 处理流程的兼容性\n\n### 文档更新\n\n#### 📚 模型推荐\n- **更新模型建议** - 文档现在推荐 Ollama 用户使用 `qwen3:8b` 而不是 `deepseek-r1:8b`\n- **性能更优** - `qwen3:8b` 具有更最新、更强大的推理能力\n- **示例改进** - 整个文档中的配置示例均已更新\n\n### 依赖项与维护\n\n#### 🔄 依赖项更新\n- **testcontainers** 更新至 v10.28.0 - 最新的测试框架改进\n- **globals** 更新至 v16.2.0 - 增强了 JavaScript 全局变量的定义\n- **自动化维护** - Renovate 机器人确保依赖项保持最新且安全\n\n## 技术细节\n\n### 变更内容\n* **新增对带有思考预算的 Gemini 模型的支持** [#441](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F441)\n* **重构：在 LLM 提示中添加类似 XML 的分隔符，以改善解析** [#442](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F442)\n* **修复：使拆分 PDF 的逻辑与 pdfcpu 的输出保持一致** [#435](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F435)\n* **文档：将推荐模型从 deepseek-r1:8b 更改为 qwen3:8b** [#439](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F439)\n* **杂项（依赖）：将 testcontainers 依赖更新至 v10.28.0** [#425](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F425)\n* **杂项（依赖）：将 globals 依赖更新至 v16.2.0** [#428](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F428)\n\n### 贡献者\n特别感谢 @thiswillbeyourgithub、@dawidkulpa 和 @moarsmokes 对本次发布的贡献！\n\n### 配置说明\n- 对于 Google Gemini AI：请设置 `GOOGLE_AI_API_KEY` 环境变量，并配置 `LLM_PROVIDER: \"","2025-05-30T14:39:51",{"id":256,"version":257,"summary_zh":258,"released_at":259},351442,"v0.19.0","## 发布亮点 – v0.19.0\n\n### 新增：灵活的 OCR 处理模式\n\n`paperless-gpt` 现在提供三种不同的 OCR 处理模式，使您能够根据所使用的 OCR 服务提供商及性能需求来优化文档处理流程：\n\n- **图像模式** *(默认)* \n 在进行 OCR 之前，先将每一页 PDF 转换为图像。 \n *适用场景*：与所有 OCR 服务提供商具有最高的兼容性。 \n *配置方式*：`OCR_PROCESS_MODE: \"image\"`\n\n- **PDF 模式** \n 直接处理单个 PDF 页面，无需转换为图像。 \n *适用场景*：保留 PDF 的原始结构，并在使用原生支持 PDF 的 OCR 服务时提升速度或准确性。 \n *配置方式*：`OCR_PROCESS_MODE: \"pdf\"`\n\n- **整页 PDF 模式** \n 将整个 PDF 作为单个文档发送至 OCR 引擎进行处理。 \n *适用场景*：适用于针对多页文档优化、且能减少 API 调用次数的 OCR 服务提供商。 \n *配置方式*：`OCR_PROCESS_MODE: \"whole_pdf\"` \n *注意*：对于大型 PDF 文件，可能会超出您的 OCR 服务提供商的 API 限制——如遇问题，请切换至 `pdf` 模式。\n\n### 功能增强与问题修复\n\n- **新特性**：原生支持 PDF 格式的 OCR 处理 [#406](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F406) \n- **修复**：Azure OpenAI LLM 集成 [#398](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F398) \n- **依赖项更新**： \n - 核心库：React、TypeScript、Node.js 类型定义、ESLint \n - 后端：Gin、GORM、Google API 相关模块、`ocrchestra` 摘要更新 \n - 构建与测试工具：Go 1.24.3、Docker 镜像、Testcontainers\n\n**完整变更日志**：[v0.18.0...v0.19.0](https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.18.0...v0.19.0)","2025-05-21T03:46:14",{"id":261,"version":262,"summary_zh":263,"released_at":264},351443,"v0.18.0","## “工作流卓越”——自动化文档处理流水线 🔄\n\n### 新功能 🚀\n1. OCR 完成标签\n - 使用 `PDF_OCR_COMPLETE_TAG` 在 OCR 处理完成后自动为文档打上标签\n - 可基于 OCR 完成状态启用工作流自动化\n - 与所有 OCR 提供商无缝兼容\n\n### 快速设置指南 🛠️\n```yaml\nenvironment:\n # 用于自动 OCR 处理\n AUTO_OCR_TAG: \"paperless-gpt-ocr-auto\" # 标记文档以触发自动 OCR\n\n # 启用 OCR 完成标签功能\n PDF_OCR_TAGGING: \"true\"\n PDF_OCR_COMPLETE_TAG: \"paperless-gpt-ocr-complete\" # OCR 完成后添加的标签\n```\n\n### 工作原理 📋\n1. 使用 `paperless-gpt-ocr-auto` 标签将文档加入 OCR 处理队列\n2. 文档将使用您配置的 OCR 提供商进行处理\n3. 处理完成后，文档会自动被标记为 `paperless-gpt-ocr-complete`\n4. 您可以利用这些标签来触发进一步的自动化或工作流\n\n### 技术改进 ⚙️\n- 增强了 OCR 工作流自动化的测试覆盖率\n- 改进了文档处理器架构\n- 通过并行工作进程优化了测试执行\n\n## 变更内容\n* 修复 OCR 完成标签，并由 @icereed 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F379 中添加了 OCR 文档处理端到端测试\n* fix(deps): 将模块 gorm.io\u002Fgorm 更新至 v1.26.0，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F377 中完成\n* chore(deps): 将依赖 vite 更新至 v6.3.5，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F381 中完成\n* chore(deps): 将依赖 @types\u002Freact-dom 更新至 v19.1.3，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F365 中完成\n* chore(deps): 将依赖 typescript-eslint 更新至 v8.31.1，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F337 中完成\n* fix(deps): 将模块 cloud.google.com\u002Fgo\u002Fdocumentai 更新至 v1.37.0，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F373 中完成\n* chore(deps): 将 eslint 单仓库更新至 v9.26.0，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F332 中完成\n* chore(deps): 将依赖 eslint-plugin-react-refresh 更新至 v0.4.20，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F349 中完成\n* fix(deps): 将 github.com\u002Fgardar\u002Focrchestra 的摘要更新至 5fe7a0d，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F376 中完成\n* fix(deps): 将模块 golang.org\u002Fx\u002Fsync 更新至 v0.14.0，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F382 中完成\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fcompare\u002Fv0.17.0...v0.17.1","2025-05-05T15:34:40",{"id":266,"version":267,"summary_zh":268,"released_at":269},351444,"v0.17.0","## 主要特性\n\n### 🤖 Mistral AI 集成\n- 新增 Mistral AI 作为 OCR 和 LLM 能力的新提供商\n- 集成了视觉模型，用于灵活的文档处理\n- 新增专门针对文档处理优化的 OCR 服务\n- 提供了 OCR 方法的配置选项\n- 增强了速率限制，并引入重试机制，以确保 API 交互的稳定性\n\n### 📄 PDF 处理改进\n- 实现了智能 PDF 页面提取，并优化了文件大小\n- 添加了智能尺寸限制（每边最大 10K 像素，总像素不超过 4000 万）\n- 引入了自适应 JPEG 质量调整（范围为 85-60）\n- 根据目标文件大小添加了智能缩放功能\n- 修复了 PDF 页面提取过大的问题\n\n## 技术改进\n\n### ⚡ 性能\n- 为 LLM 请求实现了速率限制和重试控制\n- 通过环境变量添加了可配置的速率限制\n- 优化了图像处理，以提高资源利用率\n\n### 🧪 测试与文档\n- 为 Mistral OCR 提供商添加了全面的测试\n- 添加了对受速率限制的 LLM 客户端行为的测试\n- 扩展了图像处理和错误场景的测试覆盖范围\n- 添加了 Mistral 集成及配置的相关文档\n\n## 拉取请求\n* 修复：PDF 页面提取过大的问题，由 @gardar 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F362 中完成\n* 修复（依赖项）：将 github.com\u002Fgabriel-vasile\u002Fmimetype 更新至 v1.4.9，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F351 中完成\n* 杂项（依赖项）：将 dotenv 依赖更新至 v16.5.0，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F343 中完成\n* 修复（依赖项）：将 @headlessui\u002Freact 更新至 v2.2.2，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F350 中完成\n* 杂项（依赖项）：将 @types\u002Fnode 更新至 v22.15.3，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F342 中完成\n* 修复（依赖项）：将 github.com\u002Fgardar\u002Focrchestra 的摘要更新至 2d28866，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F364 中完成\n* 杂项（依赖项）：将 testcontainers 更新至 v10.25.0，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F369 中完成\n* 杂项（依赖项）：将 @playwright\u002Ftest 更新至 v1.52.0，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F367 中完成\n* 杂项（依赖项）：将 @vitejs\u002Fplugin-react-swc 更新至 v3.9.0，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F368 中完成\n* 修复（依赖项）：将 axios 更新至 v1.9.0，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F372 中完成\n* 添加 Mistral AI 的 OCR 和 LLM 集成，由 @icereed 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F366 中完成\n* 杂项（依赖项）：将 vite 更新至 v6.3.4，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F371 中完成\n* 修复（依赖项）：将 google.golang.org\u002Fapi 模块更新至 v0.231.0，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F374 中完成\n* 修复（依赖项）：将 react-router-dom 更新至 v7.5.3，由 @renovate 在 https:\u002F\u002Fgithub.com\u002Ficereed\u002Fpaperless-gpt\u002Fpull\u002F334 中完成\n* 修复（依赖项）：将 re","2025-05-05T08:27:55"]