lix/mnote

Files

T

lix-2026 0e8b03daf8 Improve LightRAG knowledge search locator alignment

2026-06-08 20:35:49 +08:00

18 KiB

Raw Blame History

7-55 LightRAG DOCX 引用定位与 rerank 对齐设计 v1

创建时间：2026-06-08

当前状态：process

Owner：07-ai / knowledge-rag / 03-rust-web / office-preview

关联：

design/07-ai/done/7-50-lightrag-knowledge-rag-provider-v1.md

design/07-ai/done/7-51-lightrag-post-commit-hardening-v1.md

design/07-ai/process/7-54-raganything-multimodal-retrieval-alignment-v1.md

参考代码：

LightRAG：/mnt/Data1T/Mnote_data/lightrag/LightRAG

NexusRAG：/tmp/mnote-rag-eval-nexusrag

MNote：rust/crates/mnote-web/src/routes/knowledge_rag.rs

1. 背景

当前 DOCX / Office 资料检索的主要问题不是 LightRAG 完全不能检索，而是检索结果映射回 MNote resource tab 时容易错位。

已验证的现状：

MNote 已通过 /api/knowledge-rag/query 调 LightRAG /query/data，并请求 include_references=true / include_chunk_content=true。
LightRAG 返回的 reference / chunk 可以包含 file_path、chunk_id、content，但不直接返回 MNote 可用的 resourcePath/page/bbox/blockId。
MNote 当前 map_reference_plan(...) 会用 chunk quote / query 去 sidecar .blocks.jsonl 里反查 block，再生成 EvidenceLocator。
PDF / image 经 MinerU 或 Docling 解析后通常有 positions.type=bbox，可以转 page/bbox。
DOCX native parser 生成的是 positions.type=paraid，真实样本里大量 range=[null,null]，不能可靠转 page/bbox。
当前 LightRAG 已有 reranker，不应在 MNote 重复实现一套通用 reranker。

本设计目标是把“LightRAG 已有能力”和“MNote 必须补的引用定位层”明确切开。

2. CodeGraph 核对结论

2.1 LightRAG 已有 reranker 主链

源码证据：

lightrag/base.py:83 QueryParam 默认 mode="mix"。
lightrag/base.py:148 enable_rerank 由 RERANK_BY_DEFAULT 控制，默认 true。
lightrag/utils.py:3278 apply_rerank_if_enabled(...) 调 global_config["rerank_model_func"]，支持 index-based rerank result，并把 rerank_score 写回 chunk。
lightrag/utils.py:3362 process_chunks_unified(...) 的顺序是 rerank -> min_rerank_score 过滤 -> chunk_top_k 截断 -> token truncation。
lightrag/api/lightrag_server.py:1894 server 支持 cohere / jina / aliyun rerank binding；vLLM 可走 Cohere-compatible endpoint。
docs/LightRAG-API-Server.md 明确 rerank 是 query-time improvement，不需要重建索引。

当前本机运行态：

{
  "core_version": "1.5.1",
  "configuration": {
    "enable_rerank": false,
    "rerank_binding": "null",
    "rerank_model": null,
    "min_rerank_score": 0.0
  },
  "rerank_queue_status": {
    "available": false
  }
}

结论：MNote 不新增通用 reranker。MNote 只负责配置、健康状态展示、请求参数透传和结果引用消费。

2.2 LightRAG 已有 DOCX native parser 与 sidecar

源码证据：

lightrag/pipeline.py:2897 parse_native(...) 对 pending DOCX 调 extract_docx_blocks(...)。
lightrag/parser/docx/parse_document.py:1611 extract_docx_blocks(...) 按 heading / paragraph / table 拆 block。
lightrag/parser/docx/ir_builder.py:304 DOCX block position 写为 IRPosition(type="paraid", range=[uuid_start, uuid_end])。
lightrag/sidecar/writer.py:256 .blocks.jsonl content row 包含 blockid/content/heading/parent_headings/level/positions。

真实 sidecar 现状：

{
  "type": "content",
  "blockid": "5c6cda46137773fba8cf06fcfc08c313",
  "content": "...",
  "heading": "Preface/Uncategorized",
  "positions": [
    {"type": "paraid", "range": [null, null]}
  ]
}

结论：DOCX 引用定位不能伪造成 PDF 式 page/bbox。短期正确目标是段落级 / block 级定位。

2.3 NexusRAG 的强参考点

NexusRAG 不是只针对 PDF。

backend/app/services/document_parser/docling_parser.py 支持 .pdf/.docx/.pptx/.html。
backend/app/services/document_parser/marker_parser.py 支持 .pdf/.docx/.pptx/.xlsx/.html/.epub。

可借鉴点：

parser abstraction：不同 parser 都产出统一 ParsedDocument。
chunk contract：EnrichedChunk 持有 source_file/document_id/page_no/heading_path/contextualized/images/tables。
retrieval result：source card 展示文件名、页码、标题路径、相关性分数。
citation UI：答案内 citation badge 与 source card 分开，但共享同一 citation model。

不直接照搬点：

NexusRAG 的引用 ID / source card 是产品层 contract，不代表其 DOCX 一定有比 LightRAG 更强的源文档坐标。
MNote 已选 LightRAG 作为默认 provider，不能为了 citation UI 整套替换 RAG provider。
MNote 的 open-reference 必须回到 local-folder resource tab / Page Aggregate / Resource Tree，不应引入第二套文档 viewer 真相。

3. 设计原则

LightRAG 负责检索质量：parse、chunk、vector、graph、rerank、query。
MNote 负责来源真相：source registry、权限、root-relative path、resource tab 打开、citation URL、locator 降级语义。
引用定位按精度分层，不伪造：
- bbox：有 page + bbox，可精确高亮。
- paragraph：有 block / heading / context，可滚动到段落并高亮上下文。
- file：只能打开文件。
DOCX 默认先做 paragraph locator，不把 DOCX 强制转换成 PDF viewer 管线。
rerank 只走 LightRAG provider。MNote 可以做 source scope post-filter 和 citation ranking，但不能把它包装成 provider rerank。
Agent final answer 只能引用 MNote 过滤和映射后的 citations/references，不能引用 raw LightRAG chunks。

4. 目标架构

LightRAG /query/data
  -> raw.data.references / raw.data.chunks
  -> MNote source registry
  -> Evidence Mapping Layer
       - match provider file_path/doc_id -> source entry
       - match chunk_id/content/query -> sidecar block
       - classify locatorPrecision
       - build citationUrl/citationMarkdown
  -> knowledge-rag result
       - references[]
       - citations[]
       - raw kept for diagnostics only
  -> Page AI / Search UI / Source Card
  -> resource tab open-reference
       - bbox: page + bbox highlight
       - paragraph: block/context anchor highlight
       - file: file-level open

5. 数据合同

5.1 MNote citation model

新增内部规范，不要求一次性改完所有 API 字段，但 knowledge-rag、Page AI、搜索结果和 source card 应逐步收口到这组字段。

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeRagCitation {
    pub schema: String,
    pub provider: String,
    pub citation_id: String,
    pub source_id: Option<String>,
    pub source_path: String,
    pub source_root_relative_path: String,
    pub light_rag_doc_id: Option<String>,
    pub light_rag_file_path: String,
    pub light_rag_chunk_id: Option<String>,
    pub block_id: Option<String>,
    pub heading_path: Vec<String>,
    pub quote: Option<String>,
    pub quote_source: String,
    pub locator_precision: LocatorPrecision,
    pub locator_degraded: bool,
    pub citation_url: String,
    pub citation_markdown: String,
    pub relevance_score: Option<f32>,
    pub diagnostics: CitationDiagnostics,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CitationDiagnostics {
    pub quote_source: String,
    pub provider_rerank_requested: bool,
    pub provider_rerank_available: bool,
    pub raw_reference_mapped: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum LocatorPrecision {
    Bbox,
    Paragraph,
    File,
}

5.2 citation ID

采用 NexusRAG 式短 ID，但 ID 只作为 UI/display contract，不作为事实主键。

格式：

[a3z1]      普通文本来源
[IMG-p4f2] 图片来源

生成规则：

每次 query result 内稳定即可，不要求跨 query 永久稳定。
基于 provider + source_id + chunk_id/block_id + occurrence_index 做 hash，base36/base62 截断 4 字符。
同一 query 内冲突则加 salt 重算。
citation card 使用 citation_id 关联 answer badge。

5.3 locator precision 计算

fn locator_precision_from_block(block: &serde_json::Value) -> LocatorPrecision {
    let has_bbox = block
        .get("positions")
        .and_then(|value| value.as_array())
        .is_some_and(|positions| {
            positions.iter().any(|position| {
                position.get("type").and_then(|value| value.as_str()) == Some("bbox")
                    && position.get("anchor").is_some()
                    && position.get("range").and_then(|value| value.as_array()).is_some()
            })
        });

    if has_bbox {
        return LocatorPrecision::Bbox;
    }

    let has_paragraph_anchor = block.get("blockid").and_then(|value| value.as_str()).is_some()
        || block.get("heading").and_then(|value| value.as_str()).is_some()
        || block
            .get("positions")
            .and_then(|value| value.as_array())
            .is_some_and(|positions| {
                positions.iter().any(|position| {
                    position.get("type").and_then(|value| value.as_str()) == Some("paraid")
                })
            });

    if has_paragraph_anchor {
        return LocatorPrecision::Paragraph;
    }

    LocatorPrecision::File
}

6. DOCX paragraph locator

6.1 后端 locator

当 sidecar block 命中但没有 bbox：

{
  "locatorPrecision": "paragraph",
  "locatorDegraded": true,
  "locator": {
    "resourceKind": "office",
    "resourcePath": "资料/保护基.docx",
    "blockId": "2844bf0675454eb5e83f97b596866e53",
    "sourceMapPath": ".mnote/.../__parsed__/保护基.blocks.jsonl",
    "openAction": {
      "params": {
        "provider": "lightrag",
        "chunkId": "doc-xxx-chunk-001",
        "searchQuery": "三乙基硅",
        "evidenceText": "query-centered chunk/block context"
      }
    }
  }
}

要求：

有 blockid 必须传 blockId。
有 sidecar path 必须传 sourceMapPath。
evidenceText 优先取 sidecar block content 的 query-centered window，其次 chunk content。
page/bbox 缺失时不得写假值。
citationMarkdown 文案可带“定位降级”，但链接仍应可点击打开 resource tab。

6.2 前端 office-preview anchor

office-preview / docx-preview 收到 paragraph locator 后：

locator.evidenceText
  -> normalize text
  -> build anchors:
       1. query-centered phrase
       2. long rare terms
       3. heading + quote window
       4. fallback query
  -> scan rendered paragraphs / table cells
  -> score by token overlap + rare term bonus + heading match
  -> scroll into view + transient highlight

禁止：

只用 query 短词直接 find()，否则 吡咯烷 容易错跳到 N-甲基吡咯烷酮。
DOCX 无 page/bbox 时展示成精确页码。
同一 resource tab 重新加载整个 document 来响应每次 citation click；应优先 postMessage 更新 locator。

7. Rerank 对齐

7.1 配置策略

MNote 不实现 rerank model 调用，只管理 LightRAG 配置状态。

推荐配置优先级：

用户显式关闭：enable_rerank=false。
LightRAG health 显示 configuration.enable_rerank=true 且 rerank_queue_status.available=true：MNote query 默认传 enable_rerank=true。
LightRAG health 显示 rerank 不可用：MNote 仍可传 enable_rerank=true，但 diagnostics 标注 provider 未配置；或在 UI 选择“禁用 rerank”后传 false。

.env 示例：

RERANK_BINDING=cohere
RERANK_MODEL=BAAI/bge-reranker-v2-m3
RERANK_BINDING_HOST=http://127.0.0.1:8000/rerank
RERANK_BINDING_API_KEY=local-rerank
RERANK_BY_DEFAULT=True
MIN_RERANK_SCORE=0.0
MAX_ASYNC_RERANK=4
RERANK_TIMEOUT=30

说明：

本地 vLLM / rerank 服务必须先真实验证 endpoint。
之前本机测过常见 NVIDIA rerank endpoint 返回 404；不能仅凭模型名就标“rerank 已启用”。
rerank 是 query-time 能力，启用后不要求重建 LightRAG 索引。

7.2 MNote query request

/api/knowledge-rag/query 和 /api/knowledge-rag/search 请求 LightRAG 时应显式传：

{
  "query": "...",
  "mode": "mix",
  "top_k": 20,
  "chunk_top_k": 20,
  "include_references": true,
  "include_chunk_content": true,
  "enable_rerank": true
}

enable_rerank 来源：

API body 可传。
UI 设置可覆盖。
未设置时使用 MNote 从 LightRAG health 缓存到的 provider capability。

7.3 UI diagnostics

资料库设置 / dashboard 显示：

LightRAG: healthy
Embedding: nvidia/baai/bge-m3
Rerank: disabled
Rerank binding: null
Rerank queue: unavailable

当用户看到检索排序异常时，第一屏就能判断当前没有 rerank。

8. Source card 与 answer citation

借鉴 NexusRAG 的 UI contract：

8.1 inline badge

答案文本中使用短 badge：

三乙基硅基通常可作为保护基使用 [a3z1]。

规则：

每句话最多 3 个来源。
只引用直接支持该句的来源。
badge 点击打开对应 source card，同时可直接打开 citation URL。
LLM 不自行编造 citation ID；由 MNote tool result 提供可用 citation set。

8.2 source card

每个 citation card 展示：

[a3z1] 保护基.docx
定位：段落级
标题路径：酚羟基保护 > 硅基保护
相关性：LightRAG rerank_score / vector order / MNote score
引用片段：...

字段来源：

文件名：source registry。
页码：只有 locator 有 page 时显示。
标题路径：sidecar parent_headings + heading。
相关性：
- 优先 LightRAG rerank_score，如果 provider 返回。
- 否则使用 MNote 现有 reference ranking score，标注为 mnoteScore。
图片引用：sidecar drawings / image OCR 命中使用 [IMG-xxxx]。

9. 实施阶段

Phase A：rerank capability 透出

KnowledgeRagQueryRequest / KnowledgeRagSearchRequest 增加 enable_rerank。
调 LightRAG /query/data / /query/search 时显式传 enable_rerank。
status/dashboard 暴露 LightRAG health 中的 rerank 字段。
diagnostics 标注 providerRerankEnabled、providerRerankAvailable、rerankModel。
不新增 MNote reranker。

验收：

LightRAG .env 为 RERANK_BINDING=null 时，UI 明确显示 rerank disabled。
API result metadata 能看出本次 query 是否请求 rerank、provider 是否实际可用。

Phase B：citation contract 收口

在 knowledge-rag mapped reference 上补 citationId。
输出统一 citations[]，字段包含 citationMarkdown/citationUrl/locatorPrecision/quote/headingPath。
Page AI / Hermes tool result 只暴露 filtered citations，不暴露 raw chunks 给 final answer 引用。
source card 消费 citations[]，不重新解析 raw LightRAG response。

验收：

同一回答内 citation badge 能映射到 source card。
unmapped / stale / deleted provider reference 不进入可引用 citation set。

Phase C：DOCX paragraph locator

lightrag_locator_for_reference(...) 对 DOCX sidecar block 无 bbox 时返回 paragraph locator。
locatorPrecision=paragraph 时保留 blockId/sourceMapPath/evidenceText/headingPath。
citationMarkdown 对 paragraph/file 降级文案明确，但链接可点击。
office-preview 支持 blockId/evidenceText 定位，按 chunk context 打分滚动。
同一 DOCX 多次点击 citation 使用 postMessage 更新定位，不重复 reload。

验收：

吡咯烷 不错跳到仅短词匹配的其他段落。
三乙基硅 / 三甲基硅 在 DOCX 无 bbox 时至少段落级定位。
无 sidecar 或 quote 不匹配时只返回 file locator，不伪造 paragraph。

Phase D：NexusRAG 式来源卡片

source card 展示 citation ID、文件名、标题路径、定位精度、相关性、quote。
有 page/bbox 时显示页码；无 page/bbox 不显示页码。
图片 citation 使用 [IMG-xxxx] 并打开原图 / PDF 页。
answer renderer 对 citation badge 做点击联动。

验收：

答案和搜索结果都能从同一 citation model 打开来源。
source card 不依赖 LLM 生成的自由文本解析。

10. 测试计划

Rust 单测

目标文件：rust/crates/mnote-web/src/routes/knowledge_rag.rs

mapped_reference_generates_short_citation_id
docx_paraid_block_returns_paragraph_locator
docx_missing_block_degrades_to_file_locator
bbox_block_keeps_bbox_locator
query_request_passes_enable_rerank
provider_rerank_disabled_is_reported_in_diagnostics

Browser smoke

新增或扩展：

scripts/task540-knowledge-rag-office-result-open-locator-smoke.js
scripts/task543-knowledge-rag-pyrrolidine-top5-locator-smoke.js

新增断言：

DOCX citation click 后 resource tab 不重载。
paragraph locator 触发可见高亮。
locatorPrecision 与 UI 文案一致。
rerank disabled 状态在资料库设置中可见。

Provider smoke

只在配置真实 rerank endpoint 后执行：

curl /health
curl /query/data -d '{"query":"...", "mode":"mix", "enable_rerank":true}'

验收：

/health.configuration.enable_rerank=true。
rerank_queue_status.available=true。
query 日志出现 rerank 成功或 result chunk 带 rerank_score。

11. 不做

不替换 LightRAG 为 NexusRAG。
不在 MNote 复制 LightRAG vector / graph / rerank。
不把 DOCX 无 page/bbox 的命中伪造成 PDF 精确定位。
不让普通本地搜索强依赖 LightRAG。
不让 LLM 自己生成 citation ID。
不把 raw LightRAG chunk 暴露为 agent final answer 可直接引用材料。

12. 开放问题

LightRAG /query/data 当前 convert_to_user_format(...) 没有把 rerank_score 放入 formatted_chunks。如果上游 rerank 已经写回 chunk，是否要向 LightRAG 提 patch 暴露 rerank_score，还是 MNote 只显示本地 ranking score？
DOCX paraid range=[null,null] 的样本较多。是否需要在 LightRAG native parser 侧增强 paraId 恢复或写入 block ordinal，给 MNote 一个更稳定的 blockOrder？
/query/search 与 /query/data 的 reference schema 不完全一致时，MNote 是否应该先在 connector 层 normalize 为同一个 ProviderReference？
Source scope 当前仍是 MNote post-filter。长期是否需要 LightRAG provider 支持按 file_path/doc_id 过滤候选，以避免 raw retrieval 污染？

18 KiB Raw Blame History Unescape Escape