LightRAG 解析服务本地部署：MinerU 与 docling-serve 容器化搭建指南

本文讲解如何在本地为 LightRAG 自建两套外部文档解析服务：MinerU 的 mineru-api 服务（含 vLLM 预加载与 LLM 辅助标题层级修正两项进阶服务端配置）与 docling-serve（含 LaTeX 公式识别模型挂载）。LightRAG 通过 HTTP 与这两个服务通信、不在进程内运行它们的模型，因此读懂本篇后你能够独立完成从镜像构建、模型权重落盘、compose 文件改造，到 LightRAG 侧环境变量对接与缓存行为验证的全流程。

一、先分清：这份文档管的是"容器侧"，LightRAG 侧配置另有一份

MinerU 与 Docling 对 LightRAG 而言都是外部服务：LightRAG 通过 HTTP 与它们通信，不会在进程内运行它们的模型。只有当你把文件路由到 mineru 或 docling 引擎、并且希望自行搭建服务（而不是使用现成的服务端点）时，才需要本文档。

必须明确一条边界：

• 本文档（容器侧）：只包含 MinerU / docling-serve 自身的 Docker 构建、启动与容器内配置，其中没有任何 LightRAG 环境变量；
• LightRAG 侧（env 变量）：哪个扩展名交给哪个引擎、服务端点、凭据、引擎参数，请见 FileProcessingPipeline-zh.md。

这个"外部服务"定位在源码中体现得很直接：lightrag/parser/external/mineru/client.py 中的 MinerURawClient 是一个纯粹的 HTTP 客户端——它读取 MINERU_* 环境变量、向远端提交任务、轮询状态、下载 zip 结果包；lightrag/parser/external/docling/client.py 则对应 docling-serve 的异步转换接口。LightRAG 进程内没有任何 MinerU/Docling 模型代码，服务挂掉只会导致对应文档的解析任务失败（doc_status=FAILED），不会影响 LightRAG 主进程。

二、本地部署 MinerU 服务

2.1 基础部署：构建镜像并启动 API 服务

第一步，从 MinerU 官方仓库（opendatalab/MinerU）把 Dockerfile 和 compose.yaml 拷贝到本地，这两个文件在官方仓库的 docker 目录下可以找到。针对中国供应商的特殊显卡，需要选择相应的 Dockerfile。

准备好这两个文件后，构建 Docker 镜像：

docker build --tag mineru:latest .

镜像构建好后，启动 API 服务（参数 --profile api 标识仅启动 MinerU 的 API 服务，服务默认监听 8000 端口）：

docker compose -f compose.yaml --profile api up -d

镜像构建细节、GPU 驱动准备、模型权重位置等请查阅 MinerU 官方仓库的 README。

为什么 LightRAG 侧恰好指向 8000 端口：查看 env.example 可以看到 LightRAG 对本地 MinerU 的默认对接值就是 MINERU_LOCAL_ENDPOINT=http://127.0.0.1:8000（同时 MINERU_API_MODE=local），与上面 compose 中 8000:8000 的端口映射一一对应。从源码结构看，MinerURawClient 初始化时会做严格校验：MINERU_LOCAL_ENDPOINT 必填，且必须是 base URL——如果填了带 /tasks、/file_parse、/health 等 API 路径结尾的地址，会直接抛出 ValueError（见 client.py），即"服务地址只填到 http://host:8000 为止"。

2.2 进阶配置：开启 vLLM 预加载与标题层级修正（可选）

在基础部署之上，建议为本地 MinerU 额外开启两项 MinerU 服务端功能。这两项改的都是 MinerU 容器侧配置（容器内 mineru.json 与官方 compose.yaml），不涉及 LightRAG 的 env 变量；其中标题层级修正还需要一个可用的 LLM API：

• vLLM 启动预加载：让容器启动时就把 VLM 模型加载进显存，避免首个解析请求承担模型加载延迟；
• 标题层级修正（title_aided）：MinerU 借助一个外部 LLM 修正解析输出的标题层级，提升结构化产物质量。这对依赖标题结构的 P（段落语义）分块策略 尤其有帮助——P 分块策略优先按标题分割，标题层级越准确，分块语义越好。

步骤 1：导出并修改 mineru-lightrag.json

从官方镜像中把 /root/mineru.json 拷到宿主机当前目录的 mineru-lightrag.json（用固定容器名 temp_mineru，无需运行容器）：

docker create --name temp_mineru mineru:latest
docker cp temp_mineru:/root/mineru.json ./mineru-lightrag.json
docker rm temp_mineru

然后修改 mineru-lightrag.json 中的 llm-aided-config.title_aided：填入 api_key，并把 enable 改为 true：

"llm-aided-config": {
    "title_aided": {
        "api_key": "your_api_key",
        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "model": "qwen3.5-plus",
        "enable_thinking": false,
        "enable": true
    }
}

api_key / base_url / model 需替换为用户自己可用的 LLM 服务（示例使用阿里云 DashScope 的 OpenAI 兼容接口）。

步骤 2：修改官方 compose.yaml 的 api profile 服务（mineru-api）

在 mineru-api 服务上做三处改动：environment 增加 MINERU_TOOLS_CONFIG_JSON（让 MinerU 读改过的配置而非镜像内置 mineru.json），volumes 把宿主机 mineru-lightrag.json 挂进容器，command 追加 --enable-vlm-preload true 开启 vLLM 预加载。改好后的完整 mineru-api profile 如下（以 # <-- 新增 标注三处增量）：

  mineru-api:
    image: mineru:latest
    container_name: mineru-api
    restart: always
    profiles: ["api"]
    ports:
      - 8000:8000
    environment:
      MINERU_MODEL_SOURCE: local
      MINERU_TOOLS_CONFIG_JSON: /root/mineru-lightrag.json   # <-- 新增
    volumes:
      - ./mineru-lightrag.json:/root/mineru-lightrag.json    # <-- 新增
    entrypoint: mineru-api
    command:
      --host 0.0.0.0
      --port 8000
      --allow-public-http-client
      --gpu-memory-utilization 0.45                          # Reserved 10GB is fine, preventing OOM errors
      --enable-vlm-preload true                              # <-- 新增
    ulimits:
      memlock: -1
      stack: 67108864
    ipc: host
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ["0"]
              capabilities: [gpu]

示范中请按实际显卡情况调整 gpu-memory-utilization；environment / volumes / command 三处为本次新增项，其余保持官方原样。

步骤 3：重启生效

改完后重新启动 API 服务让改动生效：

docker compose -f compose.yaml --profile api up -d

2.3 LightRAG 侧如何消费这个本地服务（源码印证）

服务就绪后，LightRAG 在 MINERU_API_MODE=local 下走的是 local 协议（见 client.py 模块注释与 _download_local 实现），调用链为：

1. POST {MINERU_LOCAL_ENDPOINT}/tasks 提交 multipart 解析任务，表单中固定要求 return_md / return_middle_json / return_content_list / return_images / response_format_zip 等全部返回项；
2. 按 MINERU_POLL_INTERVAL_SECONDS（默认 2 秒）轮询 GET /tasks/{task_id}，直到 status 变为 completed；
3. GET /tasks/{task_id}/result 下载 zip 结果包，经 safe_extract_zip 防路径穿越与大小上限保护后解包，并归一化出根级 content_list.json，最后写入 _manifest.json 供 raw 缓存命中判定使用。

相关轮询上限由 MINERU_MAX_POLLS（默认 600，约 20 分钟）控制，大 PDF 可适当调高。这意味着本地 MinerU 服务只要实现了标准 mineru-api 的 /tasks 三接口，就能被 LightRAG 完整接入——这也是基础部署与进阶部署在 LightRAG 侧"看起来完全一样"的原因：进阶配置只影响解析产物质量（标题层级、首请求时延），不改变协议。

三、本地部署 docling-serve（启用 LaTeX 公式识别）

以下以 Docker 部署 docling-serve 为例，给出从镜像下载到模型挂载的完整步骤。部署完成后将 DOCLING_DO_FORMULA_ENRICHMENT=true 写入 LightRAG 的 .env 即可启用 LaTeX 公式识别。

重要提示：以下步骤基于显卡支持 CUDA 13 的环境。如果显卡较老旧、不支持 CUDA 13，需要把命令与 compose 文件中的镜像名 docling-serve-cu130:main 替换为对应 CUDA 版本的标签，可选镜像列表见 docling-serve 官方组织的 Packages 页面。

3.1 下载镜像

docker pull ghcr.io/docling-project/docling-serve-cu130:main

3.2 下载模型

# 创建 docling 工作目录
mkdir docling
cd docling

# 创建模型挂载目录
mkdir models

# 把容器内的原有模型拷贝到 models 目录
docker run --rm -it \
  -v "$(pwd)/models:/opt/app-root/src/models" \
  ghcr.io/docling-project/docling-serve-cu130:main \
  cp -r /opt/app-root/src/.cache/docling/models /opt/app-root/src/

# 下载公式识别模型
docker run --rm \
  -v "$(pwd)/models:/opt/app-root/src/models" \
  -e DOCLING_SERVE_ARTIFACTS_PATH="/opt/app-root/src/models" \
  ghcr.io/docling-project/docling-serve-cu130:main \
  docling-tools models download-hf-repo docling-project/CodeFormulaV2 -o models

两条 docker run 分别完成：把镜像内置的基础模型权重拷出到宿主机 ./models（持久化，避免容器重建后重复下载），再单独下载公式识别模型 docling-project/CodeFormulaV2——这正是 LightRAG 侧 DOCLING_DO_FORMULA_ENRICHMENT=true 的前置依赖：没有 code-formula 模型权重，公式富化不会真正生效。

3.3 创建 docker-compose.yaml 文件

在上一步的 docling 目录下创建 docker-compose.yaml，内容如下：

services:
  docling-serve:
    image: ghcr.io/docling-project/docling-serve-cu130:main
    container_name: docling-serve
    ports:
      - "5001:5001"
    environment:
      DOCLING_SERVE_ENABLE_UI: "true"
      NVIDIA_VISIBLE_DEVICES: "all"
      DOCLING_SERVE_ARTIFACTS_PATH: "/opt/app-root/src/models"
    # deploy:  # This section is for compatibility with Swarm
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: all
    #           capabilities: [gpu]
    runtime: nvidia
    restart: always
    volumes:
      - ./models:/opt/app-root/src/models

随后在该目录执行 docker compose up -d 启动服务。容器就绪后，在 LightRAG 的 .env 中设置：

DOCLING_ENDPOINT=http://localhost:5001
DOCLING_DO_FORMULA_ENRICHMENT=true

即可让 LightRAG 通过本地 docling-serve 识别文档中的公式并以 LaTeX 形式输出。

3.4 LightRAG 侧的对接细节与"双轨兼容"行为

上面两个变量在 LightRAG 仓库中的默认值与约束可对照 env.example 中 DOCLING_* 段落（约 L736-L741）：DOCLING_ENDPOINT=http://localhost:5001、DOCLING_DO_OCR=true、DOCLING_FORCE_OCR=true、DOCLING_DO_FORMULA_ENRICHMENT=false。注意三点：

1. DOCLING_ENDPOINT 只填 base URL，不带 /v1/convert/file/async 路径后缀；
2. DOCLING_DO_FORMULA_ENRICHMENT 默认为 false 是保守值：adapter 是双轨兼容的——启用时 block 的 text 字段为 LaTeX；若关闭、或因权重缺失导致 text == orig，会自动按普通文本处理且不写 equations.json。因此部署侧确认 CodeFormulaV2 模型就绪后再开启（见 FileProcessingPipeline-zh.md 中对 DOCLING_DO_FORMULA_ENRICHMENT 启用前提的说明）；
3. 公式富化开关会参与 raw 缓存签名：options_signature 覆盖 DOCLING_DO_FORMULA_ENRICHMENT 等可调环境变量，改变该值（或其他 DOCLING_* 选项）会使旧结果包缓存失效、触发重新解析，不会静默复用旧产物。

部署完成后可通过 API Server 的健康检查快照快速核对 LightRAG 实际读到的 Docling 配置：/health 端点会输出当前 DOCLING_ENDPOINT 与 do_ocr / force_ocr / ocr_engine / do_formula_enrichment 等环境快照（实现见 lightrag_server.py 的 _build_docling_status）。单文件调试则可参考 ParserDebugCLI-zh.md 使用 python -m lightrag.parser.cli --engine docling 验证服务连通性与产物结构。

四、小结：部署完成后的检查清单

服务	就绪标志	LightRAG 侧关键配置
MinerU mineru-api	curl http://localhost:8000/health 通过	MINERU_API_MODE=local、MINERU_LOCAL_ENDPOINT=http://127.0.0.1:8000（本地模式免 token）
docling-serve	容器就绪、./models 内含 CodeFormulaV2 权重	DOCLING_ENDPOINT=http://localhost:5001、DOCLING_DO_FORMULA_ENRICHMENT=true

再次强调主次边界：本文所有容器侧改动（mineru-lightrag.json、compose 的 environment/volumes/command、docling 的模型挂载）都不含 LightRAG 环境变量；LightRAG 侧的引擎路由（哪个后缀交给哪个引擎）、凭据与引擎参数请以 FileProcessingPipeline-zh.md 为准。两套服务一旦按本文部署完成，LightRAG 的 mineru / docling 引擎即具备完整的本地解析能力，其 raw 结果包还会自动缓存（_manifest.json 签名命中则免服务调用），后续重复解析无需重新请求外部服务。