Parsr 使用指南:命令行、REST API 与 Web Viewer 三种方式将文档转化为结构化数据
Parsr 使用指南:命令行、REST API 与 Web Viewer 三种方式将文档转化为结构化数据
Parsr 是一个把 PDF、文档与图片转换为富结构化数据的开源工具,其核心是一条由"提取器(Extractor)+ 清洗与重建模块(Cleaner)"构成的模块化处理管线。本文基于 usage 文档,完整讲解 Parsr 的安装、配置,以及命令行、REST API、Web Viewer 演示界面三种实际使用方式,并对照仓库源码说明每条命令与参数背后的实现细节,帮助你快速在本机跑通一次完整的"文档 → 结构化数据"流程。
1. 安装 npm 依赖
在 Parsr 仓库根目录(即克隆下来的 Parsr 文件夹)中执行:
npm install
该命令会安装解析管线核心(server/)、前端演示(demo/vue-viewer/)等所需的全部 Node 依赖。从根目录 package.json 可以看到安装过程还包含两个额外步骤:
install:pre:执行node ./scripts/preinstall,该脚本会按平台(macOS / Windows)检测并提示安装解析 PDF、执行 OCR 所依赖的外部系统程序(参见 scripts/preinstall);postinstall:执行npm run copyAssets,把需要随包分发的模型、脚本等资源复制到指定位置(见 scripts/copyFiles)。
环境前提:Parsr 的实际解析能力依赖若干外部程序(如 pdfminer、tesseract 等)。如果在运行阶段提示依赖缺失,请参考 依赖说明 与 安装指南 完成系统级安装。
2. 运行前的配置认知
Parsr 的核心是一条可高度配置的模块化处理管线:文档先由提取器转为中间表示,再依次经过若干清洗/重建模块(检测标题、段落、表格、阅读顺序等)得到最终结构化文档。这一设计在 server/src/Orchestrator.ts 中体现为 Orchestrator 类——先调用 extractor.run(filename),再调用 cleaner.run(doc, config) 执行后续所有模块。
默认配置位于 server/defaultConfig.json,开头部分定义了关键全局选项:
{
"version": 0.9,
"extractor": {
"pdf": "pdfminer",
"ocr": "tesseract",
"language": ["eng", "fra"]
},
"cleaner": [ ... ]
}
extractor.pdf:PDF 文本提取器,可选pdfminer(默认)、pdfjs、abbyy、tesseract;extractor.ocr:图像 OCR 引擎,可选tesseract(默认)、google-vision、ms-cognitive-services、amazon-textract;extractor.language:OCR 使用的语言列表;cleaner:按顺序执行的模块数组,每个模块可以是一个字符串(使用模块默认配置),也可以是[模块名, {参数...}]的形式覆盖该模块参数。默认管线依次包含 drawing-detection、image-detection、out-of-page-removal、whitespace-removal、redundancy-detection、table-detection、table-detection-2、header-footer-detection、link-detection、words-to-line-new、reading-order-detection、lines-to-paragraph、table-of-contents-detection、ml-heading-detection、list-detection、page-number-detection、hierarchy-detection、regex-matcher 等模块。
提取器的选择逻辑可在 server/src/utils.ts 中看到:getPdfExtractor 与 getOcrExtractor 会根据上述配置实例化对应的 PDFJsExtractor、PdfminerExtractor、TesseractExtractor 等类。
如何修改配置? 直接编辑 server/defaultConfig.json,或复制一份自定义配置文件,之后在命令行(-c 参数)或 API(config 字段)中指定使用。各模块的完整参数说明请参阅 配置文档。
3. 方式一:Web Viewer 演示界面
Web Viewer 是 Parsr 自带的可视化演示:上传文档、勾选模块、提交任务,并在浏览器中直观查看 JSON、Markdown、纯文本与 CSV 四种输出。
3.1 Linux / macOS 下一键启动
npm run start:web:vue
该脚本(见 package.json)会先以后台方式启动 API 服务(npm run start:api:background),再进入 demo/vue-viewer 安装依赖并执行 npm run serve。完成后打开浏览器访问 http://localhost:8080 即可使用图形界面。
3.2 Windows 下分步启动
Windows 下需要两个不同的终端,先启动 API:
npm run start:api
再在另一个终端启动前端:
cd demo/vue-viewer && npm install && npm run serve
npm run start:api 内部会先 npm run build:ts(编译 TypeScript 到 dist/)再安装 api/server 的依赖并启动服务,随后同样打开 http://localhost:8080 使用 GUI。
3.3 GUI 使用要点
在 http://localhost:8080(或点击导航栏 Upload 标签页)选择输入文件,并可启用/禁用处理模块、调整模块参数——界面上的可用参数即来自 server/defaultConfig.json。点击底部 SUBMIT 提交后,Parsr 开始处理并显示进度,完成后自动跳转到 JSON 结果页。若要配置界面未暴露的其它选项,需手动编辑配置文件后刷新页面重新加载。
更完整的界面操作说明(可见性过滤器、字体检查器、元素检查器、Markdown/文本/CSV 视图等)请参见 GUI 使用指南。
4. 方式二:命令行使用
4.1 可用参数
命令行入口是 npm run run:debug,它实际执行 ts-node server/bin/index.ts(见 package.json)。所有参数定义在 server/bin/index.ts 中,由 commander 解析:
-f, --input-file <filename> // 要处理的输入文件。
-o, --output-folder <foldername> // 输出结果的存放文件夹。
-n, --document-name <name> // 文档名称(用于生成输出文件名)。
-c, --config <filename> // 配置文件路径,从中加载应用参数。
-l, --log-level <verbosity> // 日志级别:debug、info(默认)、warn、error。
-p, --pretty-logs // 让日志可读但不再适合机器解析。
各参数在源码中的行为如下:
-f/--input-file必填:源码会按扩展名/MIME 类型自动选择处理管线——.pdf走 PDF 提取器、图片走 OCR 提取器、.xml走 Abbyy 本地 XML、.json/.eml/.docx分别走对应的JsonExtractor、EmailExtractor、DocxExtractor,其余类型会抛出Input file format is unsupported;-o/--output-folder:若目录不存在,源码会自动创建(fs.mkdirSync);文档附带的图片资源会被复制到assets_<documentName>子目录;-n/--document-name:决定输出文件名前缀,例如example会生成example.json、example.txt等;-c/--config:默认值为server/defaultConfig.json(源码中commander的默认参数即${__dirname}/defaultConfig.json);-l/--log-level:默认info;底层日志基于pino封装,见 server/src/utils/Logger.ts;-p/--pretty-logs:为 pino 开启带颜色的美化输出(prettyPrint),适合人工观察,但结构化程度下降。
输出文件由配置中的 output.formats 决定(见 server/bin/index.ts 的导出逻辑):json(富结构化 JSON)、simpleJson、text、markdown、csv、pdf 均按需导出。
4.2 使用示例
macOS / Linux:
npm run run:debug -- --input-file samples/t1.pdf --output-folder dist/ --document-name example --config server/defaultConfig.json --pretty-logs
Windows:
cmd /C "npm run run:debug -- --input-file samples/t1.pdf --output-folder samples --document-name example --config server/defaultConfig.json --pretty-logs"
说明:
--之后的参数原样透传给ts-node server/bin/index.ts。上例中的samples/t1.pdf是文档自带的示例路径;当前仓库 samples 目录实际提供的测试文件包括README.pdf、bitcoin.pdf、foo.pdf、testparagraph.pdf等,可直接用它们替换--input-file的值做首次验证。命令执行后,dist/(Windows 为samples/)下会出现以example为前缀的各类输出文件。
5. 方式三:REST API
Parsr 同时提供异步 REST API,适合集成进其他系统或前端。
5.1 安装并启动 API 服务
npm run install:api
npm run start:api
install:api等价于npm install --prefix api/server,只为 API 服务安装依赖;start:api会编译核心 TypeScript、安装 API 依赖并启动服务。
API 服务入口为 api/server/src/index.ts:new ApiServer() 后调用 launchServer(3001),因此服务默认监听 localhost:3001(见 api/server/src/api.ts 中的 app.listen(port, ...))。
5.2 端点概览
所有端点位于 /api/v1.0(/api/v1 与 /api 指向同一路由),核心端点如下(实现见 api/server/src/api.ts):
| 方法 | 端点 | 说明 |
|---|---|---|
| POST | /document |
以 multipart 表单上传文件(字段 file)与可选配置(字段 config),返回队列 ID |
| GET | /queue/{id} |
查询处理队列状态(含进度信息) |
| GET | /json/{id} |
获取富 JSON 结果 |
| GET | /simple-json/{id} |
获取简化 JSON 结果 |
| GET | /text/{id} |
获取纯文本结果 |
| GET | /markdown/{id} |
获取 Markdown 结果 |
| GET | /csv/{id} 与 /csv/{id}/{page}/{table} |
获取表格 CSV 列表 / 指定页与表的 CSV |
| GET | /xml/{id} |
获取 XML 结果 |
| GET | /thumbnail/{id}/{page}、/image/{docId}/{imageId} |
获取页面缩略图与文档内图片 |
| GET | /default-config、/modules、/module-config/{name} |
获取服务器默认配置、模块列表与单个模块配置 |
| GET | /check-installation |
检查外部依赖是否齐备 |
API 支持上传的类型在源码中有明确白名单:.docx、.eml、application/pdf、.xml、image/tiff、image/png、image/jpeg、application/json。
API 是异步的:POST /document 返回 202 Accepted 及唯一队列 ID,随后轮询 /queue/{id} 得知处理状态,处理完成后按 ID 拉取各格式结果。完整的请求/响应示例、状态码说明与 curl 用法请参见 API 使用指南;交互式接口文档可参考 api/swagger/openapi.yaml。
6. 运行测试
仓库使用 Mocha 编写了覆盖各处理模块与导出器的测试(用例位于 test 目录,如 paragraph-merge.spec.ts、table-detection.spec.ts、markdown-exporter.spec.ts 等)。执行:
npm run test
内部等价于 mocha -t 15000 -r ts-node/register test/**/**/*.spec.ts(见 package.json),会在 15 秒超时限制下对全部 *.spec.ts 测试文件逐一运行。在修改配置、更换提取器或二次开发后,可用它验证管线行为是否符合预期。
7. 小结
Parsr 提供了三条互补的使用路径:
- 命令行:
npm run run:debug配合-f/-o/-n/-c/-l/-p六个参数,适合脚本化、批处理与本地调试; - REST API:
npm run start:api启动 3001 端口的异步服务,适合 Web 应用与系统集成; - Web Viewer:
npm run start:web:vue一键拉起 8080 端口的可视化界面,适合快速体验与人工检查输出。
三者共享同一套核心管线与 server/defaultConfig.json 配置体系。动手前建议先阅读 配置文档 了解各模块参数,再结合本仓库 samples 目录下的 PDF 示例文件完成首次端到端验证。
