Paperless-ngx 文档元数据增强

它解决的具体问题

Paperless-ngx 的文档入库流程里，OCR 只负责把扫描件变成可搜索的文本，但元数据层完全是另一回事。一份 PDF 进来之后，标题往往还是原始文件名或者自动生成的哈希，标签需要人逐个补，通信人（correspondent）字段十有八九是空的。结果是：全文检索能命中，但按通信人筛选、按标签归类、按标题归档这些真正日常的用法全都使不上劲。

这个技能针对的是已经入库的 OCR 归档，而不是新文档的入站流水线。也就是说，你不需要重新扫描，也不用改消费队列的配置，只需要把现有的归档重新过一遍，用模型补出更聪明的标题、标签和通信人信息。

核心能力

• 复用已有 OCR 文本：直接读取 Paperless-ngx 中已经解析完成的文档内容，不触发新的 OCR 作业。
• 生成结构化元数据：由 LLM 产出三件套——title、tags、correspondent，三者一起构成文档的检索骨架。
• 回写为文档元数据：把生成结果推送回 Paperless-ngx，成为正式的文档属性，而不是一份外部索引。
• 面向存量归档：适合那些「OCR 早就跑完、但元数据一直没人收拾」的历史文档库。

关键步骤

1. 确认 Paperless-ngx 实例可访问，且目标文档的 OCR 归档已经存在。
2. 启动 paperless-gpt 运行时，并配置可用的 LLM 凭据。
3. 对归档中的文档逐个取文本，交给模型推理出标题、标签与通信人。
4. 将三元组作为文档元数据写回 Paperless-ngx。
5. 在实例内按标签或通信人重新检索，验证回写是否生效。

适用边界与注意点

• 依赖 OCR 文本质量：模型能看到的只有 OCR 结果，扫描件模糊、版面错乱时，生成的标题和通信人同样会跑偏。低质量 OCR 归档建议先重跑识别再补元数据。
• 需要完整的运行时栈：Paperless-ngx 实例、paperless-gpt 运行时、受支持的 LLM 凭据三者缺一不可。
• LLM 凭据按供应商配置：上游文档以 OpenAI 为例，需要能访问 gpt-4o 或 gpt-3.5-turbo 一类的模型。
• 部署路径跟随上游：上游提供基于容器的简单部署方式，需先具备容器运行环境。
• 这不是入站处理：新文档入库时的自动分类不在本技能覆盖范围内，它面向的是存量文档的补全。
• 回写前确认目标字段：批量改写标题和标签会直接影响现有的文件夹与标签体系，建议先小批量试跑再全量执行。