Parsr 使用指南:命令行、REST API 与 Web Viewer 三种方式将文档转化为结构化数据

原创2026-10-09 10:14:202,277 阅读
文章标签:后端数据工程

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 使用要点

Parsr Web Viewer 文档上传与模块配置界面

在 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 提供了三条互补的使用路径:

  1. 命令行:npm run run:debug 配合 -f/-o/-n/-c/-l/-p 六个参数,适合脚本化、批处理与本地调试;
  2. REST API:npm run start:api 启动 3001 端口的异步服务,适合 Web 应用与系统集成;
  3. Web Viewer:npm run start:web:vue 一键拉起 8080 端口的可视化界面,适合快速体验与人工检查输出。

三者共享同一套核心管线与 server/defaultConfig.json 配置体系。动手前建议先阅读 配置文档 了解各模块参数,再结合本仓库 samples 目录下的 PDF 示例文件完成首次端到端验证。

登录后查看全文
Parsr