本文整理自本地部署笔记，记录 MinerU Windows 便携部署的目录结构、环境变量、模型配置、API/WebUI、分层 PDF、古籍 OCR 增强，以及常见问题和启动关闭方法。项目目录为
C:MinerU，整理日期 2026-08-05。
一、当前部署状态
当前是一套便携式部署：Python、依赖、模型、配置、缓存、输入输出都尽量放在 C:MinerU 下面。
主要目录：
<code class="language-text">C:MinerU ├─ runtimepython 便携 Python ├─ source MinerU 源码，当前安装为本地 editable 包 ├─ models 本地模型缓存 ├─ portable-homemineru.json MinerU 配置 ├─ input 输入文件目录 ├─ output API/WebUI 输出目录 ├─ downloads 安装包、pip 缓存 └─ tools 自定义后处理脚本</code>
当前关键版本：
<code class="language-text">mineru 3.4.4，路径 C:MinerUsource gradio 6.8.0 torch 2.13.0+cu130 torchvision 0.28.0+cu130 transformers 4.57.6 huggingface_hub 0.36.2 hf-xet 1.5.2 accelerate 1.14.0 pypdf 6.14.2 pypdfium2 5.10.1 reportlab 5.0.0 opencv-python 5.0.0.93 pillow 12.3.0 psutil 7.2.2</code>
GPU 已按 NVIDIA CUDA 环境配置，check-gpu.cmd 可检查 PyTorch 是否能识别显卡。
二、便携环境关键点
入口脚本都会先调用 portable-env.cmd，它负责设置这些环境变量：
<code class="language-bat">PYTHON=C:MinerUruntimepythonpython.exe USERPROFILE=C:MinerUportable-home HOME=C:MinerUportable-home HF_HOME=C:MinerUmodelshuggingface HUGGINGFACE_HUB_CACHE=C:MinerUmodelshuggingfacehub MODELSCOPE_CACHE=C:MinerUmodelsmodelscope MINERU_TOOLS_CONFIG_JSON=C:MinerUportable-homemineru.json MINERU_MODEL_SOURCE=local MINERU_API_OUTPUT_ROOT=C:MinerUoutput MINERU_PDF_RENDER_USE_THREADS=true</code>
几个变量很关键：
USERPROFILE/HOME改到portable-home，避免配置写到系统用户目录。HF_HOME/MODELSCOPE_CACHE固定模型缓存位置。MINERU_TOOLS_CONFIG_JSON指向项目内配置文件。MINERU_MODEL_SOURCE=local强制使用本地模型。MINERU_API_OUTPUT_ROOT让 API 输出落到output。
三、模型配置
配置文件：C:MinerUportable-homemineru.json，关键内容：
<code class="language-json">{
"models-dir": {
"pipeline": "models/modelscope/models/OpenDataLab--PDF-Extract-Kit-1.0/snapshots/master",
"vlm": "models/huggingface/MinerU2.5-Pro-2605-1.2B"
},
"model-source": "local"
}</code>
含义：
pipeline使用本地 PDF-Extract-Kit 模型。vlm使用本地强模型MinerU2.5-Pro-2605-1.2B。model-source=local避免启动时重新联网拉模型。
Pipeline 模型下载脚本为 download-models.cmd，内部命令：
<code class="language-bat">"%PYTHON%" -m mineru.cli.models_download --model_type pipeline --source modelscope</code>
强模型已放在 C:MinerUmodelshuggingfaceMinerU2.5-Pro-2605-1.2B。
四、API 与 WebUI 部署
API 启动脚本 run-api.cmd，实际命令：
<code class="language-bat">"%PYTHON%" -m mineru.cli.fast_api --host 0.0.0.0 --port 8000 --allow-public-http-client</code>
API 地址：
<code class="language-text">本机：http://127.0.0.1:8000/docs 局域网：http://<本机局域网 IP>:8000/docs</code>
WebUI 启动脚本 run-gradio.cmd，实际命令：
<code class="language-bat">"%PYTHON%" -m mineru.cli.gradio_app --server-name 0.0.0.0 --server-port 7860 --api-url http://127.0.0.1:8000</code>
WebUI 地址：
<code class="language-text">本机：http://127.0.0.1:7860 局域网：http://<本机局域网 IP>:7860</code>
一键启动脚本 start-webui.cmd 会：
1. 检查 http://127.0.0.1:8000/health。 2. API 不存在时启动 run-api.cmd。 3. 检查 http://127.0.0.1:7860。 4. WebUI 不存在时启动 run-gradio.cmd。 5. 自动打开浏览器访问 WebUI。
五、命令行解析脚本
普通 pipeline 解析：
<code class="language-bat">run-mineru.cmd inputyour-file.pdf</code>
内部使用自定义提交脚本：
<code class="language-bat">"%PYTHON%" "%MINERU_ROOT%toolssubmit_mineru_task.py" "%~1" --backend pipeline --api-url http://127.0.0.1:8000</code>
CPU 备用模式：
<code class="language-bat">run-mineru-cpu.cmd inputyour-file.pdf</code>
强模型高精度模式：
<code class="language-bat">run-mineru-strong.cmd inputyour-file.pdf</code>
内部参数：
<code class="language-bat">--backend hybrid-engine --effort high --layered-pdf --api-url http://127.0.0.1:8000</code>
注意：命令行脚本依赖 API 已经启动；如果没有启动，先运行 run-api.cmd 或直接运行 start-webui.cmd。
六、WebUI 已加的自定义能力
OCR 语言显示中文化
WebUI 的 OCR 语言下拉已改成中文说明，例如 ch（中文、英文、日文、繁体中文、拉丁文），不用再看英文语言组合。
同步生成分层 PDF
高级选项里新增并默认勾选“同步生成分层 PDF”。PDF 输入解析完成后，会自动生成 *_origin_layered.pdf 并写入结果 zip。
分层 PDF 包含两个图层：
<code class="language-text">Original Page 原始页图层，可关闭 OCR Text OCR 文字图层，可关闭</code>
OCR 文字和框使用高对比红色，便于校对。
古籍/长卷分块 OCR 补漏
高级选项里新增，默认关闭，适用场景：
- 古籍长卷
- 竖排文字
- 从右到左阅读
- 页面很宽
- 普通 OCR 出现大片空白、整页只有几个 OCR 块，甚至 0 个 OCR 块
工作方式：
1. 只处理宽页。 2. 只处理 OCR 文本块少于阈值的页面。 3. 把页面渲染成图。 4. 横向切成重叠窄块。 5. 按古籍方向从右到左跑 OCR。 6. 合并坐标后按“列中心从右到左、列内从上到下”排序。 7. 把补出来的文字写进 OCR Text 图层。
默认关闭，是为了避免影响普通现代文档、表格、横排 PDF。
手动后处理命令：
<code class="language-bat">.python.cmd toolsmake_layered_pdf.py <任务输出目录> --ancient-vertical-ocr</code>
备用只画框模式：
<code class="language-bat">.python.cmd toolsmake_layered_pdf.py <任务输出目录> --box-only</code>
七、分层 PDF 实现注意
分层 PDF 由 toolsmake_layered_pdf.py 生成。关键实现：
- 使用
pypdf写可选内容组 OCG。 - 原始页面包进
Original Page图层。 - OCR 文字包进
OCR Text图层。 - OCR 字体优先使用 Windows 字体：
C:WindowsFontsDeng.ttf、C:WindowsFontssimhei.ttf、C:WindowsFontssimsunb.ttf。 - 默认使用嵌入式 TrueType 字体，减少 Adobe Acrobat 闪退风险。
- 文字颜色和边框颜色为红色
#dc2626。
八、已验证过的结果
当前古籍样例启用分块补漏后，低 OCR 宽页补充结果示例：
<code class="language-text">第 1 页：补 11 块 第 2 页：补 42 块 第 4 页：补 42 块 第 6 页：补 42 块 第 8 页：补 42 块</code>
验证方式：
<code class="language-bat">.python.cmd -m py_compile toolsmake_layered_pdf.py sourceminerucligradio_app.py toolssubmit_mineru_task.py</code>
PDF 结构检查过：
<code class="language-text">图层：Original Page, OCR Text pypdf strict=True 可读 Poppler pdfinfo 可读 Poppler 可渲染页面</code>
九、应该避开的坑
1. IDM 拦截结果 zip
报错示例：Failed to download result ZIP ... 204 - Intercepted by the IDM Advanced Integration。这是 IDM 把 MinerU 从本地 API 下载结果 zip 的请求接管了，不是 OCR 或模型失败。
处理：
- 退出 IDM，或暂停 IDM 浏览器集成。
- 在 IDM 里关闭“使用高级浏览器集成”。
- 把
127.0.0.1、localhost加入 IDM 例外。
2. WebUI 正在运行时看不到新选项
修改 sourceminerucligradio_app.py 后，已有 WebUI 进程不会自动热更新。运行 restart-webui.cmd，或关闭 API/WebUI 窗口后重新运行 start-webui.cmd。
3. 分层 PDF 打开闪退
风险主要来自可选图层对象结构不够稳、OCR 文字层使用 CIDFont 时 Acrobat 处理不稳、原始页和 OCR 页内容流混合不规范。当前规避：OCProperties 写成间接对象，只保留两个明确 OCG，OCR 文字层使用嵌入式 TrueType 字体，红色文字和边框方便辨认。如果 Acrobat 仍异常，可先用福昕或浏览器验证；只有 Acrobat 崩时优先怀疑其图层/字体兼容性。
4. 关闭原始图层后大片空白
这通常不是分层 PDF 漏画，而是上游 _model.json 本来没有 OCR 出主体文字。关闭 Original Page 后只剩少数红字，说明 OCR Text 层确实只有这些块；古籍长卷请勾选“古籍/长卷分块 OCR 补漏”。
5. 古籍分块 OCR 不适合所有文档
它假设“竖排、从右到左、长卷宽页”，不建议用于现代横排论文、表格密集文件、普通扫描合同、图文混排页面，否则可能补出重复块、顺序不合阅读习惯，或增加处理时间。
6. 古籍 OCR 顺序不要按横排理解
古籍默认阅读顺序为“列从右到左、列内从上到下”，当前分块补漏也按这个顺序合并，不按现代横排从左到右排序。
7. 控制台中文路径乱码
PowerShell 或 CMD 输出中文路径时可能显示乱码，但文件本身通常正常。判断以资源管理器和实际文件存在为准。
8. 旧 zip 不会自动包含后生成的 PDF
结果 zip 生成之后又手动生成 _origin_layered.pdf，旧 zip 不会自动更新。WebUI 正常流程里分层 PDF 在压缩前生成；手动补生成后需要重新打包。
9. 端口占用
API 用 8000，WebUI 用 7860。启动失败先检查端口：
<code class="language-bat">netstat -ano | findstr :8000 netstat -ano | findstr :7860</code>
10. 局域网访问安全
当前 API 使用 --host 0.0.0.0 --allow-public-http-client，方便局域网访问，但只建议在可信内网使用，不要直接暴露公网。
11. 便携目录可以移动，但显卡驱动不能便携
整个 C:MinerU 可以复制到别的位置或另一台机器，但另一台电脑仍需要 Windows、可用 NVIDIA 驱动、能支持当前 PyTorch CUDA 运行时的显卡环境。
十、常用检查命令
<code class="language-bat">check-gpu.cmd python.cmd -V .python.cmd -m py_compile toolsmake_layered_pdf.py sourceminerucligradio_app.py toolssubmit_mineru_task.py .python.cmd toolsmake_layered_pdf.py --help</code>
十一、启动方法
推荐一键启动：
<code class="language-bat">start-webui.cmd</code>
它会自动启动 API 和 WebUI，并打开 http://127.0.0.1:7860。
分开启动：
<code class="language-bat">run-api.cmd run-gradio.cmd</code>
命令行解析前先确认 API 已启动：
<code class="language-bat">run-mineru.cmd inputyour-file.pdf run-mineru-strong.cmd inputyour-file.pdf run-mineru-cpu.cmd inputyour-file.pdf</code>
十二、关闭方法
方法一：直接关闭 MinerU API 和 MinerU WebUI 两个 CMD 窗口。
方法二：按端口结束进程：
<code class="language-bat">for /f "tokens=5" %P in ('netstat -ano ^| findstr /R /C:":8000 .*LISTENING" /C:":7860 .*LISTENING"') do taskkill /F /PID %P</code>
写进 .cmd 文件时 %P 要改成 %%P。
方法三：重启服务：
<code class="language-bat">restart-webui.cmd</code>
它会先结束 8000 和 7860 端口上的服务，再调用 start-webui.cmd 重新启动，适合修改了 WebUI 代码、新增选项没出现、服务卡住、端口被旧进程占用等情况。
十三、推荐使用习惯
普通 PDF：勾选“同步生成分层 PDF”即可。
古籍长卷：勾选“同步生成分层 PDF”，再勾选“古籍/长卷分块 OCR 补漏”。
校对时：打开 *_origin_layered.pdf，在 PDF 图层面板切换 Original Page 和 OCR Text，红色文字就是 OCR 层。
如果下载失败且看到 IDM 提示，先处理 IDM，不要重装模型。
*本文依据本地部署笔记整理，命令、路径、版本与报错均以实际环境为准。*
