5.3 · 知识图谱可视化（Knowledge Graph Visualization）

Sidecar Format 与 Multimodal 处理（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/HKUDS/LightRAG/5.3-sidecar-format-and-multimodal-processing

翻译时间：2026-05-27T08:45:20.647Z

翻译模型：deepseek-chat

原文字符数：9763

项目：LightRAG (lightrag)

---

Sidecar 格式与多模态处理

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• docs/LightRAGSidecarFormat-zh.md
• lightrag/chunk_schema.py
• lightrag/exceptions.py
• lightrag/external_parser/docling/ir_builder.py
• lightrag/external_parser/mineru/__init__.py
• lightrag/external_parser/mineru/ir_builder.py
• lightrag/llm/_vision_utils.py
• lightrag/multimodal_context.py
• lightrag/prompt_multimodal.py
• lightrag/sidecar/ir.py
• lightrag/sidecar/writer.py
• tests/external_parser/docling/test_ir_builder.py
• tests/external_parser/mineru/test_ir_builder.py
• tests/sidecar/test_writer.py
• tests/test_chunking_raw_lightrag_parity.py
• tests/test_extract_entities.py
• tests/test_multimodal_content_truncation.py
• tests/test_multimodal_surrounding_context.py
• tests/test_parse_native_lightrag_e2e.py
• tests/test_pipeline_analyze_multimodal.py
• tests/test_vlm_cache_key.py

LightRAG 使用"Sidecar"架构来处理多模态内容（图像、表格和公式）。当使用 native、mineru 或 docling 等高级解析引擎时，LightRAG 会将文档文本与其多模态对象和元数据分离，并以标准化的目录布局进行存储。这使得管线能够执行基于 VLM 的专门分析和上下文感知处理，同时保持文本与视觉元素之间的关联。

目的与范围

Sidecar 格式作为 LightRAG 中多模态文档的通用内部表示（IR）docs/LightRAGSidecarFormat-zh.md:3-5。其主要目标是：

1. 对象分离：以结构化方式存储"正文文本 + 多模态对象 + 元数据" docs/LightRAGSidecarFormat-zh.md:3-3。
2. VLM 集成：为视觉语言模型（VLM）提供清晰的接口，使其能够结合周围文本上下文分析图像 lightrag/sidecar/writer.py:11-12。
3. 可追溯性：维护稳定的 ID（blockid），将向量片段链接回原始文档中的特定段落或对象 docs/LightRAGSidecarFormat-zh.md:125-125。

__parsed__ 目录布局

当文档被处理时，会在工作空间的 __parsed__ 文件夹内创建一个名为 <filename>.parsed/ 的目录 docs/LightRAGSidecarFormat-zh.md:23-23。

目录结构

__parsed__/<filename>.parsed/
├── <filename>.blocks.jsonl      # 文本块和文档元数据
├── <filename>.drawings.json     # 图像/图形 Sidecar（ID -> 条目）
├── <filename>.tables.json       # 表格 Sidecar（ID -> 条目）
├── <filename>.equations.json    # 公式 Sidecar（ID -> 条目）
└── <filename>.blocks.assets/    # 原始图像文件（png、wmf 等）

来源：docs/LightRAGSidecarFormat-zh.md:22-36

Sidecar 文件详情

文件	格式	内容
blocks.jsonl	JSONL	第一行为 type="meta"；后续行为 type="content" 块 docs/LightRAGSidecarFormat-zh.md:40-40。
drawings.json	JSON	图像对象字典。键为 im-<hash>-<seq> docs/LightRAGSidecarFormat-zh.md:150-152。
tables.json	JSON	表格对象字典。键为 tb-<hash>-<seq> docs/LightRAGSidecarFormat-zh.md:11-11。
equations.json	JSON	复杂 LaTeX 公式字典。键为 eq-<hash>-<seq> docs/LightRAGSidecarFormat-zh.md:12-12。

来源：docs/LightRAGSidecarFormat-zh.md:7-13，lightrag/sidecar/writer.py:9-12

数据流：从解析器到 Sidecar

从原始文件（PDF、DOCX）到 Sidecar 格式的转换由 IRDoc（中间表示）和 write_sidecar 函数管理。

实体关系：IR 到 Sidecar

下图说明了内部代码实体如何映射到物理 Sidecar 文件。

代码实体到 Sidecar 存储映射

graph TD
    subgraph "自然语言空间（输入）"
        DOC["原始文档（.pdf、.docx）"]
    end

    subgraph "代码实体空间（内存）"
        IRDoc["IRDoc（lightrag/sidecar/ir.py）"]
        IRBlock["IRBlock"]
        IRTable["IRTable"]
        IRDrawing["IRDrawing"]
        IREquation["IREquation"]

        IRDoc -->|包含| IRBlock
        IRBlock -->|引用| IRTable
        IRBlock -->|引用| IRDrawing
        IRBlock -->|引用| IREquation
    end

    subgraph "Sidecar 存储（磁盘）"
        B_JSONL["blocks.jsonl"]
        T_JSON["tables.json"]
        D_JSON["drawings.json"]
        E_JSON["equations.json"]
        ASSETS["blocks.assets/"]
    end

    IRDoc -->|write_sidecar| B_JSONL
    IRTable -->|write_sidecar| T_JSON
    IRDrawing -->|write_sidecar| D_JSON
    IREquation -->|write_sidecar| E_JSON
    IRDrawing -->|materialize_assets| ASSETS

来源：lightrag/sidecar/ir.py:1-28，lightrag/sidecar/writer.py:59-101，lightrag/sidecar/writer.py:133-133

多模态分析管线

Sidecar 写入完成后，LightRAG 会调用 analyze_multimodal 流程。此阶段使用大语言模型（LLM）（用于表格/公式）和视觉语言模型（VLM）（用于图像）生成描述性摘要。

周围上下文组装

为提高分析准确性，LightRAG 会为每个多模态对象提取"周围上下文" lightrag/multimodal_context.py:5-11。

• 前导上下文：对象之前的文本 lightrag/multimodal_context.py:16-16。
• 后续上下文：对象之后的文本 lightrag/multimodal_context.py:16-16。
• 标签原子性：在上下文提取过程中，其他多模态标签（如 <table>）被视为原子单元，因此不会被截断 lightrag/multimodal_context.py:27-28。

分析逻辑

1. VLM 处理：图像与原始图像字节和周围文本一起发送给 VLM 角色的大语言模型 tests/test_pipeline_analyze_multimodal.py:5-7。
2. 表格/公式处理：这些内容以文本形式（表格为 JSON/HTML，公式为 LaTeX）发送给 EXTRACT 角色的大语言模型 tests/test_pipeline_analyze_multimodal.py:5-7。
3. 结果回填：大语言模型输出被写回 Sidecar 条目的 llm_analyze_result 字段 docs/LightRAGSidecarFormat-zh.md:172-179。

多模态分析流程

sequenceDiagram
    participant P as _PipelineMixin
    participant M as multimodal_context.py
    participant L as 大语言模型（VLM/EXTRACT 角色）
    participant W as sidecar/writer.py

    P->>M: enrich_sidecars_with_surrounding(doc_id)
    M->>M: find_target_span() 在 blocks.jsonl 中
    M->>M: build_surrounding() 使用 Token 预算
    P->>L: aquery_multimodal(prompt, image_inputs?)
    L-->>P: JSON {name, description, ...}
    P->>W: 使用 llm_analyze_result 更新 Sidecar JSON

来源：lightrag/multimodal_context.py:15-20，tests/test_pipeline_analyze_multimodal.py:80-104，lightrag/prompt_multimodal.py:21-25

实现细节

占位符标签

在 blocks.jsonl 内部，多模态对象通过 XML 风格的占位符标签表示 docs/LightRAGSidecarFormat-zh.md:130-132。

• 表格：<table id="tb-..." format="json">...</table> docs/LightRAGSidecarFormat-zh.md:134-134
• 图形：<drawing id="im-..." format="png" path="..." /> docs/LightRAGSidecarFormat-zh.md:135-135
• 公式：<equation id="eq-..." format="latex">...</equation> docs/LightRAGSidecarFormat-zh.md:136-136

关键函数和类

• write_sidecar：生成 .parsed/ 目录的入口点。负责 ID 分配（tb-、im-、eq-）和块 ID 计算 lightrag/sidecar/writer.py:59-67。
• IRDoc / IRBlock：解析器适配器用于描述文档结构的数据类，在序列化到磁盘之前使用 lightrag/sidecar/ir.py:32-176。
• build_surrounding：在标签周围提取文本的逻辑，同时考虑 Token 限制和段落边界 lightrag/multimodal_context.py:104-112。
• prompt_multimodal.py：包含 image_analysis、table_analysis 和 equation_analysis 的系统提示词 lightrag/prompt_multimodal.py:52-136。

稳定性与缓存

LightRAG 确保重新解析同一文档时，即使解析时间发生变化，也能产生稳定的 blockid 和文本内容。这是通过以下方式实现的：

• 在合并文本进行片段切分之前，从 blocks.jsonl 中剥离 meta 行 tests/test_parse_native_lightrag_e2e.py:8-12。
• 基于内容和位置计算 blockid：md5(doc_id + ":" + block_index + ":" + heading + ":" + content) docs/LightRAGSidecarFormat-zh.md:125-125。
• 在 Sidecar 的 llm_cache_list 中存储大语言模型分析缓存 ID，以便在文档删除时进行清理 tests/test_pipeline_analyze_multimodal.py:14-15。

来源：lightrag/sidecar/writer.py:1-20，lightrag/multimodal_context.py:1-62，lightrag/prompt_multimodal.py:1-29，tests/test_pipeline_analyze_multimodal.py:1-21