nyxtronlab/paperless-aissist

Paperless-AIssist

为https://github.com/paperless-ngx/paperless-ngx%E6%8F%90%E4%BE%9B%E5%8F%AF%E6%8E%A7%E7%9A%84AI%E6%96%87%E6%A1%A3%E5%A4%84%E7%90%86%E5%B7%A5%E5%85%B7%EF%BC%8C%E8%AE%A9%E4%BD%A0%E9%80%90%E6%AD%A5%E5%86%B3%E5%AE%9A%E6%AF%8F%E4%B8%AA%E6%96%87%E6%A1%A3%E7%9A%84%E5%A4%84%E7%90%86%E6%AD%A5%E9%AA%A4%E3%80%82

通过标签控制处理流程：用ai-process标签运行完整流水线，或用ai-title、ai-ocr等步骤标签仅执行所需功能。本地Ollama可低成本处理元数据，付费视觉模型可保留给标记为OCR的文档——文本和视觉模型独立配置。支持Ollama（本地）、[] ()和OpenRouter。

核心功能

• 模块化标签工作流：按文档需求执行步骤（ai-title/ai-ocr/ai-fields等），或用ai-process执行全流程
• 文本与视觉模型分离：元数据生成用本地Ollama，视觉OCR用付费模型，独立配置
• 可配置提示词：所有步骤的提示词可通过Web UI编辑，提供示例模板
• 元数据分类：LLM从Paperless现有元数据中选择通讯人、文档类型和标签
• 标题生成：将扫描文件名替换为有意义的标题
• 自定义字段提取：将结构化数据导入Paperless自定义字段（支持按文档类型配置）
• 视觉OCR：用视觉模型（Ollama/OpenAI等）直接从页面图像读取文档
• OCR后处理：分类前用LLM纠正OCR错误
• 文档日期检测：发现可靠原始日期时更新Paperless文档日期
• 文档聊天：通过Web UI询问任何文档的问题
• 文档搜索与预览：从聊天页搜索Paperless文档，预览AI处理结果而不修改原数据
• 自动化API：通过 cron、Home Assistant或自定义脚本触发/停止/检查处理
• 自动调度器：按配置间隔轮询带ai-process标签的新文档
• 多语言UI：支持英文和德文
• 可选认证：用Paperless-ngx凭据保护Web UI（默认禁用）

使用场景

• 需要灵活控制AI处理步骤的Paperless-ngx用户
• 希望本地模型处理元数据、云端模型处理OCR的混合部署场景
• 需要自定义提示词优化文档分类和字段提取的用户
• 需通过API自动化文档处理的集成需求（如Home Assistant联动）

配置说明

所有设置通过Web UI管理，存储在SQLite中。只需挂载卷以持久化配置：

yaml
volumes:
  - paperless-aissist-data:/app/data

快速开始

1. 拉取并运行容器

bash
docker run -d \
  --name paperless-aissist \
  -p 8000:8080 \
  -e PUID=1000 \
  -e PGID=1000 \
  -v paperless-aissist-data:/app/data \
  --restart unless-stopped \
  nyxtronlab/paperless-aissist:latest

访问Web UI：http://localhost:8000

容器以非root用户运行，设置PUID和PGID匹配主机用户/组（尤其是Unraid环境）。

2. Docker Compose部署

yaml
services:
  paperless-aissist:
    image: nyxtronlab/paperless-aissist:latest
    container_name: paperless-aissist
    ports:
      - "8000:8080"
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - paperless-aissist-data:/app/data
    restart: unless-stopped

volumes:
  paperless-aissist-data:

Docker Desktop/Mac/Windows：用host.docker.internal访问主机Ollama
Linux主机网络：用主机LAN IP或172.17.0.1

3. Web UI配置

1. 进入设置验证Paperless和Ollama URL
2. 设置LLM模型（见推荐模型）
3. 在Paperless-ngx中创建至少两个标签：ai-process和ai-processed，可选创建步骤标签
4. 给文档添加ai-process标签用现有文本处理元数据；添加ai-ocr+ai-process用视觉OCR+元数据处理

LLM提供商

每个模型可选择不同提供商：Ollama本地运行，OpenAI/Grok/OpenRouter需API密钥。视觉模型可与主LLM不同：

OpenAI兼容端点（如LM Studio、vLLM）也可用：设置提供商为openai并指向本地服务器URL。

自动化API

外部工具可控制处理流程，适合cron、Webhook或Home Assistant集成。在设置→高级→自动化API生成专用令牌（仅显示一次）。
使用Bearer令牌调用：

bash
curl -H "Authorization: Bearer paia_..." \
  http://localhost:8000/api/automation/status

可用端点：

Home Assistant示例：

yaml
rest_command:
  paperless_aissist_process_all:
    url: "http://paperless-aissist.local:8000/api/automation/process/start"
    method: post
    headers:
      Authorization: "Bearer paia_your_token_here"
      Content-Type: "application/json"

推荐模型

文本模型

视觉OCR模型

处理流水线

带ai-process标签的文档执行标准元数据流程（用Paperless现有文本）；视觉OCR需ai-ocr标签触发：

1. 标题生成 → 2. 分类（通讯人/类型/标签）→3. 自定义字段提取→4. 标签替换（移除触发标签，添加ai-processed）

模块化标签工作流

用步骤标签替代全流程：

提示词管理

所有步骤的提示词可在Web UI提示词页配置，支持类型：title/correspondent/document_type/extract（自定义字段）等。可加载示例模板，支持类型特定提示词（如仅对发票提取字段）。

认证配置

默认Web UI开放，可启用Paperless-ngx凭据认证：在设置→高级中设auth_enabled=true，登录时用Paperless-ngx用户名/密码。

MCP协议

启用后可通过Claude Desktop等MCP客户端控制处理，需生成自动化API令牌并配置客户端（如Claude Desktop的claude_desktop_config.json添加服务器信息）。

架构

• 后端：Python/FastAPI（处理流程、模型客户端、Paperless API、调度器）
• 前端：React 18/TypeScript/Tailwind CSS
• 数据库：SQLite（配置、提示词、日志）
• 运行时：nginx+uvicorn（通过supervisord单容器）

与类似项目对比

Paperless-AIssist是Paperless-ngx的AI中间件，而非替代品，适合需要模块化控制、提示词自定义、模型分离的用户。对比其他项目（如Paperless-ngx原生AI、paperless-ai-next等）各有侧重，选择需根据需求。

许可证

MIT