RAG (技术文档检索)
概述
PlantPulse RAG 是让 AI 能够即时检索和引用制造现场的技术文档、手册、SOP、规定的 RAG(Retrieval-Augmented Generation) 检索服务器。
通过 4 种检索模式提供准确且符合语境的文档检索，文档中的表格·图片·公式在建立索引时也会被转写成文字一并纳入检索范围。
文档检索分为两层。
- RAG API (
plantpulse-rag-api) — 用户和 AI 实际接触的一层。提供文档管理界面和 检索 API。 - LightRAG — 实际执行索引·检索的内部引擎。不对外暴露， 仅可通过 RAG API 访问。
也就是说没有直接打开 LightRAG 的地址或 WebUI(/webui) 的方法。文档相关操作都在 RAG API
界面中完成。（旧的自研服务器 plantpulse-rag 已归档，LightRAG WebUI 直接
上传的路径已于 2026-07-30 被下方的 Documents 界面取代。）
检索模式
| 模式 | 说明 | 适用场景 |
|---|---|---|
| hybrid（默认） | local + global — 同时利用知识图谱中的实体和关系 | 一般文档检索（推荐） |
| naive | 仅使用文档片段的向量相似度（不使用图谱） | 概念性问题、相似文档探索 |
| local | 以问题中出现的实体（设备·零部件等）为中心 | 确认特定对象的详细内容 |
| global | 以实体之间的关系为中心 | 跨多个文档的综合信息 |
若给出以上四种以外的模式名称，则不会执行检索而直接拒绝（REST 422）→ RAG 算法
使用路径
| 操作 | 位置 |
|---|---|
| 以聊天方式提问 | 副驾驶的提问 — 智能体会经由 MCP 网关自动调用 RAG API 的 rag_search 工具（见下文«聊天的文档检索只走网关»）。点击答案下方的依据卡片（文档 · 图纸 · 视频）即可在对话旁的右侧面板打开文档原文 · 图纸 · 视频 → 提问 — 右侧面板 |
| 直接进行检索 | RAG API 控制台的 Query 界面 |
| 上传·删除·查看文档列表 | RAG API 控制台的 Documents 界面 |
| 查看自动同步结果 | RAG API 控制台的 Sync History 界面 |
| 查看索引失败原因 | RAG API 控制台的 Logs 界面 |
副驾驶**没有内置的文档检索。**聊天的文档检索只有 MCP 网关背后的 RAG 工具 rag_search 这一个。
- 网关一开始就启用
rag_search·rag_list_documents。若管理员将其关闭，聊天将找不到文档。 - 找不到文档时，管理员请在 AI 管理控制台 › MCP 网关 › 服务器 中确认 RAG Gateway 服务器是否已启用，并在工具中确认
rag_search是否已启用 → AI 管理控制台 — MCP 网关 - 用户一侧需要拥有聊天工具权限（
tool:mcp）→ 权限 - 若已关闭或网关无应答，对手册 · 图纸 · 规程类问题不会编造答案，而是予以拦截 —「现在无法使用文档检索（MCP 网关无应答）…」 或「文档检索工具已关闭，或未授权给此账户 …」→ 提问 — 回答中断或停止时
- RAG API 控制台的查询测试以及文档原文 · 视频播放不经过网关，因此若这些画面正常、只有聊天找不到文档，问题出在网关一侧。
在聊天中打开文档原文
点击提问答案下方的文档依据卡片，即可在右侧面板打开该文档的原文。不会跳转到文档界面或打开新标签页。
| 文档 | 在面板中的表现 |
|---|---|
| 以浏览器的 PDF 查看方式原样显示在面板内。顶部栏有在新标签页打开 · 下载原件 | |
| 非 PDF 格式（Word · Excel · 文字文件等） | 不会在面板内渲染 —— 显示「该格式无法在此查看，请下载原件后打开」及下载原件 |
| 无法在页面内渲染 PDF 的浏览器（手机等） | 显示「此浏览器不支持 PDF 查看，请下载原件后打开」及下载原件 |
| 受控等级文档 | 显示「此为受控等级文档，无法打开或下载原件」 —— 没有打开·下载按钮 |
- 当文档检索找到答案所依赖的段落时，卡片上会附带引用段落（若是已知页码的 PDF，还会显示「第12页」），面板会在上方显示该段落，并在该页打开。 页码未知的文档（非 PDF 文档·无法识别文字的扫描 PDF·尚未生成页码信息的文档）将从第 1 页打开。 没有附带段落或页码的来源也很常见 —— 尤其是混有图片·扫描页的文档，为避免出现错误页码，不会附加页码信息。段落可以是原文中的一句话，也可以是表格中的一行。
- 🔴 无文字层的韩文扫描 PDF 无法被读取。 请上传带有文字层的 PDF。
- 权限和查阅等级会在每次打开时重新核验。无法查看的文档将回复「您没有查看此文档的权限」→ 权限
- 若索引仍在但没有保存的原件，则会提示「找不到原文。原件未保存或文档已被删除」。
- 建议依据中附带的文档也会以相同的面板打开。
- 文档卡片的标题为「设备名称 · 文档名称」（直接上传的文档则为「公共文档 · 文档名称」），面板顶部栏会显示文档名称。 同一文档的多个段落会合并为一张卡片。
- AI 仅检索但未在答案中使用的文档不会作为依据卡片出现。
与插入对话的文件不同
通过提问输入框的插入文件放入的文件（包括视频 · 音频）不会进入本文档检索。二者彼此独立。
| 文档检索（RAG） | 插入对话的文件 | |
|---|---|---|
| 放入的人 | 管理员（Documents 界面 · 管理控制台） · 平台自动同步 | 提问的人 —— 输入框的插入文件 |
| 使用范围 | 所有人的所有对话（在权限 · 阅览等级之内） | 仅该对话 —— 只有该对话的所有者可见 |
| AI 的读取方式 | 用 rag_search 查找相关段落 | 直接读取所插入文件的页 · 工作表 · 幻灯片，视频 · 音频则读取转写片段 |
| 视频播放 | 任何已登录的人 | 仅该对话的所有者 |
| 删除时机 | 管理员删除或从台账中移除时 | 删除对话时一并删除 |
- 多人需反复查找的文档（手册 · SOP · 规定）请上传到文档检索。只用于当前这个提问的文件则插入对话。
- 没有把插入对话的文件转入文档检索的功能。需由管理员另行上传同一文件。
- 插入方法与上限（50MB · 视频 · 音频 1GB · 60 分钟 · 每个对话 20 个 · 前 100 页）见 AI 聊天 — 插入文件。
文档进入的两种路径
文档可通过两种方式被建立索引。根据进入方式不同，管理方法也有所不同。
| 路径 | 来源 | 说明 |
|---|---|---|
| 自动同步 | 平台中设备上的附加文档 | 在平台中将文档附加到设备后，会被周期性自动建立索引。无需在 RAG 一侧单独上传 |
| 手动上传 | Documents 界面 | 直接上传不属于任何设备的文档（通用规定、培训资料等）。原件会被单独保存，重新建立索引后依然保留 |
若将设备附属文档手动上传到 RAG，会与平台的文档台账产生不一致。 设备文档在平台中附加到设备，RAG 交由自动同步处理，这样管理更简单。
文档中的表格·图片
PDF · DOCX · PPTX · XLSX 在建立索引时会单独提取图片·表格·公式，并由 Aura 为图片撰写说明文字 一并纳入索引。因此诸如「这张图纸中的阀门编号」这类原本存在于图片中的内容也可以被检索到。
检索对象是文字。在聊天中附加照片读取仪表数值·铭牌文字，属于 视觉工具的职责，如有需要，AI 会以该结果为线索再次检索文档 → 提问 — 用照片提问
图纸 · 视频也可检索 —— 需要先开启
管理员开启后，RAG 除文档外还会对图纸和视频·音频建立索引。两者默认均为关闭。
| 内容 | 接受格式 | 附加到答案中的内容 | 开启开关 |
|---|---|---|---|
| 图纸 | dxf · 矢量 PDF（上传时指定为«图纸»，或平台台账中的文档类型为图纸） | 图纸卡片 —— 在页面预览中突出显示对应位置、版本徽章、与最新版对比 | DRAWING_INGEST_ENABLED |
| 视频 · 音频 | 视频 mp4 · mov · mkv · webm，音频 m4a · mp3 · wav，字幕 srt · vtt | 场景卡片 —— 从该时刻起在答案中播放 | 安装开关 PI_MEDIA_ENABLED |
使用方法和限制请参见 用图纸提问 · 用视频 · 音频提问，开启方法参见 环境设置。开启视频·音频后，提问输入框的语音提问（麦克风）也会一并开启。
文档被检索到之前
문서 등록 (플랫폼 설비 첨부 / Documents 화면 업로드)
│
▼
파싱 — PDF·DOCX·이미지에서 텍스트와 표를 추출
│
▼
청킹 — 검색 단위로 잘게 나눔
│
▼
임베딩 — 각 조각을 벡터로 변환
│
├──▶ 벡터 저장소 (유사도 검색)
└──▶ 지식 그래프 (엔티티·관계 추출)
注册后不会立即可被检索到。解析和嵌入完成后才会出现在结果中， 若刚上传的文档未被检索到，请先在 Sync History 界面确认处理状态。
可建立索引的格式共有六种
仅对 PDF · DOCX · PPTX · XLSX · MD · TXT 建立索引（开启图纸·视频后，会增加上表中的格式）。自动同步遇到此外的文档时， 不会建立索引，而是统计跳过原因并记录在同步结果中。
| 跳过原因 | 含义 | 处理位置 |
|---|---|---|
ext_not_allowed | 以上六种以外的扩展名 | 转换格式后重新附加 |
ext_unknown | 无法识别扩展名 —— 台账中没有文件格式，文档名中也没有扩展名 | 平台一侧的文档台账 |
size_over_limit | 超过最大文件大小（默认 50 MB） | 拆分文件或提高上限 |
ingest_failed | 已接收但在索引阶段失败 | plantpulse-lightrag 日志 → 问题排查 |
/health 的 ingest即使所有存储均正常运行，也可能出现一条文档都未进入的状态。RAG API 的 /health 会
以 ingest 告知最后一次同步结果，若非 ok · disabled，整体 status 即为 degraded。
ingest | 含义 |
|---|---|
ok | 上次同步成功 |
error | 上次同步失败 |
unknown | 从未运行过或无法读取历史记录 —— 不是«正常»状态 |
disabled | 同步已关闭 |
运营人员已排除的文档，即便运行全量重建索引（Reindex All）也仍保持排除状态。
可管理的文档类型
| 文档类型 | 示例 | AI 应用 |
|---|---|---|
| 维护手册 | 各设备的定期巡检流程、润滑油更换周期 | 发现异常时即时提供适当的处置方案 |
| SOP | 各工序的作业流程、安全流程、质量检验标准 | 按作业步骤提供准确指导 |
| 安全规定 | 化学品 MSDS、安全健康规定、应急响应手册 | 危险情况下即时参考相关规定 |
| 技术规格书 | 设备规格、传感器规格、允许范围 | 参考异常判定基准值 |
| 事故/故障报告 | 以往故障案例、原因分析、防止再发对策 | 基于相似案例推测原因 |
| 培训资料 | 新员工培训教材、工序说明书、质量培训 | 支持现场培训 |
配置
嵌入模型·分块大小·Top-K 等检索参数属于 LightRAG 引擎一侧的配置，无法在界面中更改。当前生效的值可在 RAG API 控制台的 Config 界面查看（令牌·密码会以掩码方式显示）。
运行中通常需要调整的多为同步相关项。
| 项目 | 说明 |
|---|---|
| 同步启用与否 | 开启或关闭平台设备文档的自动索引 |
| 同步周期 | 确认平台文档变更的间隔 |
| 单次索引文档数量 | 一个周期内处理的上限 —— 用于初期大量涌入时的负载调控 |
| 最大文件大小 | 超过此大小（默认 50 MB）的文档将被跳过 |
应用场景
| 场景 | 检索示例 |
|---|---|
| 确认维护流程 | "注射机轴承更换方法" → 维护手册 |
| 参考安全规定 | "氮气泄漏时的应对流程" → 应急响应手册 |
| 异常处置指南 | "温度传感器异常时的巡检项目" → 巡检 SOP |
| 检索历史案例 | "去年3号线注射机故障原因" → 故障报告 |
| 图纸中的尺寸 · 版次 | "Ø62 H7 在哪里？" → 图纸·页·区域（开启图纸采集时） |
| 培训视频中的场景 | "压装轴承前需要确认什么？" → 维护培训视频中的该时刻（开启视频·音频时） |
| 确认规格 | "注射机允许温度范围" → 技术规格书 |