尧图网站建设 
LiteParse 完全指南Rust 空间感知文档解析库与 lit CLI 实战【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparse导读LiteParse 是当前仓库的核心 Rust 库与 CLI 工具主打快速、轻量、完全本地运行的 PDF 与多格式文档解析核心能力是空间文本提取spatial text extraction——在保留每个文本项的坐标、尺寸、旋转角度与字体信息的基础上重建文档内容并可直接输出带标题、表格、列表、图片与链接的 Markdown。读完本文你将掌握 LiteParse 的库级接入方式、全部配置项语义、Markdown 渲染管线、OCR 引擎Tesseract / HTTP / 原生 ONNX OAR的接入与切换、文档复杂度预检以及litCLI 的完整命令用法。本文以 crates/liteparse/README.md 为主体并结合 config.rs、parser.rs、main.rs 等源码对每个关键点做实现级佐证。一、项目定位零云端依赖的本地文档解析器LiteParse 在仓库内以工作区 crate 形式组织核心实现位于 crates/liteparse/其 Cargo 描述为 Fast, lightweight PDF and document parsing with spatial text extraction见 Cargo.toml。几个关键设计事实完全本地运行解析过程不依赖任何云端服务所有文本提取、布局投影、OCR 都在本机完成空间信息保留文本项携带视口坐标top-left 原点、72 DPI、宽度、高度、旋转角度、字体名与字号等字段见 types.rs 中的TextItem多绑定生态核心库之外仓库还提供 Node.jspackages/node/、crates/liteparse-napi/、Pythonpackages/python/、crates/liteparse-python/与 WASMpackages/wasm/、crates/liteparse-wasm/等语言绑定本文聚焦 Rust 库与litCLI 本身。值得注意的并发模型见 parser.rsLiteParse是Send Sync的可安全跨线程共享但 PDFium 本身非线程安全所有 PDFium FFI 工作文档加载、页面渲染、文本提取都通过pdfium::Library持有的进程级全局锁串行化。OCR 与网格投影grid projection阶段在锁外执行因此对 OCR 密集文档可保持完全并发。二、安装与工程接入在Cargo.toml中添加依赖[dependencies] liteparse 2或者安装 CLI 二进制cargo install liteparse安装完成后会同时获得名为lit的 CLI 可执行文件该 bin 目标定义于 Cargo.toml。关于默认 feature 的说明默认 feature 为tesseract内置 Tesseract OCR 引擎。如果不需要 OCR、或打算改用 HTTP OCR 服务器可以用default-features false关闭详见下文Feature 矩阵。三、快速上手第一个解析程序LiteParse 的入口类型是LiteParse配合LiteParseConfig使用use liteparse::{LiteParse, LiteParseConfig}; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { let parser LiteParse::new(LiteParseConfig::default()); let result parser.parse(document.pdf).await?; println!({}, result.text); for page in result.pages { println!(Page {}: {} text items, page.page_num, page.text_items.len()); } Ok(()) }parse返回的ParseResult见 parser.rs包含字段含义total_pages源文档总页数应用target_pages/max_pages限制之前pages已完成投影布局的页面列表VecParsedPagepage_errors开启continue_on_page_error时收集的页面级提取失败text按页拼接的完整文档文本outline文档书签/大纲存在时未打标签的 PDF 上被 Markdown 渲染器用作高优先级标题来源images配置了extract_images时提取的位图带与 Markdown 引用一致的id/formatscreenshots配置了extract_screenshots时以 PNG 编码的页面截图doc_meta/xfa_packets/form_type等按需开启的文档级元数据、XFA 数据包与表单类型核心的parse/parse_input/is_complex方法均在 parser.rs 定义parse在非 WASM 平台可用WASM 下请使用parse_input传入字节。四、配置详解LiteParseConfig 全字段LiteParseConfig是解析行为的总开关。README 给出了最常用的一组配置use liteparse::{LiteParse, LiteParseConfig, OutputFormat}; let config LiteParseConfig { ocr_enabled: true, // Enable OCR (default: true) ocr_language: eng.to_string(), // Tesseract language code ocr_server_url: None, // HTTP OCR server URL (optional) tessdata_path: None, // Path to tessdata directory (optional) max_pages: 1000, // Max pages to parse target_pages: Some(1-5,10.into()), // Specific pages (optional) dpi: 150.0, // Rendering DPI output_format: OutputFormat::Json, // Json | Text | Markdown extract_annotations: false, // Include page annotations in output extract_structure_tree: false, // Include tagged-PDF logical structure preserve_very_small_text: false, // Keep tiny text extract_text_metadata: false, // Opt in to rich PDF text metadata password: None, // Password for protected documents quiet: false, // Suppress progress output ..Default::default() }; let parser LiteParse::new(config);上述字段的语义与默认值均可从 config.rs 的Default实现L216-L268核实这里结合源码补充几个关键细节ocr_enabled的默认值是条件编译的仅在编译了tesseractfeature 时才默认为truecfg!(feature tesseract)。未内置引擎的构建关闭tesseract或 WASM默认关闭 OCR避免OCR 已开启但无可用引擎的报错此时若显式设置ocr_enabled: true且提供了ocr_server_url仍可正常启用。ocr_languageTesseract 格式的语言代码如eng、fra、deu。注意对 OAR 引擎该字段不生效见自定义 OCR 引擎一节。target_pages支持1-5,10,15-20这样的范围语法。底层由parse_target_pages解析config.rs L293-L338会先对范围做展开前的上限校验MAX_TARGET_PAGES 100_000防止1-4294967295这类参数在展开时耗尽内存。num_workersOCR 并发 worker 数默认是CPU 核心数 − 1最少 1见 config.rs L271-L275。dpi渲染页面的分辨率同时影响 OCR 与截图。output_formatJson | Text | Markdown三选一序列化时小写json/text/markdown见 config.rs L198-L204。4.1 注解提取extract_annotations设置extract_annotations: true后ParsedPage::annotations会被填充包含注解子类型subtype、内容contents、作者/标题、PDF 日期字符串、视口空间矩形与 quadpoint 矩形、外部链接 URI。两点重要约束README 原文要点源码亦印证于 config.rs L66-L69它与extract_links相互独立——extract_links只控制 Markdown 链接渲染该字段在未开启时值为None。4.2 逻辑结构树提取extract_structure_tree设置extract_structure_tree: true后ParsedPage::structure_tree会被填充为完整的 tagged-PDF 层级结构全部根节点、元素类型/ID、实际文本与替代文本actual/alternate text、标题、类型化标量属性、MCID、递归子节点以及被引用的链接注解。未启用页为None启用的未打标签页面则没有根节点。4.3 其余值得关注的扩展配置除 README 示例外config.rs 还公开了更多按需开关均默认关闭以保持轻量输出extract_screenshots将每页渲染为 PNG 放入ParseResult.screenshots注意 PNG 载荷可能很大continue_on_page_error页面级 PDFium 提取失败时继续解析并在page_errors中上报文档打开级失败仍为致命错误extract_form_fields提取 AcroForm 控件字段与值同时会暴露ParseResult.form_typeextract_blocks输出每页已分类的布局块标题、段落、列表项、带单元格框的表格、代码、分隔线、图形带包围盒独立于output_formatJSON/Text 模式同样可用extract_content_bounds/extract_xfa_packets/extract_document_metadata分别输出页面内容范围、原始 XFA 数据包、文档级来源元数据日期、版本/安全信息、签名、增量保存标记、trailer ID、XMP、源文件大小crop_box按页面四边裁剪比例0~1限制输出区域OCR 合并后仍生效skip_diagonal_text丢弃偏离最近直角超过 2° 的倾斜文本ocr_failure_fatal系统级 OCR 全部失败时是否中止整个解析默认true便于暴露根因设false可保留已恢复的文本、返回降级结果ocr_hedge_delays_msHTTP OCR 引擎的请求对冲时间表毫秒例如[0, 5000, 10000, 15000, 20000]会在每个延迟点追加重复请求、取先成功者降低慢 pod 的尾延迟对 Tesseract 引擎无效keep_headers_footers默认情况下 Markdown 渲染会剥离跨页重复的页眉/页脚行与Page N of M之类的页面装饰置true则全部保留emit_word_boxes为每个TextItem输出词级子包围盒TextItem.words注意这会近似翻倍文本项载荷仅建议做词级 bbox 归属时开启extract_text_metadata为文本项附加丰富 PDF 文本元数据MCID、字形宽度、字体度量/字重/异常状态、填充/描边颜色、原始字符码、生成尾空格状态等对应 types.rs 的TextMetadata结构detect_screenshot_rects在渲染截图上检测实心矩形与粗线并附加到ScreenshotResult.rects基于光栅扫描页也适用但每页多一次全位图扫描render_form_fields将 AcroForm 域外观填充值、勾选状态绘制进渲染光栅会初始化 PDFium 表单环境并执行文档动作因此默认关闭include_complexity在parse过程中附带每页复杂度信号与is_complex相同的信号。五、Markdown 输出与图像处理LiteParse 可以直接把文档渲染成 Markdown包括从空间布局重建的标题、表格、列表、图片与链接。将output_format设为OutputFormat::Markdown后渲染结果位于result.textuse liteparse::config::{ImageMode, LiteParseConfig, OutputFormat}; let config LiteParseConfig { output_format: OutputFormat::Markdown, image_mode: ImageMode::Placeholder, extract_images: true, image_output_dir: Some(./images.into()), extract_links: true, ..Default::default() }; let result LiteParse::new(config).parse(document.pdf).await?; println!({}, result.text); // rendered MarkdownMarkdown 渲染由三个互相关联的旋钮控制配置项默认值作用image_modeImageMode::Placeholder位图在输出中的呈现方式Placeholder默认按阅读顺序在图片的 y 位置输出引用但不返回像素字节Off完全剥离图片引用Embed与Placeholder呈现一致同时把内嵌像素字节提取进ParseResult.images等价于设置extract_imagesextract_imagesfalse返回内嵌图片字节与元数据但不改变 Markdown 图片处理方式这是唯一真正开启提取的开关ImageMode::Embed为向后兼容也会启用见 config.rs L206-L214 的effective_extract_imagesimage_output_dirNone将提取的图片文件写入磁盘并返回其文件名/路径要求extract_images: true重复图片资源复用同一文件。若设置了目录但未开启提取validate_output_config会直接报配置错误parser.rs L316-L324extract_linkstrue将超链接注解渲染为text设false输出纯锚文本图片去重的实现细节值得说明write_extracted_imagesparser.rs L86-L116只写入每个资源的规范文件canonical file重复放置项保留各自name但path指向规范文件随后rewrite_duplicate_image_refsparser.rs L124-L160把 Markdown 中重复放置的图引用改写为规范文件名保证引用到的文件一定真实存在。另外Markdown 模式下渲染器默认会剥离跨页重复的页眉/页脚与页面装饰可通过keep_headers_footers: true保留。文档也明确提示重建质量随文档复杂度而变化reconstruction quality varies with document complexity复杂排版请结合下文复杂度预检评估。六、从字节解析与多格式输入除文件路径外LiteParse 支持直接传入内存字节适合网络响应、内存缓冲等场景use liteparse::types::PdfInput; let pdf_bytes: Vecu8 std::fs::read(document.pdf)?; let result parser.parse_input(PdfInput::Bytes(pdf_bytes)).await?; println!({}, result.text);PdfInput定义于 types.rs L5-L11Path(String)指向磁盘文件Bytes(Vecu8)持有内存字节。CLI 也支持-从 stdin 读取文档见 main.rs例如curl -sL … | lit parse -。支持的格式类别格式前置条件PDF.pdf无Microsoft Office.docx、.xlsx、.pptx等需要系统安装 LibreOfficeOpenDocument.odt、.ods、.odp需要系统安装 LibreOffice图片.png、.jpg、.tiff等无非 PDF 输入会先被转换为 PDF 再解析resolve_inputparser.rs L478-L490通过conversion::resolve_pdf_input完成转换并用PdfInputGuard保活转换产生的临时文件。这也是为什么extract_document_metadata对非 PDF 转换来源返回None——来源元数据描述的是中间 PDF 而非调用者原始文件见 parser.rs L517-L519。七、文档复杂度预检is_complex 与 ComplexityReason在决定投入完整解析之前先检查文档是否需要 OCR 或更重的处理可以大幅节省成本。is_complex是仅基于文本层的轻量通道为每页返回PageComplexityStats包含needs_ocr判定及其背后的信号适用于把文档路由到不同管线、拒绝无法处理的文档、估算处理成本。use liteparse::types::PdfInput; let parser LiteParse::new(LiteParseConfig::default()); let pages parser.is_complex(PdfInput::Path(document.pdf.into())).await?; if pages.iter().any(|p| p.needs_ocr) { // Route to the OCR-enabled pipeline, inspect p.reasons, etc. for page in pages.iter().filter(|p| p.needs_ocr) { println!(Page {} needs OCR: {:?}, page.page_number, page.reasons); } }reasons是VecComplexityReason可能的变体README 原文枚举定义于 ocr_merge.rs L64-L90Scanned—— 扫描页整页位图NoText—— 无文本SparseText—— 文本稀疏EmbeddedImages—— 内嵌图片Garbled—— 乱码文本VectorText—— 矢量文本未覆盖的矢量区域超阈值时触发AnnotationText—— 仅有注解文本用于与真正空白页区分文档明确提醒新变体可能随时间增加匹配时应宽容处理match leniently避免因枚举新增而编译失败。此外除 OCR 需求信号外每个统计项还携带layout信号多栏、带线表格、图形密集由真实的网格投影通道计算可用于把页面路由到更高精度的管线——即便该页并不需要 OCR。八、自定义 OCR 引擎OcrEngine trait 与 OAR 原生 ONNX 后端8.1 实现 OcrEngine trait 接入自有引擎LiteParse 的 OCR 层通过 trait 抽象可自由插拔后端use liteparse::ocr::OcrEngine; use std::sync::Arc; let parser LiteParse::new(LiteParseConfig::default()) .with_ocr_engine(Arc::new(my_engine));OcrEnginetrait定义于 ocr/mod.rs L40-L60要求实现三个成员name() - str引擎名称prefers_grayscale() - bool是否偏好单通道灰度缓冲内部二值化的引擎如 Tesseract 返回true按颜色训练的引擎需要 RGB渲染器据此决定输出灰度还是 RGB 缓冲见 parser.rs L573recognize(image_data, width, height, options) - FutureVecOcrResult对页面位图执行识别返回词级结果文本、像素坐标包围盒[x1,y1,x2,y2]、0.0~1.0 置信度以及可选的旋转检测四点多边形供投影器恢复旋转文本方向见 ocr/mod.rs L11-L24。with_ocr_engine设置后该引擎会覆盖内置选择逻辑HTTP OCR / Tesseract也是无内置引擎环境如 WASM 由 JS 侧提供回调引擎接入 OCR 的主要机制parser.rs L287-L292。引擎选择逻辑见 parser.rs L531-L572优先使用覆盖引擎否则按ocr_server_url是否为Some选择HttpOcrEngine或 Tesseract。8.2 原生 ONNX 后端oar-ocr如需原生 ONNX 后端启用oar-ocrfeature 并提供检测模型、识别模型与匹配的字符字典use liteparse::ocr::oar::OarOcrEngine; use liteparse::{LiteParse, LiteParseConfig}; use std::path::Path; use std::sync::Arc; let models Path::new(models); let engine OarOcrEngine::from_models( models.join(pp-ocrv6_small_det.onnx), models.join(pp-ocrv6_small_rec.onnx), models.join(ppocrv6_dict.txt), )?; let parser LiteParse::new(LiteParseConfig::default()) .with_ocr_engine(Arc::new(engine)); # Ok::(), Boxdyn std::error::Error(())8.3 自动下载预设模型启用oar-ocr-auto-downloadfeature 后可使用预设。首次使用时oar-ocr会从 ModelScope 下载检测模型、识别模型与匹配字典校验其 SHA-256 摘要并缓存到$OAR_HOME默认~/.oaruse liteparse::ocr::oar::OarOcrEngine; // Smallest / fastest PP-OCRv6 configuration. let engine OarOcrEngine::ppocr_v6_tiny()?; # Ok::(), Boxdyn std::error::Error(())预设覆盖当前与上一代 PP-OCR从最快到最准依次为ppocr_v6_tiny、ppocr_v6_small、ppocr_v6_medium源码中三个预设构造器见 ocr/oar.rs L136-L166每个预设都接好正确的检测器/识别器/字典三件套。对于 PP-OCRv4、语言专用识别器或自定义组合请用from_models配合匹配的字典。8.4 混搭模型与字典匹配的坑要自己混搭检测器、识别器与字典可把已注册的裸文件名传给from_models。必须让识别器与匹配的字典成对出现——tiny 识别器需要ppocrv6_tiny_dict.txt而更大的模型使用ppocrv6_dict.txt字典不匹配会静默产生乱码文本不会报错use liteparse::ocr::oar::OarOcrEngine; let engine OarOcrEngine::from_models( pp-ocrv6_small_det.onnx, pp-ocrv6_small_rec.onnx, ppocrv6_dict.txt, )?; # Ok::(), Boxdyn std::error::Error(())8.5 内存模型、构建器与内存控制三个产物检测/识别模型、字典都接受内存字节因此整个管线可以用include_bytes!嵌入二进制而不是以文件形式分发。更精细的场景使用OAROCRBuilder配合OarOcrEngine::from_builderocr/oar.rs L88-L130 也推荐该构造器可配置模型专属设置或可选的朝向orientation与矫正rectification模型。所有可失败构造器返回liteparse::LiteParseError。实现细节所有构造器使用保守的批大小并将页面推理串行化以避免并发调度页面时成倍放大推理内存占用。另外注意OcrOptions::language对 OAR 引擎不生效——支持的语言由识别模型与字符字典决定若此时仍配置了ocr_language会触发一次性告警以显式说明该事实。九、Feature 矩阵LiteParse 通过 Cargo features 控制 OCR 后端与推理加速能力定义于 Cargo.toml L17-L27Feature默认说明tesseract✅ 默认通过tesseract-rs内置 Tesseract OCR不需要 OCR 或改用 HTTP OCR 服务器时可用default-features false关闭oar-ocr❌通过oar-ocr提供原生 ONNX 后端支持本地或内存模型仅限非 WASM 的 Rust APIoar-ocr-auto-download❌通过oar-ocr启用已注册模型文件名的 SHA-256 校验下载与缓存oar-ocr-cuda/oar-ocr-tensorrt/oar-ocr-directml/oar-ocr-coreml/oar-ocr-webgpu/oar-ocr-openvino❌把选中的 ONNX Runtime 执行提供方execution provider转发给oar-ocr重要事实Node.js、Python 与 WASM 绑定都以default-features false构建且不暴露上述 OAR features因此它们的发布二进制不会继承 OAR 模型或运行时依赖体积。十、命令行工具 lit 实战lit是该 crate 构建的 CLI 二进制定义于 Cargo.toml子命令在 main.rs L23-L38 定义。README 给出的核心用法lit parse document.pdf lit parse document.pdf --format json -o output.json lit parse document.pdf --format markdown -o output.md lit screenshot document.pdf -o ./screenshots lit batch-parse ./input ./output lit is-complex document.pdf其余选项见lit --help。结合 main.rs 的实现各子命令的常用参数如下10.1 lit parselit parse file [选项]-o, --output path输出文件路径缺省打印到 stdout--format json|text|markdown输出格式默认text可简写md见parse_output_formatmain.rs L341-L351--no-ocr禁用 OCR--ocr-language codeOCR 语言Tesseract 格式默认eng--ocr-server-url urlHTTP OCR 服务器地址不提供则用 Tesseract--ocr-server-header Name: Value可重复的 OCR 服务器请求头如--ocr-server-header Authorization: Bearer token解析逻辑见 main.rs L370-L379--tessdata-path dirtessdata 目录覆盖TESSDATA_PREFIX环境变量--max-pages n最大解析页数默认 1000--target-pages range目标页如1-5,10,15-20--dpi f渲染 DPI默认 150--image-mode off|placeholder|embedMarkdown 图片呈现方式默认placeholder--extract-images提取内嵌图片字节与元数据--image-output-dir dir图片写出目录需配合--extract-images--no-links禁用超链接提取Markdown 中输出纯锚文本例如对齐无链接语法的纯文本基准--keep-headers-footers在 Markdown 中保留页眉/页脚--extract-annotations/--extract-form-fields/--extract-structure-tree/--extract-blocks/--extract-xfa-packets/--extract-content-bounds各类结构化数据提取开关--complexity在 JSON 每页附带complexity对象与is-complex同一信号--extract-text-metadata在文本项与 JSON 输出中附带富文本元数据--extract-vector-graphics输出页面级矢量形状与合并后的横/竖线--continue-on-page-error页面级提取失败时继续并写入 JSON 的page_errors--preserve-small-text保留极小文本--password pwd受保护文档密码-q, --quiet抑制进度输出--num-workers nOCR 并发数默认 CPU 核心 − 1。输入路径为-时从 stdin 读取文档字节main.rs L456-L460。输出 JSON 的序列化在json::format_json_result中完成。10.2 lit screenshotlit screenshot file -o ./screenshots [选项]将页面渲染为 PNG 写入输出目录命名形如page_N.pngmain.rs L503-L513。支持--target-pages如1,3,5或1-5默认全部页、--dpi默认 150、--password、-q/--quiet。10.3 lit batch-parselit batch-parse input_dir output_dir [选项]批量解析目录中的文档输出目录镜像输入目录的相对结构batch_output_path保留嵌套路径见 main.rs L729-L743按输出格式生成.json/.md/.txt文件。除与parse相同的格式与提取选项外还支持--recursive递归搜索输入目录--extension ext只处理指定扩展名如.pdf自动补点结束时报出 batch complete: N succeeded, M failed 汇总任一失败则退出码为 1main.rs L630-L637。10.4 lit is-complexlit is-complex file [选项]输出每页复杂度统计的 JSON可直接配合jq并支持--compact输出无空白 JSON。human-readable 判定写到 stderr退出码本身也是信号任一页需要 OCR 时退出码为 1因此可作为 shell 谓词——lit is-complex doc.pdf lit parse --no-ocr doc.pdf这类简单文档跳过 OCR的流水线是安全可行的main.rs L679-L711。十一、仓库内部如何继续深挖布局与 Markdown 渲染管线markdown_layout/模块crates/liteparse/src/markdown_layout/实现块分类、标题/列表/表格/水平线/跨区域结构识别apply_layout的一次分类、多消费者共享设计见 parser.rs L241-L276网格投影projection.rscrates/liteparse/src/projection.rs负责把文本项投影到网格恢复阅读顺序OCR 合并与复杂度ocr_merge.rscrates/liteparse/src/ocr_merge.rs实现PageComplexityStats与calculate_page_complexityOCR 引擎实现ocr/tesseract.rs、ocr/http_simple.rs、ocr/oar.rscrates/liteparse/src/ocr/集成测试crates/liteparse/tests/integration_test.rs 覆盖端到端解析行为。十二、许可证Apache-2.0。仓库根目录的 LICENSE 为完整许可证文本。提示本文基于当前仓库liteparsecrate 版本 2.14.4编写所有配置项、CLI 参数与 feature 均以仓库实际实现为准使用其他版本时请以对应版本的文档与lit --help输出为准。【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LiteParse 完全指南：Rust 空间感知文档解析库与 lit CLI 实战
LiteParse 完全指南Rust 空间感知文档解析库与 lit CLI 实战【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparse导读LiteParse 是当前仓库的核心 Rust 库与 CLI 工具主打快速、轻量、完全本地运行的 PDF 与多格式文档解析核心能力是空间文本提取spatial text extraction——在保留每个文本项的坐标、尺寸、旋转角度与字体信息的基础上重建文档内容并可直接输出带标题、表格、列表、图片与链接的 Markdown。读完本文你将掌握 LiteParse 的库级接入方式、全部配置项语义、Markdown 渲染管线、OCR 引擎Tesseract / HTTP / 原生 ONNX OAR的接入与切换、文档复杂度预检以及litCLI 的完整命令用法。本文以 crates/liteparse/README.md 为主体并结合 config.rs、parser.rs、main.rs 等源码对每个关键点做实现级佐证。一、项目定位零云端依赖的本地文档解析器LiteParse 在仓库内以工作区 crate 形式组织核心实现位于 crates/liteparse/其 Cargo 描述为 Fast, lightweight PDF and document parsing with spatial text extraction见 Cargo.toml。几个关键设计事实完全本地运行解析过程不依赖任何云端服务所有文本提取、布局投影、OCR 都在本机完成空间信息保留文本项携带视口坐标top-left 原点、72 DPI、宽度、高度、旋转角度、字体名与字号等字段见 types.rs 中的TextItem多绑定生态核心库之外仓库还提供 Node.jspackages/node/、crates/liteparse-napi/、Pythonpackages/python/、crates/liteparse-python/与 WASMpackages/wasm/、crates/liteparse-wasm/等语言绑定本文聚焦 Rust 库与litCLI 本身。值得注意的并发模型见 parser.rsLiteParse是Send Sync的可安全跨线程共享但 PDFium 本身非线程安全所有 PDFium FFI 工作文档加载、页面渲染、文本提取都通过pdfium::Library持有的进程级全局锁串行化。OCR 与网格投影grid projection阶段在锁外执行因此对 OCR 密集文档可保持完全并发。二、安装与工程接入在Cargo.toml中添加依赖[dependencies] liteparse 2或者安装 CLI 二进制cargo install liteparse安装完成后会同时获得名为lit的 CLI 可执行文件该 bin 目标定义于 Cargo.toml。关于默认 feature 的说明默认 feature 为tesseract内置 Tesseract OCR 引擎。如果不需要 OCR、或打算改用 HTTP OCR 服务器可以用default-features false关闭详见下文Feature 矩阵。三、快速上手第一个解析程序LiteParse 的入口类型是LiteParse配合LiteParseConfig使用use liteparse::{LiteParse, LiteParseConfig}; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { let parser LiteParse::new(LiteParseConfig::default()); let result parser.parse(document.pdf).await?; println!({}, result.text); for page in result.pages { println!(Page {}: {} text items, page.page_num, page.text_items.len()); } Ok(()) }parse返回的ParseResult见 parser.rs包含字段含义total_pages源文档总页数应用target_pages/max_pages限制之前pages已完成投影布局的页面列表VecParsedPagepage_errors开启continue_on_page_error时收集的页面级提取失败text按页拼接的完整文档文本outline文档书签/大纲存在时未打标签的 PDF 上被 Markdown 渲染器用作高优先级标题来源images配置了extract_images时提取的位图带与 Markdown 引用一致的id/formatscreenshots配置了extract_screenshots时以 PNG 编码的页面截图doc_meta/xfa_packets/form_type等按需开启的文档级元数据、XFA 数据包与表单类型核心的parse/parse_input/is_complex方法均在 parser.rs 定义parse在非 WASM 平台可用WASM 下请使用parse_input传入字节。四、配置详解LiteParseConfig 全字段LiteParseConfig是解析行为的总开关。README 给出了最常用的一组配置use liteparse::{LiteParse, LiteParseConfig, OutputFormat}; let config LiteParseConfig { ocr_enabled: true, // Enable OCR (default: true) ocr_language: eng.to_string(), // Tesseract language code ocr_server_url: None, // HTTP OCR server URL (optional) tessdata_path: None, // Path to tessdata directory (optional) max_pages: 1000, // Max pages to parse target_pages: Some(1-5,10.into()), // Specific pages (optional) dpi: 150.0, // Rendering DPI output_format: OutputFormat::Json, // Json | Text | Markdown extract_annotations: false, // Include page annotations in output extract_structure_tree: false, // Include tagged-PDF logical structure preserve_very_small_text: false, // Keep tiny text extract_text_metadata: false, // Opt in to rich PDF text metadata password: None, // Password for protected documents quiet: false, // Suppress progress output ..Default::default() }; let parser LiteParse::new(config);上述字段的语义与默认值均可从 config.rs 的Default实现L216-L268核实这里结合源码补充几个关键细节ocr_enabled的默认值是条件编译的仅在编译了tesseractfeature 时才默认为truecfg!(feature tesseract)。未内置引擎的构建关闭tesseract或 WASM默认关闭 OCR避免OCR 已开启但无可用引擎的报错此时若显式设置ocr_enabled: true且提供了ocr_server_url仍可正常启用。ocr_languageTesseract 格式的语言代码如eng、fra、deu。注意对 OAR 引擎该字段不生效见自定义 OCR 引擎一节。target_pages支持1-5,10,15-20这样的范围语法。底层由parse_target_pages解析config.rs L293-L338会先对范围做展开前的上限校验MAX_TARGET_PAGES 100_000防止1-4294967295这类参数在展开时耗尽内存。num_workersOCR 并发 worker 数默认是CPU 核心数 − 1最少 1见 config.rs L271-L275。dpi渲染页面的分辨率同时影响 OCR 与截图。output_formatJson | Text | Markdown三选一序列化时小写json/text/markdown见 config.rs L198-L204。4.1 注解提取extract_annotations设置extract_annotations: true后ParsedPage::annotations会被填充包含注解子类型subtype、内容contents、作者/标题、PDF 日期字符串、视口空间矩形与 quadpoint 矩形、外部链接 URI。两点重要约束README 原文要点源码亦印证于 config.rs L66-L69它与extract_links相互独立——extract_links只控制 Markdown 链接渲染该字段在未开启时值为None。4.2 逻辑结构树提取extract_structure_tree设置extract_structure_tree: true后ParsedPage::structure_tree会被填充为完整的 tagged-PDF 层级结构全部根节点、元素类型/ID、实际文本与替代文本actual/alternate text、标题、类型化标量属性、MCID、递归子节点以及被引用的链接注解。未启用页为None启用的未打标签页面则没有根节点。4.3 其余值得关注的扩展配置除 README 示例外config.rs 还公开了更多按需开关均默认关闭以保持轻量输出extract_screenshots将每页渲染为 PNG 放入ParseResult.screenshots注意 PNG 载荷可能很大continue_on_page_error页面级 PDFium 提取失败时继续解析并在page_errors中上报文档打开级失败仍为致命错误extract_form_fields提取 AcroForm 控件字段与值同时会暴露ParseResult.form_typeextract_blocks输出每页已分类的布局块标题、段落、列表项、带单元格框的表格、代码、分隔线、图形带包围盒独立于output_formatJSON/Text 模式同样可用extract_content_bounds/extract_xfa_packets/extract_document_metadata分别输出页面内容范围、原始 XFA 数据包、文档级来源元数据日期、版本/安全信息、签名、增量保存标记、trailer ID、XMP、源文件大小crop_box按页面四边裁剪比例0~1限制输出区域OCR 合并后仍生效skip_diagonal_text丢弃偏离最近直角超过 2° 的倾斜文本ocr_failure_fatal系统级 OCR 全部失败时是否中止整个解析默认true便于暴露根因设false可保留已恢复的文本、返回降级结果ocr_hedge_delays_msHTTP OCR 引擎的请求对冲时间表毫秒例如[0, 5000, 10000, 15000, 20000]会在每个延迟点追加重复请求、取先成功者降低慢 pod 的尾延迟对 Tesseract 引擎无效keep_headers_footers默认情况下 Markdown 渲染会剥离跨页重复的页眉/页脚行与Page N of M之类的页面装饰置true则全部保留emit_word_boxes为每个TextItem输出词级子包围盒TextItem.words注意这会近似翻倍文本项载荷仅建议做词级 bbox 归属时开启extract_text_metadata为文本项附加丰富 PDF 文本元数据MCID、字形宽度、字体度量/字重/异常状态、填充/描边颜色、原始字符码、生成尾空格状态等对应 types.rs 的TextMetadata结构detect_screenshot_rects在渲染截图上检测实心矩形与粗线并附加到ScreenshotResult.rects基于光栅扫描页也适用但每页多一次全位图扫描render_form_fields将 AcroForm 域外观填充值、勾选状态绘制进渲染光栅会初始化 PDFium 表单环境并执行文档动作因此默认关闭include_complexity在parse过程中附带每页复杂度信号与is_complex相同的信号。五、Markdown 输出与图像处理LiteParse 可以直接把文档渲染成 Markdown包括从空间布局重建的标题、表格、列表、图片与链接。将output_format设为OutputFormat::Markdown后渲染结果位于result.textuse liteparse::config::{ImageMode, LiteParseConfig, OutputFormat}; let config LiteParseConfig { output_format: OutputFormat::Markdown, image_mode: ImageMode::Placeholder, extract_images: true, image_output_dir: Some(./images.into()), extract_links: true, ..Default::default() }; let result LiteParse::new(config).parse(document.pdf).await?; println!({}, result.text); // rendered MarkdownMarkdown 渲染由三个互相关联的旋钮控制配置项默认值作用image_modeImageMode::Placeholder位图在输出中的呈现方式Placeholder默认按阅读顺序在图片的 y 位置输出引用但不返回像素字节Off完全剥离图片引用Embed与Placeholder呈现一致同时把内嵌像素字节提取进ParseResult.images等价于设置extract_imagesextract_imagesfalse返回内嵌图片字节与元数据但不改变 Markdown 图片处理方式这是唯一真正开启提取的开关ImageMode::Embed为向后兼容也会启用见 config.rs L206-L214 的effective_extract_imagesimage_output_dirNone将提取的图片文件写入磁盘并返回其文件名/路径要求extract_images: true重复图片资源复用同一文件。若设置了目录但未开启提取validate_output_config会直接报配置错误parser.rs L316-L324extract_linkstrue将超链接注解渲染为text设false输出纯锚文本图片去重的实现细节值得说明write_extracted_imagesparser.rs L86-L116只写入每个资源的规范文件canonical file重复放置项保留各自name但path指向规范文件随后rewrite_duplicate_image_refsparser.rs L124-L160把 Markdown 中重复放置的图引用改写为规范文件名保证引用到的文件一定真实存在。另外Markdown 模式下渲染器默认会剥离跨页重复的页眉/页脚与页面装饰可通过keep_headers_footers: true保留。文档也明确提示重建质量随文档复杂度而变化reconstruction quality varies with document complexity复杂排版请结合下文复杂度预检评估。六、从字节解析与多格式输入除文件路径外LiteParse 支持直接传入内存字节适合网络响应、内存缓冲等场景use liteparse::types::PdfInput; let pdf_bytes: Vecu8 std::fs::read(document.pdf)?; let result parser.parse_input(PdfInput::Bytes(pdf_bytes)).await?; println!({}, result.text);PdfInput定义于 types.rs L5-L11Path(String)指向磁盘文件Bytes(Vecu8)持有内存字节。CLI 也支持-从 stdin 读取文档见 main.rs例如curl -sL … | lit parse -。支持的格式类别格式前置条件PDF.pdf无Microsoft Office.docx、.xlsx、.pptx等需要系统安装 LibreOfficeOpenDocument.odt、.ods、.odp需要系统安装 LibreOffice图片.png、.jpg、.tiff等无非 PDF 输入会先被转换为 PDF 再解析resolve_inputparser.rs L478-L490通过conversion::resolve_pdf_input完成转换并用PdfInputGuard保活转换产生的临时文件。这也是为什么extract_document_metadata对非 PDF 转换来源返回None——来源元数据描述的是中间 PDF 而非调用者原始文件见 parser.rs L517-L519。七、文档复杂度预检is_complex 与 ComplexityReason在决定投入完整解析之前先检查文档是否需要 OCR 或更重的处理可以大幅节省成本。is_complex是仅基于文本层的轻量通道为每页返回PageComplexityStats包含needs_ocr判定及其背后的信号适用于把文档路由到不同管线、拒绝无法处理的文档、估算处理成本。use liteparse::types::PdfInput; let parser LiteParse::new(LiteParseConfig::default()); let pages parser.is_complex(PdfInput::Path(document.pdf.into())).await?; if pages.iter().any(|p| p.needs_ocr) { // Route to the OCR-enabled pipeline, inspect p.reasons, etc. for page in pages.iter().filter(|p| p.needs_ocr) { println!(Page {} needs OCR: {:?}, page.page_number, page.reasons); } }reasons是VecComplexityReason可能的变体README 原文枚举定义于 ocr_merge.rs L64-L90Scanned—— 扫描页整页位图NoText—— 无文本SparseText—— 文本稀疏EmbeddedImages—— 内嵌图片Garbled—— 乱码文本VectorText—— 矢量文本未覆盖的矢量区域超阈值时触发AnnotationText—— 仅有注解文本用于与真正空白页区分文档明确提醒新变体可能随时间增加匹配时应宽容处理match leniently避免因枚举新增而编译失败。此外除 OCR 需求信号外每个统计项还携带layout信号多栏、带线表格、图形密集由真实的网格投影通道计算可用于把页面路由到更高精度的管线——即便该页并不需要 OCR。八、自定义 OCR 引擎OcrEngine trait 与 OAR 原生 ONNX 后端8.1 实现 OcrEngine trait 接入自有引擎LiteParse 的 OCR 层通过 trait 抽象可自由插拔后端use liteparse::ocr::OcrEngine; use std::sync::Arc; let parser LiteParse::new(LiteParseConfig::default()) .with_ocr_engine(Arc::new(my_engine));OcrEnginetrait定义于 ocr/mod.rs L40-L60要求实现三个成员name() - str引擎名称prefers_grayscale() - bool是否偏好单通道灰度缓冲内部二值化的引擎如 Tesseract 返回true按颜色训练的引擎需要 RGB渲染器据此决定输出灰度还是 RGB 缓冲见 parser.rs L573recognize(image_data, width, height, options) - FutureVecOcrResult对页面位图执行识别返回词级结果文本、像素坐标包围盒[x1,y1,x2,y2]、0.0~1.0 置信度以及可选的旋转检测四点多边形供投影器恢复旋转文本方向见 ocr/mod.rs L11-L24。with_ocr_engine设置后该引擎会覆盖内置选择逻辑HTTP OCR / Tesseract也是无内置引擎环境如 WASM 由 JS 侧提供回调引擎接入 OCR 的主要机制parser.rs L287-L292。引擎选择逻辑见 parser.rs L531-L572优先使用覆盖引擎否则按ocr_server_url是否为Some选择HttpOcrEngine或 Tesseract。8.2 原生 ONNX 后端oar-ocr如需原生 ONNX 后端启用oar-ocrfeature 并提供检测模型、识别模型与匹配的字符字典use liteparse::ocr::oar::OarOcrEngine; use liteparse::{LiteParse, LiteParseConfig}; use std::path::Path; use std::sync::Arc; let models Path::new(models); let engine OarOcrEngine::from_models( models.join(pp-ocrv6_small_det.onnx), models.join(pp-ocrv6_small_rec.onnx), models.join(ppocrv6_dict.txt), )?; let parser LiteParse::new(LiteParseConfig::default()) .with_ocr_engine(Arc::new(engine)); # Ok::(), Boxdyn std::error::Error(())8.3 自动下载预设模型启用oar-ocr-auto-downloadfeature 后可使用预设。首次使用时oar-ocr会从 ModelScope 下载检测模型、识别模型与匹配字典校验其 SHA-256 摘要并缓存到$OAR_HOME默认~/.oaruse liteparse::ocr::oar::OarOcrEngine; // Smallest / fastest PP-OCRv6 configuration. let engine OarOcrEngine::ppocr_v6_tiny()?; # Ok::(), Boxdyn std::error::Error(())预设覆盖当前与上一代 PP-OCR从最快到最准依次为ppocr_v6_tiny、ppocr_v6_small、ppocr_v6_medium源码中三个预设构造器见 ocr/oar.rs L136-L166每个预设都接好正确的检测器/识别器/字典三件套。对于 PP-OCRv4、语言专用识别器或自定义组合请用from_models配合匹配的字典。8.4 混搭模型与字典匹配的坑要自己混搭检测器、识别器与字典可把已注册的裸文件名传给from_models。必须让识别器与匹配的字典成对出现——tiny 识别器需要ppocrv6_tiny_dict.txt而更大的模型使用ppocrv6_dict.txt字典不匹配会静默产生乱码文本不会报错use liteparse::ocr::oar::OarOcrEngine; let engine OarOcrEngine::from_models( pp-ocrv6_small_det.onnx, pp-ocrv6_small_rec.onnx, ppocrv6_dict.txt, )?; # Ok::(), Boxdyn std::error::Error(())8.5 内存模型、构建器与内存控制三个产物检测/识别模型、字典都接受内存字节因此整个管线可以用include_bytes!嵌入二进制而不是以文件形式分发。更精细的场景使用OAROCRBuilder配合OarOcrEngine::from_builderocr/oar.rs L88-L130 也推荐该构造器可配置模型专属设置或可选的朝向orientation与矫正rectification模型。所有可失败构造器返回liteparse::LiteParseError。实现细节所有构造器使用保守的批大小并将页面推理串行化以避免并发调度页面时成倍放大推理内存占用。另外注意OcrOptions::language对 OAR 引擎不生效——支持的语言由识别模型与字符字典决定若此时仍配置了ocr_language会触发一次性告警以显式说明该事实。九、Feature 矩阵LiteParse 通过 Cargo features 控制 OCR 后端与推理加速能力定义于 Cargo.toml L17-L27Feature默认说明tesseract✅ 默认通过tesseract-rs内置 Tesseract OCR不需要 OCR 或改用 HTTP OCR 服务器时可用default-features false关闭oar-ocr❌通过oar-ocr提供原生 ONNX 后端支持本地或内存模型仅限非 WASM 的 Rust APIoar-ocr-auto-download❌通过oar-ocr启用已注册模型文件名的 SHA-256 校验下载与缓存oar-ocr-cuda/oar-ocr-tensorrt/oar-ocr-directml/oar-ocr-coreml/oar-ocr-webgpu/oar-ocr-openvino❌把选中的 ONNX Runtime 执行提供方execution provider转发给oar-ocr重要事实Node.js、Python 与 WASM 绑定都以default-features false构建且不暴露上述 OAR features因此它们的发布二进制不会继承 OAR 模型或运行时依赖体积。十、命令行工具 lit 实战lit是该 crate 构建的 CLI 二进制定义于 Cargo.toml子命令在 main.rs L23-L38 定义。README 给出的核心用法lit parse document.pdf lit parse document.pdf --format json -o output.json lit parse document.pdf --format markdown -o output.md lit screenshot document.pdf -o ./screenshots lit batch-parse ./input ./output lit is-complex document.pdf其余选项见lit --help。结合 main.rs 的实现各子命令的常用参数如下10.1 lit parselit parse file [选项]-o, --output path输出文件路径缺省打印到 stdout--format json|text|markdown输出格式默认text可简写md见parse_output_formatmain.rs L341-L351--no-ocr禁用 OCR--ocr-language codeOCR 语言Tesseract 格式默认eng--ocr-server-url urlHTTP OCR 服务器地址不提供则用 Tesseract--ocr-server-header Name: Value可重复的 OCR 服务器请求头如--ocr-server-header Authorization: Bearer token解析逻辑见 main.rs L370-L379--tessdata-path dirtessdata 目录覆盖TESSDATA_PREFIX环境变量--max-pages n最大解析页数默认 1000--target-pages range目标页如1-5,10,15-20--dpi f渲染 DPI默认 150--image-mode off|placeholder|embedMarkdown 图片呈现方式默认placeholder--extract-images提取内嵌图片字节与元数据--image-output-dir dir图片写出目录需配合--extract-images--no-links禁用超链接提取Markdown 中输出纯锚文本例如对齐无链接语法的纯文本基准--keep-headers-footers在 Markdown 中保留页眉/页脚--extract-annotations/--extract-form-fields/--extract-structure-tree/--extract-blocks/--extract-xfa-packets/--extract-content-bounds各类结构化数据提取开关--complexity在 JSON 每页附带complexity对象与is-complex同一信号--extract-text-metadata在文本项与 JSON 输出中附带富文本元数据--extract-vector-graphics输出页面级矢量形状与合并后的横/竖线--continue-on-page-error页面级提取失败时继续并写入 JSON 的page_errors--preserve-small-text保留极小文本--password pwd受保护文档密码-q, --quiet抑制进度输出--num-workers nOCR 并发数默认 CPU 核心 − 1。输入路径为-时从 stdin 读取文档字节main.rs L456-L460。输出 JSON 的序列化在json::format_json_result中完成。10.2 lit screenshotlit screenshot file -o ./screenshots [选项]将页面渲染为 PNG 写入输出目录命名形如page_N.pngmain.rs L503-L513。支持--target-pages如1,3,5或1-5默认全部页、--dpi默认 150、--password、-q/--quiet。10.3 lit batch-parselit batch-parse input_dir output_dir [选项]批量解析目录中的文档输出目录镜像输入目录的相对结构batch_output_path保留嵌套路径见 main.rs L729-L743按输出格式生成.json/.md/.txt文件。除与parse相同的格式与提取选项外还支持--recursive递归搜索输入目录--extension ext只处理指定扩展名如.pdf自动补点结束时报出 batch complete: N succeeded, M failed 汇总任一失败则退出码为 1main.rs L630-L637。10.4 lit is-complexlit is-complex file [选项]输出每页复杂度统计的 JSON可直接配合jq并支持--compact输出无空白 JSON。human-readable 判定写到 stderr退出码本身也是信号任一页需要 OCR 时退出码为 1因此可作为 shell 谓词——lit is-complex doc.pdf lit parse --no-ocr doc.pdf这类简单文档跳过 OCR的流水线是安全可行的main.rs L679-L711。十一、仓库内部如何继续深挖布局与 Markdown 渲染管线markdown_layout/模块crates/liteparse/src/markdown_layout/实现块分类、标题/列表/表格/水平线/跨区域结构识别apply_layout的一次分类、多消费者共享设计见 parser.rs L241-L276网格投影projection.rscrates/liteparse/src/projection.rs负责把文本项投影到网格恢复阅读顺序OCR 合并与复杂度ocr_merge.rscrates/liteparse/src/ocr_merge.rs实现PageComplexityStats与calculate_page_complexityOCR 引擎实现ocr/tesseract.rs、ocr/http_simple.rs、ocr/oar.rscrates/liteparse/src/ocr/集成测试crates/liteparse/tests/integration_test.rs 覆盖端到端解析行为。十二、许可证Apache-2.0。仓库根目录的 LICENSE 为完整许可证文本。提示本文基于当前仓库liteparsecrate 版本 2.14.4编写所有配置项、CLI 参数与 feature 均以仓库实际实现为准使用其他版本时请以对应版本的文档与lit --help输出为准。【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考