229 lines
11 KiB
Markdown
229 lines
11 KiB
Markdown
# 7-56 LightRAG Native DOCX Sidecar 可定位块粒度优化 v1
|
||
|
||
> 创建时间：2026-06-09
|
||
>
|
||
> 当前状态：`process`
|
||
>
|
||
> Owner：07-ai / knowledge-rag / LightRAG native parser / office-preview
|
||
>
|
||
> 前置完成：
|
||
> - `design/07-ai/done/7-55-lightrag-docx-citation-rerank-alignment-v1.md`
|
||
>
|
||
> 参考：
|
||
> - LightRAG native DOCX parser：`/mnt/Data1T/Mnote_data/lightrag/LightRAG/lightrag/parser/docx/`
|
||
> - LightRAG sidecar writer：`/mnt/Data1T/Mnote_data/lightrag/LightRAG/lightrag/sidecar/writer.py`
|
||
> - Docling adapter 对照：`/mnt/Data1T/Mnote_data/lightrag/LightRAG/lightrag/parser/external/docling/`
|
||
> - NexusRAG：仅作为 parse-before-index 架构佐证，不照搬 pipeline
|
||
|
||
## 1. 结论
|
||
|
||
当前 DOCX 定位问题的根因不是 MNote 缺少查询后 parser，而是 LightRAG native DOCX sidecar 把已解析到的段落信息压成了过粗的 content block。
|
||
|
||
实测样本：
|
||
|
||
```text
|
||
/mnt/Data1T/Mnote_data/users/mnote-e2e/workspaces/my-space/新页面233155/中国化妆品新原料产业发展调研报告_03（20260410）.docx
|
||
```
|
||
|
||
对比结果：
|
||
|
||
```text
|
||
native parser 旧行为：
|
||
- python-docx 可读到 68 个 paragraph，且有 w14:paraId
|
||
- sidecar 只写 1 个 content block
|
||
- positions 只有 paraid range [第一段, 最后一段]
|
||
|
||
docling parser 当前行为：
|
||
- docling raw JSON 有 70 个 texts
|
||
- LightRAG docling IR builder 也合并为 1 个 block
|
||
- DOCX prov/bbox 为空，不提供 Word 原生 paraId
|
||
|
||
native parser 优化后：
|
||
- sidecar 写 67 个 content block
|
||
- 每个 block 带单段 paraid range
|
||
- positions.paraid.anchor 写 paragraph ordinal
|
||
- 额外写 text_fingerprint position
|
||
```
|
||
|
||
因此当前主线选择：**优先优化 LightRAG native DOCX sidecar，不切换到 Docling 作为 DOCX 定位主路径。**
|
||
|
||
Docling 保留为外部 parser 能力，适合 PDF/图片/跨格式解析对照；但对 DOCX 回跳原 Word 段落，native 能拿到 `paraId`，更适合作为定位底座。
|
||
|
||
## 2. 设计目标
|
||
|
||
把 DOCX native sidecar 从 document-sized block 改为 paragraph/section-addressable blocks：
|
||
|
||
```text
|
||
DOCX native parse
|
||
-> paragraphs[]
|
||
text
|
||
paraId
|
||
paragraphOrdinal
|
||
inferred heading
|
||
textFingerprint
|
||
-> blocks.jsonl
|
||
content block per addressable paragraph/table slice
|
||
positions: paraid + paragraph ordinal
|
||
positions: text fingerprint
|
||
heading / parent_headings
|
||
-> LightRAG indexing/query
|
||
-> MNote citation/locator
|
||
chunk/reference -> blockid/positions -> office-preview 定位
|
||
```
|
||
|
||
## 3. 当前实施
|
||
|
||
已在 LightRAG 本地源码完成第一步：
|
||
|
||
- `lightrag/parser/docx/parse_document.py`
|
||
- 新增 `addressable_blocks` 参数。
|
||
- 新增 Normal 样式报告标题启发式识别。
|
||
- 新增 paragraph-level block 输出。
|
||
- 每个 addressable block 写 `paragraph_ordinal` 与 `text_fingerprint`。
|
||
- `lightrag/parser/docx/ir_builder.py`
|
||
- `IRPosition(type="paraid")` 的 `anchor` 写 paragraph ordinal。
|
||
- 追加 `IRPosition(type="text_fingerprint")`。
|
||
- `lightrag/pipeline.py`
|
||
- native DOCX production parse path 调用 `extract_docx_blocks(..., addressable_blocks=True)`。
|
||
|
||
## 4. 验证证据
|
||
|
||
命令：
|
||
|
||
```bash
|
||
cd /mnt/Data1T/Mnote_data/lightrag/LightRAG
|
||
.venv/bin/python -m lightrag.parser.cli \
|
||
'/mnt/Data1T/Mnote_data/users/mnote-e2e/workspaces/my-space/新页面233155/中国化妆品新原料产业发展调研报告_03（20260410）.docx' \
|
||
--engine native \
|
||
-o /tmp/mnote-lightrag-parser-cosmetics-native-v3 \
|
||
--preview 8
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
[sidecar] wrote 67 blocks
|
||
positions example:
|
||
[
|
||
{"type":"paraid","anchor":4,"range":["6692C49B","6692C49B"]},
|
||
{"type":"text_fingerprint","anchor":"1454ec0b0ffd9fc0"}
|
||
]
|
||
```
|
||
|
||
PDF 对照样本：
|
||
|
||
```text
|
||
/mnt/Data1T/Mnote_data/users/mnote-e2e/workspaces/my-space/新页面233155/parsertest.pdf
|
||
```
|
||
|
||
MinerU parse 已能输出 `positions.type=bbox` 与 page anchor，PDF 当前先消费现有 bbox，不作为 7-56 首要补丁对象。
|
||
|
||
## 5. 后续收口
|
||
|
||
- MNote `knowledge_rag` mapper 应优先消费 provider sidecar 中的 `blockid/positions`，逐步退役 query-time quote 反查 block。
|
||
- office-preview 应优先使用 `paraid.anchor` 或 paraid range 定位；没有可用 paraId 时再用 `text_fingerprint/displayQuote` 做降级匹配。
|
||
- 重新索引 DOCX 后才能让旧资料库命中使用新 sidecar 粒度。
|
||
- LightRAG 服务需要重启后才会使用本地源码改动。
|
||
- 本轮已执行 `systemctl --user restart mnote-lightrag.service`，`/health` 返回 healthy；当前 parser routing 仍是 `*:native-iteP,*:mineru-iteP,*:legacy-R`，DOCX 默认走 native。
|
||
|
||
## 6. MNote 与 LightRAG 的新分工
|
||
|
||
LightRAG 已提供 keyword / vector / graph / hybrid 检索、rerank、query 与 chunk/reference 返回。MNote 不应继续维护第二套召回、排序或 sidecar exact search 作为主路径。
|
||
|
||
新的主合同：
|
||
|
||
```text
|
||
MNote
|
||
- source registry：本地路径、allowed roots、索引状态、LightRAG doc/file 映射
|
||
- scope：搜索目录 / 后续排除目录 / 权限过滤
|
||
- facade：把 UI / Page AI 请求转为 LightRAG query/search/data 参数
|
||
- citation：把 LightRAG reference/chunk 归一化为 MNote result/citation
|
||
- locator：消费 LightRAG sidecar positions 并打开原文件
|
||
|
||
LightRAG
|
||
- parse / OCR / chunk / vector / graph / rerank / hybrid retrieval
|
||
- DOCX native 输出 paraid / paragraph ordinal / text fingerprint
|
||
- PDF/MinerU 输出 page/bbox
|
||
```
|
||
|
||
因此，MNote 允许保留的“手搓”只限定位适配；定位适配只能消费 LightRAG 已返回的 reference/chunk/source sidecar 信息，不能重新执行一套 MNote 检索或 parser：
|
||
|
||
- `bbox -> pdf-preview`
|
||
- `paraid / paragraphOrdinal / textFingerprint -> office-preview`
|
||
- `blockId / sourceMapPath / evidenceText -> provider 引用后的定位线索`
|
||
|
||
不再作为主路径继续扩写：
|
||
|
||
- MNote 独立 sidecar exact search provider
|
||
- MNote query-time DOCX parser
|
||
- MNote 自己 rerank / 多 provider 融合排序
|
||
- MNote query-time sidecar quote 反查
|
||
- 旧 `docs_search` / `mnote.evidence.search` / LiteParse local evidence search
|
||
|
||
## 7. 退役计划
|
||
|
||
阶段 A：完成 provider positions 消费。
|
||
|
||
- `knowledge_rag` locator 解析 `positions.type=bbox / paraid / text_fingerprint`。
|
||
- citation URL 与 resource tab 透传 `paragraphOrdinal / paraIdStart / paraIdEnd / textFingerprint`。
|
||
- office-preview 优先按段落定位，再回退到当前文本定位。
|
||
|
||
阶段 B：退役 query-time sidecar 反查与旧 evidence/docs 搜索。
|
||
|
||
- 删除 `find_lightrag_sidecar_quote_for_query` / `find_lightrag_sidecar_block_for_query` 这类 query-time sidecar quote 反查 helper；MNote 不再用 sidecar 作为检索补召回。
|
||
- `docs_search`、`docs_read`、`mnote.evidence.*` Hermes tool 统一返回退役错误，引导使用 `mnote.knowledge_rag.query/open_reference`。
|
||
- `/api/evidence/search` 只保留退役 guard，不再保留可被内部调用的 `search_payload`。
|
||
- 搜索结果去重可以保留在 MNote locator/result 层，但召回与排序不再依赖 MNote sidecar exact search。
|
||
- `/api/knowledge-rag/search` 的 `mode=exact` 走 LightRAG `/query/search`；`mode=mix/local/global/hybrid/naive` 走 LightRAG `/query/data`。
|
||
- 搜索面板“全盘资料库”接入 LightRAG 检索模式：综合 `mix`、图谱混合 `hybrid`、向量 `naive`、实体 `local`、关系 `global`、关键词 `exact`。`精确匹配`开关会强制走 `exact`。
|
||
|
||
阶段 C：退役 MNote parser 主路径。
|
||
|
||
- 删除或冻结 MNote 后端 DOCX/PDF parser 参与 RAG 搜索的入口。
|
||
- 保留 source-map / locator 兼容读取，用于历史索引和旧 OCR 结果打开。
|
||
- 新索引统一由 LightRAG parser sidecar 产出定位信息。
|
||
|
||
## 8. 不做
|
||
|
||
- 不在 MNote 新增一套 DOCX parser。
|
||
- 不把 DOCX 默认切到 Docling。
|
||
- 不在 MNote 实现 rerank；rerank 仍走 LightRAG 原生能力。
|
||
- 不把 DOCX 无 bbox 伪造成 PDF 页内精确定位。
|
||
|
||
## 9. Agent / MCP 边界
|
||
|
||
LightRAG 官方内核不提供 Skill/MCP/plugin 系统；社区已有 `lightragmcp`、`mcp-lightrag` 等 MCP server，可把 LightRAG query、文档管理、图谱查询包装成 Agent 工具。这一层适合接给 Reasonix / Hermes / Claude Desktop 这类 Agent runtime，但它不能替代 MNote 的 source registry 与引用打开能力。
|
||
|
||
推荐边界：
|
||
|
||
```text
|
||
Reasonix / Hermes
|
||
-> 可直接挂 LightRAG MCP：查询、问答、图谱、管理
|
||
-> 返回 LightRAG reference/chunk/citation 数据
|
||
|
||
MNote
|
||
-> 提供 mnote.knowledge_rag.open_reference 或等价 locator bridge
|
||
-> 把 Agent 引文里的 file_path/chunk_id/blockid/positions 映射到原文件 tab、PDF bbox、DOCX paragraph
|
||
-> 做 allowed roots / workspace source registry / citationUrl
|
||
```
|
||
|
||
因此更好的长期方案不是在 MNote 内继续手搓搜索工具，而是：
|
||
|
||
- Agent 侧：可以挂 `lightrag_native=/mnt/Data1T/mnote/scripts/lightrag-native-mcp.sh`，让 Agent 原生调用 LightRAG 检索、`query_data`、图谱、文档和 pipeline 能力；MNote 不把第三方 MCP server 嵌入 Web runtime。
|
||
- MNote 侧：保留极薄的 `knowledge_rag.query/search/open_reference` facade，服务 UI、权限、source registry 与可点击引用；若 Agent 已直接通过 LightRAG MCP 检索，MNote 只需要 citation bridge。
|
||
- Citation bridge：`mnote_lightrag_bridge=/mnt/Data1T/mnote/scripts/mnote-lightrag-mcp.sh` 已提供 `open_mnote_reference`，输入 LightRAG `file_path` / `chunk_id`，输出 MNote `citationUrl` / `openAction`，不参与检索和排序。
|
||
|
||
当前本机配置审计：
|
||
|
||
- `/home/lix/.reasonix/config.json` 已配置 `lightrag_native=/mnt/Data1T/mnote/scripts/lightrag-native-mcp.sh` 与 `mnote_lightrag_bridge=/mnt/Data1T/mnote/scripts/mnote-lightrag-mcp.sh`。
|
||
- `/home/lix/.hermes/profiles/mnote-u-mnote-e2e-default/config.yaml` 已配置 `lightrag_native` 与 `mnote_lightrag_bridge` MCP server。
|
||
- MNote 内已有 `skills/mnote-knowledge-rag/SKILL.md`、`skills/mnote-lightrag-bridge/SKILL.md` 和 Hermes manifest 的 `mnote.knowledge_rag.status/query/open_reference`，这是当前 agent 调用 LightRAG 后回到 MNote 引用定位的 facade。
|
||
- 包名核验：PyPI 可见 `mcp-lightrag 0.2.2` 与 `lightrag-mcp 0.1.1`，但 `mcp-lightrag 0.2.2` 对当前本机 LightRAG 版本会触发 `QueryRequest.__init__() got an unexpected keyword argument 'max_token_for_text_unit'`。当前 Reasonix/Hermes 原生 LightRAG MCP 改用 `l-pw2c-lightrag-server-mcp@1.2.2`，并保留 MNote bridge 做 citation/open-reference 映射。
|
||
|
||
MCP / MNote tool 变更后的强制验收：
|
||
|
||
- 使用 Reasonix ACP / Page AI 发起真实资料库问题，确认 AI 可见回答包含 MNote citation 链接，而不是 raw JSON、provider 内部路径或手写 `/documents`。
|
||
- 从 AI 回答中点击 citation 链接，必须在 MNote 中打开对应资源 tab；PDF 要落到 page/bbox，DOCX 要落到 paragraph/block，降级资源至少要打开到正确 resource tab 并明确 `locatorDegraded`。
|
||
- 验收证据必须包含 Reasonix run payload 摘要、回答截图、点击后打开定位截图、console/network 摘要和 `result.json`。
|
||
- 当前可复用 smoke：`scripts/task530-knowledge-rag-page-ai-final-answer-smoke.js`，它会使用 Reasonix Page AI 得到 citation，并点击 AI 返回的链接验证 MNote 资源定位打开。
|