MinerU 新手入门安装指南：浏览器插件安装教程，低成本，附性能优化参数

MinerU适合什么人使用

MinerU是一类面向文档解析的AI工具，常用于把PDF、扫描件、论文、说明书、课件等资料转换为Markdown、JSON、图片切片等结构化结果。相比手动复制粘贴，它更适合处理多页文档、复杂排版、表格、公式和图文混排内容。对新手来说，推荐从“本地安装MinerU核心能力＋浏览器扩展提交任务”的方式入门：日常在浏览器中打开资料页面或下载链接，通过扩展把文件交给本地服务处理，既方便，也能减少持续使用在线服务的费用。

低成本使用的关键在于两点：第一，尽量使用本地算力完成解析，普通电脑也可以处理文字型PDF；第二，按文档类型开启必要功能，不要默认开启所有高耗时模块。例如纯文字资料无需高精度OCR，普通报告不一定需要复杂公式识别，批量任务也不适合一次性塞满。

安装前准备

建议使用Windows 10/11、macOS或主流Linux系统。硬件方面，8GB内存可处理轻量文档，16GB以上更稳；如果有NVIDIA显卡，解析速度会更好，没有显卡也可以用CPU模式，只是处理扫描件和复杂版面时耗时更长。软件方面，需要提前安装Python 3.10或3.11，并确认pip可用；如果计划安装浏览器扩展，建议使用Chrome、Edge或其他兼容扩展机制的浏览器。

新手要特别注意路径问题。项目目录、模型目录、输出目录尽量使用英文和数字，不要放在层级过深或含特殊符号的位置。安装过程中如果出现权限报错，不要随意修改系统目录，建议把工具安装在用户目录下，例如D盘或个人主目录中的ai-tools文件夹。

安装MinerU核心环境

第一步，创建独立环境。使用conda或venv都可以，目的是避免与电脑上其他Python项目冲突。创建后进入环境，再升级pip。第二步，安装MinerU相关包。常见做法是通过pip安装magic-pdf及其完整依赖，安装完成后检查命令是否可运行。第三步，准备模型文件。模型通常需要单独下载并在配置文件中指定路径，首次使用时建议选择官方推荐的基础模型组合，不要急着替换为更大的模型。

第四步，进行一次小文件测试。选择一份2到5页的PDF，运行解析命令，观察是否能生成Markdown、图片和中间结果。如果测试文件成功，再处理较大的资料。新手常犯的错误是安装完成后直接解析几百页文件，一旦参数不合适，很难判断是环境问题、模型问题还是文件本身问题。

浏览器扩展安装流程

浏览器扩展的作用是把“下载文件、复制路径、打开命令行”这些步骤简化为按钮操作。安装方式通常有两种：一种是从可信扩展来源直接安装；另一种是下载扩展源码或打包文件，在浏览器扩展管理页手动加载。无论哪种方式，都要确认扩展来源可靠，不要安装来历不明的压缩包。

以手动加载为例，先打开浏览器扩展管理页面，开启开发者模式；然后选择“加载已解压的扩展”，指向扩展目录中的dist或build文件夹。安装成功后，工具栏会出现扩展图标。点击图标进入设置页，填写本地MinerU服务地址，例如http://127.0.0.1:端口号，并设置输出目录、任务超时时间、默认解析模式。保存后可用一个小PDF链接测试提交。

如果扩展需要本地服务配合，必须先启动MinerU服务端，再点击浏览器中的解析按钮。服务端可以设置为开机后手动启动，不建议新手一开始就配置为后台长期运行。这样做便于观察日志，出现错误时也更容易定位原因。

插件配置重点

扩展设置里最重要的是三类配置。第一类是连接配置，包括服务地址、端口、请求超时和最大文件大小。端口不要和其他软件冲突，超时时间建议从300秒起步，大文件可提高到900秒。第二类是解析配置，包括是否启用OCR、表格识别、公式识别、版面分析、图片导出。文字型PDF建议关闭OCR；扫描件必须开启OCR；论文类资料可开启公式识别；普通资料可先关闭高耗时功能。

第三类是输出配置。建议默认输出Markdown和原始资源文件夹，方便后续导入知识库、笔记软件或检索系统。JSON适合二次开发，普通用户不必每次都生成。输出文件命名建议包含日期和原文件名，避免批量处理后混乱覆盖。

低成本性能优化参数

如果使用CPU模式，核心思路是降低单次任务压力。可将批处理大小设置为1到2，DPI设置为144或160，普通文档足够清晰；只有扫描模糊、字号很小的资料再提高到200。线程数不要盲目拉满，通常设置为CPU核心数的一半到三分之二更稳定，电脑还可以正常使用。

如果有显卡，可以将设备参数设为cuda，并适当提高layout_batch_size和ocr_batch_size，例如从2开始试，显存充足再逐步增加。显存不足时会出现任务中断或速度异常，解决办法不是继续增大参数，而是降低批量、降低DPI、分段解析。macOS用户可尝试mps模式，但不同机型表现差异较大，稳定性优先于速度。

功能开关也直接影响成本。formula_enable只在含大量公式的资料中开启；table_enable适合报表和实验数据类文档；ocr_enable只在扫描件、图片PDF、无法复制文字的文件中开启。对清晰的电子PDF，优先使用文本抽取和版面分析，速度更快，资源占用更低。

常见问题与处理

安装依赖失败，多数与Python版本、网络源、系统权限有关。先确认Python版本是否符合要求，再尝试升级pip，并切换到稳定的软件源。模型找不到时，检查配置文件中的路径是否写错，尤其注意斜杠方向和空格。浏览器扩展显示连接失败时，先在浏览器地址栏打开本地服务地址，确认服务是否启动，再检查端口是否一致。

解析结果乱码，通常是原PDF字体编码特殊，可尝试开启OCR或更换解析模式。表格错位时，不要只依赖Markdown结果，应同时查看导出的图片切片和JSON结构。处理大文件卡住时，建议先拆分为每50页一组，确认结果稳定后再批量执行。扩展按钮无反应时，可打开浏览器扩展详情页查看错误信息，或重新加载扩展。

安全边界与使用建议

处理内部资料、合同、简历、研发文档等敏感内容时，优先使用本地模式，不要把文件上传到不可信服务。扩展只授予必要权限，能限制为指定站点就不要开放全部页面权限。输出目录也要妥善管理，解析后的图片和Markdown同样可能包含敏感信息，清理原文件时别忘了清理结果文件夹。

新手最佳实践是先建立三套预设：快速模式用于文字型PDF，开启版面分析、关闭OCR和公式；扫描模式用于图片资料，开启OCR，DPI设为160到200；精细模式用于论文和复杂表格，开启表格与公式，但限制单次页数。通过预设切换，比每次手动改参数更不容易出错。

总体来看，MinerU入门并不复杂：先完成核心环境安装，再配置浏览器扩展，最后根据文档类型调整参数。真正影响体验的不是安装命令本身，而是能否用小样本测试、按需开启功能、控制批量和保存清晰的输出结构。只要遵循这些原则，普通电脑也能以较低成本完成高质量文档解析。