ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Docling 基础使用实战:DocumentConverter 与 CLI 文档转换全流程

Docling 基础使用实战:DocumentConverter 与 CLI 文档转换全流程 Docling 基础使用实战DocumentConverter 与 CLI 文档转换全流程【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文基于 Docling 官方文档 Usage 入门指南 展开完整覆盖其两条核心使用路径通过 Python APIDocumentConverter将任意受支持格式的文件或 URL、内存流转换为统一的 Docling Document 并导出 Markdown/JSON 等格式以及通过终端 CLI 一行命令完成本地转换与 VLM 流水线转换。读完后你将掌握 Docling 的格式-后端-流水线映射机制、转换控制参数页数/大小/页范围/错误策略以及 CLI 的关键选项能够独立完成从“拿到一份 PDF”到“产出可入 RAG 语料的 Markdown/JSON/Chunks”的完整链路。两条核心使用路径Docling 官方文档将使用方式归纳为两步把源文件转换convert为一个 Docling Document用这个 Docling Document 驱动你的后续工作流导出、分块、序列化等。对应地Docling 提供两种等价入口Python API核心类是 DocumentConverter通过convert()拿到ConversionResult其.document属性即统一的文档模型CLIdocling命令Typer 应用定义于 docling/cli/main.py适合脚本化、批处理和快速验证场景。Python APIDocumentConverter 最小示例官方入门片段与 docs/examples/minimal.py 完全一致from docling.document_converter import DocumentConverter source report.pdf # 文件路径或 URL官方示例使用 arXiv 论文 PDF converter DocumentConverter() doc converter.convert(source).document print(doc.export_to_markdown()) # 输出: ### Docling Technical Report[...]要点DocumentConverter()默认接受全部受支持的输入格式格式到后端/流水线的映射在内部自动完成convert()的source可以是本地路径、Path、URL或DocumentStream内存字节流适合 Web 应用场景返回的ConversionResult除document外还携带status成功/部分成功/失败/跳过与errors列表便于做批量作业的失败分类。格式 → 后端 → 流水线的默认映射document_converter.py 中的_get_default_option()定义了每种InputFormat的默认FormatOption从源码结构看映射遵循清晰的分层输入类型默认流水线默认后端源码依据PDFStandardPdfPipeline布局检测 OCR 表格结构ThreadedDoclingParseDocumentBackendPdfFormatOption图片PNG/JPEG/TIFF 等StandardPdfPipelineImageDocumentBackendImageFormatOptionDOCX/XLSX/PPTX、MD、HTML、LaTeX、EPUB、CSV 等结构化格式SimplePipeline无页面布局分析直接解析结构各格式专用 BackendWordFormatOption 等音频WAV/MP3 等AsrPipelineNoOpBackendAudioFormatOption视频MP4/AVI/MOVVideoPipelineNoOpBackendVideoFormatOption已序列化的 Docling JSONSimplePipelineDoclingJSONBackend映射表这套默认映射是可参数化的构造DocumentConverter时可通过allowed_formats限定接受哪些格式、通过format_options覆盖某个格式的后端与流水线选项。例如 docs/usage/advanced_options.md 展示了离线模型部署的写法from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.document_converter import DocumentConverter, PdfFormatOption artifacts_path /local/path/to/models pipeline_options PdfPipelineOptions(artifacts_pathartifacts_path) converter DocumentConverter( format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) } )此外DocumentConverter内部以(流水线类, 选项哈希)为键缓存已初始化的流水线实例见 初始化缓存哈希由 create_pipeline_options_hash 生成因此批量转换同一格式文档时不会重复加载模型。批量转换与转换控制参数convert()实际上是convert_all()的单体封装convert 实现两者共享同一组控制参数均来自 docstring 声明参数默认值说明source必填路径/URL/DocumentStream/HttpSource的列表convert_all或单个convertheadersNoneURL 拉取时的 HTTP 请求头字典raises_on_errorTrueTrue时首个失败直接抛ConversionErrorFalse时错误捕获进ConversionResult供逐文档处理max_num_pages不限单文档接受的最大页数超限文档不转换max_file_size不限单文件大小上限字节page_range全部页只转换指定页范围PDF 等页面型文档批量示例对应convert_all的官方 docstringfrom pathlib import Path converter DocumentConverter() paths list(Path(docs/).glob(*.pdf)) for result in converter.convert_all(paths, max_file_size20 * 1024 * 1024): print(result.status, result.document.export_to_markdown()[:100])当批量大小与并发度配置大于 1 时settings.perf.doc_batch_size/doc_batch_concurrency转换会走线程池并行处理_convert 实现。convert_string直接转换字符串内容对于已有 Markdown/HTML/DocLang 字符串的场景convert_string 支持InputFormat.MD、InputFormat.HTML、InputFormat.XML_DOCLANG三种格式内部自动包装成DocumentStream并补齐扩展名from docling.datamodel.base_models import InputFormat result converter.convert_string( h1Title/h1pSome text./p, formatInputFormat.HTML, namemy_page, ) print(result.document.export_to_markdown())CLI 使用终端直接转换安装后最简用法与 docs/examples/minimal.py 的 CLI 等价物docling report.pdf这里有个值得注意的实现细节docling命令组通过 _DefaultCommandGroup 重写了参数解析——当第一个 token 不是已知子命令convert、convert-remote时会自动在其前补上convert因此docling report.pdf等价于docling convert report.pdf。source参数支持本地文件、目录或 URL多个源可重复传入。完整选项可通过docling --help查看仓库内 docs/reference/cli.md 是由 scripts/render_cli_reference.py 从活的 Typer 应用自动生成的 CLI 参考文档明确注明“勿手改”可作为选项的权威出处。关键选项速查以下选项摘自 convert 命令定义 与 CLI 参考默认值均来自源码选项取值/默认值说明--from可重复默认全部格式限定接受的输入格式odf一次展开为 odt/ods/odp--to可重复默认md输出格式md、json、yaml、html、html_split_page、text、doctags、vtt、doclang、dclx、chunks--pipelinelegacy/standard/vlm/asr默认standard处理 PDF 或图片的流水线--vlm-model默认granite_doclingVLM 预设见下文列表--asr-model默认whisper_tiny音频/视频的 Whisper 系列预设含 MLX、native、S2T 变体--ocr/--no-ocr默认开启是否对位图内容跑 OCR--ocr-modedefault/full_page/layout_regions/pdf_aware_layout_regions送进 OCR 引擎的文档区域--ocr-engine/--layout-engine/--table-structure-engine默认auto/layout_object_detection/docling_tableformer三个阶段的模型引擎启用--allow-external-plugins后可用第三方插件--show-external-plugins可列出--pdf-backendthreaded_docling_parse另有pypdfium2、docling_parse等PDF 解析后端--pdf-password无默认受保护 PDF 的密码--page-range无默认只转换页范围如1-4PDF、XLSX、PPTX 后端支持--tables/--no-tables默认开启是否启用表格结构模型--table-modeaccurate/fast表格结构模型模式--image-export-modeplaceholder/embedded/referenced默认embedded图片在 JSON/YAML/HTML/Markdown 输出中的呈现方式base64 内嵌 vs PNG 引用 vs 占位--html-image-fetchnone/local/remote/all默认noneHTML/EPUB 输入中图片资源的抓取策略--output.结果输出目录--artifacts-path无默认模型工件本地路径离线部署--enable-remote-services默认关闭使用连接远程服务的模型前必须显式开启--enrich-code/--enrich-formula/--enrich-picture-classes/--enrich-picture-description/--enrich-chart-extraction默认全关各增强模型开关--deviceauto加速设备选择--num-threads4线程数--verbose/--quiet-v/-vv/-q日志级别-q适合被 AI Agent 或脚本调用时静默输出--profiling/--save-profiling默认关阶段级耗时统计表格打印/落 JSON--abort-on-error默认关首个错误即中止整批处理用 VLM 流水线转换官方入门文档给出的第二条命令演示了视觉语言模型路径docling --pipeline vlm --vlm-model granite_docling report.pdf从 convert 命令定义 可见--pipeline与--vlm-model的作用域限定为“PDF 或图片文件”默认 VLM 预设即granite_docling源码注释指出它支持含 MLX 在内的加速路径。--vlm-model的 help 文本会在运行时列出当前安装可用的全部预设CLI 参考 中记录的预设列表为smoldocling、granite_docling、deepseek_ocr、granite_vision、pixtral、got_ocr、phi4、qwen、nanonets_ocr2、gemma_12b、gemma_27b、dolphin、glm_ocr、lightonocr、falcon_ocr、chandra_ocr2、unlimited_ocr、dots_ocr、dots_mocr。注意 CLI 的依赖前提docling/cli/main.py顶部对typer/rich做了导入保护缺少时会提示pip install docling完整包推荐、pip install docling-slim[cli]或pip install typer rich三种安装路径依赖检查。导出与 RAG 分块--to各格式的落盘逻辑集中在 export_documentsjson/yaml/html/md/text分别调用save_as_json、save_as_yaml、save_as_html、save_as_markdown等方法doctags走save_as_doctagsvtt走save_as_vttdoclang调export_to_doclang()dclx调save_as_doclang_archivelatex使用 docling-core 的LaTeXDocSerializer--to chunks时初始化分块器--chunks-type hierarchical用HierarchicalChunker默认hybrid则基于 HuggingFace tokenizer 构建HybridChunker--chunks-tokenizer默认sentence-transformers/all-MiniLM-L6-v2--chunks-max-tokens控制单块 token 上限输出逐行 JSONL每行携带chunk_index、text、headings、page_numbers等 RAG 元数据。一个典型的“转 RAG 语料”命令docling report.pdf \ --to md --to json \ --to chunks --chunks-type hybrid --chunks-max-tokens 512 \ --output ./outMarkdown 导出若产生空文件CLI 会把该文档标记为失败并记录ErrorItem空输出检查这是排查“转换成功但内容为空”类问题时的关键日志点。支持的输入/输出格式速览格式清单以 docs/usage/supported_formats.md 为准。输入格式覆盖办公与文档PDFDOCX/XLSX/PPTX旧版 DOC/XLS/PPT依赖 LibreOfficeODT/ODS/ODPEPUBApple Pages需format-iwork依赖文本标记Markdown、AsciiDoc、LaTeX、HTML/XHTML、CSV、WebVTT、BoxNote图像与媒体PNG/JPEG/TIFF/BMP/WEBP音频WAV/MP3/M4A/AAC/OGG/FLAC需asr扩展视频MP4/AVI/MOV音频轨将被提取转写需asr扩展与ffmpeg邮件.eml/.msgSchema 专用DocLang XML.dclg/.dclg.xml、DocLang 归档.dclx、USPTO XML、JATS XML、XBRL XML、EBCDIC需通过EbcdicBackendOptions传入 COBOL 记录布局、Docling JSON。输出格式包括HTML支持图片内嵌与引用两种模式、Markdown、JSONDocling Document 无损序列化、DocLang XML、纯文本、Doctags、WebVTT、DocLang 归档.dclx、ChunksJSONLRAG 分块、LaTeX.tex独立文档图片输出为占位符。从入门到进阶下一步官方文档的 “Whats next” 指向 Usage 子页面与示例目录结合仓库结构建议的深入路径为转换定制与流水线功能开关docs/usage/advanced_options.md模型预取与离线使用、远程服务开关enable_remote_services、图像分辨率/缩放、表格抽取控制完整示例见 docs/examples/custom_convert.py格式能力边界docs/usage/supported_formats.md增强功能图片描述、代码/公式识别、图表数据提取docs/usage/enrichments.md 及 docs/examples/enrich_doclingdocument.pyRAG 集成与分块序列化docs/examples/ 中的hybrid_chunking.ipynb、rag_langchain.ipynb、rag_llamaindex.ipynb等系列笔记本架构原理docs/concepts/architecture.md 解释了“转换器 → 后端 → 流水线 → 选项”的组件关系其中虚线框组件为可子类化的基类是理解本文FormatOption机制的底图GPU/RTX 加速docs/usage/gpu.md 与 docs/usage/vision_models.md。关键源码与验证路径docling/document_converter.pyDocumentConverter、各*FormatOption默认映射、convert/convert_all/convert_string全量实现docling/cli/main.pyTyper 应用、convert命令全部选项、导出与分块落盘逻辑docling/datamodel/pipeline_options.pyPdfPipelineOptions、VlmPipelineOptions、OCR/布局/表格各选项模型测试用例tests/test_e2e_conversion.py、tests/test_cli.py、tests/test_backend_docling_parse.py 覆盖了端到端转换、CLI 行为与 PDF 解析后端的回归验证最小可运行示例docs/examples/minimal.py、docs/examples/batch_convert.py。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表