企业官网建设流程全解析

Paperless-ngx 怎么启用 LLM 索引让文档聊天基于相似文档检索回答

【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx

如果你已经在运行 Paperless-ngx，想让顶栏的文档聊天（Document chat）基于相似文档检索来回答问题，需要启用两个东西：AI 总开关加 LLM 后端，以及让LLM 索引（基于向量索引的 RAG）生效的 embedding 后端。这两部分都默认关闭，只在你显式配置后才工作。本文适用于 Docker Compose、单容器或裸机部署的现有 Paperless-ngx 实例。

一个必须知道的边界：启用这些功能后，文档内容（以及元数据）会发送到你配置的 LLM 后端。如果后端是远程托管服务，文档会离开你的服务器并可能产生费用；如果在意隐私，应选本地后端（Ollama 或自托管的 OpenAI 兼容网关）。文档见 AI features。

第一步：启用 AI 并配置 LLM 后端

所有 AI 设置都可以用PAPERLESS_AI_*环境变量提供，也可以在后台Settings → Application Configuration里设置；数据库中的值优先于环境变量（见 configuration.md 的 AI 一节）。最低要求是：

• PAPERLESS_AI_ENABLED— 总开关，默认false，必须设为true；
• PAPERLESS_AI_LLM_BACKEND— 必填，取值ollama（本地运行）或openai-like（OpenAI 本身或任何 OpenAI 兼容 API）；
• PAPERLESS_AI_LLM_MODEL— 后端使用的模型。不指定时，openai-like默认gpt-3.5-turbo，ollama默认llama3.1；
• openai-like后端通常需要PAPERLESS_AI_LLM_API_KEY和/或PAPERLESS_AI_LLM_ENDPOINT；Ollama后端则要求PAPERLESS_AI_LLM_ENDPOINT指向你的 Ollama 服务器。

一个全本地（Ollama）的最小配置示例：

PAPERLESS_AI_ENABLED=true PAPERLESS_AI_LLM_BACKEND=ollama PAPERLESS_AI_LLM_MODEL=llama3.1 PAPERLESS_AI_LLM_ENDPOINT=http://ollama-server:11434

如果改用 OpenAI 兼容的远程 API，把PAPERLESS_AI_LLM_BACKEND设为openai-like，并配置对应的模型名与PAPERLESS_AI_LLM_API_KEY。

这一步完成后，AI 建议（"Suggest" 控件）已经可用，但文档聊天还没有检索能力——那需要 LLM 索引。

第二步：设置 embedding 后端以启用 LLM 索引

设置 embedding 后端即开启LLM 索引，它是你所有文档的向量索引，支撑 RAG：启用后，AI 建议会基于相似的已有文档，文档聊天也能检索到相关上下文。索引只有在AI 已启用并且设置了 embedding 后端两个条件同时满足时才会构建。

• PAPERLESS_AI_LLM_EMBEDDING_BACKEND— 取值huggingface（完全本地）、ollama或openai-like（OpenAI 兼容 embeddings API），默认None；
• PAPERLESS_AI_LLM_EMBEDDING_MODEL— 不指定时按后端取默认值：openai-like为text-embedding-3-small，huggingface为sentence-transformers/all-MiniLM-L6-v2，ollama为embeddinggemma；
• PAPERLESS_AI_LLM_EMBEDDING_ENDPOINT— 可选，不设置时 embedding 请求复用PAPERLESS_AI_LLM_ENDPOINT。

在上面的 Ollama 示例基础上补一行即开启索引：

PAPERLESS_AI_LLM_EMBEDDING_BACKEND=ollama

注意：huggingface本地 embedding 会在首次使用时把模型下载到 Paperless 数据目录，因此首次运行需要网络访问和一定的磁盘空间。

改完环境变量后按你的部署方式让配置生效：Docker 部署重启容器，裸机部署重启各服务。

第三步：手动构建索引

索引默认由任务调度器按PAPERLESS_LLM_INDEX_TASK_CRON（默认10 2 * * *，每天一次）自动增量更新，但首次启用功能、或更换 embedding 后端/模型后，应手动执行rebuild从数据库中的全部文档从头构建。管理命令语法为（见 administration.md 的 Managing the LLM (AI) index 一节）：

document_llmindex {rebuild,update,compact,migrate}

• rebuild：从头构建索引，首次启用或更换后端/模型时使用；
• update：增量索引新增和变更的文档，这是定时任务执行的内容；
• compact：回收空间并优化磁盘上的向量存储。

按部署方式执行（命令调用方式见 administration.md 的 Management utilities 一节）。/path/to/paperless请替换为你实际的 paperless 检出目录：

Docker Compose（paperless 运行中）：

cd /path/to/paperless docker compose exec webserver document_llmindex rebuild

裸机：

cd /path/to/paperless/src python3 manage.py document_llmindex rebuild

文档明确提示：这些命令在 AI 未启用或未配置 embedding 后端时没有任何效果。所以如果 rebuild 跑完却没有索引效果，先回到第一、二步检查PAPERLESS_AI_ENABLED和PAPERLESS_AI_LLM_EMBEDDING_BACKEND是否都正确配置。

验证：用顶栏聊天提问

LLM 索引启用后，验证方式是直接打开界面顶栏（top app toolbar）的聊天控件提问：

• 它根据当前视图在"单篇文档"和"跨多篇文档"两种模式间切换；
• 回答中会附带它所依据的源文档链接，你可以顺着链接核对答案确实来自你的文档。

如果聊天能给出带源文档链接的回答，说明 LLM 索引与检索链路已经工作。之后新增/变更的文档会由每日定时任务自动增量索引进来；想立即刷新可手动跑document_llmindex update，向量存储占用异常时可跑compact回收空间。

升级与维护时的注意事项

• document_llmindex migrate用于迁移索引结构，若索引 schema 已是最新则为 no-op，每次升级后运行都安全（见 administration.md 的升级步骤）。
• 更换 embedding 后端或模型后，旧向量与新向量不可比，需要重新rebuild。
• 可选项（按需调整，均见 configuration.md）：PAPERLESS_AI_LLM_EMBEDDING_CHUNK_SIZE（默认1024，embedding 后端拒绝大输入或截断影响检索质量时调低）、PAPERLESS_AI_LLM_CONTEXT_SIZE（默认8192）、PAPERLESS_AI_LLM_REQUEST_TIMEOUT（默认120秒，本地或慢推理服务超时调大）、PAPERLESS_AI_LLM_OUTPUT_LANGUAGE（不设置时跟随用户界面语言）。
• 安全边界：Paperless-ngx 把文档内容作为不可信数据传给 LLM；默认允许解析到私有/回环地址的 AI 端点（方便本地后端），需要阻断时可把PAPERLESS_AI_LLM_ALLOW_INTERNAL_ENDPOINTS设为false。
• LLM 功能不替换内置的非 LLM 匹配与建议系统，两者并存。

完成以上配置与 rebuild 后，聊天即为基于 RAG 的检索式回答：先由向量索引找到相似文档，再由 LLM 结合检索到的上下文作答，并给出源文档链接供核对。

【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx